TABLE OF CONTENTS

asl.library/AllocAslRequest
asl.library/AllocFileRequest
asl.library/AslRequest
asl.library/FreeAslRequest
asl.library/FreeFileRequest
asl.library/RequestFile


asl.library/AllocAslRequest			   asl.library/AllocAslRequest

  NAME
	AllocAslRequest -- alloc an ASL requester, with TagItem modifiers (V36)

  SYNOPSIS
	request = AllocAslRequest( type, ptags )
	D0			   D0	 A0

	APTR	request;
	ulong	type;
	struct TagItem	*ptags;

  FUNCTION
	Allocates an ASL requester data structure of the specified type,
	with optional TagItem modifiers.

  INPUTS
	type = type of requester to create.  Currently defined types
	    include ASL_FileRequest and ASL_FontRequest.
	ptags = pointer to a tagitem array, which is defined for each
	    specified type.  See "asl.h" and example programs for usage
	    of various tag types.  See AslRequest() for specifications
	    of currently defined tag values and their effects.

	Note that tag values stay in effect for each use of the
	requester until they are cleared or modified by passing the
	same tag with a new value.

	AllocAslRequestTags( type, tags... ) which accepts your tags
	on the stack, is available in amiga.lib.

	Example Usage: AllocAslRequestTags( ASL_FileRequest,
				            ASL_Hail, "My Title Bar",
				            TAG_DONE );

  RESULT
	Pointer to an initialized requester data structure, or NULL on
	failure.  The data structure returned will match the requested
	type; for type ASL_FileRequest, a struct FileRequester *; for
	ASL_FontRequest, a struct FontRequester *.

	The requester returned may then be passed to AslRequest(), and
	is freed by calling FreeAslRequest().

  SEE ALSO
	AslRequest(), FreeAslRequest()


asl.library/AllocFileRequest			   asl.library/AllocFileRequest

  NAME
	AllocFileRequest -- allocates a FileRequester structure (V36)

  SYNOPSIS
	request = AllocFileRequest()
	D0

	struct FileRequester *request;

  FUNCTION
	Creates and initializes the data structure required to pass to the
	RequestFile() function.

  INPUTS
	None.  If you wish to get other than default values, you can use
	AllocAslRequest() to set up a file request with tag items.

  RESULT
	Pointer to a struct FileRequester, which is to be passed to the
	RequestFile() function.

	The returned FileRequester pointer has public fields which are
	readable by the application as defined in aslbase.h.

  CAUTION
	The application MUST use either the AllocFileRequest(), or
	AllocAslRequest(), function to allocate the structure to be passed to
	the FileRequest() or AslRequest() functions; it is not possible to
	create a struct FileRequest except through the library calls.

	Also, any modifications MUST be done through TagItem values, rather
	than directly modifying, unless explicitly documented otherwise.

  SEE ALSO
	RequestFile(), FreeAslRequest(), AslRequest()


