# 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
- LINE x1,y1,x2,y2
  draws a line 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.
- RECTANGLE x1,y1,x2,y2
  draws a rectangle from x1,y1 to x2,y2, the coordinates are in pixels
- BUTTON
  defines a button
- LABEL
  defines a label
- TEXT
  defines a text gadget
- CHECK
  defines a checkbox

## Keywords for BUTTON definition

- 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
- 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:
  - {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}
  - {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.
- 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.
- END
  indicates the end of the definition

## Keywords for LABEL definitions

- LEFT, TOP, HEIGHT, WIDTH, END
  see BUTTON keywords
- CAPTION string
  sets the text on the label to string

## Keywords for TEXT definitions

- LEFT, TOP, HEIGHT, WIDTH, 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 referenced 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, 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 referenced with {Cx}

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
    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
    rectangle 1,1,319,199
    rectangle 3,3,317,197
    rectangle 5,5,315,195
    *setting first button, this is always cancel !
    button
      top 10
      left 10
      height 20
      width 100
      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