home *** CD-ROM | disk | FTP | other *** search
/ DOpus Plus / DOpus Plus.iso / SDK / docs / requesters.doc < prev    next >
Encoding:
Text File  |  1998-10-26  |  9.6 KB  |  258 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.             AR_Requester (struct FileRequester *)
  118.  
  119.             If you pass a filerequester structure with this tag, AND you
  120.             have a string gadget displayed (by passing the AR_Buffer),
  121.             the string gadget will be given a popup 'file' button which,
  122.             when clicked, will invoke this filerequester.
  123.  
  124.         The callback function is a function that you define to handle the
  125.         situation when the parent window needs to be refreshed. If the parent
  126.         window is simplerefresh, you should provide this function. The function
  127.         has the following prototype:
  128.  
  129.             void __asm refresh_callback(    register __d0 ULONG type,
  130.                                             register __a0 struct Window *window,
  131.                                             register __a1 ULONG data )
  132.  
  133.         The routine will be called whenever the parent window needs to be
  134.         refreshed. 'type' is the IDCMP message type; usually
  135.         IDCMP_REFRESHWINDOW. 'window' is a pointer to the parent window, and
  136.         'data' is the data value passed to the AsyncRequest() function.
  137.  
  138.     INPUTS
  139.         ipc      - your process' IPCData pointer
  140.         type     - type of requester to display
  141.         window   - parent window for requester
  142.         callback - your callback function
  143.         data     - data that is passed to the callback
  144.         tags     - control tags
  145.  
  146.     RESULT
  147.         Returns the result from the requester. Returns 0 if the requester
  148.         could not be displayed.
  149.  
  150.     NOTES
  151.         For a REQTYPE_SIMPLE requester, the default gadget IDs are (from
  152.         left to right), 1, 2, 3 ... 0. The right-most gadget is defined as
  153.         0 to act as a "cancel" gadget. Therefore, in a simple "Ok", "Cancel"
  154.         requester, "Ok" returns 1 (or TRUE) and "Cancel" returns 0 (or FALSE).
  155.  
  156.     SEE ALSO
  157.         asl.library/AllocAslRequest(), GetEditHook()
  158.  
  159. dopus5.library/OpenStatusWindow               dopus5.library/OpenStatusWindow
  160.  
  161.     NAME
  162.         OpenStatusWindow - open a status window
  163.  
  164.     SYNOPSIS
  165.         OpenStatusWindow(title, text, screen, flags, unused)
  166.                            A0    A1      A2     D0     D1
  167.  
  168.         struct Window *OpenStatusWindow(char *, char *, struct Screen *, 
  169.                                         ULONG, long);
  170.  
  171.     FUNCTION
  172.         A status window is kind of like a "dumb" progress window; it has
  173.         the ability to display a single line of text.
  174.  
  175.     INPUTS
  176.         title  - status window title
  177.         text   - initial text to display
  178.         screen - screen to open on
  179.         flags  - set to 0
  180.         unused - set to 0
  181.  
  182.     RESULT
  183.         Returns a pointer to the new window. To close the status window,
  184.         call CloseConfigWindow() on it.
  185.  
  186.     SEE ALSO
  187.         SetStatusText(), CloseConfigWindow()
  188.  
  189. dopus5.library/SelectionList                     dopus5.library/SelectionList
  190.  
  191.     NAME
  192.         SelectionList - display a list in a requester
  193.  
  194.     SYNOPSIS
  195.         SelectionList(  list, window, screen,
  196.                         title, initialsel, flags,
  197.                         buffer, okay_txt, cancel_txt )
  198.  
  199.         short SelectionList(    Att_List *, struct Window *, struct Screen *,
  200.                                 char *, short, ULONG,
  201.                                 char *, char *, char * );
  202.  
  203.     FUNCTION
  204.         This routine displays a requester containing a listview gadget,
  205.         prompting the user to select an item from the list. The requester
  206.         can optionally have a directory field, which allows the user to open
  207.         an ASL file requester to locate a directory that is not in the list.
  208.  
  209.     INPUTS
  210.         list       - Att_List to display (the name of each node is displayed)
  211.         window     - parent window
  212.         screen     - screen to open on if no window specified
  213.         title      - title of requester
  214.         initialsel - initially selected item, or -1 for no selection
  215.         flags      - control flags. Specify SLF_DIR_FIELD to get a directory
  216.                      field
  217.         buffer     - If SLF_DIR_FIELD is specified, this must point to a
  218.                      buffer (256 bytes or greater) to contain the path name
  219.                      chosen by the user
  220.         okay_txt   - text for the "Ok" gadget
  221.         cancel_txt - text for the "Cancel" gadget
  222.  
  223.     RESULT
  224.         Returns the number of the selected item in the list, or -1 if the
  225.         user made no selection. If a directory field was specified with
  226.         SLF_DIR_FIELD, and -1 is returned, you should check the supplied
  227.         buffer to see if it is empty. If not, the user selected a path
  228.         manually.
  229.  
  230.     SEE ALSO
  231.         Att_NewList()
  232.  
  233. dopus5.library/SetStatusText                     dopus5.library/SetStatusText
  234.  
  235.     NAME
  236.         SetStatusText - change text in a status window
  237.  
  238.     SYNOPSIS
  239.         SetStatusText(window, text)
  240.                         A0     A1
  241.  
  242.         void SetStatusText(struct Window *, char *);
  243.  
  244.     FUNCTION
  245.         Changes the text displayed in the supplied status window.
  246.  
  247.     INPUTS
  248.         window - status window
  249.         text   - new text to display
  250.  
  251.     RESULT
  252.         The text is displayed immediately. Do NOT call this function on a
  253.         window other than one returned by the OpenStatusWindow() call.
  254.  
  255.     SEE ALSO
  256.         OpenStatusWindow()
  257.  
  258.