Amiga ISO Collection

home *** CD-ROM | disk | FTP | other *** search

/ Amiga ISO Collection / AmigaUtilCD2.iso / Programming / Basic / wst!blz1.dms / in.adf / docs / NeilsReqToolsLib.doc < prev next >

Wrap

Text File | 1994-09-05 | 37.9 KB | 835 lines

Library: neilsreqtoolslib #54 Author: Neil O'Rourke, 6 Victoria St, TAMWORTH, NSW 2340, AUSTRALIA Overview: Access to the ReqTools library. Commands: Author's Documentation ReqToolslib V1.70b Neil O'Rourke ** BETA FOUR ** This is an implementation of Nico Franco's ReqTools library. There are two different implementations of each function, a simple one (denoted by EZ (pronounced E-Zee) in the command name), and a complex one. The simple implementation has bog standard requesters that the programmer has little (if any) control over. The purpose of these is to get your programs working fast (or it could be that you don't need all the fancy options that are available), with a minimum of setup for the requesters. That isn't to say the requesters aren't powerful; on the contrary, ReqTools requesters leave ASL requesters in the dust when it comes down to sheer power. The more complex implementation requires you to build a TagList and supply it to the requester. This shouldn't really be needed, as all the EZ requesters have a resonable set of defaults and options to avoid this. All the ReqTools requesters attach themselves to the window that DOS errors are. To do this, simply make your window the current window with Use Window WindowNum, then CatchDosErrs. By default, the requesters will go to the Workbench. Compatibility ~~~~~~~~~~~~~ All ReqTools requesters, with the exception of the ScreenMode request, are compatible with KickStart 1.3. DO NOT CALL RTEZSCREENMODEREQUEST IF YOU ARE RUNNING 1.3!! THIS IS YOUR RESPONSIBILITY! Future Directions ~~~~~~~~~~~~~~~~~ The recent releases of ReqTools have included a preferences program to control the behaviour of requesters. This does not sit well with the pre-programmed options that my interface code uses. It could be that future releases of ReqToolsLib will not set these, but this is early days and only time and user feed-back will indicate the path to go. Simple Functions (EZ) ~~~~~~~~~~~~~~~~~~~~~ result=RTEZRequest(Title$,BodyText$,GadgetText$ [,ReqPosition [, DefaultResponse, Flags]]) --------------------------------------------------------------- Opens a simple requester in the center of your screen. You can have multiple gadgets in Gadget$, seperate the by a bar (|). To have multiple lines in your gadget, seperate them by a Chr$(10). Title$ can be whatever you want. If it is left blank, the title of the calling window will be used. The requester auto-adjusts its size to the length of the body text. Also, the requester will block any input to the calling window, and if the user selects that window he will see the usual wait pointer. The requester returns the number of the gadget selected, gadget zero is the extreme right hand gadget (usually Cancel), and numbered from one starting from the left hand side of the requester. The optional parameter ReqPos allows relative positioning of the requester. You can have the requester open up in the center of the screen (the default position), or the center of the window, or the TopLeft corner of the screen or window. The valid flags are: #REQPOS_POINTER =0 Relative to MousePointer #REQPOS_CENTERWIN =1 Center of window #REQPOS_CENTERSCR =2 Center of screen (default) #REQPOS_TOPLEFTWIN =3 TopLeft of the window #REQPOS_TOPLEFTSCR =4 TopLeft of the screen (Amiga default) There are two further options: DefaultResponse allows you to change what gadget is selected when the Return key is hit, and this is by default the left hand gadget (1) Flags controls a few other items in the requester. #EZREQB_NORETURNKEY =1 Turns off the return key as positive response #EZREQB_LAMIGAQUAL =2 Keyboard shortcuts are limited to LA-V and LA-B #EZREQB_CENTERTEXT =4 Centers the text in the requester. You can make keyboard shortcuts for the gadgets by placing an underscore character '_' before the character you wish to have as the shortcut, for example your "Ok" gadget could be defined as "_Ok", and Right Amiga-O would then satisfy the requester. result=RTEZFlagsRequest(Title$,BodyText$,GadgetText$,IDCMPFlags[,ReqPos]) ------------------------------------------------------------------------- This requester is similar to the standard RTEZRequest, but it can also be satisfied by an IDCMP flag (eg DiskInserted). Either the gadget number or the IDCMP flag will be returned in result. This requester also supports no gadgets, by supplying "" as the GadgetText$. Since the window is locked, the user cannot proceed until the request is satisfied. Use this at your own peril! This requester can force the user to take an action he may not want to, if you don't supply any gadgets. Think, have second thoughts, and then think some more. With enough thought, you *will* come to the conclusion that the user needs at least one gadget. The ReqPosition flag is also available for this requester, as is the keyboard shortcuts. *MyFont.TextAttr=RTEZFontRequest(Title$) ---------------------------------------- Brings up the Font requester, and returns a pointer to a TextAttr structure. The Font requester has had a total rewrite for the V1.7 release of ReqToolsLib. Using it is just the same, but it now returns a saner structure. The structure is defined: NewType.TA Name.s YSize.w Style.b Flags.b End Newtype *MyScreenMode =RTEZScreenModeRequest(Title$ [,DisplayFlags]) ------------------------------------------------------------ Returns a pointer to the following structure: NEWTYPE.MyScreenMode DisplayID.l DisplayWidth.w DisplayHeight.w DisplayDepth.w OverscanType.w AutoScroll.l End NEWTYPE The DisplayFlags field allows you to have control over what options you offer the user. By default, the requester has a resonable set of options, but you may wish to add too (or subtract from) these. Allowable flags are: #SCREQF_OVERSCANGAD - Add an overscan cycle gadget to the requester. After the requester returns you may read the overscan type in '\OverscanType' If this is 0 no overscan is selected (Regular Size), if non-zero it holds one of the OSCAN_... values defined in the include file 'intuition /screens.[h|i]'. #SCREQF_AUTOSCROLLGAD- Add an autoscroll checkbox gadget to the requester. After the requester returns read '\AutoScroll' to see if the user prefers autoscroll to be on or off. #SCREQF_SIZEGADS - Add width and height gadgets to the requester. If you do not add these gadgets the width and height returned will be the default width and height for the selected overscan type. #SCREQF_DEPTHGAD - Add a depth slider gadget to the requester. If you do not add a depth gadget, the depth returned will be the maximum depth this mode can be opened in. #SCREQF_NONSTDMODES - Include all modes. Unless this flag is set RTEZScreenModeRequest() will exclude nonstandard modes. Nonstandard modes are presently HAM and EHB (ExtraHalfBrite). So unless you are picking a mode to do some rendering in leave this flag unset. Without this flag set the mode returned will be a normal bitplaned mode. #SCREQF_GUIMODES - Set this flag if you are getting a screen mode to open a user interface screen in. The modes shown will be standard modes with a high enough resolution (minumum 640 pixels). If this flag is set the SCREQF_NONSTDMODES flag is ignored. Do not attempt to call this requester under WB1.3. SelectedColour.w=RTEZPaletteRequest(Title$,FirstColour) --------------------------------------------------------- Brings up the Palette requester. Returns the last colour the user selected, or -1 if the user hit cancel. If the user changed the colours, they are reflected in the viewport that the window is attached to. name$=RTEZLoadFile(Title$,FileName$) ------------------------------------ This brings up the standard file requester. The directories are buffered, so it doesn't have to reload the directory each time it is called. Note that FileName$ must be at least 108 characters long (use the MaxLen function of this). Note that by default, pattern matching is not enabled. If you want to match a particular pattern, use the RTEZSetPattern command described below. Also, the file name isn't copied to FileName$. You can have a default file name by writing to FileName$, but this will be cleared after the call finishes. This is also true of the SaveFile requester. name$=RTEZSaveFile(Title$,FileName$) ------------------------------------ A seperate requester, the SaveFile requester is different from the LoadFile requester in a number of ways. First, it has a seperate buffer from the LoadFile requester. Second, the OK text is changed to Save. Third, the user cannot double-click a file to select it, to prevent accidental deletions. Finally, if the user types in a non-existent directory, he will be asked if he would like that directory created. FileName$ must be at least 108 bytes long as well. Note that by default, pattern matching is not enabled. If you want to match a particular pattern, use the RTEZSetPattern command described below. name$=RTEZPathRequest(Title$) ----------------------------- Prompts the user to select a path. This is also a seperate requester to the LoadFile and SaveFile requesters, and maintains its own directory list. ret.l=RTEZMultiLoadFile(Title$) ------------------------------- Allows the user to select multiple files for loading (this makes no sense for saving). ret is either True for a list having been selected, or False if the user cancelled. If you call RTEZMultiLoadFile, any previous FileList that was loaded is deleted, even if the user cancels the requester. name$=RTNextPathEntry --------------------- This function returns the next file from a RTEZMultiLoadFile call, or a null string is there is no entry, so you can safely loop about until an empty string is returned. RTEZSetDefaultDirectory Requester#,Directory$ --------------------------------------------- This can be used to set a default directory for the user. Directory$ is the default path, and Requester# is one of the following: 0 - EZLoadFile 1 - EZSaveFile 2 - EZPathRequest 3 - EZMultiLoadFile RTEZSetPattern Requester#,Pattern$ ---------------------------------- Enables and sets the pattern matching in LoadFile and SaveFile requesters. Valid requesters are: 0 - EZLoadFile 1 - EZSaveFile 3 - EZMultiLoadFile RTEZFreePattern Requester# -------------------------- Turns off pattern matching in the requester. Valid requester numbers are: 0 - EZLoadFile 1 - EZSaveFile 3 - EZMultiLoadFile result.l=RTEZGetLong(Title$,BodyText$ [,DefaultValue]) ------------------------------------------------------ This prompts the user for a number. BodyText$ can be formatted with chr$(10) if needed. DefaultValue can be supplied to suggest a value to the user. result.l=RTEZGetLongRange(Title$,BodyText$,Min.l,Max.l [,DefaultValue]) ----------------------------------------------------------------------- Like RTEZGetLong, but this imposes an inclusive minimum and maximum on the number entered. Again, DefaultValue can be used to suggest a value to the user. returned$=RTEZGetString(Title$,BodyText$,MaxChars [,DefaultString]) ------------------------------------------------------------------- Prompts the user to enter a string (which can be up to MaxChars in length). As usual, you can format the BodyText$ with chr$(10) and supply a default string. If you do supply one, then make sure that the length of the string is less than MaxChars, otherwise you could corrupt innocent memory. WinLock=RTLockWindow(Window#) ----------------------------- This locks the numbered window, blocks all input to that window except depth arranging (and the Zip gadget, under 2.0), and put up the standard wait pointer. If you have some utility to make the hands spin or something like that, then that happens as well. WinLock must be saved! RTUnlockWindow Window#,WinLock ------------------------------- Unlocks the window that you locked with RTLockWindow. RTVersion and RTRevision ------------------------ Both these functions return the version number and revision number of the ReqTools library that this code interfaces to. Of no real use at the moment, but future developments in ReqTools may require a minimum library version to work. ReqToolsLib will always open whatever ReqTools are available. IsReqToolsActive ---------------- Returns True if ReqTools was able to initialise, and False if it wasn't (eg not available). ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Advanced Functions ~~~~~~~~~~~~~~~~~~ The following functions can be considered advanced, in that they require a bit more work on the programmers part. ret.l=RTASyncRequest(Title$,BodyText$,GadgetText$) -------------------------------------------------- This function puts up a request, locks the window and returns immediately. If the requester couldn't be put up, ret is False. The program is now free to continue, but the user can have the option of aborting a lengthy operation if required. Important Note: Do not attempt to have two asyncronous requesters up. Note: As of V1.41b, RTASyncRequest uses the current window for the requester. ret.l=RTCheckASyncRequest ------------------------- Checks the status of the asyncronous requester, and returns True if it is still up. RTEndASyncRequest ----------------- Ends the asyncronous request, under program control, and unlocks the calling window. NOTE: Do not call this finction if the user has hit the gadget in the request! The requester automatically frees its self. These three commands require a demonstration to illustrate: NoCli:WBStartup WbToScreen 0 Window 0,10,10,100,100,$8|$1000|2|4,"RTTest window",2,1 CatchDosErrs ret.l=RTASyncRequest("Hi There!","Please Wait...","Cancel") If ret ;The requester opened OK For x.w=10 To 1 Step -1 WLocate 0,10 NPrint "Seconds:",x VWait(50) ret1.l=RTCheckASyncRequest ;Is the requester still up? If NOT ret1 ;No, so end this processing Pop If:Pop For:Pop If Goto cancelled EndIf Next x RTEndASyncRequest ;Normal finish EndIf End cancelled: a.l=RTEZRequest("Oi!","You cancelled!?!","Sure Did") End ret.l=RTASyncPaletteRequest(Title$,FirstColour) ----------------------------------------------- Similar to RTEZPaletteRequest, this command puts up a palette requester and returns immediatly. Note, however, that the calling window is NOT locked, unlike all other ReqTools requesters. This allows you to launch a seperate palette requester and continue processing. ret.l=RTCheckASyncPaletteRequest -------------------------------- Returns True if the requester is still up, False if the user hit Ok or Cancel. NOTE: There is no way to detect exactly how the user exited the command. RTEndASyncPaletteRequest ------------------------ Closes the requester. A short demonstration program to illustrate: WbToScreen 0 Window 0,0,0,200,100,$40,"Hi there",2,1 CatchDosErrs ret.l=RTASyncPaletteRequest("Play with these",1) count.l=0 If ret While count<100 count+1 WLocate 0,0 NPrint "Seconds:",count If NOT RTCheckASyncPaletteRequest Then Goto quit Delay_ 60 Wend RTEndASyncPaletteRequest EndIf quit: Free Window 0 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TagList Functions ~~~~~~~~~~~~~~~~~ ret=RTRequest(BodyText$,GadgetText$,TagList) -------------------------------------------- This is the standard form of the ReqTools Requester. You must supply the tag list to control the requester. The requester title, if not specified in the tag list, will be "Information" if you have only one response gadget, or "Request" if you have two or more responses. If you don't supply a tag list, ReqTools will use its own defaults. It is *your* responsibility to ensure the TagList is correctly set up. Most of the tags of interest are included in RTEZRequest and RTEZFlagsRequest as standard. Acceptable tags are: #RT_Window - *name.Window Window that will be used to find the screen to put the requester on. You *MUST* supply this if you are a task calling this function and not a process! This is because tasks don't have a pr_WindowPtr. #RT_IDCMPFlags - (LONG) Extra idcmp flags to return on. If one these IDCMP flags causes the requester to abort the return code will equal the flag in question. #RT_ReqPos - (LONG) One of the following: #REQPOS_POINTER - requester appears where the mouse pointer is (default). #REQPOS_CENTERSCR - requester is centered on the screen. #REQPOS_CENTERWIN - requester is centered in the window (only works if the pr_WindowPtr of your process is valid or if you use RT_Window). If RT_Window is NULL the requester will be centered on the screen. #REQPOS_TOPLEFTSCR - requester appears at the top left of the screen. #REQPOS_TOPLEFTWIN - requester appears at the top left of the window (only works if the pr_WindowPtr of your process is valid or if you use RT_Window). The requester will always remain in the visible part of the screen, so if you use the Workbench 2.0 ScreenMode preferences editor to enlarge your Workbench screen and you scroll around, the requester will always appear in the part you can see. REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR also apply to the visible part of the screen. So if you use one of these the requester will be appear in the center or the top left off what you can see of the screen as opposed to the entire screen. REQPOS_CENTERWIN and REQPOS_TOPLEFTWIN fall back to REQPOS_CENTERSCR or REQPOS_TOPLEFTSCR respectively when there is no parent window. So you can safely use these without worrying about the existence of a window. #RT_LeftOffset - (LONG) Offset of left edge of requester relative to position specified with RT_ReqPos (does not offset the requester when RT_ReqPos is REQPOS_POINTER). #RT_TopOffset - (LONG) Offset of top edge of requester relative to position specified with RT_ReqPos (does not offset the requester when RT_ReqPos is REQPOS_POINTER). #RT_PubScrName - (*string) Name of public screen requester should appear on. When this tag is used the RT_Window tag will be ignored. If the public screen is not found the requester will open on the default public screen. Only works on Kickstart 2.0! reqtools.library does not check this, it is up to you *NOT* to use this tag on Kickstart 1.3 or below! Note that the 1.3 version of reqtools.library also understands and supports this tag (on 2.0). #RT_Screen - (*name.Screen) Address of screen to put requester on. You should never use this, use RT_Window or RT_PubScrName. #RT_ReqHandler - (struct rtHandlerInfo **) Using this tag you can start an "asynchronous" requester. ti_TagData of the tag must hold the address of a pointer variable to a rtHandlerInfo structure. The requester will initialize this pointer and will return immediately after its normal initialization. The return code will not be what you would normally expect. If the return code is _not_ equal to CALL_HANDLER an error occurred and you should take appropriate steps. If the return code was CALL_HANDLER everything went ok and the requester will still be up! See the explanation for rtReqHandlerA() below for the following steps you have to take. #RT_WaitPointer - (BOOL) If this is TRUE the window calling the requester will get a standard wait pointer set while the requester is up. This will happen if you used the RT_Window tag or if your process's pr_WindowPtr is valid. Note that after the requester has finished your window will be ClearPointer()-ed. If you used a custom pointer in your window you will have to re-set it, or not use the RT_WaitPointer tag and put up a wait pointer yourself. If your program requires ReqTools V38 it is advised you use RT_LockWindow instead. Defaults to FALSE. #RT_LockWindow - (BOOL) [V38] If this is TRUE the window calling the requester will get locked. It will no longer accept any user input and it will get standard wait pointer set. This will happen only if you used the RT_Window tag or if your process's pr_WindowPtr is valid. RT_LockWindow will restore a custom pointer if you have used one (unlike RT_WaitPointer). So you do not have to worry about having to restore it yourself. It is advised you use this tag as much as possible. Defaults to FALSE. #RT_ScreenToFront - (BOOL) [V38] Boolean indicating whether to pop the screen the requester will appear on to the front. Default is TRUE. #RT_ShareIDCMP - (BOOL) [V38] Boolean indicating whether to share the IDCMP port of the parent window. Use this tag together with the RT_Window tag to indicate the window to share IDCMP with. Sharing the IDCMP port produces less overhead, so it is advised you use this tag. Defaults to FALSE. #RT_Locale - (struct Locale *) [V38] Locale to determine what language to use for the requester text. If this tag is not used or its data is NULL, the system's current default locale will be used. Default NULL. #RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call this hook for each IDCMP message it gets that doesn't belong to its window. Only applies if you used the RT_ShareIDCMP tag to share the IDCMP port with the parent window. Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtReqInfo *) your requester info A1 - (struct IntuiMessage *) the message After you have finished examining the message and your hook returns, ReqTools will reply the message. So do not reply the message yourself! #RT_Underscore - (char) [V38] Indicates the symbol that precedes the character in the gadget label to be underscored. This is to define a keyboard shortcut for this gadget. Example: to define the key 'Q' as a keyboard shortcut for "Quit" and 'N' for "Oh, No!" you would use the tag RT_Underscore, '_' and pass as gadfmt "_Quit|Oh, _No!". Do not use the symbol '%' as it is used for string formatting. The usual character to use is '_' like in the example. IMPORTANT: the shortcuts defined using RT_Underscore take precedence of the default shortcuts! It is for example not wise to use a 'N' for a positive response! Pick your shortcuts carefully! #RT_TextAttr - (struct TextAttr *) [V38] Use this font for the requester. Default is to use the screen font. Note that the font must already be opened by you. ReqTools will call OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font cannot be opened using OpenFont() the default screen font will be used. #RTEZ_ReqTitle - (char *) Title of requester window, default is "Request" unless the requester has less than 2 responses, then the default title is "Information". #RTEZ_Flags - (ULONG) Flags for rtEZRequestA(): #EZREQF_NORETURNKEY - turn off the RETURN key as shortcut for positive response. #EZREQF_LAMIGAQUAL - keyboard shortcuts are limited to Left Amiga 'V' and 'B', ESC and RETURN. #EZREQF_CENTERTEXT - centers each line of body text in the requester window. Useful for about requesters. #RTEZ_DefaultResponse - (ULONG) Response value that will be returned when the user presses the return key. Will be ignored if the EZREQF_NORETURNKEY flag is set. The text for this response will be printed in bold. Default is 1. name$=RTFileRequest(Title$,FileName$,TagList) --------------------------------------------- This is the standard ReqTools requester, and is seperate from the LoadFile, SaveFile and PathRequest requesters. No setup is done, but the file name etc is returned as per the above requesters. Most of the tags that you would set normally are included as standard in the RTREZxFile requesters. It is *your* responsibility to ensure that the TagList is correctly set up. Acceptable tags are: #RT_Window - see rtEZRequestA() #RT_ReqPos - see rtEZRequestA() #RT_LeftOffset - see rtEZRequestA() #RT_TopOffset - see rtEZRequestA() #RT_PubScrName - see rtEZRequestA() #RT_Screen - see rtEZRequestA() #RT_ReqHandler - see rtEZRequestA() #RT_WaitPointer - see rtEZRequestA() #RT_LockWindow - [V38] see rtEZRequestA() #RT_ScreenToFront - [V38] see rtEZRequestA() #RT_ShareIDCMP - [V38] see rtEZRequestA() #RT_Locale - [V38] see rtEZRequestA() #RT_IntuiMsgFunc - (struct Hook *) [V38] The requester will call this hook for each IDCMP message it gets that doesn't belong to its window. Only applies if you used the RT_ShareIDCMP tag to share the IDCMP port with the parent window. Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtFileRequester *) your requester A1 - (struct IntuiMessage *) the message After you have finished examining the message and your hook returns, ReqTools will reply the message. So do not reply the message yourself! #RT_Underscore - (char) [V38] Indicates the symbol that precedes the character in a gadget's label to be underscored. This will also define the keyboard shortcut for this gadget. Currently only needed for RTFI_OkText. Usually set to '_'. #RT_DefaultFont - (struct TextFont *) This tag allows you to specify the font to be used in the requester when the screen font is proportional. Default is GfxBase->DefaultFont. #RT_TextAttr - (struct TextAttr *) [V38] Use this font for the requester. Must be a fixed width font, _not_ a proportional one. Default is to use the screen font or the default font (if the screen font is proportional). Note that the font must already be opened by you. ReqTools will call OpenFont() on this TextAttr, _not_ OpenDiskFont()! If the font cannot be opened using OpenFont() or if the font is proportional the default screen font will be used (or the font set with RT_DefaultFont). #RTFI_Flags - (ULONG) Several flags: #FREQF_NOBUFFER - do _not_ use a buffer to remember directory contents for the next time the file requester is used. #FREQF_MULTISELECT - allow multiple files to be selected. rtFileRequest() will return a pointer to an rtFileList structure which will contain all selected files. Use rtFreeFileList() to free the memory used by this file list. #FREQF_SELECTDIRS - set this flag if you wish to enable the selecting of dirs as well as files. You *must* also set FREQF_MULTISELECT. Directories will be returned together with files in rtFileList, but with StrLen equal to -1. If you need the length of the directory's name use strlen(). #FREQF_SAVE - Set this if you are using the requester to save or delete something. Double-clicking will be disabled so it is harder to make a mistake and select the wrong file. If the user enters a non-existent directory in the drawer string gadget, a requester will appear asking if the directory should be created. #FREQF_NOFILES - Set this if you want to use the requester to allow the user to select a directory rather than a file. Ideal for getting a destination dir. May be used with FREQF_MULTISELECT and FREQF_SELECTDIRS. #FREQF_PATGAD - When this is set a pattern gadget will be added to the requester. #RTFI_Height - (ULONG) Suggested height of file requester window. #RTFI_OkText - (char *) Replacement text for "Ok" gadget, max 6 chars long. #RTFI_VolumeRequest - (ULONG) [V38] The presence of this tag turns the file requester into a volume/assign disk requester. This requester can be used to get a device name ("DF0:", "DH1:",..) or an assign ("C:", "FONTS:",...) from the user. The result of this requester can be found in the filereq->Dir field. The volume can also be changed with rtChangeReqAttrA() and the RTFI_Dir tag. Note that the user may edit the disk/assign names, or enter a new one. Note also that the real device name is returned, not the name of the volume in the device. For example "DH1:", not "Hard1:". The tag data (ULONG) is used to set following flags: #VREQF_NOASSIGNS - Do not include the assigns in the list, only the real devices. #VREQF_NODISKS - Do not include devices, just show the assigns. #VREQF_ALLDISKS - Show _all_ devices. Default behavior is to show only those devices which have valid disks inserted into them. So if you have no disk in drive DF0: it will not show up. Set this flag if you do want these devices included. NOTE: Do *NOT* use { RTFI_VolumeRequest, TRUE }! You are then setting the VREQF_NOASSIGNS flag! Use { RTFI_VolumeRequest, 0 } for a normal volume requester. NOTE: If you use the RTFI_FilterFunc described below the third parameter will be a pointer to a rtVolumeEntry structure rather than a pointer to a FileInfoBlock structure! Tech note: the DOS device list has been unlocked, so it is safe to e.g. Lock() this device and call Info() on this lock. NOTE: A file requester structure allocated with rtAllocRequest() should not be used for both a file and a volume requester. Allocate two requester structures if you need both a file and a volume requester in your program! #RTFI_FilterFunc - (struct Hook *) [V38] Call this hook for each file in the directory being read (or for each entry in the volume requester). Parameters are as follows: A0 - (struct Hook *) your hook A2 - (struct rtFileRequester *) your filereq A1 - (struct FileInfoBlock *) fib of file OR (struct rtVolumeEntry *) device or assign in case of a volume requester. If your hook returns TRUE the file will be accepted. If it returns FALSE the file will be skipped and will not appear in the requester. IMPORTANT NOTE: If you change your hook's behavior you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())! IMPORTANT NOTE: When this callback hook is called from a volume requester the pr_WindowPtr of your process will be set to -1 so *no* DOS requesters will appear when an error occurs! #RTFI_AllowEmpty - (BOOL) [V38] If RTFI_AllowEmpty is TRUE an empty file string will also be accepted and returned. Defaults to FALSE, meaning that if the user enters no filename the requester will be canceled. You should use this tag as little as possible!