Amiga ISO Collection/AmigaUtilCD1.iso/GFX/Painting/OpalPaint2,3-020+Version.LHA/ARexxReq.doc

Text File | 1994-04-22 | 17.5 KB | 494 lines

                    OpalPaint ARexx Requester Comands.



                        INTRODUCTION

   This  document  describes  using the new requester commands available in
OpalPaint  v2.3.   This  set of commands provides ARexx with the ability to
build  custom  requesters on the OpalPaint screen, thus greatly simplifying
the  user  interface  of  most  ARexx scripts and allowing more complicated
functions to be implemented in ARexx.



                        ACKNOWLEDGEMENTS

   Special  thanks  must go to Carmen Rizzolo and Greg Niles for their help
in the designing and testing of this interface.



                        NEW REQUESTER COMMANDS

        ReqBuild        - Initialise a new Requester.
        AddGadget       - Add a Gadget to the requester.
        AddText         - Add text to the requester.
        AddHeading      - Add heading text to the requester.
        AddBox          - Add a bevelled box to the requester.
        InitGadget      - Initialise the default value for a gadget.
        MutualEx        - Set up Mutual Exclusion between gadgets.
        Request         - Display the requester.
        GadgetStatus    - Gadget the state of gadgets in the requester.



                        NOTE ON PARAMETERS

  All text string containing spaces needs to be enclosed in quotes, however
ARexx  strips  the  first  level  of  quotes  before sending the command to
OpalPaint.  Therfore two levels of quoting are required.  e.g.

        '"This is one string" "This is another"'

   It  is  a good idea to always put all parameters in quotes as ARexx also
has  a  problem when negative numbers are sent as paremeters, it interprets
the '-' as a subtraction operator an usually generates an error.  Therefore
all  of  my  examples  will  have all parameters enclosed in single quotes.
e.g.
        AddGadget 'Button Gad1 0 -10 100 10 "A Button"'



                        CREATING A CUSTOM REQUESTER

  Creating a requester in ARexx is fairly easy, the following steps outline
the process of creating a requester.

        1) Call ReqBuild to initialise the requester.
        2) Add Elements to the requester using AddGadget, AddText,
           AddHeading, AddBox.
        3) Call MutualEx if required to set up mutual exclude groups.
        4) Call InitGadget for any gadgets that need initialising.
        5) Call Request to display the requester.
        6) Get the values entered by the user using the GadgetStatus command.


NOTE:   During  step  5,  the  Requester  command does not return until the
request is removed by the user hitting OK, Cancel or another button gadget.

TIP:  Positioning of elements within a requester can become a little tricky
if  the  requester becomes complex.  It is sometimes useful to use a screen
capture  program such as Grabbit to take a snapshot of the OpalPaint screen
when  your requester is displayed.  This snapshot can then be loaded into a
standard palette mapped paint program (or even OpalPaint) where the gadgets
and  text  can  be  positioned  more freely.  The final coordinates for the
gadgets  can  then be obtained from the paint program and used in the ARexx
script.



                        GADGET TYPES

  The  most important part of any requester is gadgets, using the AddGadget
command  several  different types of gadgets can be created.  The following
gadget types are currently available.

1) Button:

   A  Button  consists  of  a  rectangular border containing a text string.
When a button is selected by the user, the requester is removed and control
returns to ARexx.  The OK and Cancel gadgets that appear on most requesters
in OpalPaint are examples of buttons.

2) Toggle:

   A  Toggle  gadget is the same in appearance as a button.  However when a
toggle is selected it simply depresses, showing the user that the gadget is
selected.   For  example, the DrawModes requester in OpalPaint contains one
toggle gadget for each available drawmode, the currently active drawmode is
shown as depressed.

3) Check:

  A  Check gadget appears as a small rectangular box, when the user selects
a  check  gadget,  a  check  mark (tick) appears within the box.  The check
gadget,  unlike  the last 2 gadget types, does not have any text associated
with  it,  but  text  can  be  added  later.   The Preferences requester in
OpalPaint contains a Check gadget for each available preference option.

4) HProp:

  A HProp gadget is a horizontal proportional (slider) gadget.  This gadget
