home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / FileMover / HF-OM1.DMS / in.adf / OpusSDK.lha / SDK / docs / requesters.doc < prev    next >
Encoding:
Text File  |  1996-09-01  |  9.3 KB  |  252 lines
  1. dopus5.library/AsyncRequest                       dopus5.library/AsyncRequest
  2.  
  3.     NAME
  4.         AsyncRequest - display a requester
  5.  
  6.     SYNOPSIS
  7.         AsyncRequest(ipc, type, window, callback, data, tags)
  8.                       A0   D0     A1       A2      A3    D1
  9.  
  10.         long AsyncRequest(IPCData *, long, struct Window *,
  11.                           REF_CALLBACK, APTR, struct TagItem *);
  12.  
  13.         long AsyncRequestTags(IPCData *, long, struct Window *,
  14.                               REF_CALLBACK, APTR, Tag, ...);
  15.  
  16.     FUNCTION
  17.         Displays requesters of different types. The name of this function
  18.         is slightly misleading, as the routine itself is not asynchronous.
  19.         However, the requester is launched by a separate process, which makes
  20.         it possible for you to provide a callback function that can handle
  21.         refreshing of a window while the requester is displayed. There are
  22.         currently two types of requesters defined:
  23.  
  24.  
  25.         REQTYPE_FILE
  26.  
  27.         This opens an ASL file requester. The FileRequester itself is defined
  28.         by you; this routine simples opens it with a separate process,
  29.         providing asynchronicity. The only value tag for this requester type
  30.         is AR_Requester, with which you specify the address of a file
  31.         requester structure obtained via AllocAslRequest().
  32.  
  33.  
  34.         REQTYPE_SIMPLE
  35.  
  36.         This displays a simple text requester to the user. There are several
  37.         control tags for this requester type which give you great control
  38.         over the appearance of the requester :
  39.  
  40.             AR_Window (struct Window *)
  41.  
  42.             Use this to specify a parent window for the requester. The
  43.             requester will appear centered over this window (overrides
  44.             AR_Screen)
  45.  
  46.             AR_Screen (struct Screen *)
  47.  
  48.             Use this to specify a parent screen for the requester. The
  49.             requester will appear centered in the screen.
  50.  
  51.             AR_Title (char *)
  52.  
  53.             The requester title. This is displayed in the title bar of the
  54.             requester window. If not specified, this value defaults to
  55.             "Directory Opus Request".
  56.  
  57.             AR_Message (char *)
  58.  
  59.             The requester message. This is the text displayed in the main
  60.             body of the requester. Use a \n character to represent a linefeed.
  61.  
  62.             AR_Button (char *)
  63.  
  64.             This tag allows you to define a button for the requester. You
  65.             can use this tag multiple times.
  66.  
  67.             AR_ButtonCode (long)
  68.  
  69.             Specifies the ID code for the previous AR_Button tag. By default,
  70.             buttons are numbered 1, 2, 3, ... in the order they appear in the
  71.             tag list. This tag allows you to change the ID codes, and
  72.             therefore the result code from the AsyncRequest() function.
  73.  
  74.             AR_Buffer (char *)
  75.  
  76.             If you want a string gadget to be displayed in the requester,
  77.             specify this tag with a pointer to a string buffer.
  78.  
  79.             AR_BufLen (long)
  80.  
  81.             If a buffer was specified with AR_Buffer, you must also supply
  82.             this tag to set the size of the buffer.
  83.  
  84.             AR_History (Att_List *)
  85.  
  86.             Points to an Att_List which contains the history list for this
  87.             gadget. If supplied, the user will be able to press the cursor
  88.             up and down keys to access the history. See the docs on
  89.             GetEditHook() for more information.
  90.  
  91.             AR_CheckMark (char *)
  92.  
  93.             If you want a check mark gadget to appear in the requester,
  94.             specify this as a pointer to the text for the gadget.
  95.  
  96.             AR_CheckPtr (short *)
  97.  
  98.             If you specify the AR_CheckMark tag, you must also supply this
  99.             tag. ti_Data is a pointer to a short variable which will receive
  100.             the state of the checkmark gadget when the requester is closed.
  101.  
  102.             AR_Flags (ULONG)
  103.  
  104.             Control flags.
  105.  
  106.         The control flags for the AR_Flags tag are :
  107.  
  108.             SRF_LONGINT     - the string gadget is an integer field
  109.             SRF_CENTJUST    - center-justify the string gadget
  110.             SRF_RIGHTJUST   - right-justify the string gadget
  111.             SRF_PATH_FILTER - filter path characters from string field
  112.             SRF_SECURE      - set for secure password field
  113.             SRF_HISTORY     - set if supplying the AR_History tag
  114.             SRF_CHECKMARK   - set if supplying the AR_CheckMark tag
  115.             SRF_MOUSE_POS   - center requester over mouse pointer
  116.  
  117.  
  118.         The callback function is a function that you define to handle the
  119.         situation when the parent window needs to be refreshed. If the parent
  120.         window is simplerefresh, you should provide this function. The function
  121.         has the following prototype:
  122.  
  123.             void __asm refresh_callback(    register __d0 ULONG type,
  124.                                             register __a0 struct Window *window,
  125.                                             register __a1 ULONG data )
  126.  
  127.         The routine will be called whenever the parent window needs to be
  128.         refreshed. 'type' is the IDCMP message type; usually
  129.         IDCMP_REFRESHWINDOW. 'window' is a pointer to the parent window, and
  130.         'data' is the data value passed to the AsyncRequest() function.
  131.  
  132.     INPUTS
  133.         ipc      - your process' IPCData pointer
  134.         type     - type of requester to display
  135.         window   - parent window for requester
  136.         callback - your callback function
  137.         data     - data that is passed to the callback
  138.         tags     - control tags
  139.  
  140.     RESULT
  141.         Returns the result from the requester. Returns 0 if the requester
  142.         could not be displayed.
  143.  
  144.     NOTES
  145.         For a REQTYPE_SIMPLE requester, the default gadget IDs are (from
  146.         left to right), 1, 2, 3 ... 0. The right-most gadget is defined as
  147.         0 to act as a "cancel" gadget. Therefore, in a simple "Ok", "Cancel"
  148.         requester, "Ok" returns 1 (or TRUE) and "Cancel" returns 0 (or FALSE).
  149.  
  150.     SEE ALSO
  151.         asl.library/AllocAslRequest(), GetEditHook()
  152.  
  153. dopus5.library/OpenStatusWindow               dopus5.library/OpenStatusWindow
  154.  
  155.     NAME
  156.         OpenStatusWindow - open a status window
  157.  
  158.     SYNOPSIS
  159.         OpenStatusWindow(title, text, screen, flags, unused)
  160.                            A0    A1      A2     D0     D1
  161.  
  162.         struct Window *OpenStatusWindow(char *, char *, struct Screen *, 
  163.                                         ULONG, long);
  164.  
  165.     FUNCTION
  166.         A status window is kind of like a "dumb" progress window; it has
  167.         the ability to display a single line of text.
  168.  
  169.     INPUTS
  170.         title  - status window title
  171.         text   - initial text to display
  172.         screen - screen to open on
  173.         flags  - set to 0
  174.         unused - set to 0
  175.  
  176.     RESULT
  177.         Returns a pointer to the new window. To close the status window,
  178.         call CloseConfigWindow() on it.
  179.  
  180.     SEE ALSO
  181.         SetStatusText(), CloseConfigWindow()
  182.  
  183. dopus5.library/SelectionList                     dopus5.library/SelectionList
  184.  
  185.     NAME
  186.         SelectionList - display a list in a requester
  187.  
  188.     SYNOPSIS
  189.         SelectionList(  list, window, screen,
  190.                         title, initialsel, flags,
  191.                         buffer, okay_txt, cancel_txt )
  192.  
  193.         short SelectionList(    Att_List *, struct Window *, struct Screen *,
  194.                                 char *, short, ULONG,
  195.                                 char *, char *, char * );
  196.  
  197.     FUNCTION
  198.         This routine displays a requester containing a listview gadget,
  199.         prompting the user to select an item from the list. The requester
  200.         can optionally have a directory field, which allows the user to open
  201.         an ASL file requester to locate a directory that is not in the list.
  202.  
  203.     INPUTS
  204.         list       - Att_List to display (the name of each node is displayed)
  205.         window     - parent window
  206.         screen     - screen to open on if no window specified
  207.         title      - title of requester
  208.         initialsel - initially selected item, or -1 for no selection
  209.         flags      - control flags. Specify SLF_DIR_FIELD to get a directory
  210.                      field
  211.         buffer     - If SLF_DIR_FIELD is specified, this must point to a
  212.                      buffer (256 bytes or greater) to contain the path name
  213.                      chosen by the user
  214.         okay_txt   - text for the "Ok" gadget
  215.         cancel_txt - text for the "Cancel" gadget
  216.  
  217.     RESULT
  218.         Returns the number of the selected item in the list, or -1 if the
  219.         user made no selection. If a directory field was specified with
  220.         SLF_DIR_FIELD, and -1 is returned, you should check the supplied
  221.         buffer to see if it is empty. If not, the user selected a path
  222.         manually.
  223.  
  224.     SEE ALSO
  225.         Att_NewList()
  226.  
  227. dopus5.library/SetStatusText                     dopus5.library/SetStatusText
  228.  
  229.     NAME
  230.         SetStatusText - change text in a status window
  231.  
  232.     SYNOPSIS
  233.         SetStatusText(window, text)
  234.                         A0     A1
  235.  
  236.         void SetStatusText(struct Window *, char *);
  237.  
  238.     FUNCTION
  239.         Changes the text displayed in the supplied status window.
  240.  
  241.     INPUTS
  242.         window - status window
  243.         text   - new text to display
  244.  
  245.     RESULT
  246.         The text is displayed immediately. Do NOT call this function on a
  247.         window other than one returned by the OpenStatusWindow() call.
  248.  
  249.     SEE ALSO
  250.         OpenStatusWindow()
  251.  
  252.