asl.library/AslRequest					 asl.library/AslRequest

  NAME
	AslRequest -- get input from user for an ASL requester (V36)

  SYNOPSIS
	BOOL result = AslRequest( request, ptags );
	D0                        A0       A1

	BOOL	result;
	APTR	request;
	struct TagItem	*ptags;

  FUNCTION
	Prompts the user for input, based on the specific type of
	requester and modifying tagitems.  The actions and results
	are specific to the type but in general the action is to open
	a requesting window prompting the user for a specific input.
	If the user cancels or the system aborts the request, NULL
	is returned, otherwise the request data structure readable
	data reflects the user input.
	Note that tag values stay in effect for each use of the
	requester until they are cleared or modified by passing the
	same tag with a new value.

  INPUTS
	request = requester structure allocated with AllocAslRequest().
	ptags = pointer to an array of TagItems which may be used to
	    modify the requester.

	AslRequestTags( type, tags... ) which accepts your tags
	on the stack, is available in amiga.lib.

	Example Usage: AslRequestTags( ASL_FileRequest,
				       ASL_Hail, "My Title Bar",
				       TAG_DONE );

  TAGS

	( REMEMBER - ALL DATA STRUCTURES ARE READ-ONLY EXCEPT BY USING
	  TAGITEMS !!! )

	ASL_Hail (STRPTR) - Hailing text to prompt user, typically
	    displayed in window title bar.
	ASL_Window (struct Window *) - Parent window for the request
	    function, which is used to select the screen on which the
	    requesting window will be displayed and also is used for
	    a shared IDCMP port.

	ASL_LeftEdge (WORD) - Preferred display position for left edge where
	    request window should open.
	ASL_TopEdge (WORD) - Preferred top edge of request window.
	ASL_Width (WORD)   - Preferred width of request window.
	ASL_Height (WORD)  - Preferred height of request window.

	ASL_HookFunc (APTR) - Pointer to callback function, specific to
	    each AslRequest type.

	ASL_File (STRPTR) - FileRequester initial filename string.
	ASL_Dir (STRPTR) - FileRequester initial directory path string.

	ASL_FontName (STRPTR) - FontRequester initial fontname string.
	ASL_FontHeight (UWORD) - FontRequester initial height (ta_YSize).
	ASL_FontStyles (UBYTE) - FontRequester initial styles (ta_Style).
	ASL_FontFlags (UBYTE) - FontRequester initial flags (ta_Flags).
	ASL_FrontPen (BYTE) - FontRequester front pen color (fo_FrontPen).
	ASL_BackPen (BYTE) - FontRequester back pen color (fo_BackPen).
	ASL_MinHeight (UWORD) - Minimum height for FontRequester display
	    of font sizes.  (Application must check return value).
	ASL_MaxHeight (UWORD) - Maximum height for FontRequester display
	    of font sizes. (Application must check ta_YSize returned).

	ASL_OKText (STRPTR) - Replacement for default "OK" gadget text.
	    ( Limited to approx. six characters ).
	ASL_CancelText (STRPTR) - Replacement for default "CANCEL"
	    gadget text. ( Limited to approx. six characters ).

	ASL_FuncFlags (ULONG) - Function flags, depends on requester
	    type.  Example: FILF_SAVE for FileRequester.
	ASL_ExtFlags1 (ULONG) - Extended flags (to pass FILF1_ bitdefs)
		   Example: FIL1F_NOFILES for file requester

  RESULT
	If NULL, typically the user cancelled the requester or a system
	failure prevented the requester from being opened.  If non-zero,
	values will be set depending on the particular type of request,
	in the requesting data structure.  See "libraries/asl.h" for
	information on the READ-ONLY fields in each specific type of
	requester.

  NOTES

	Asl provides a way for applications to interact with requester
	operation via a callback (hook) function.  For the ASL file and
	font requesters, there are two ASL_FuncFlags to specify that you
	want a callback:

	     for FileRequester: FILF_DOWILDFUNC and FILF_DOMSGFUNC
	     for FontRequester: FONF_DOWILDFUNC and FONF_DOMSGFUNC

	The DOWILDFUNC allows you to perform the pattern matching.
	The DOMSGFUNC allows you to handle IDCMP messages received
	for windows that are sharing a UserPort with the requester.

	If you set one or both of these flags via the ASL_FuncFlags
	tagitem, you must provide a pointer to your hook function
	using the ASL_HookFunc tagitem.  Your function will be called
	as follows:

	 ULONG rf_Function(ULONG Mask, CPTR Object, CPTR AslRequester)

	The Mask value is a copy of the specific ASL_FuncFlag value
	the callback is for.  Object is a pointer to a data object
	specific to the reason for the callback (defined by Mask).
	AslRequester is a pointer to the requester structure.

	Note that you can only define one HookFunc per requester.
	Your hook function must examine the Mask passed to it to
	determine what the callback is for and what the Object is.

	The following table will explain what is passed to, and
	expected to be returned by a hook functions for various masks:

	FileRequester DOWILDFUNC
	Purpose: to accept or reject individual files for display list
	Inputs:	Mask		= FILF_DOWILDFUNC
		Object		= struct AnchorPath *
		AslRequester	= struct FileRequester *
	Result: You return zero to accept file for display in list


	FontRequester DOWILDFUNC
	Purpose: to accept or reject individual fonts for display list
	Inputs:	Mask		= FONF_DOWILDFUNC
		Object		= struct TextAttr *
		AslRequester	= struct FontRequester *
	Result: You return non-zero to accept font for display in list


	FileRequester (or FontRequester) DOMSGFUNC
	Purpose: to handle IDCMP msgs for other windows sharing port
	Inputs:	Mask		= FILF_DOMSGFUNC (FONF_DOMSGFUNC)
		Object		= struct IntuiMessage *
		AslRequester	= struct FileRequester (FontRequester) *
	Result: You must return the Object pointer (asl will Reply the Object)

  SEE ALSO
	AllocAslRequest(), FreeAslRequest()


asl.library/FreeAslRequest			     asl.library/FreeAslRequest

  NAME
	FreeAslRequest - frees requester obtained from AllocAslRequest (V36)

  SYNOPSIS
	FreeAslRequest( request )
			A0

	APTR request;

  FUNCTION
	FreeAslRequest() is used to free the structure returned by
	AllocAslRequest() or AllocFileRequest(), in order to free
	all resources associated with that requester after the
	application has completed all use of the data structures.

  INPUTS
	request - value returned from AllocAslRequest() or
			AllocFileRequest().

  RESULT
	None.  All resources associated with the request will be
	freed.

  SEE ALSO
	AllocAslRequest(), AslRequest(), AllocFileRequest()


asl.library/FreeFileRequest			    asl.library/FreeFileRequest

  NAME
	FreeFileRequest -- frees requester allocated by AllocFileRequest (V36)

  SYNOPSIS
	FreeFileRequest( request )
			 A0

	struct FileRequester *request;

  FUNCTION
	This function is identical to the FreeAslRequest() function, but is
	documented for source code compatability and ease of use.
	Applications may use either FreeAslRequest() or FreeFileRequest() to
	free the data structures allocated by AllocFileRequest().

  INPUTS
	request = the return value from AllocFileRequest().

  SEE ALSO
	FreeAslRequest()

asl.library/RequestFile					asl.library/RequestFile

  NAME
	RequestFile -- request user to select file(s) (V36)

  SYNOPSIS
	BOOL result = RequestFile( request )
	D0                         A0

	BOOL	result;
	struct FileRequester *request;

  FUNCTION
	RequestFile() displays a file requester and waits for the user to
	select filenames or cancel the request.  This function is identical
	to the AslRequest() function, except that there is no TagList to
	modify the settings for the requester.  See AslRequest() for details.

  INPUT
	request = struct FileRequester * returned by AllocFileRequest().

  RESULT
	result - See AslRequest() result.  NULL indicates cancelled.

  SEE ALSO
	AllocFileRequest(), FreeFileRequest(), AslRequest()




[Back to Amiga Developer Docs]