allows  the  user  to  select a number within a given range by dragging the
slider within the gadgets container.  The current value is displayed to the
right of the gadgets container.

5) VProp:

   A  VProp  gadget  is  identical  in operation to a HProp except that the
gadget is displayed vertically rather than horizontally.  The current value
for the gadget is displayed below the gadgets container.

6) Cycle:

  A  Cycle  gadget  has  similar imagery to a button, (a rectangular border
containing  text),  with  the  addition of a cycle arrow at the left of the
gadget  to indicate that it is a cycle gadget.  The Cycle gadget allows the
user  to  cycle through a list of available choices by simply selecting it.
The currently selected choice is displayed as text in the gadget.

7) String:

   A string gadget is used for text entry.  This gadget appears as a raised
border  with  the current text string displayed in it.  The user can modify
the text in the gadget by selecting it and typing in a new value.


8) Integer:

   An  integer  gadget  is  identical in appearance as a string gadget.  An
integer gadget however will only allow the user to enter an integer numeric
value.

                        GADGET NAMES

  Each  gadget is given a name which is used to reference the gadget in any
subsequent  commands.   Each  gadget name must be unique.  This name is not
case sensitive.

  The  names  "Okay" and "Cancel" are reserved and cannot be used as gadget
names.


                        POSITIONING ELEMENTS

   There  are several methods that can be used to position elements such as
Gadgets, Text and Boxes within the requester.

   The  positioning can be an absolute position in pixels, in this case the
position  is  simply  specified  as two integers in "x y" format.  If the x
value is positive then the horizontal position is relative to the left hand
edge  of  the  requester, if the x value is negative then it is relative to
the  right  hand  edge  of  the  requester.  Likewise a positive y value is
relative to the top and a negative y value is relative to the bottom of the
requester.  The position being specified is always the top-left hand corner
of the element (gadget etc).

  Examples:
        10 10   ; Place element 10 pixels from the top-left of the requester.
        -100 50 ; Place element 100 pixels from the right and 50 form the top.

   The  x  y  parameters  can  also  be changed to the keywords CenterX and
CenterY,  which  will center the object horizontally and/or vertically with
respect to the requester.

  Examples:
        CenterX CenterY   ;Place element in the center of the requester.
        CenterX 20        ;Place element in Center Horizontally and at y=20.


  An  element can also be positioned relative to a gadget which has already
been added to the requester. To use relative positioning, you need to specify
one of the relative keywords along with the gadget name to be used as a
reference, followed by an x y offset to set the spacing between the element
and the gadget. i.e. [Relative Keyword] [GadName] [x y]

  The currently available relative keywords are Above, Below, Left, Right.

Examples:
        Below Gadget1 0 10        ;10 pixels below Gadget1.
        Above Gadget1 0 -10       ;10 pixels below Gadget1.
        Right Gadget1 20 0        ;20 pixels right of Gadget1.
        Left Gadget1 -20 0        ;20 pixels left of Gadget1.
        Above Gadget1 CenterX -10 ;10 pixel above Gadget1, Centered horizontally.


NOTES:  1 - The gadget must have already been added using AddGadget.
        2 - The x y offset is signed, so a negative y will move the
            object upwards while a positive value will move it downwards.


TIP:  The quickest and easiest way to create a requester is to position one
gadget  using  absolute  positioning  and  then use relative positioning to
place the gadgets around it.



                        COMMAND SUMMARY

        ReqBuild
        Usage: ReqBuild w h Heading

 This  command  starts the requester building process, this command MUST be
issued  before any of the other requester commands.  The only parameters to
this  command  are  the width and height (in pixels) of the requester and a
heading string which will be displayed at the top of the requester.

 Example:
        ReqBuild '400 200 "My ARexx Options"'



        AddGadget
        Usage: AddGadget GadgetName GadgetType Position Size TypeInfo

 This  command  is  used  to  create  a  new gadget for the requester.  The
GadgetName,  GadgetType  and Position parameters have been described in the
sections above.

  The  Size  parameter  specifies  the  size  of the gadget.  This size can
either  be  one  of  the  3  available  default  sizes "Small","Medium" and
"Large",  or  a custom size can be specified by giving the gadget width and
height in pixels.

  The  TypeInfo  parameter  is  any  additional parameters required for the
