# PCOpus Requester definition

You can find an example requester in 'Example.req'. Inside that file you can find this text as plain ASCII, too.
Any Requester must have 'PCOpus Requester' in the first line, so PCOpus will recognize it.
All lines that have no keyword at the beginning are ignored, so you can use '*', '/', '.', '+' or something like that as first char to indicate a comment.
Behind any keyword must not be anything except what is stated below, i.e. no comments behind known keywords !

## Main Keywords

- TITLE
  Sets the title of the requester, may be left out
- SIZE width,height
  Sets the size of the requester, width and height are in pixels
- BACKGROUND r,g,b
  Sets the background-color of the requester to r(ed), g(reen), b(lue). R,g and b must be values between 0 and 255.
- FOREGROUND r,g,b
  Sets the foreground-color to r(ed), g(reen), b(lue). R,g and b must be values between 0 and 255.
  The foreground-color is the current drawing-color. So you can draw some colorful rectangles/lines if you change the foreground-color before drawing.
- PICTURE filename
  loads picture filename as background of requester. Be sure to load the picture before drawing lines, otherwise the lines will be overwritten.
- LINE x1,y1,x2,y2
  draws a line from x1,y1 to x2,y2, the coordinates are in pixels
- RECTANGLE x1,y1,x2,y2
  draws a rectangle from x1,y1 to x2,y2, the coordinates are in pixels
- FILE filename
  filename is the name of a file created in your (PCOpus) temp directory
  If FILE is not present in a requester, the values are not saved.
  If FILE is present, every time you leave the requester, all values are saved to filename. These values are loaded when calling the requester next time. If you change a byte in the requester ASCII file, the values are not loaded. PCOpus can not determine if you have only changed some text or added an item.
- CENTERUNDERMOUSE x
  if x is greater than 0, the requester will be centered under the mouse for faster access
- NORESIZE
  this is an indicator if the requester may be resized to fit the size of the button it is in. It takes no parameters. You must use it BEFORE any SIZE, LINE or RECTANGLE commands. Using it as the first command should do the trick :-)
- CONTROLTYPEPOSMIX YES/NO
  this is a switch to tell PCOpus if the controls should be handled separately when using relative positioning with leading '++' or '--'. If set to YES, any relative positioning that occurs is reckoned relative to the previous set value for ANY control, if set to NO, the last value of the same type of control (BUTTON/LABEL/TEXT/CHECK) is used.
- BUTTON
  defines a button
- LABEL
  defines a label
- TEXT
  defines a text gadget
- CHECK
  defines a checkbox
- VARIABLE
  defines a variable
- COMBOBOX
  defines a combobox

## Keywords for BUTTON definition

- BACKGROUND, FOREGROUND
  see main keywords. FOREGROUND does not work for buttons, though !
- LEFT x
  sets the left position of the item to x, x is in pixels.
- TOP x
  sets the top position of the item to x, x is in pixels
- HEIGHT x
  sets the height of the item to x pixels
- WIDTH x
  sets the width of the item to x pixels
- NOTE: You may use relative values for LEFT, TOP, HEIGHT and WIDTH. To do this, enter the values like this: 'LEFT ++30' if the current control should be placed 30 pixels further right than the previous control of the same type, or 'HEIGHT --10' if the current control should be 10 pixels less high than the previous control of the same type. This allows very flexible placing of many controls.
- TOOLTIP x
  sets the tooltip-text of the item to x, x is a string
- ID x
  sets the id of the item to nr. x
  the id is the number the item can be referenced with, using {B3} 3 is the id here
  this id has nothing to do with any id's used in TEXT, CHECK or LABEL definition !
- TYPE cycle/command
  sets the type of the item, possible values are cycle and command
- CAPTION string
  sets the caption (the text on the button) to string
  if the button is a 'cycle' type, definitions like this are possible:
  CAPTION a,b,c,d,e,f
  the text on the button will cycle throug a,b,c,d,e and f
  the value of the button you get with {Bx} is the value that is present on the button in the moment.
  You could define a button that lets you select different archivers this way: (always remember, type must be 'cycle' !)
  CAPTION LHA,ARJ,ZIP,RAR
  One more thing: if you need certain values and want to have another text on the button (a text that is easier to understand) you can use this:
  CAPTION No Compression/m0,Best/m1,Good/m2,Fast/m3,Fastest/m4
  this would define the possibilities of the -m switch of ARJ.
  In the requester you would read: No Compression OR Best OR Good OR Fast OR Fastest, but with {Bx} you would get m0 OR m1 OR m2 OR m3 OR m4 !
  If the TYPE is cycle, the text on the button will have a '@' at the first position, this is ignored of course when you request the value of the button, it only indicates, that this button is a cycle type.
