home *** CD-ROM | disk | FTP | other *** search
Text File | 1992-03-21 | 50.2 KB | 1,257 lines |
- TABLE OF CONTENTS
-
- reqtools.library/rtAllocRequestA
- reqtools.library/rtChangeReqAttrA
- reqtools.library/rtEZRequestA
- reqtools.library/rtFileRequestA
- reqtools.library/rtFontRequestA
- reqtools.library/rtFreeFileList
- reqtools.library/rtFreeReqBuffer
- reqtools.library/rtFreeRequest
- reqtools.library/rtGetLongA
- reqtools.library/rtGetStringA
- reqtools.library/rtGetVScreenSize
- reqtools.library/rtPaletteRequestA
- reqtools.library/rtReqHandlerA
- reqtools.library/rtScreenToFrontSafely
- reqtools.library/rtSetReqPosition
- reqtools.library/rtSetWaitPointer
- reqtools.library/rtSpread
-
- reqtools.library/rtAllocRequestA reqtools.library/rtAllocRequestA
-
- NAME rtAllocRequestA()
-
- req = rtAllocRequestA (type, taglist);
-
- APTR rtAllocRequestA (ULONG, struct TagItem *);
- D0 D0 A0
-
- req = rtAllocRequest (type, tag1,...);
-
- APTR rtAllocRequest (ULONG, Tag,...);
-
- DESCRIPTION
- Allocates a requester structure for you in a future compatible manner.
- This is the only way to properly allocate a rtFileRequester,
- rtFontRequester or rtReqInfo structure. The structure will be
- initialized for you.
-
- Use rtFreeRequest() to free the requester structure when you no longer
- need it.
-
- INPUTS
- type - type of structure to allocate, currently RT_REQINFO,
- RT_FILEREQ or RT_FONTREQ.
- taglist - pointer to array of tags (currently always NULL).
-
- TAGS
- no tags defined yet
-
- RESULT
- req - pointer to the requester allocated or NULL if no memory.
-
- BUGS
- none known
-
- SEE ALSO
- rtFreeRequest()
-
- reqtools.library/rtChangeReqAttrA reqtools.library/rtChangeReqAttrA
-
- NAME rtChangeReqAttrA()
-
- [long =] rtChangeReqAttrA (req, taglist);
-
- [LONG] rtChangeReqAttrA (APTR, struct TagItem *);
- A1 A0
-
- [long =] rtChangeReqAttr (req, tag1,...);
-
- [LONG] rtChangeReqAttr (APTR, Tag,...);
-
- DESCRIPTION
- Change requester attributes with supplied taglist. This is the only
- correct way to change the attributes listed below.
-
- The return code from rtChangeReqAttrA() should be ignored unless stated
- otherwise.
-
- INPUTS
- req - pointer to requester.
- taglist - pointer to array of tags.
-
- TAGS
- for the file requester:
- RTFI_Dir - (char *)
- Name of new directory to position file requester
- in. The requester's buffer will be deallocated.
- RTFI_MatchPat - (char *)
- New pattern string to match files on.
- RTFI_AddEntry - (BPTR)
- THIS *MUST* BE THE LAST TAGĀ (just before TAG_END)!
- Tagdata must hold a lock on a file or directory
- you want to add to the file requester's buffer.
- The lock should have been obtained using Lock(),
- and you must unlock this lock yourself.
- It is your responsability to make sure the file
- or directory is indeed in the directory the file
- requester is in.
- If the entry is already in the file requester's
- buffer it will simply be updated.
- It is harmless to call this function if the
- requester's buffer is not initialized.
- rtChangeReqAttr() will return a boolean to
- indicate success or failure (out of memory).
- RTFI_RemoveEntry - (char *)
- Name of file or directory you want to remove from
- the file requester's buffer.
- It is your responsability to make sure the file
- or directory is indeed in the directory the file
- requester is in.
- It is harmless to call this function if the
- requester's buffer is not initialized.
- for the font requester:
- RTFO_FontName - (char *)
- Set the name of the currently selected font.
- RTFO_FontHeight - (UWORD)
- Set the fontsize of the currently selected font.
- RTFO_FontStyle - (UBYTE)
- Set the style of the current font.
- RTFO_FontFlags - (UBYTE)
- Set the flags of the current font.
-
- RESULT
- none
-
- BUGS
- none known
-
- SEE ALSO
- dos.library/Lock()
-
- reqtools.library/rtEZRequestA reqtools.library/rtEZRequestA
-
- NAME rtEZRequestA()
-
- ret = rtEZRequestA (bodyfmt, gadfmt, reqinfo, argarray, taglist);
-
- ULONG rtEZRequestA
- (char *, char *, struct rtReqInfo *, APTR, struct TagItem *);
- D0 A1 A2 A3 A4 A0
-
- ret = rtEZRequest (bodyfmt, gadfmt, reqinfo, taglist, arg1, arg2,...);
-
- ULONG rtEZRequest
- (char *, char *, struct rtReqInfo *, struct TagItem *,...);
-
- ret = rtEZRequestTags(bodyfmt, gadfmt, reqinfo, argarray, tag1,...);
-
- ULONG rtEZRequestTags(char *, char *, struct rtReqInfo *, APTR, Tag,...);
-
- DESCRIPTION
- This function puts up a requester for you and waits for a response from
- the user. If the response is positive, this procedure returns TRUE.
- If the response is negative, this procedure returns FALSE.
- The function may also return an IDCMP flag or a value corresponding with
- one of other possible responses (see below).
-
- 'gadfmt' may contain several possible responses. Seperate these
- responses by a '|'. For example: "Yes|No", or 'Yes|Maybe|No". The
- responses should be typed in the same order as they will appear on
- screen, from left to right. There is no limit to the number of responses
- other than the width of the screen the requester will appear on.
-
- 'bodyfmt' can contain newlines ('\n', ASCII 10). This will cause a new
- line to be started (surprise, surprise :-).
- You may also include 'printf' style formating codes. The format arguments
- should be pointed to by 'argarray'.
- You can use formatting codes in 'gadfmt' as well. The arguments for
- this format string should follow the ones for 'bodyfmt'.
-
- NOTE: The formatting is done by exec.library/RawDoFmt(), so be aware that
- to display a 32-bit integer argument you must use "%ld", not "%d",
- since RawDoFmt() is "word-oriented."
-
- The second and third function use a variable number of arguments. These
- functions can be found in 'reqtools[nb].lib'.
- The second function has the RawDoFmt arguments as variable args, the
- third the tags. If you need both this is what you can do:
-
- ...
- {
- ULONG tags[] = { RTEZ_ReqTitle, (ULONG)"mytitle", TAG_END };
-
- rtEZRequest ("String, num: %s, %ld", NULL, "Ok",
- (struct TagItem *)tags, "six", 6);
- }
- ...
-
- You can satisfy the requester with the following keyboard shortcuts:
- 'Y' or Left Amiga 'V' for a positive response,
- ESC, 'N', 'R' or Left Amiga 'B' for a negative response.
-
- If EZREQF_NORETURNKEY is _not_ set (see RTEZ_Flags below) the RETURN key
- is also accepted as a shortcut for the positive response (can be changed
- using RTEZ_DefaultResponse, see below). The response that will be
- selected when you press RETURN will be printed in bold.
-
- The EZREQF_LAMIGAQUAL flag should be used when you put up a requester
- for a destructive action (e.g. to delete something). When it is set
- the keyboard shortcuts are limited to Left Amiga 'V' and 'B' so it is
- harder to accidently select something you will regret.
- Note that the RETURN and ESC key remain active! To disable the RETURN
- key use the EZREQF_NORETURNKEY flag. The ESC key cannot be disabled.
-
- You may pass a NULL for 'gadfmt', but make sure you know what you are
- doing. Passing a NULL opens an EZRequester with NO responses, just a
- body text. This implies the user has no means of "answering" this
- requester. You must therefore use the RT_IDCMPFlags tag to allow some
- other events to end the requester (e.g. IDCMP_MOUSEBUTTONS,
- IDCMP_INACTIVEWINDOW,...) or you must make use of the ReqHandler feature.
- Using a requester handler you can end the requester by program control.
- This way you can e.g. put up a requester before you start loading a file
- and remove it after the file has been loaded. Do not pass an empty
- string as 'gadfmt'!
-
- 'reqinfo' can be used to customize the requester. For greater control
- use the tags listed below. The advantage of the rtReqInfo structure is
- that it is global, where tags have to be specified each function call.
- See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
-
- INPUTS
- bodyfmt - requester body text, can be format string a la RawDoFmt().
- gadfmt - text for gadgets (left to right, seperated by '|') or NULL.
- argarray - pointer to array of arguments for format string(s).
- reqinfo - pointer to a rtReqInfo structure allocated with
- rtAllocRequest() or NULL.
- taglist - pointer to a TagItem array.
-
- TAGS
- RT_Window - (struct 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 - (ULONG)
- 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 - (ULONG)
- 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 - (ULONG)
- 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 - (ULONG)
- 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 - (char *)
- 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 - (struct 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 occured 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.
- Defaults to FALSE. It is advised you use this tag as
- much as possible.
- 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
- shorcut 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.
-
- RESULT
- ret - 1 (TRUE) for leftmost (positive) response, then each consecutive
- response will return 1 more, the rightmost (false) respons will
- return 0 (FALSE), so 1,2,3,...,num-1,0 -- or idcmp flag.
-
- NOTE
- Automatically adjusts the requester to the screen's font.
-
- rtEZRequestA() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
- exec.library/RawDoFmt(), rtReqHandlerA()
-
- reqtools.library/rtFileRequestA reqtools.library/rtFileRequestA
-
- NAME rtFileRequestA()
-
- ret = rtFileRequestA (filereq, filename, title, taglist);
-
- APTR rtFileRequestA
- (struct rtFileRequester *, char *, char *, struct TagItem *);
- D0 A1 A2 A3 A0
-
- ret = rtFileRequest (filereq, filename, title, tag1,...);
-
- APTR rtFileRequest (struct rtFileRequester *, char *, char *, Tag,...);
-
- DESCRIPTION
- Get a directory and filename(s), or just a directory from the user.
-
- 'filename' should point to an array of at least 108 chars. The filename
- already in 'filename' will be displayed in the requester when it comes
- up. When the requester returns 'filename' will probably have changed.
-
- Setting certain flags may result in the calling of a caller-supplied
- hook.
- The hook will be called with A0 holding the address of your hook
- structure (you may use the h_Data field to your own liking), A1 a pointer
- to the requester structure ('req') and A2 a pointer to an array of
- longwords ('param[]').
- 'param[0]' will hold the type of the hook, the rest (if any) depends on
- that type.
- 'req' will point to the requester structure of the requester calling the
- hook.
-
- SAS/C users can define their function thus:
-
- ULONG __asm __saveds hookfunc (register __a0 struct Hook *hook,
- register __a2 APTR req,
- register __a1 ULONG *param)
- {
- switch (param[0]) {
- case REQHOOK_WILDFILE:
- /* param[1] holds address of a FileInfoBlock */
- ...
- return (skipit);
- case REQHOOK_WILDFONT:
- /* param[1] holds address of a TextAttr */
- ...
- return (skipit);
- default:
- return (0);
- }
- }
-
- Your hook should then be initialized like this:
-
- hook->h_Entry = hookfunc;
- /* in this case no need to initialize hook->h_SubEntry */
- hook->h_Data = your_userdata_if_needed;
-
- Succesively you should initialize the filereq->Hook field to point to
- your hook. Note that there is no tag to set the hook!
-
- You can also use a stub written in machine code to call
- your function. (see 'utility/hooks.h')
-
- Always check the hook's type to see why it is being called! You should
- always return a value to tell the requester what to do after your hook
- has finished. The return value of 0 has been reserved for "continue as
- usual". So if your hook is called with a type other than the ones you
- understand/handle return a 0!
-
- Hook types ('param[0]') currently implemented for rtFileRequest():
-
- REQHOOK_WILDFILE:
- Set the FREQF_DOWILDFUNC flag to activate. The requester will
- call your hook for each file in the directory.
- 'param[1]' will hold the address of a struct FileInfoBlock. If
- your hook returns TRUE the file will be skipped an will not
- appear in the requester.
-
- Finally note that when you change your hook or your hook's behaviour
- you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())!
-
- INPUTS
- filereq - pointer to a struct rtFileRequester allocated with
- rtAllocRequestA().
- filename - pointer to an array of chars (must be 108 bytes big).
- title - pointer to requester window title (null terminated).
- taglist - pointer to a TagItem array.
-
- TAGS
- 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_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.
- RTFI_Flags - (ULONG)
- Several flags:
- FREQF_NOBUFFER - do _not_ use a buffer to remember
- directory contents for the next
- time rtFileRequestA() is used.
- FREQF_MULTISELECT - allow multiple files to be
- selected. rtFileRequestA() will
- return a pointer to a 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
- 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 directory.
- May be used with FREQF_MULTISELECT
- and FREQF_SELECTDIRS.
- FREQF_PATGAD - When this is set a pattern gadget
- will be added to the requester.
- FREQF_DOWILDFUNC - Call req->Hook for each entry in
- the directory.
- Note that there is no tag to set
- the hook. You must initialize
- the req->Hook field with a pointer
- to a valid hook structure.
- See above for more information on
- the calling of hooks.
- RTFI_Height - (ULONG)
- Suggested height of file requester window.
- RTFI_OkText - (char *)
- Replacement text for "Ok" gadget, max 6 characters long.
-
- RESULT
- ret - TRUE if the user selected a file (check 'filereq->Dir' for the
- directory and 'filename' for the filename) or FALSE if the
- requester was canceled -- or a pointer to a struct rtFileList
- (if FREQF_MULTISELECT was used).
-
- NOTE
- Automatically adjusts the requester to the screen's font.
- If the screen's font is proportional the default font will be used.
-
- If the requester got too big for the screen because of a very large font,
- the topaz.font will be used.
-
- rtFileRequest() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtFontRequestA reqtools.library/rtFontRequestA
-
- NAME rtFontRequestA()
-
- bool = rtFontRequestA (fontreq, title, taglist);
-
- BOOL rtFontRequestA (struct rtFontRequester *, char *, struct TagItem *);
- D0 A1 A3 A0
-
- bool = rtFontRequest (fontreq, title, tag1,...);
-
- BOOL rtFontRequest (struct rtFontRequester *, char *, Tag,...);
-
- DESCRIPTION
- Let the user select a font and a style (optional).
-
- Setting certain flags may result in the calling of a caller-supplied
- hook. See rtFileRequest() for more information on the calling of this
- hook.
-
- Hook types ('param[0]') currently implemented for rtFontRequest():
-
- REQHOOK_WILDFONT:
- Set the FREQF_DOWILDFUNC flag to activate. The requester will
- call your hook for each font in the system's font list.
- 'param[1]' will hold the address of a struct TextAttr. If your
- hook returns TRUE the font will be skipped.
-
- Finally note that when you change your hook or your hook's behaviour
- you _MUST_ purge the requester's buffer (using rtFreeReqBuffer())!
-
- INPUTS
- fontreq - pointer to a struct rtFontRequester allocated with
- rtAllocRequestA().
- title - pointer to requester window title (null terminated).
- taglist - pointer to a TagItem array.
-
- TAGS
- 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_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.
- RTFO_Flags - (ULONG)
- Several flags:
- FREQF_NOBUFFER - do not buffer the font list
- for subsequent calls to
- rtFontRequestA().
- FREQF_FIXEDWIDTH - only display fixed-width fonts.
- FREQF_COLORFONTS - display color fonts also.
- FREQF_CHANGEPALETTE - change the screen's palette
- to match that of a selected
- color font.
- FREQF_LEAVEPALETTE - leave the palette as it is
- when exiting rtFontRequestA()
- Useful in combination with
- FREQF_CHANGEPALETTE.
- FREQF_SCALE - allow fonts to be scaled
- when they don't exist in the
- requested size.
- (works on Kickstart 2.0 only,
- has no effect on 1.2/1.3).
- FREQF_STYLE - include gadgets so the user
- may select the font's style.
- FREQF_DOWILDFUNC - Call req->Hook for each font.
- Note that there is no tag to
- set the hook. You must
- initialize the req->Hook
- field with a pointer to a
- valid hook structure.
- See rtFileRequest() for more
- information on the calling of
- this hook.
- RTFO_Height - (ULONG)
- Suggested height of font requester window.
- RTFO_OkText - (char *)
- Replacement text for "Ok" gadget. Maximum 6 chars.
- (7 is still ok, but not esthetically pleasing)
- RTFO_SampleHeight - (ULONG)
- Height of font sample display in pixels (default 24).
- RTFO_MinHeight - (ULONG)
- Minimum font size displayed.
- RTFO_MaxHeight - (ULONG)
- Maximum font size displayed.
-
- RESULT
- bool - TRUE if the user selected a font (freq->Attr holds the font),
- FALSE if the requester was canceled.
-
- NOTE
- Automatically adjusts the requester to the screen's font.
- If the screen's font is proportional the default font will be used.
-
- If the requester got too big for the screen because of a very large font,
- the topaz.font will be used.
-
- rtFontRequest() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtFreeFileList reqtools.library/rtFreeFileList
-
- NAME rtFreeFileList()
-
- rtFreeFileList (filelist);
-
- void rtFreeFileList (struct rtFileList *);
- A0
-
- DESCRIPTION
- Frees a filelist returned by rtFileRequest() when the FREQF_MULTISELECT
- flag was set. Call this after you have scanned the filelist and you no
- longer need it.
-
- INPUTS
- filelist - pointer to rtFileList structure, returned by rtFileRequest()
- (may be NULL).
-
- RESULT
- none
-
- BUGS
- none known
-
- SEE ALSO
- rtFileRequest()
-
- reqtools.library/rtFreeReqBuffer reqtools.library/rtFreeReqBuffer
-
- NAME rtFreeReqBuffer()
-
- rtFreeReqBuffer (req);
-
- void rtFreeReqBuffer (APTR);
- A1
-
- DESCRIPTION
- Frees the buffer associated with 'req'. In case of a file requester this
- function will deallocate the directory buffer, in case of a font
- requester the font list.
-
- It is safe to call this function for requesters that have no buffer, so
- you may call this for all requesters to free as much memory as possible.
-
- INPUTS
- req - pointer to requester.
-
- RESULT
- none
-
- BUGS
- none known
-
- SEE ALSO
- rtFileRequest(), rtFontRequest()
-
- reqtools.library/rtFreeRequest reqtools.library/rtFreeRequest
-
- NAME rtFreeRequest()
-
- rtFreeRequest (req);
-
- void rtFreeRequest (APTR);
- A1
-
- DESCRIPTION
- Free requester structure previously allocated by rtAllocRequestA().
- This will also free all buffers associated with the requester, so there
- is no need to call rtFreeReqBuffer() first.
-
- INPUTS
- req - pointer to requester (may be NULL).
-
- RESULT
- none
-
- BUGS
- none known
-
- SEE ALSO
- rtAllocRequestA()
-
- reqtools.library/rtGetLongA reqtools.library/rtGetLongA
-
- NAME rtGetLongA()
-
- ret = rtGetLongA (&longvar, title, reqinfo, taglist);
-
- ULONG rtGetLongA (ULONG *, char *, struct rtReqInfo *, struct TagItem *);
- D0 A1 A2 A3 A0
-
- ret = rtGetLong (&longvar, title, reqinfo, tag1,...);
-
- ULONG rtGetLong (ULONG *, char *, struct rtReqInfo *, Tag,...);
-
- DESCRIPTION
- Puts up a requester to get a signed long (32-bit) number from the user.
-
- 'reqinfo' can be used to customize the requester. For greater control
- use the tags listed below. The advantage of the rtReqInfo structure is
- that it is global, where tags have to be specified each function call.
- See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
-
- INPUTS
- &longvar - address of long (32 bit!) variable to hold result.
- title - pointer to null terminated title of requester window.
- reqinfo - pointer to a rtReqInfo structure allocated with
- rtAllocRequest() or NULL.
- taglist - pointer to a TagItem array.
-
- TAGS
- RT_Window - see rtEZRequestA()
- RT_IDCMPFlags - 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()
- RTGL_Min - (ULONG)
- Minimum allowed value. If the user tries to enter a
- smaller value the requester will refuse to accept it.
- RTGL_Max - (ULONG)
- Maximum allowed value, higher values are refused.
- RTGL_Width - (ULONG)
- Width if requester window in pixels. This is only a
- suggestion. rtGetLongA() will not go below a
- certain width.
- RTGL_ShowDefault - (BOOL)
- If this is TRUE (default) the value already in
- 'longvar' will be displayed in the requester when it
- comes up. If set to FALSE the requester will be empty.
-
- RESULT
- ret - TRUE if user entered a number, FALSE if not. If one of your idcmp
- flags caused the requester to end 'ret' will hold this flag.
-
- NOTE
- 'longvar' will NOT change if the requester is aborted.
-
- Automatically adjusts the requester to the screen's font.
-
- rtGetLongA() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtGetStringA reqtools.library/rtGetStringA
-
- NAME rtGetStringA()
-
- ret = rtGetStringA (buffer, maxchars, title, reqinfo, taglist);
-
- ULONG rtGetStringA
- (UBYTE *, ULONG, char *, struct rtReqInfo *, struct TagItem *);
- D0 A1 D0 A2 A3 A0
-
- ret = rtGetString (buffer, maxchars, title, reqinfo, tag1,...);
-
- ULONG rtGetString (UBYTE *, ULONG, char *, struct rtReqInfo *, Tag,...);
-
- DESCRIPTION
- Puts up a string requester to get a line of text from the user.
- The string present in 'buffer' upon entry will be displayed, ready to
- be edited.
-
- 'reqinfo' can be used to customize the requester. For greater control
- use the tags listed below. The advantage of the rtReqInfo structure is
- that it is global, where tags have to be specified each function call.
- See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
-
- INPUTS
- buffer - pointer to buffer to hold characters entered.
- maxchars - maximum number of characters that fit in buffer (EX-cluding
- the 0 to terminate the string !).
- title - pointer to null terminated title of requester window.
- reqinfo - pointer to a rtReqInfo structure allocated with
- rtAllocRequest() or NULL.
- taglist - pointer to a TagItem array.
-
- TAGS
- RT_Window - see rtEZRequestA()
- RT_IDCMPFlags - 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()
- RTGS_Width - (ULONG)
- Width of requester window in pixels. This is only a
- suggestion. rtGetStringA() will not go below a certain
- width.
- RTGS_AllowEmpty - (BOOL)
- If RTGS_AllowEmpty is TRUE an empty string will also
- be accepted and returned. Defaults to FALSE, meaning
- that if the user enters an empty string the requester
- will be canceled.
-
- RESULT
- ret - TRUE if user entered something, FALSE if not. If one of your idcmp
- flags caused the requester to end 'ret' will hold this flag.
-
- NOTE
- The contents of the buffer will NOT change if the requester is aborted.
-
- Automatically adjusts the requester to the screen's font.
-
- rtGetStringA() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtGetVScreenSize reqtools.library/rtGetVScreenSize
-
- NAME rtGetVScreenSize()
-
- rtGetVScreenSize (screen, widthptr, heightptr);
-
- ULONG rtGetVScreenSize (struct Screen *, ULONG *, ULONG *);
- D0 A0 A1 A2
-
- DESCRIPTION
- Use this function to get the size of the visible portion of a screen.
-
- The value returned by rtGetVScreenSize() can be used for vertical
- spacing. It will be larger for interlaced and productivity screens.
- Using this number for spacing will assure your requester will look
- good on an interlaced and a non-interlaced screen.
-
- Current return codes are 2 for non-interlaced and 4 for interlaced.
- These values may change in the future, don't depend on them too much.
- They will in any case remain of the same magnitude.
-
- INPUTS
- screen - pointer to the screen.
- widthptr - address of an ULONG variable to hold the width.
- heightptr - address of an ULONG variable to hold the height.
-
- RESULT
- none
-
- NOTE
- This function is for the advanced reqtools user.
-
- BUGS
-
- SEE ALSO
-
- reqtools.library/rtPaletteRequestA reqtools.library/rtPaletteRequestA
-
- NAME rtPaletteRequestA()
-
- color = rtPaletteRequestA (title, reqinfo, taglist);
-
- LONG rtPaletteRequestA (char *, struct rtReqInfo *, struct TagItem *);
- D0 A2 A3 A0
-
- color = rtPaletteRequest (title, reqinfo, tag1,...);
-
- LONG rtPaletteRequest (char *, struct rtReqInfo *, Tag,...);
-
- DESCRIPTION
- Put up a palette requester so the user can change the screen's colors.
-
- The colors are changed in the viewport of the screen the requester will
- appear on, so that is where you will find them after the palette
- requester returns.
-
- The selected color is returned, so you can also use this requester to let
- the user select a color.
-
- 'reqinfo' can be used to customize the requester. For greater control
- use the tags listed below. The advantage of the rtReqInfo structure is
- that it is global, where tags have to be specified each function call.
- See libraries/reqtools.[hi] for a description of the rtReqInfo structure.
-
- INPUTS
- title - pointer to requester window title (null terminated).
- reqinfo - pointer to a rtReqInfo structure allocated with
- rtAllocRequest() or NULL.
- taglist - pointer to a TagItem array.
-
- TAGS
- 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_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.
- RTPA_Color - (ULONG)
- Initially selected color of palette. Default is 1.
-
- RESULT
- color - the color number of the selected color or -1 if the user
- canceled the requester.
-
- NOTE
- Automatically adjusts the requester to the screen's font.
- If the screen's font is proportional the default font will be used.
-
- If the requester got too big for the screen because of a very large font,
- the topaz.font will be used.
-
- rtPaletteRequestA() checks the pr_WindowPtr of your process to find the
- screen to put the requester on.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtReqHandlerA reqtools.library/rtReqHandlerA
-
- NAME rtReqHandlerA()
-
- ret = rtReqHandlerA (handlerinfo, sigs, taglist);
-
- ULONG rtReqHandlerA (struct rtHandlerInfo *, ULONG, struct TagItem *);
- D0 A1 D0 A0
-
- ret = rtReqHandler (handlerinfo, sigs, tag1,...);
-
- ULONG rtReqHandler (struct rtHandlerInfo *, ULONG, Tag,...);
-
- DESCRIPTION
- This function should be called if you used the RT_ReqHandler tag with a
- requester function.
-
- The requester you used the tag with will have returned immediately after
- its initialization and will have initialized a pointer to a rtHandlerInfo
- structure for you.
- You should now do the following:
-
- Check the DoNotWait field. If it is FALSE you have to wait for the
- signals in the WaitMask field (plus your own signals if you like).
- If any of the signals in WaitMask are received or DoNotWait was not FALSE
- you have to call rtReqHandlerA() and check its return value for one of
- the following values:
-
- CALL_HANDLER - Check DoNotWait again, Wait() if you have to
- and call rtReqHandlerA() again. In other words, loop.
- everything else - normal return value, requester has finished. This
- return value will be the same as if the requester
- had run normally.
-
- You must pass the signals you received to rtReqHandlerA().
-
- NOTE: if you want to wait for your own signals do not do so if
- DoNotWait is TRUE. Call rtReqHandlerA() and if you must know
- if one of your signals arrived use SetSignal() to find this out.
- If you are waiting for a message to arrive at a message port you
- can simple call GetMsg and check if it is non-null.
- DoNotWait will naturally only be TRUE when it absolutely,
- positively has to be. A multitasking machine as the Amiga should
- use Wait() as much as possible.
-
- This is an example of a "requester loop":
-
- ...
- struct rtHandlerInfo *hinfo;
- ULONG ret, mymask, sigs;
-
- ...
- /* calculate our mask */
- mymask = 1 << win->UserPort->mp_SigBit;
-
- /* We use the RT_ReqHandler tag to cause the requester to return
- after initializing.
- Check the return value to see if this setup went ok. */
- if (rtFontRequest (req, "Font", RT_ReqHandler, &hinfo, TAG_END)
- == CALL_HANDLER) {
- do {
- /* Wait() if we can */
- if (!hinfo->DoNotWait)
- sigs = Wait (hinfo->WaitMask | mymask);
-
- /* check our own message port */
- while (msg = GetMsg (win->UserPort)) {
- ...
- /* here we handle messages received at our windows IDCMP ...
- port */
- ...
- }
-
- /* let the requester do its thing (remember to pass 'sigs') */
- ret = rtReqHandler (hinfo, sigs, TAG_END);
-
- /* continue this loop as long as the requester is up */
- } while (ret == CALL_HANDLER)
-
- /* when we get here we know the requester has finished, 'ret'
- is the return code. */
- ...
- }
- else notify ("Error opening requester!");
- ...
-
- INPUTS
- handlerinfo - pointer to handler info structure initialized by using
- the RT_ReqHandler tag when calling a requester function.
- sigs - the signals received by previous wait, will be ignored if
- hinfo->DoNotWait was TRUE.
- taglist - pointer to a TagItem array.
-
- TAGS
- RTRH_EndRequest - supplying this tag will end the requester. The return
- code from rtReqHandlerA() will _not_ be CALL_HANDLER,
- but the requester return code. If the tagdata of this
- tag is REQ_CANCEL the requester will be canceled, if it
- is REQ_OK the requester will be ok-ed.
- In case of an EZRequest tagdata should be the return
- code of the requester (TRUE, FALSE or 2,3,4,...).
-
- RESULT
- ret - CALL_HANDLER if you have to call rtReqHandlerA() again,
- or the normal return value from the requester.
-
- BUGS
- none known
-
- SEE ALSO
- rtEZRequest() (RT_ReqHandler explanation)
-
- reqtools.library/rtScreenToFrontSafely reqtools.library/rtScreenToFrontSafely
-
- NAME rtScreenToFrontSafely()
-
- rtScreenToFrontSafely (screen);
-
- void rtScreenToFrontSafely (struct Screen *);
- A0
-
- DESCRIPTION
- Brings the specified screen to the front of the display, but only after
- checking it is still in the list of currently open screens.
-
- This function can be used to bring a screen back to the front of the
- display after bringing another screen to the front. If the first screen
- closed while you where busy it is harmless to call this function, unlike
- calling the normal ScreenToFront().
-
- INPUTS
- screen - pointer to the screen.
-
- RESULT
- none
-
- NOTE
- This function is for the advanced reqtools user.
-
- BUGS
- none known
-
- SEE ALSO
- intuition.library/ScreenToFront()
-
- reqtools.library/rtSetReqPosition reqtools.library/rtSetReqPosition
-
- NAME rtSetReqPosition()
-
- rtSetReqPosition (reqpos, newwindow, screen, window);
-
- void rtSetReqPosition
- (ULONG, struct NewWindow *, struct Screen *, struct Window *);
- D0 A0 A1 A2
-
- DESCRIPTION
- Sets newwindow->LeftEdge and newwindow->TopEdge according to reqpos.
-
- Except for the left- and topedge 'newwindow' must already be completely
- initialized.
-
- The newwindow->LeftEdge and newwindow->TopEdge already in the NewWindow
- structure will be used as offsets to the requested position. If you'd
- like a window at position (25,18) from the top left of the screen you
- would fill newwindow->LeftEdge with 25, newwindow->TopEdge with 18 and
- call rtSetReqPosition() with reqpos equal to REQPOS_TOPLEFTSCR.
-
- Don't forget to make sure newwindow->LeftEdge and newwindow->TopEdge
- are 0 if you don't want to offset your window.
-
- In case of REQPOS_POINTER you can use them to point to your window's
- hotspot, where the pointer should point. If you call rtSetReqPosition()
- with the left- and topedge equal to 0 you'd get a window appearing with
- its top- and leftedge equal to the current pointer position.
-
- Note that the screen pointer may _NOT_ be NULL. If you have your own
- window open you can supply yourwindow->WScreen to this function.
-
- The window pointer is only required if reqpos is REQPOS_CENTERWIN or
- REQPOS_TOPLEFTWIN. Even in this case you may call rtSetReqPosition()
- with a NULL window pointer. The positions will simply fall back to
- REQPOS_CENTERSCR and REQPOS_TOPLEFTSCR respectively.
-
- INPUTS
- reqpos - one of the REQPOS_... constants usable with RT_ReqPos.
- newwindow - pointer to your (already initialized) NewWindow structure.
- screen - pointer to screen the requester will appear on.
- window - pointer to parent window or NULL.
-
- RESULT
- none
-
- NOTE
- This function is for the advanced reqtools user.
-
- BUGS
- none known
-
- SEE ALSO
- RT_ReqPos tag
-
- reqtools.library/rtSetWaitPointer reqtools.library/rtSetWaitPointer
-
- NAME rtSetWaitPointer()
-
- rtSetWaitPointer (window);
-
- void rtSetWaitPointer (struct Window *);
- A0
-
- DESCRIPTION
- Change the window's pointer image to that of a wait pointer. Call this
- function whenever your program will be busy doing something for a lengthy
- period of time.
-
- It is recomended you call this function before calling any of the
- requester functions. This way if the user clicks in your window he will
- know he must respond to the requester before doing anything else. See
- also the RT_WaitPointer tag for an automatic way of setting the wait
- pointer.
-
- INPUTS
- window - pointer to the window to receive the wait pointer.
-
- RESULT
- none
-
- NOTE
- The wait pointer will look exactly like the standard Workbench 2.0
- wait pointer. In combination with PointerX or, even better, ClockTick
- the handle will turn.
-
- BUGS
- none known
-
- SEE ALSO
-
- reqtools.library/rtSpread reqtools.library/rtSpread
-
- NAME rtSpread()
-
- rtSpread (posarray, sizearray, totalsize, min, max, num);
-
- void rtSpread (ULONG *, ULONG *, ULONG, ULONG, ULONG, ULONG);
- A0 A1 D0 D1 D2 D3
-
- DESCRIPTION
- Evenly spread a number of objects over a certain length.
- Primary use is for arrangement of gadgets in a window.
-
- Example:
-
- 'sizearray' holds following values: 4, 6, 4, 2 and 8,
- 'totalsize' is 24 (= 4 + 6 + 4 + 2 + 8),
- 'min' is 3, 'max' is 43,
- and finally, 'num' is 5.
-
- After calling rtSpread() 'posarray' would hold the following
- values: 3, 11, 19, 26 and 31.
-
- My attempt at a visual representation:
-
- | |
- | | | |
- | OOOO OOOOOO OOOO OO OOOOOOOO |
- | | | |
- | 1 1 2 2 3 3 4 4
- 0----5----0----5----0----5----0----5----0----5
-
- INPUTS
- posarray - pointer to array to be filled with positions.
- sizearray - pointer to array of sizes.
- totalsize - total size of all objects (sum of all values in sizearray).
- min - first position to use.
- max - last position, first _NOT_ to use.
- num - number of objects (size of posarray and sizearray).
-
- RESULT
- none
-
- NOTE
- This function is for the advanced reqtools user.
-
- BUGS
- none known
-
- SEE ALSO
-
-