particular  gadget type, the additional parameters for each gadget type are
described below:


1) Button:
   The  only  additional  parameter  for this gadget type is the text which
will appear within the gadget.

2) Toggle:
   The  only  additional  parameter  for this gadget type is the text which
will appear within the gadget.

3) Check:
   There are no additional parameters for this gadget type.

  NOTE:   Currently  the  Check  gadget only comes in one size.  For future
compatibility you should specify "Medium" for all check gadgets.

4) HProp:
   Additional prop gadget parameters are:

        MinValue MaxValue [Steps [Percent]]

   The  MinValue  and  MaxValue  parameters  set the numeric range that the
slider  will cover.  The optional step parameter sets the stepping distance
(granularity)  of  the  slider,  the  default  step is 1.  If the "Percent"
keyword  is  specified  a  percentage sign will be printed after the slider
value.

  Examples:

        0 100            ;Simple slider with range 0 to 100
        0 100 5          ;Slider with range of 0 to 100 in steps of 5
        -50 50 0.1       ;Slider with range -50 to 50 in steps of 0.1
        0 100 1 Percent  ;A Percentage slider with range 0% to 100%

5) VProp:
   The VProp parameters are identical to the HProp gadget type.

6) Cycle:
   The  aditional  parameters  to  the  cycle gadget are simply the list of
available choices for that gadget.

  Example:

        '"A500" "A1000" "A2000" "A4000"'   ;Cycle gadget with 4 choices.

7) String:
   The  string  gadget  takes  only  1  parameter.  This optional parameter
describes  the  maximum  number  of characters that can be entered into the
string gadget.  If this is not specified then 200 is used.

  NOTE:   Currently  only  the  Width parameter is recognised by the String
gadget, for future compatibility you should specifiy the height of a string
gadget as 10 if you are not using one of the default sizes.


8) Integer:
   Additional parameters are:

        [MinValue MaxValue]

   The  optional  MinValue  MaxValue  parameters set the allowable range of
values  that can be entered by the user.  If these values are not specified
then there will be no limits on the range.

  NOTE:   Currently  only  the Width parameter is recognised by the Integer
gadget,  for  future  compatibility  you  should  specifiy  the height of a
Integer gadget as 10 if you are not using one of the default sizes.


        PUTTING IT ALL TOGETHER

  Examples of the AddGadget Command:

1)      AddGadget 'Button Gad1 100 50 Medium "Render"'

This command adds a button with the text 'Render' appearing in it.


2)      AddGadget 'Toggle Gad1 100 50 Medium "Motion Blur"'

   This  command  adds  a  toggle gadget that enables the user to enable or
disable motion blur.


3)      AddGadget 'Check Gad1 100 50 Medium'


4)      AddGadget 'HProp Gad1 100 50 Large 0 100 1 Percent'

  This creates a slider with the range of 0 to 100, the value is displayed
as a percentage.


5)      AddGadget 'HProp Gad1 10 50 Medium -10 10 0.1'

   This creates a slider with a range of -10 to 10 in steps of 0.1.


6)      AddGadget 'Cycle Gad1 100 50 Medium  A500 A1000 A2000 A2500 A4000'

  This  creates a cycle gadget which allows the user to select his computer
type from a list of 5 possible choices.


7)      AddGadget 'String Gad1 100 50 Medium'

8)      AddGadget 'String Gad1 100 50 Medium 30'

   String gadget that accepts up to 30 characters.


9)      AddGadget 'Integer Gad1 100 50 Medium'

10)     AddGadget 'Integer Gad1 100 50 Medium 0 10'

   Integer gadget that accepts a range of 0 to 10.


11)     AddGadget 'Button Gad2 Below Gad1 0 -10 Small "Done"'

   Add a button 10 pixels below Gad2 with the text "Done" in it.





        AddText
        Usage:  AddText Position Text

  This  command is used to add text to the requester.  The text positioning
is described above.

Example:
        AddText 'Left Gad1 -10 0 "Enable Motion Blur"'



        AddHeading
        Usage:  AddHeading Position Text

  This  command  is  similar  to AddText, except that the text is displayed
