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