home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / Converter / PHOGEN3.DMS / in.adf / DevDocs.lha / help / pgs_autodocs.doc < prev   
Encoding:
Text File  |  1995-03-29  |  26.7 KB  |  975 lines
  1. TABLE OF CONTENTS
  2.  
  3. pgs.library/CloseProgress
  4. pgs.library/Error
  5. pgs.library/GetDimensions
  6. pgs.library/GetEnvVal
  7. pgs.library/GetLine
  8. pgs.library/GetListAndVal
  9. pgs.library/GetListOption
  10. pgs.library/GetOkCancel
  11. pgs.library/GetOneOption
  12. pgs.library/GetOneValue
  13. pgs.library/GetScaleDimensions
  14. pgs.library/GetString
  15. pgs.library/GetThreeValues
  16. pgs.library/GetTwoOptions
  17. pgs.library/GetTwoValues
  18. pgs.library/InitRandom
  19. pgs.library/KWriteF
  20. pgs.library/LoadIFFPalette
  21. pgs.library/OpenProgress
  22. pgs.library/Random
  23. pgs.library/ReleaseLine
  24. pgs.library/SetEnvVal
  25. pgs.library/SetProgress
  26. pgs.library/ThreeButtonReq
  27. pgs.library/Error               
  28.  
  29.    NAME
  30.    Error -- Generate an Error requester.
  31.  
  32.    SYNOPSIS
  33.    Error(STRPTR text);
  34.                  A0
  35.  
  36.    FUNCTION
  37.    Displays the requester and waits until OK has been selected, then returns.
  38.  
  39.    INPUTS
  40.    text - String pointer to Null-terminated text to display in requester. 
  41.  
  42.    RESULT
  43.  
  44.    SEE ALSO
  45.  
  46.    BUGS
  47.    Currently uses intuition EasyRequest(). Needs to be changed to use
  48.    our own gadget system.
  49. pgs.library/GetOkCancel              
  50.  
  51.    NAME
  52.    GetOkCancel -- Display a requester with OK and CANCEL buttons.
  53.  
  54.    SYNOPSIS
  55.    GetOkCancel(STRPTR windowtext,STRPTR maintext);
  56.                            A0             A1
  57.  
  58.    FUNCTION
  59.    Displays the requester and waits until OK or CANCEL have been selected.
  60.  
  61.    INPUTS
  62.    windowtext - String for window title text.
  63.    maintext - String pointer to Null-terminated text to display in requester. 
  64.  
  65.    RESULT
  66.  
  67.    The return value indicates success or failure with one of the following 
  68.    values:
  69.  
  70.       0           CANCEL selected
  71.       1           OK selected
  72.       2           Requester failed to open.
  73.  
  74.  
  75.    SEE ALSO
  76.  
  77.    BUGS
  78. pgs.library/GetOneValue
  79.  
  80.    NAME
  81.    GetOneValue -- Display a requester allowing user to select a value.
  82.  
  83.    SYNOPSIS
  84.    GetOneValue(STRPTR wintitle, STRPTR gadgettext, LONG min, LONG max, 
  85.                         a0                a1          d0       d1      
  86.  
  87.                LONG *variable);
  88.                       a2       
  89.       
  90.    FUNCTION
  91.  
  92.    Displays the requester and waits until OK or CANCEL have been selected.
  93.  
  94.    INPUTS
  95.    wintitle   - The title of the requester window.
  96.    gadgettext - The text to display above the slider.
  97.    min        - The minimum value for the slider (signed integer value)
  98.    max        - The maximum value for the slider (signed integer value)
  99.    *variable  - A pointer to a signed integer for the result. This value
  100.                 is read to initialise the slider to the start value.
  101.  
  102.    RESULT
  103.    the 32-bit signed integer pointed to by variable (a2) is updated
  104.    if OK was selected.
  105.  
  106.    The return value indicates success or failure with one of the following 
  107.    values:
  108.  
  109.       0           CANCEL selected
  110.       1           OK selected
  111.       2           Requester failed to open.
  112.  
  113.    SEE ALSO
  114.  
  115.    BUGS
  116.    If minimum and maximum are the same value it does not bring up the
  117.    requester at all and returns immediately with *variable set to the
  118.    value and the result 
  119. pgs.library/GetTwoValues
  120.  
  121.    NAME
  122.    GetTwoValues -- Display a requester allowing user to select two values.
  123.  
  124.    SYNOPSIS
  125.    GetTwoValues(STRPTR wintitle, STRPTR gadgettext, LONG min, LONG max,
  126.                          a0                a1          d0       d1    
  127.  
  128.                 LONG *variable, STRPTR gadgettext2, LONG min2, LONG max2, 
  129.                         a2           a3               d2        d3
  130.                
  131.                 LONG *variable2);
  132.                         a5
  133.  
  134.    FUNCTION
  135.  
  136.    Displays the requester and waits until OK or CANCEL have been selected.
  137.  
  138.    INPUTS
  139.    wintitle   - The title of the requester window.
  140.    gadgettext - The text to display above the first slider.
  141.    min        - The minimum value for the first slider (signed integer value)
  142.    max        - The maximum value for the first slider (signed integer value)
  143.    *variable  - A pointer to a signed integer for the result. This value
  144.                 is read to initialise the first slider to the start value.
  145.    gadgettext2- The text to display above the second slider.
  146.    min2       - The minimum value for the second slider (signed integer value)
  147.    max2       - The maximum value for the second slider (signed integer value)
  148.    *variable2 - A pointer to a signed integer for the result. This value
  149.                 is read to initialise the second slider to the start value.
  150.  
  151.    RESULT
  152.    The 32-bit signed integers pointed to by variable (a2) and variable2 (a5)
  153.    are updated if OK was selected.
  154.  
  155.    The return value indicates success or failure with one of the following 
  156.    values:
  157.  
  158.       0           CANCEL selected
  159.       1           OK selected
  160.       2           Requester failed to open.
  161.  
  162.    SEE ALSO
  163.  
  164.    BUGS
  165.    If either sliders minimum and maximum are the same value it may well 
  166.    crash currently.
  167. pgs.library/GetDimensions
  168.  
  169.    NAME
  170.    GetDimensions -- Display a requester to select a new image size
  171.  
  172.    SYNOPSIS
  173.    GetTwoValues(STRPTR wintitle, ULONG *xsize, ULONG *ysize);
  174.                          a0            a1            a2    
  175.  
  176.    FUNCTION
  177.  
  178.    Displays the requester and waits until OK or CANCEL have been selected.
  179.  
  180.    INPUTS
  181.    wintitle   - The title of the requester window.
  182.    *xsize     - A pointer to the unsigned 32-bit variable containing
  183.                 the x size.
  184.    *ysize     - A pointer to the unsigned 32-bit variable containing
  185.                 the y size.
  186.  
  187.    RESULT
  188.    The 32-bit signed integers pointed to by xsize (a1) and ysize (a2)
  189.    are updated if OK was selected.
  190.  
  191.    The return value indicates success or failure with one of the following 
  192.    values:
  193.  
  194.       0           CANCEL selected
  195.       1           OK selected
  196.       2           Requester failed to open.
  197.  
  198.    SEE ALSO
  199.    GetScaleDimensions()
  200.  
  201.    BUGS
  202. pgs.library/GetString
  203.  
  204.    NAME
  205.    GetString -- Display a requester to enter a string.
  206.  
  207.    SYNOPSIS
  208.    GetString(STRPTR wintitle, STRPTR gadgettext, STRPTR string);
  209.                       a0            a1                 a2    
  210.  
  211.    FUNCTION
  212.  
  213.    Displays the requester and waits until OK or CANCEL have been selected.
  214.  
  215.    INPUTS
  216.  
  217.    wintitle   - The title of the requester window.
  218.    gadgettext - A pointer to the title text for the gadget.
  219.               
  220.    string     - A pointer to the destination string. You must allocate
  221.                 enough space to store the resultant string (256 bytes).
  222.                 The initial contents of this string determine the default
  223.                 text displayed in the requester.
  224.  
  225.    RESULT
  226.  
  227.    The string is written to the address pointed to by 'string'
  228.    if OK was selected.
  229.  
  230.    The return value indicates success or failure with one of the following 
  231.    values:
  232.  
  233.       0           CANCEL selected
  234.       1           OK selected
  235.       2           Requester failed to open.
  236.  
  237.    SEE ALSO
  238.  
  239.    BUGS
  240. pgs.library/OpenProgress
  241.  
  242.    NAME
  243.    OpenProgress -- Get ready to open a Progress Requester.
  244.  
  245.    SYNOPSIS
  246.    OpenProgress(STRPTR wintitle, STRPTR gadgettext);
  247.                         a0            a1              
  248.  
  249.    FUNCTION
  250.  
  251.    Nothing immediately. Progress requester is prepared but not
  252.    displayed until first SetProgress() call.
  253.  
  254.    You do NOT have to call OpenProgress() during normal operation
  255.    of .GIO files, as OpenProgress() is automatically called before
  256.    your code is accessed (if required).
  257.  
  258.    INPUTS
  259.  
  260.    wintitle   - The title of the requester window.
  261.    gadgettext - A pointer to the title text for the gadget.
  262.  
  263.    RESULT
  264.  
  265.    None.
  266.  
  267.    SEE ALSO
  268.    SetProgress(),CloseProgress()
  269.  
  270.    BUGS
  271. pgs.library/SetProgress
  272.  
  273.    NAME
  274.    SetProgress -- Set the contents of the progress requester
  275.  
  276.    SYNOPSIS
  277.    OpenProgress(STRPTR gadgettext, ULONG value);
  278.                         a0            d0              
  279.  
  280.    FUNCTION
  281.  
  282.    If a progress requester is open, it updates the text (if
  283.    gadgettext is non-zero) and the value of the slider (from zero to 100)
  284.  
  285.    If a progress requester is not open, and OpenProgress has not been
  286.    called since the program started or the last call to CloseProgress,
  287.    then the function exits silently without error.
  288.  
  289.    If OpenProgress has been called since the last call to CloseProgress
  290.    (or program start) and the progress requester is not already open,
  291.    then it is opened.
  292.  
  293.    You should check the return code regularly to see if the user
  294.    has requested to abort your operation.
  295.  
  296.    You need not check SetProgress() each line of image data you
  297.    handle (it causes too much of a speed penalty). For most 
  298.    work the code from BMP.C is adequate: (y is the line number)
  299.  
  300.    if(!(y%16)) // don't slow down by calling SetProgress too often
  301.    {
  302.       if(SetProgress(0,100-(y*100/giodata->Height))!=1)
  303.       {
  304.          giodata->Error = LOAD_ABORTED;
  305.          goto err;
  306.       }
  307.    }
  308.  
  309.    Do NOT call SetProgress multiple times with the string set, otherwise
  310.    the text can flicker as it is updated every time. It is best to set
  311.    the text before your main loop with
  312.  
  313.    SetProgress("Now converting image...",0);
  314.  
  315.    and then use
  316.  
  317.    if(SetProgress(0,y*100/maxy)!=1) goto err;
  318.  
  319.    inside your loop.
  320.  
  321.  
  322.    INPUTS
  323.  
  324.    gadgettext - A pointer to the title text for the gadget, or zero if
  325.                 you want the text unchanged.
  326.  
  327.    value      - The new position (between 0 and 100) for the slider.
  328.                 Note - you can make sliders go backwards if you want!
  329.  
  330.    RESULT
  331.  
  332.       0           CANCEL selected
  333.       1           OK selected
  334.       2           Requester failed to open.
  335.  
  336. (SetProgress(0,value)!=1)
  337.  
  338.    SEE ALSO
  339.    OpenProgress(),CloseProgress()
  340.  
  341.    BUGS
  342. pgs.library/CloseProgress
  343.  
  344.    NAME
  345.    CloseProgress -- Close the progress requester.
  346.  
  347.    SYNOPSIS
  348.    CloseProgress(void);
  349.                                 
  350.    FUNCTION
  351.  
  352.    If a progress requester is open, it is closed.
  353.  
  354.    If OpenProgress() has been called then the 'ready to open' state
  355.    of the requester is cancelled.
  356.  
  357.    You do not need to call CloseProgress() for normal .GIO use
  358.    as it is done for you on exiting your code.
  359.  
  360.    INPUTS
  361.  
  362.    None
  363.  
  364.    RESULT
  365.  
  366.    Requester is closed, if displayed.
  367.  
  368.    SEE ALSO
  369.    OpenProgress(),SetProgress()
  370.  
  371.    BUGS
  372.  
  373. pgs.library/ThreeButtonReq
  374.  
  375.    NAME
  376.    ThreeButtonReq -- A simple three-button requester.
  377.  
  378.    SYNOPSIS
  379.    ThreeButtonReq(STRPTR wintitle, STRPTR windowtext, STRPTR gadget1text,
  380.                         a0                a1                  a2
  381.  
  382.                   STRPTR gadget2text, STRPTR gadget3text);
  383.                         a3                a5                                
  384.    FUNCTION
  385.  
  386.    Opens a simple requester with three buttons.
  387.  
  388.    INPUTS
  389.  
  390.    wintitle    - The title of the requester window.
  391.    windowtext  - The text to display inside the window.
  392.    gadget1text - The text for the first button.
  393.    gadget2text - The text for the second button.
  394.    gadget3text - The text for the third button.
  395.  
  396.    RESULT
  397.  
  398.    0 - Close gadget selected or other error.
  399.    1 - Button 1 selected
  400.    2 - Button 2 selected
  401.    3 - Button 3 selected
  402.  
  403.    SEE ALSO
  404.  
  405.    BUGS
  406.    Doesn't use same return results as the other requesters - be careful!
  407.  
  408. pgs.library/KWriteF
  409.  
  410.    NAME
  411.    KWriteF -- Output serial debugging information.
  412.  
  413.    SYNOPSIS
  414.    KWriteF(STRPTR formatstring, LONG val1, LONG val2);
  415.                   a0              d0         d1
  416.                                 
  417.    FUNCTION
  418.  
  419.    The string and val1 and val2 are passed to the kprintf() as
  420.  
  421.    kprintf(formatstring,val1,val2);
  422.  
  423.    Only two values can be passed, these can be zero if not needed.
  424.   
  425.    This function was required for internal use, we have left it in
  426.    the library in case it is of benefit for other developers.
  427.  
  428.    INPUTS
  429.  
  430.    formatstring - A standard C Type formatting string.
  431.    val1         - Value 1
  432.    val2         - Value 2
  433.  
  434.    RESULT
  435.  
  436.    Output to serial port at hardware default (9600) speed.
  437.  
  438.    SEE ALSO
  439.  
  440.    BUGS
  441.  
  442. pgs.library/LoadIFFPalette
  443.  
  444.    NAME
  445.    LoadIFFPalette -- Loads an IFF Palette file.
  446.  
  447.    SYNOPSIS
  448.    LoadIFFPalette(STRPTR name, APTR address);
  449.                        a0           a1
  450.    FUNCTION
  451.  
  452.    If name is supplied, the palette is loaded into the address
  453.    pointed to by a1. This is assumed to have at least 768 bytes of free
  454.    memory to store the palette.
  455.   
  456.    If a name is not supplied, an ASL file requester is displayed allowing
  457.    the user to load any IFF palette (or a palette from an IFF-ILBM file).
  458.    The default path is photogenics:data/colourmaps which contains
  459.    several pre-designed palettes.
  460.  
  461.    INPUTS
  462.  
  463.    name    - Name of the palette to load (or NULL)
  464.    address - Address to load the palette to.
  465.  
  466.    RESULT
  467.  
  468.    Up to 768 bytes of RGB palette data are loaded. Format for
  469.    palette is standard IFF byte per component, NOT OS3.x longword
  470.    per component. It is NOT a standard system ColorMap structure!
  471.  
  472.    SEE ALSO
  473.  
  474.    BUGS
  475.  
  476.    May not be too happy at loading <256 colour palettes. Will probably
  477.    fill up rest of registers with garbage.
  478.  
  479. pgs.library/GetTwoOptions
  480.  
  481.    NAME
  482.    GetTwoOptions -- Display a requester with two switchable options
  483.  
  484.    SYNOPSIS
  485.    GetTwoOptions(STRPTR wintitle,STRPTR gadgettext, STRPTR gadgetseltext,
  486.                      a0                a1                   a2
  487.  
  488.                  UBYTE *variable, STRPTR gadgettext2, STRPTR gadgetseltext2,
  489.                      a3                a5                   d0
  490.  
  491.                  UBYTE *variable2);
  492.                      d1           
  493.    FUNCTION
  494.  
  495.    Displys a requester with two switchable options. The gadgets toggle
  496.    between text displaying the first and second (gadgettext & gadgetseltext)
  497.    strings.
  498.  
  499.  
  500.    INPUTS
  501.  
  502.    wintitle       - Window title text
  503.    gadgettext     - Text for first gadget ('OFF' position)
  504.    gadgetseltext  - Text for first gadget ('ON' position)
  505.    variable       - Variable to store toggle status of first gadget.
  506.    gadgettext2    - Text for second gadget ('OFF' position)
  507.    gadgetseltext2 - Text for second gadget ('ON' position)
  508.    variable2      - Variable to store toggle status of second gadget.
  509.    
  510.    
  511.    RESULT
  512.  
  513.       0           CANCEL selected
  514.       1           OK selected
  515.       2           Requester failed to open.
  516.  
  517.    If OK is selected, variable and variable2 are updated to the boolean
  518.    result of each gadget (0 = gadgettext, 1 = gadgetseltext).
  519.  
  520.    SEE ALSO
  521.    GetOneOption
  522.  
  523.    BUGS
  524. pgs.library/GetLine
  525.  
  526.    NAME
  527.    GetLine -- Get a pointer to a line of 24-bit RGB data
  528.  
  529.    SYNOPSIS
  530.    GetLine(struct GIOData *data, ULONG line);
  531.                      a0                d0
  532.  
  533.    FUNCTION
  534.  
  535.    Returns the start address of line y of image data. Any access
  536.    to this data (either for read or write) MUST be inside a 
  537.    GetLine/ReleaseLine pair. Do *NOT* cache results of this
  538.    function and under NO circumstances try and calculate the
  539.    position of one line based on any other information.
  540.  
  541.    With future virtual memory support, this function could cause 
  542.    the line of data to be loaded from disk.
  543.  
  544.    INPUTS
  545.  
  546.    giodata - Pointer to the GIOData structure.
  547.    line    - Line number of image data.
  548.    
  549.    
  550.    RESULT
  551.  
  552.    Locks the line for your exclusive use and returns the address.
  553.  
  554.    SEE ALSO
  555.    ReleaseLine
  556.  
  557.    BUGS
  558.    Must *NOT* be used except inside GioRead() and GioWrite() functions.
  559.    Elsewhere, where the GioData does not have an associated 24-bit
  560.    buffer it WILL crash!
  561. pgs.library/ReleaseLine
  562.  
  563.    NAME
  564.    ReleaseLine -- Release a pointer to a line of 24-bit RGB data
  565.  
  566.    SYNOPSIS
  567.    ReleaseLine(struct GIOData *data, ULONG line);
  568.                       a0                d0
  569.  
  570.    FUNCTION
  571.  
  572.    Returns the start address of line y of image data. Any access
  573.    to this data (either for read or write) MUST be inside a 
  574.    GetLine/ReleaseLine pair. Do *NOT* cache results of this
  575.    function and under NO circumstances try and calculate the
  576.    position of one line based on any other information.
  577.  
  578.    With future virtual memory support, this function could cause 
  579.    the line of data to be loaded from disk.
  580.  
  581.    INPUTS
  582.  
  583.    giodata - Pointer to the GIOData structure.
  584.    line    - Line number of image data.
  585.    
  586.    
  587.    RESULT
  588.  
  589.    Locks the line for your exclusive use and returns the address.
  590.  
  591.    SEE ALSO
  592.    GetLine
  593.  
  594.    BUGS
  595.    Must *NOT* be used except inside GioRead() and GioWrite() functions.
  596.    Elsewhere, where the GioData does not have an associated 24-bit
  597.    buffer it WILL crash!
  598. pgs.library/GetThreeValues
  599.  
  600.    NAME
  601.    GetThreeValues -- Display a requester allowing user to select three values.
  602.  
  603.    SYNOPSIS
  604.    GetTwoValues(STRPTR wintitle, STRPTR gadgettext, LONG min, LONG max,
  605.                          a0                a1          d0       d1    
  606.  
  607.                 LONG *variable, STRPTR gadgettext2, LONG min2, LONG max2, 
  608.                         a2           a3               d2        d3
  609.                
  610.                 LONG *variable2, STRPTR gadgettext3, LONG min3, LONG max3,
  611.                         a5           d4               d5          d6
  612.    
  613.                 LONG *variable3);
  614.                         d7
  615.    FUNCTION
  616.  
  617.    Displays the requester and waits until OK or CANCEL have been selected.
  618.  
  619.    INPUTS
  620.    wintitle   - The title of the requester window.
  621.    gadgettext - The text to display above the first slider.
  622.    min        - The minimum value for the first slider (signed integer value)
  623.    max        - The maximum value for the first slider (signed integer value)
  624.    *variable  - A pointer to a signed integer for the result. This value
  625.                 is read to initialise the first slider to the start value.
  626.    gadgettext2- The text to display above the second slider.
  627.    min2       - The minimum value for the second slider (signed integer value)
  628.    max2       - The maximum value for the second slider (signed integer value)
  629.    *variable2 - A pointer to a signed integer for the result. This value
  630.                 is read to initialise the second slider to the start value.
  631.    gadgettext3- The text to display above the third slider.
  632.    min3       - The minimum value for the third slider (signed integer value)
  633.    max3       - The maximum value for the third slider (signed integer value)
  634.    *variable3 - A pointer to a signed integer for the result. This value
  635.                 is read to initialise the third slider to the start value.
  636.  
  637.    RESULT
  638.    The 32-bit signed integers pointed to by variable (a2), variable2 (a5)
  639.    and variable3 (d7) are updated if OK was selected.
  640.  
  641.    The return value indicates success or failure with one of the following 
  642.    values:
  643.  
  644.       0           CANCEL selected
  645.       1           OK selected
  646.       2           Requester failed to open.
  647.  
  648.    SEE ALSO
  649.  
  650.    BUGS
  651.    If any slider minimum and maximum are the same value it may well 
  652.    crash currently.
  653. pgs.library/GetScaleDimensions
  654.  
  655.    NAME
  656.    GetScaleDimensions -- Display a requester to select a new image size
  657.  
  658.    SYNOPSIS
  659.    GetScaleDimensions(STRPTR wintitle, ULONG *xsize, ULONG *ysize);
  660.                               a0            a1            a2    
  661.  
  662.    FUNCTION
  663.  
  664.    Displays the requester and waits until OK or CANCEL have been selected.
  665.  
  666.    This differs slightly from the standard GetDimensions requester. 
  667.    It allows you to select an image based on the original size (eg. 50%,
  668.    200%, 400%) and to lock the aspect when using the sliders. This was
  669.    designed for the Scale option in Photogenics, although there is no reason
  670.    it should not be used elsewhere.
  671.  
  672.    INPUTS
  673.    wintitle   - The title of the requester window.
  674.    *xsize     - A pointer to the unsigned 32-bit variable containing
  675.                 the x size.
  676.    *ysize     - A pointer to the unsigned 32-bit variable containing
  677.                 the y size.
  678.  
  679.    RESULT
  680.    The 32-bit signed integers pointed to by xsize (a1) and ysize (a2)
  681.    are updated if OK was selected.
  682.  
  683.    The return value indicates success or failure with one of the following 
  684.    values:
  685.  
  686.       0           CANCEL selected
  687.       1           OK selected
  688.       2           Requester failed to open.
  689.  
  690.    SEE ALSO
  691.    GetDimensions()
  692.  
  693.    BUGS
  694. pgs.library/GetListOption
  695.  
  696.    NAME
  697.    GetListOption -- Display a requester with a cycle gadget
  698.  
  699.    SYNOPSIS
  700.    GetListOption(STRPTR wintitle, STRPTR gadgettext
  701.                            a0              a1          
  702.       
  703.                  struct TagList *taglist, ULONG *variable);
  704.                            a2              a3    
  705.  
  706.    FUNCTION
  707.  
  708.    Displays the requester and waits until OK or CANCEL have been selected.
  709.  
  710.    If OK was selected the numeric value for the chosen option on the cycle 
  711.    gadget is put into variable (a3).
  712.  
  713.    NOTE: Future versions of this function may well automatically use
  714.    a listview type selector where the number of options on the cyclic
  715.    gadget is greater than a specific number, or if a new tag (yet to
  716.    be defined) is used.
  717.  
  718.    INPUTS
  719.    wintitle   - The title of the requester window.
  720.    gadgettext - The title text for the gadget.
  721.    taglist    - A taglist defining the options for the cyclic gadget.
  722.    variable   - The variable to update if OK is selected.
  723.  
  724.    Possible tags are:
  725.  
  726.       PGTAG_LISTMIN (0x81910050)
  727.          Usually you'd set this to zero, the first numbered tag.
  728.  
  729.       PGTAG_LISTMAX (0x81910060)
  730.          Set this to the maximum tag number (usually number of tags - 1)
  731.  
  732.       PGTAG_ENTRY (0x81900a0)
  733.          Each entry is started with this tag.
  734.    
  735.       PGTAG_ENTRYID (0x81900b0)
  736.          Each entry has an ID specified with this tag.
  737.  
  738.       PGTAG_ENTRYTEXT 0x81900c0
  739.          The text is selected with this tag.
  740.  
  741.       PGTAG_ENTRYEND 0x81900e0
  742.          Each entry has to end with this tag.
  743.  
  744.       PGTAG_END 0x8191ffff
  745.          The whole tag list must be finished off with this (followed by
  746.          the normal 0,0 tag end.)
  747.  
  748.       An example taglist (a fragment from the backdrop loader):
  749.  
  750. {
  751.    PGTAG_LISTMIN,       0,
  752.    PGTAG_LISTMAX,       3,
  753.  
  754.    PGTAG_ENTRY,         0,
  755.    PGTAG_ENTRYID,       0,
  756.    PGTAG_ENTRYTEXT,     (ULONG) "Left to Right",
  757.    PGTAG_ENTRYEND,      0,
  758.  
  759.    PGTAG_ENTRY,         0,
  760.    PGTAG_ENTRYID,       1,
  761.    PGTAG_ENTRYTEXT,     (ULONG) "Right to Left",
  762.    PGTAG_ENTRYEND,      0,
  763.  
  764.    PGTAG_ENTRY,         0,
  765.    PGTAG_ENTRYID,       2,
  766.    PGTAG_ENTRYTEXT,     (ULONG) "Top to Bottom",
  767.    PGTAG_ENTRYEND,      0,
  768.  
  769.    PGTAG_ENTRY,         0,
  770.    PGTAG_ENTRYID,       3,
  771.    PGTAG_ENTRYTEXT,     (ULONG) "Bottom to Top",
  772.    PGTAG_ENTRYEND,      0,
  773.  
  774.    PGTAG_END,           0,
  775.    TAG_END
  776.    };
  777.    
  778.    RESULT
  779.    *variable is updated if OK was selected.
  780.  
  781.    The return value indicates success or failure with one of the following 
  782.    values:
  783.  
  784.       0           CANCEL selected
  785.       1           OK selected
  786.       2           Requester failed to open.
  787.  
  788.    SEE ALSO
  789.  
  790.    BUGS
  791.    The gadget imagery is not ideal at the moment. This will be improved
  792.    shortly. The hitbox for backwards movement is limited to a small area
  793.    immediately over the <- symbol. 
  794. pgs.library/GetOneOption
  795.    NAME
  796.    GetOneOption -- Display a requester with a switchable option
  797.  
  798.    SYNOPSIS
  799.    GetOneOption(STRPTR wintitle,STRPTR gadgettext, STRPTR gadgetseltext,
  800.                      a0                a1                   a2
  801.  
  802.                  UBYTE *variable);
  803.                      a3           
  804.    FUNCTION
  805.  
  806.    Displys a requester with a switchable option. The gadget toggles
  807.    between text displaying the first and second (gadgettext & gadgetseltext)
  808.    strings.
  809.  
  810.  
  811.    INPUTS
  812.  
  813.    wintitle       - Window title text
  814.    gadgettext     - Text for first gadget ('OFF' position)
  815.    gadgetseltext  - Text for first gadget ('ON' position)
  816.    variable       - Variable to store toggle status of first gadget.
  817.    
  818.    RESULT
  819.  
  820.       0           CANCEL selected
  821.       1           OK selected
  822.       2           Requester failed to open.
  823.  
  824.    If OK is selected, variable is updated to the boolean result of the
  825.    gadget (0 = gadgettext, 1 = gadgetseltext).
  826.  
  827.    SEE ALSO
  828.    GetTwoOptions
  829.  
  830.    BUGS
  831. pgs.library/InitRandom [V1.2]
  832.  
  833.    NAME
  834.    InitRandom - Initialises the Random number generator.
  835.  
  836.    SYNOPSIS
  837.    InitRandom(ULONG seed);
  838.                
  839.  
  840.    FUNCTION
  841.    Initialises the random number generators used in Photogenics. The
  842.    current time is used if the supplied seed is zero.
  843.  
  844.    INPUTS
  845.    seed  - Default seed (or zero)
  846.  
  847.    RESULT
  848.    None
  849.  
  850.    SEE ALSO
  851.    Random()
  852.  
  853.    BUGS
  854. pgs.library/Random [V1.2]
  855.  
  856.    NAME
  857.    Random - Returns a random number between 0 and very very large.
  858.  
  859.    SYNOPSIS
  860.    number = Random(type);
  861.     d0              d0
  862.  
  863.    FUNCTION
  864.    Returns a random number.
  865.    There are two types of random number routine. If type == 0
  866.    a slow but good random number routine is used. If type == 1 a
  867.    faster but less random routine is used. 
  868.  
  869.    INPUTS
  870.    type   - Type of random number routine.
  871.  
  872.    RESULT
  873.    number = Random number (between 0 and 0x7fffffff)
  874.  
  875.    SEE ALSO
  876.    InitRandom()
  877.  
  878.    BUGS
  879. pgs.library/GetEnvVal [V1.2]
  880.  
  881.    NAME
  882.    GetEnvVal -- Simple Environment variable loading.
  883.  
  884.    SYNOPSIS
  885.    GetEnvVal(STRPTR varname, APTR val, ULONG size);
  886.                 a0              a1         d0
  887.        
  888.    FUNCTION
  889.    Reads the environment variable from env:photogenics/<varname>.
  890.    Reads size bytes to address val. 
  891.  
  892.    INPUTS
  893.    varname - ASCII name of environment variable.
  894.    val     - Address to store value.
  895.    size    - Size of data to load.
  896.  
  897.    RESULT
  898.    Data is loaded into address val.
  899.  
  900.    SEE ALSO
  901.    SetEnvVal
  902.  
  903.    BUGS
  904. pgs.library/SetEnvVal [V1.2]
  905.  
  906.    NAME
  907.    SetEnvVal -- Simple Environment variable saving.
  908.  
  909.    SYNOPSIS
  910.    SetEnvVal(STRPTR varname, APTR val, ULONG size);
  911.                  a0              a1         d0
  912.        
  913.    FUNCTION
  914.    Writes the environment variable to envarc:photogenics/<varname>.
  915.    Writes size bytes from address val. 
  916.  
  917.    INPUTS
  918.    varname - ASCII name of environment variable.
  919.    val     - Address to read from.
  920.    size    - Size of data to save.
  921.  
  922.    RESULT
  923.    Data is written to envarc: and env:.
  924.  
  925.    SEE ALSO
  926.    GetEnvVal
  927.  
  928.    BUGS
  929. pgs.library/GetListAndVal [V1.2]
  930.  
  931.    NAME
  932.    GetListAndVal -- Display a requester with one cycle and one slider gadget
  933.  
  934.    SYNOPSIS
  935.    GetListAndVal(STRPTR wintitle, STRPTR gadgettext, 
  936.                         a0                a1
  937.  
  938.                  struct TagList *taglist, LONG *variable, 
  939.                         a2                   a3
  940.                  
  941.                   LONG min, LONG max, STRPTR gadgettext2 LONG *variable2);
  942.                       d0       d1            d2                a5
  943.  
  944.    FUNCTION
  945.  
  946.    Displays the requester and waits until OK or CANCEL have been selected.
  947.  
  948.    INPUTS
  949.    wintitle    - The title of the requester window.
  950.    gadgettext  - The title text for the cycle gadget.
  951.    taglist     - Taglist describing cycle (See GetListOption for details)
  952.    *variable   - Pointer to the variable for the result of the cycle gadget.
  953.    min         - The minimum value for the slider (signed integer value)
  954.    max         - The maximum value for the slider (signed integer value)
  955.    gadgettext2 - The title text for the slider gadget.
  956.    *variable2  - A pointer to a signed integer for the slider result. This 
  957.                  value is read to initialise the slider to the start value.
  958.  
  959.    RESULT
  960.    Both variable and variable2 are updated if OK was selected.
  961.  
  962.    The return value indicates success or failure with one of the following 
  963.    values:
  964.  
  965.       0           CANCEL selected
  966.       1           OK selected
  967.       2           Requester failed to open.
  968.  
  969.    SEE ALSO
  970.  
  971.    BUGS
  972.    If minimum and maximum are the same value it does not bring up the
  973.    requester at all and returns immediately.
  974.  
  975.