with  a  drop  shadow  to  make  it stand out.  This should be reserved for
headings only.

        AddBox
        Usage: AddBox Position Size [Raised]

  This  adds  a bevelled box to the requester.  The position can be relative
or  absolute,  note however that the position is only for the top left-hand
corner  of the box and not the complete box itself.  This means that if you
specifiy  a  box  to  be  placed  above  a  gadget  the  whole box will not
necessarily be above that gadget, only the top left corner will be.

  The  box size is always specified in pixels (there are no default sizes).
If the 'Raised' keyword is specified the box will appear raised rather than
recessed.

Examples:
        AddBox 10 10 100 100
        AddBox Above Gad1 -10 10 100 100 Raised

  The second example places the top left corner of the box 10 pixels above and
to the left of Gad1. The box is 100x100 and is recessed.



        InitGadget
        Usage: InitGadget GadName InitValue

  Before  the  requester  is  displayed,  the gadgets can be initialised to
default  values  using this command.  The initial value varies depending on
the gadget type.  The parameter for each gadget types are:

        Button  - Cannot be initialised (has no state).
        Toggle  - Either 'Selected' 'Unselected' '0' or '1'.
        Check   - Either 'Selected' 'Unselected' '0' or '1'.
        HProp   - Numeric value within valid slider range.
        VProp   - Numeric value within valid slider range.
        Cycle   - Any entry which was defined in the cycle list.
        String  - Text string up to the maximum length the gadget can hold.
        Integer - Integer value in the valid range for the gadget.

  For the Toggle and Check values, '1' is equivalent to 'Selected' and
'0' is equivalent to Unselected.

   Examples:

        InitGadget Toggle1 Selected
        InitGadget Check1 1
        InitGadget HorizProp 10
        InitGadget Cycle1 A4000
        InitGadget String1 'Ram:Temp'
        InitGadget Integer1 10



        MutualEx
        Usage: MutualEx [Gad1 Gad2 Gad3 ...]

  A  Group of Check or Toggle gadgets can be defined to exclude each other.
If a gadget within a Mutual Exclude group is selected, all other gadgets in
that  group  are  deselected,  this  means that only one gadget can ever be
selected at one time.

  By  specifying  more  than  1 MutualEx command, multiple Mutual Exclusion
groups can be set up.

  Example: This creates a requester similar to the transparency requester.

        AddGadget 'Toggle Std 50 30 Medium "Standard"'
        AddGadget 'Toggle RGB Below Std 0 10 Medium "RGB"'
        AddGadget 'Toggle HSV Below RGB 0 10 Medium "HSV"'
        AddGadget 'Toggle Alpha Below HSV 0 10 Medium "Alpha"'
        MutualEx Std RGB HSV Alpha

  NOTE:   Mutual  exclusion  is only possible for toggle and check gadgets.
Only the first 32 gadgets in a requester can take part in Mutual exclusion.


        Request
        Usage:  Request [NoOK] [NoCancel]

  Once  the requester had been defined, this command is used to display the
requester.   When  the requester exits, the returned value will be either 1
if OK or a Button gadget was hit, and 0 if cancel was hit.

  This  command  accepts  2  parameters,  "NoCancel"  to create a requester
without a cancel gadget, and "NoOK" for a requester without an Okay gadget.


        GadgetStatus
        Usage: GadgetStatus GadName

   Once  the  requester  has  completed,  the  status of any gadgets can be
interrogated using this command.  The return value from this command varies
depending on the gadget type:

        Button  - 1 if gadget was hit (and closed requester), else 0.
        Toggle  - 1 if gadget was selected, else 0.
        Check   - 1 if gadget was selected, else 0.
        HProp   - Numeric value within valid slider range.
        VProp   - Numeric value within valid slider range.
        Cycle   - Any entry which was defined in the cycle list.
        String  - Text string entered into the gadget.
        Integer - Integer value entered into gadget.


  The  2 reserved gadget names, "Okay" and "Cancel" can also be used by the
command to determine if the Okay or Cancel gadget was hit by the User.  i.e
the following command can be used to check if the OK gadget was hit.

        GadgetStatus Okay
        if Result=1 then OKHit