workbench/libs/reqtools/rtfilerequesta.c

   1 /*
   2     Copyright © 1995-2001, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     Desc:
   6     Lang: English
   7 */
   8
   9 #include <exec/types.h>
  10 #include <proto/exec.h>
  11 #include <proto/reqtools.h>
  12 #include <proto/intuition.h>
  13 #include <exec/libraries.h>
  14 #include <exec/memory.h>
  15 #include <aros/libcall.h>
  16
  17 #include "reqtools_intern.h"
  18
  19 /*****************************************************************************
  20
  21     NAME */
  22
  23     AROS_LH4(APTR, rtFileRequestA,
  24
  25 /*  SYNOPSIS */
  26
  27         AROS_LHA(struct rtFileRequester *, filereq, A1),
  28         AROS_LHA(char *, file, A2),
  29         AROS_LHA(char *, title, A3),
  30         AROS_LHA(struct TagItem *, taglist, A0),
  31
  32 /*  LOCATION */
  33
  34         struct ReqToolsBase *, ReqToolsBase, 9, ReqTools)
  35
  36 /*  FUNCTION
  37         Get a directory and filename(s), or just a directory from the user.
  38
  39         'filename' should point to an array of at least 108 chars. The
  40         filename already in 'filename' will be displayed in the requester
  41         when it comes up. When the requester returns 'filename' will
  42         probably have changed.
  43
  44         Using certain tags may result in the calling of a caller-supplied
  45         hook.
  46
  47         The hook will be called with A0 holding the address of your hook
  48         structure (you may use the h_Data field to your own liking), A2 a
  49         pointer to the requester structure calling the hook ('req') and A1
  50         a pointer to an object. The object is variable and depends on what
  51         your hook is for.
  52
  53         This is an example of a hook suitable to be used with the
  54         RTFI_FilterFunc tag:
  55
  56         SAS/C users can define their function thus:
  57
  58         BOOL __asm __saveds filterfunc(
  59                 register __a0 struct Hook *filterhook,
  60                 register __a2 struct rtFileRequester *req,
  61                 register __a1 struct FileInfoBlock *fib )
  62         {
  63             BOOL accepted = TRUE;
  64
  65             // examine fib to decide if you want this file in the requester
  66             ...
  67             return( accepted );
  68         }
  69
  70         Your hook structure should then be initialized like this:
  71
  72             filterhook->h_Entry = filterfunc;
  73             // in this case no need to initialize hook->h_SubEntry
  74             filterhook->h_Data = your_userdata_if_needed;
  75
  76         You can also use a stub written in machine code to call your
  77         function. (see 'utility/hooks.h')
  78
  79     INPUTS
  80         filereq  - pointer to a struct rtFileRequester allocated with
  81             rtAllocRequestA().
  82         filename - pointer to an array of chars (must be 108 bytes big).
  83         title    - pointer to requester window title (null terminated).
  84         taglist  - pointer to a TagItem array.
  85
  86     TAGS
  87         RT_Window - see rtEZRequestA()
  88
  89         RT_ReqPos - see rtEZRequestA()
  90
  91         RT_LeftOffset - see rtEZRequestA()
  92
  93         RT_TopOffset - see rtEZRequestA()
  94
  95         RT_PubScrName - see rtEZRequestA()
  96
  97         RT_Screen - see rtEZRequestA()
  98
  99         RT_ReqHandler - see rtEZRequestA()
 100
 101         RT_WaitPointer - see rtEZRequestA()
 102
 103         RT_LockWindow - [V38] see rtEZRequestA()
 104
 105         RT_ScreenToFront - [V38] see rtEZRequestA()
 106
 107         RT_ShareIDCMP - [V38] see rtEZRequestA()
 108
 109         RT_Locale - [V38] see rtEZRequestA()
 110
 111         RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call
 112             this hook for each IDCMP message it gets that doesn't belong to
 113             its window. Only applies if you used the RT_ShareIDCMP tag to
 114             share the IDCMP port with the parent window. Parameters are as
 115             follows:
 116
 117                 A0 - (struct Hook *) your hook
 118                 A2 - (struct rtFileRequester *) your requester
 119                 A1 - (struct IntuiMessage *) the message
 120
 121             After you have finished examining the message and your hook
 122             returns, ReqTools will reply the message. So do not reply the
 123             message yourself!
 124
 125         RT_Underscore - (char) [V38] Indicates the symbol that precedes the
 126             character in a gadget's label to be underscored. This will also
 127             define the keyboard shortcut for this gadget. Currently only
 128             needed for RTFI_OkText. Usually set to '_'.
 129
 130         RT_DefaultFont - (struct TextFont *) This tag allows you to specify
 131             the font to be used in the requester when the screen font is
 132             proportional. Default is GfxBase->DefaultFont. This tag is
 133             obsolete in ReqTools 2.2 and higher.
 134
 135         RT_TextAttr - (struct TextAttr *) [V38] Use this font for the
 136             requester. Default is to use the screen font. Note that the
 137             font must already be opened by you. ReqTools will call
 138             OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font
 139             cannot be opened using OpenFont() or if the font is
 140             proportional the default screen font will be used (or the font
 141             set with RT_DefaultFont).
 142
 143         RTFI_Flags - (ULONG) Several flags:
 144
 145             FREQF_NOBUFFER - do _not_ use a buffer to remember directory
 146                 contents for the next time the file requester is used.
 147
 148             FREQF_MULTISELECT - allow multiple files to be selected.
 149                 rtFileRequest() will return a pointer to an rtFileList
 150                 structure which will contain all selected files. Use
 151                 rtFreeFileList() to free the memory used by this file list.
 152
 153             FREQF_SELECTDIRS - set this flag if you wish to enable the
 154                 selecting of dirs as well as files. You *must* also set
 155                 FREQF_MULTISELECT. Directories will be returned together
 156                 with files in rtFileList, but with StrLen equal to -1. If
 157                 you need the length of the directory's name use strlen().
 158
 159             FREQF_SAVE - Set this if you are using the requester to save or
 160                 delete something. Double-clicking will be disabled so it is
 161                 harder to make a mistake and select the wrong file. If the
 162                 user enters a non-existent directory in the drawer string
 163                 gadget, a requester will appear asking if the directory
 164                 should be created.
 165
 166             FREQF_NOFILES - Set this if you want to use the requester to
 167                 allow the user to select a directory rather than a file.
 168                 Ideal for getting a destination dir. May be used with
 169                 FREQF_MULTISELECT and FREQF_SELECTDIRS.
 170
 171             FREQF_PATGAD - When this is set a pattern gadget will be added
 172                 to the requester.
 173
 174         RTFI_Height - (ULONG) Suggested height of file requester window.
 175
 176         RTFI_OkText - (char *) Replacement text for "Ok" gadget, max 6
 177             chars long.
 178
 179         RTFI_VolumeRequest - (ULONG) [V38] The presence of this tag turns
 180             the file requester into a volume/assign disk requester. This
 181             requester can be used to get a device name ("DF0:", "DH1:",..)
 182             or an assign ("C:", "FONTS:",...) from the user. The result of
 183             this requester can be found in the filereq->Dir field. The
 184             volume can also be changed with rtChangeReqAttrA() and the
 185             RTFI_Dir tag.
 186
 187             Note that the user may edit the disk/assign, or enter a new
 188             one. Note also that the real device name is returned, not the
 189             name of the volume in the device. For example "DH1:", not
 190             "Hard1:". The tag data (ULONG) is used to set following flags:
 191
 192             VREQF_NOASSIGNS - Do not include the assigns in the list, only
 193                 the real devices.
 194
 195             VREQF_NODISKS - Do not include devices, just show the assigns.
 196
 197             VREQF_ALLDISKS - Show _all_ devices. Default behavior is to
 198                 show only those devices which have valid disks inserted
 199                 into them. So if you have no disk in drive DF0: it will not
 200                 show up. Set this flag if you do want these devices
 201                 included.
 202
 203             NOTE: Do *NOT* use { RTFI_VolumeRequest, TRUE }! You are then
 204                 setting the VREQF_NOASSIGNS flag! Use { RTFI_VolumeRequest,
 205                 0 } for a normal volume requester.
 206
 207             NOTE: If you use the RTFI_FilterFunc described below the third
 208                 parameter will be a pointer to a rtVolumeEntry structure
 209                 rather than a pointer to a FileInfoBlock structure! Tech
 210                 note: the DOS device list has been unlocked, so it is safe
 211                 to e.g. Lock() this device and call Info() on this lock.
 212
 213             NOTE: A file requester structure allocated with
 214                 rtAllocRequest() should not be used for both a file and a
 215                 volume requester. Allocate two requester structures if you
 216                 need both a file and a volume requester in your program!
 217
 218         RTFI_FilterFunc - (struct Hook *) [V38] Call this hook for each
 219             file and directory in the directory being read (or for each
 220             entry in the volume requester). Parameters are as follows:
 221
 222             A0 - (struct Hook *) your hook
 223             A2 - (struct rtFileRequester *) your filereq
 224             A1 - (struct FileInfoBlock *) fib of file OR (struct
 225                 rtVolumeEntry *) device or assign in case of a volume
 226                 requester.
 227
 228             If your hook returns TRUE the file will be accepted. If it
 229             returns FALSE the file will be skipped and will not appear in
 230             the requester.
 231
 232             IMPORTANT NOTE: If you change your hook's behavior you _MUST_
 233                 purge the requester's buffer (using rtFreeReqBuffer())!
 234
 235             IMPORTANT NOTE: When this callback hook is called from a volume
 236                 requester the pr_WindowPtr of your process will be set to
 237                 -1 so *no* DOS requesters will appear when an error occurs!
 238
 239         RTFI_AllowEmpty - (BOOL) [V38] If RTFI_AllowEmpty is TRUE an empty
 240             file string will also be accepted and returned. Defaults to
 241             FALSE, meaning that if the user enters no filename the
 242             requester will be canceled. You should use this tag as little
 243             as possible!
 244
 245     RESULT
 246         ret - TRUE if the user selected a file (check 'filereq->Dir' for
 247             the directory and 'filename' for the filename) or FALSE if the
 248             requester was canceled -- or a pointer to a struct rtFileList
 249             (if FREQF_MULTISELECT was used).
 250
 251     NOTES
 252         You CANNOT call the file requester from a task because it uses DOS
 253         calls!
 254
 255         Automatically adjusts the requester to the screen font.
 256
 257         If the requester got too big for the screen because of a very large
 258         font, the topaz.font will be used.
 259
 260         rtFileRequest() checks the pr_WindowPtr of your process to find the
 261         screen to put the requester on.
 262
 263     EXAMPLE
 264
 265     BUGS
 266         none known
 267
 268     SEE ALSO
 269
 270     INTERNALS
 271
 272     HISTORY
 273
 274 ******************************************************************************/
 275 {
 276     AROS_LIBFUNC_INIT
 277
 278     return FileRequestA((struct RealFileRequester *)filereq, file, title, taglist); /* in filereq.c */
 279
 280     AROS_LIBFUNC_EXIT
 281
 282 } /* rtFileRequestA */