- FUNCTION string
  sets the function that is executed when this button is pressed to string
  FUNCTION only takes effect when TYPE command is defined !
  After a button is pressed that is TYPE command, the requester is closed !
  FUNCTION definition is quite powerful. Something like this is possible:
  FUNCTION ARJ {C1:1} -y{EC1}{C2:0}{C3:1} -x{EC3} -v{EC2} {B1} {T3} {F}
  Possible brackets are (please not that these are case-sensitive !!):
  - {Cx}
    value of Checkbox with id x, this is 0 or 1 (checked or unchecked) !
  - {Cx:y}
    if Checkbox with id x has value y, everything between {Cx:y} and {ECx} is used, if the Checkbox has another value, everything between is removed, in the example above anything between {C2:0} and {EC2} would be used if the Checkbox with id 2 would be checked.
  - {Bx}
    caption of button with id x, only useful for cycle-types
  - {Bx:a}
    if button with id x shows a at the moment, everything between {Bx:a} and {EBx} would be used, otherwise it would be removed
  - {Tx}
    text in text gadget with id x is inserted here
  - {Tx:a}
    see {Bx:a}
  - {Vx}
    value of the variable with id x is inserted here
  - {Vx:a}
    see {Bx:a}
  - {EXy}
    indicates the end of the above demonstrated 'if-clause', X must be B, C or T, y is the id if the item
  - {F}, {f}, {o}, ...
    any bracket from the PCOpus external command definitions may be used here too, PCOpus will insert the filenames later.
  From Version 1.80e PCOpus supports multiple lines per command/function.
  '*!*' is used to indicate a carriage return.
  Example:
  FUNCTION c:*!*cd c:\windows*!*control
  will be translated to three lines:
  c:
  cd c:\windows
  control
  This is necessary if you are starting batchfiles that require the current directory to be the directory they are in.
  From version 2.0b PCOpus allows the use of internal commands (like *!GotoDir for example, and all other of course, too) . It is possible to have any combination of internal commands and DOS-commands as function.
  Three special commands exist:
  *DOALLFILES*: this does the same as enabling the 'Do all files' checkbox in button-definition.
  *PAUSE*: this does the same as enabling the 'Pause' checkbox.
  *TESTMODE*: this is for your convenience. Use this command inside the function string and the function will not be executed. Open the list (with the 'V'-Button) and see what your button produced.
  The reason for this is simple: If you define a requester that needs 'Do all files' or 'Pause' for some functions but not for all, you can enable these options with these keywords. The use of the keywords: function *PAUSE**DOALLFILES*echo {f}
  Please note: the keywords are case-sensitive and must not be followed by '*!*' as other combined commands.
  Of course you can define something like this, too: function {C1:1}*DOALLFILES*{EC1}
  So you can select these options in the requester itself !
- DEFAULT x
  sets the default value of a cycle type to x.
  if CAPTION is A,B,C,D,E,F and DEFAULT is 4, the text on the button on startup of the requester would be E, indexes are beginning with 0 !
- PICTURE x
  sets the background picture for this button to x.
  x must include the complete pathname to the picture
  Example: c:\windows\requesters\background1.bmp
  Assigned names are supported. If you have assigned 'Pics' to c:\windows\requesters, you may use 'pics:\background1.bmp' instead. If your picture resides in the PCOpus directory, you can leave out the path. If the file you stated here does not exist, the background of the button stays grey.
  Once a picture is defined, it is used for all following buttons until PICTURE is stated without argument or an invalid name is given.
- SHORTCUT x
  Sets the shortcut for this button to x. x may be any useful key. Alt-F4 ist not useful ! For more information about shortcuts read the Button-definition description. Shortcuts are only useable if requesters are used in buttons.
- END
  indicates the end of the definition

## Keywords for LABEL definitions

- LEFT, TOP, HEIGHT, WIDTH, TOOLTIP, FOREGROUND, BACKGROUND, END
  see BUTTON keywords
- Additional information for BACKGROUND
  if you do not state a background color, the label will be transparent, so a picture on the requester itself will be visible.
- CAPTION string
  sets the text on the label to string

## Keywords for TEXT definitions

- LEFT, TOP, HEIGHT, WIDTH, TOOLTIP, SHORTCUT, END
  see BUTTON keywords
- TEXT string
  sets the text of the gadget on startup to string
- ID x
  sets the id of the text gadget to x, may be referred to with {Tx}
- MIN x
  sets the minimal value to x
- MAX x
  sets the maximal value to x
  if MIN or MAX have a value >0 you may only give numbers between MIN and MAX
  No chars are allowed in this case

All textgadgets support double-click to open a file-requester. This is not useful in all cases, though !

## Keywords for CHECK definitions

- LEFT, TOP, HEIGHT, WIDTH, TOOLTIP, SHORTCUT, FOREGROUND, BACKGROUND, END
  see BUTTON keywords
- CAPTION string
  sets the text right of the checkbox to string
- EXCLUDE x1,x2,x3
  if this checkbox is activated, the checkboxes with id x1, id x2 and id x3 are deactivated. You may use any number of arguments.
- DEFAULT x
  sets the default value to x, 0 or 1 is useful here
- ID x
  sets the id of the checkbox to x, may be referred to with {Cx}

## Keywords for VARIABLE definitions

- VALUE string
  sets the value of the variable to string
- ASSIGN string
  sets the value of the variable to the real path of assigned directory or environment variable string. For example ASSIGN PCOpus will set the current value to the directory PCOpus was started from, ASSIGN *env_temp will set the value the the path of your systems temp directory. This finally allows the use of flexible, system independent pathes inside requesters.
- ID x
  sets the id of the variable to x, may be referred to with {Vx}

## Keywords for COMBOBOX definitions

- LEFT, TOP, WIDTH, TOOLTIP, SHORTCUT, FOREGROUND, BACKGROUND, END
  see BUTTON keywords
- ADD string
  adds the given string to the drop down-area of the combobox
- ID x
  sets the id of the combobox to x, may be referred to with {Lx}

Please note that if VALUE and ASSIGN are stated, the value set later is used !

These requesters are powerful instruments. You must take care when defining requesters. It is possible to define complete nonsens here. If you have problems or comments, please EMail !

Below is a little (and quite simple AND useless) example, please read through it, there is some additional information.

    PCOpus Requester
    file test1.req
    *Values are saved to file test1.req in temp directory
    centerundermouse 1
    size 320,200
    *size of the requester will be 320x200 pixels
    *drawing some rectangles, since we have no window title (no TITLE defined), this looks nice, in full color now ...
    foreground 60,0,0
    rectangle 1,1,319,199
    foreground 120,0,0
    rectangle 3,3,317,197
    foreground 255,0,0
    rectangle 5,5,315,195
    *setting first button, this is always cancel !
    button
      top 10
      left 10
      height 20
      width 100
      tooltip Exit without action
      caption Cancel
      picture klex.bmp
    end
    *IMPORTANT ! IMPORTANT ! IMPORTANT !
    *Since it is not possible to leave a requester if no button is defined on it,
    *there is always a first button, this button MUST be Cancel !
    *You may define whatever you want for it, if you click on it, the requester is
    *closed with no action !

    button
      top 40
      left 10
      height 20
      width 100
      function echo {f}{C1:1}"Hello World !"{T1}{EC1}{B1}{T1}{C1:0} Option 1 is off !{EC1}
      caption Test&Button
      type command
    end
    *If you are unsure about what you have defined or what you will get when clicking on
    *some things or not, it is quite a good idea to have defined 'echo' as function
    *during testing.
    *This command does only a pretty senseless thing and the text it echos is not very
    *overwhelming either.
    *Please note, that for {f} the first selected file in the active window is inserted,
    *as you are used to from the PCOpus external commands !

    *setting first label
    label
      top 10
      left 120
      height 15
      width 100
      caption label 1
    end
    *and the first textgadget
    text
      id 1
      top 45
      left 120
      heigth 20
      width 120
      text test-text-gadget
    end
    *here we use the data from previous items for quick positioning :-)
    *if you leave out LEFT, TOP, HEIGHT or WIDTH the values from the previous item
    *OF THE SAME TYPE are used, this is very convenient. You can quickly change sizes
    *of buttons if you only have the size defined in the first button
    button
      id 1
      top 100
      type cycle
      caption 1/a,2/b,3/c,4/d
      default 5
    end
    *As you see here, default is set to 5, but we have no 5. value, you will get an empty
    *button when starting up, but after the first click on this button, you will only have
    *the choice between 1, 2, 3 and 4 !
    label
      top 100
      caption label2
    end
    text
      top 135
      text text2
    end
    check
      id 1
      top 10
      left 250
      height 20
      width 60
      default 0
      caption option1
      exclude 2,3,4
    end
    *An example for excluding checkbuttons, just play around a bit, it is simple to understand
    check
      id 2
      top 33
      default 1
      caption option2
      exclude 1,3,4
    end
    check
      id 3
      top 56
      caption option3
      exclude 1,2,4
    end
    check
      id 4
      top 79
      caption option4
    end
    check
      id 5
      top 150
      exclude 6
      default 1
      caption option5
    end
    check
      id 6
      exclude 5
      top 173
      default 1
      caption option6
    end
    End PCOpus Requester