ASL Library - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:18:47Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:18, 26 January 2025
Line 24:		Line 24:
	Opening an ASL requester requires the use of three functions:		Opening an ASL requester requires the use of three functions:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR request = AllocAslRequest( ULONG type, struct TagItem *tagList );		APTR request = AllocAslRequest( ULONG type, struct TagItem *tagList );
	APTR request = AllocAslRequestTags( uint32 type, Tag Tag1, ... );		APTR request = AllocAslRequestTags( uint32 type, Tag Tag1, ... );
Line 117:		Line 117:
	A requester always passes three parameters to your custom hook function:		A requester always passes three parameters to your custom hook function:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester)		ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester)
	</syntaxhighlight>		</syntaxhighlight>
Line 168:		Line 168:
	The following example illustrates the use of a hook function for both _DOWILDFUNC and _DOMSGFUNC.		The following example illustrates the use of a hook function for both _DOWILDFUNC and _DOMSGFUNC.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** filehook.c		** filehook.c

Costel Mincea: /* ASL Library */

2022-04-06T10:14:21Z

ASL Library

← Older revision		Revision as of 10:14, 6 April 2022
Line 2:		Line 2:
	== ASL Library ==		== ASL Library ==

	A)pplication S)~~tandard~~ L)ibrary		A)pplication S)upport L)ibrary

	This article describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.		This article describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.

Costel Mincea at 08:54, 6 April 2022

2022-04-06T08:54:21Z

← Older revision		Revision as of 08:54, 6 April 2022
Line 1:		Line 1:
	{{WIP}}		{{WIP}}
	== ASL Library ==		== ASL Library ==

			A)pplication S)tandard L)ibrary

	This article describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.		This article describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.

Steven Solie: /* Calling Custom Functions from a Requester */

2015-11-03T23:05:14Z

Calling Custom Functions from a Requester

← Older revision		Revision as of 23:05, 3 November 2015
Line 109:		Line 109:
	The FILF_DOWILDFUNC and FONF_DOWILDFUNC flags cause a requester to call the function you specify with the ASL_HookFunc tag for every file or font entry. The requester displays the file or font name only if your hook function tells it to. For a file requester, if your hook function returns a zero, the file requester will display the file name. For a font requester, if your hook function returns anything but zero, the font requester will display the font name and size.		The FILF_DOWILDFUNC and FONF_DOWILDFUNC flags cause a requester to call the function you specify with the ASL_HookFunc tag for every file or font entry. The requester displays the file or font name only if your hook function tells it to. For a file requester, if your hook function returns a zero, the file requester will display the file name. For a font requester, if your hook function returns anything but zero, the font requester will display the font name and size.

	The FILF_DOMSGFUNC and FONF_DOMSGFUNC flags cause a requester to call your hook function whenever it receives an IntuiMessage that it cannot use at the IDCMP port that it shares with your window. (See the section on "ASL Requesters and Custom Screens" ~~earlier~~ in ~~this~~ ~~chapter~~ for more information about sharing IDCMP ports.) If the requester receives any messages that are not meant for the requester it will call your hook function (specified with the ASL_HookFunc tag). Your hook function is responsible for returning a pointer to the IntuiMessage. The requester will take care of replying to the message.		The FILF_DOMSGFUNC and FONF_DOMSGFUNC flags cause a requester to call your hook function whenever it receives an IntuiMessage that it cannot use at the IDCMP port that it shares with your window. (See the section on [[#ASL Requesters and Custom Screens\|ASL Requesters and Custom Screens]] for more information about sharing IDCMP ports.) If the requester receives any messages that are not meant for the requester it will call your hook function (specified with the ASL_HookFunc tag). Your hook function is responsible for returning a pointer to the IntuiMessage. The requester will take care of replying to the message.

	=== Parameters Passed to Custom Hook Functions ===		=== Parameters Passed to Custom Hook Functions ===
Line 115:		Line 115:
	A requester always passes three parameters to your custom hook function:		A requester always passes three parameters to your custom hook function:

			<syntaxhighlight>
	<pre>
	ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester)		ULONG MyHookFunc(ULONG type, CPTR object, CPTR AslRequester)
			</syntaxhighlight>
	</pre>

	If MyHookFunc() is called from a file requester doing _DOWILDFUNC, the three parameters are:		If MyHookFunc() is called from a file requester doing _DOWILDFUNC, the three parameters are:

Steven Solie: /* ASL Library */

2015-11-03T23:03:38Z

ASL Library

← Older revision		Revision as of 23:03, 3 November 2015
Line 2:		Line 2:
	== ASL Library ==		== ASL Library ==

	This ~~chapter~~ describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.		This article describes the asl.library. The sole purpose of this library is to provide standard file and font requesters for application programs.

	It is easier to understand the asl.library if you are familiar with some basic concepts of the Amiga operating system, especially TagItem arrays (described in [[Utility_Library\|Utility Library]]), Intuition screens and windows, graphics library font structures, and AmigaDOS pattern matching.		It is easier to understand the asl.library if you are familiar with some basic concepts of the Amiga operating system, especially TagItem arrays (described in [[Utility_Library\|Utility Library]]), Intuition screens and windows, graphics library font structures, and AmigaDOS pattern matching.

Steven Solie: /* Creating an ASL Requester */

2014-04-25T14:53:42Z

Creating an ASL Requester

← Older revision		Revision as of 14:53, 25 April 2014
Line 22:		Line 22:
	Opening an ASL requester requires the use of three functions:		Opening an ASL requester requires the use of three functions:

			<syntaxhighlight>
	<pre>
	APTR request = AllocAslRequest( ULONG type, struct TagItem *tagList );		APTR request = AllocAslRequest( ULONG type, struct TagItem *tagList );
			APTR request = AllocAslRequestTags( uint32 type, Tag Tag1, ... );
	BOOL success = AslRequest( APTR request, struct TagItem *tagList );		BOOL success = AslRequest( APTR request, struct TagItem *tagList );
			BOOL success = AslRequestTags( APTR request, Tag Tag1, ... );
	VOID FreeAslRequest( APTR request );		VOID FreeAslRequest( APTR request );
			</syntaxhighlight>
	</pre>

	The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either a FileRequester structure or a FontRequester structure. You specify the type of requester you want for AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: either ASL_FileRequest, to ask for a FileRequester structure, or ASL_FontRequest, to ask for a FontRequester structure.		The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either a FileRequester structure or a FontRequester structure. You specify the type of requester you want for AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: either ASL_FileRequest, to ask for a FileRequester structure, or ASL_FontRequest, to ask for a FontRequester structure.

Steven Solie: /* Displaying an ASL Requester */

2014-04-25T14:50:55Z

Displaying an ASL Requester

← Older revision		Revision as of 14:50, 25 April 2014
Line 45:		Line 45:

	Generally, options that you wish to specify only once, such as the initial position and size, should be specified as tags when you allocate the requester. Options that you wish to control for each use of the requester should be passed as tags each time the requester is opened with AslRequest().		Generally, options that you wish to specify only once, such as the initial position and size, should be specified as tags when you allocate the requester. Options that you wish to control for each use of the requester should be passed as tags each time the requester is opened with AslRequest().

			=== ASL Requesters and Custom Screens ===

			An application that uses a custom screen normally wants its requesters to open on its screen. Using the ASL_Window tag, a program can associate a requester with a specific window so that the requester appears on the same screen as the window. The ASL_Window tag is followed by a pointer to a window structure. ASL_Window works with both file and font requesters.

			Normally, a requester associated with a window (using ASL_Window) shares that window's IDCMP port for its communication. An application may not want to share an IDCMP port with the requester. Using the ASL_FuncFlags tag, a program can ask for a requester that creates its own IDCMP port. There are two flags that accomplish this. The first, FILF_NEWIDCMP, is used on file requesters. The other, FONF_NEWIDCMP, is used on font requesters.

	== Freeing an ASL Requester ==		== Freeing an ASL Requester ==

Steven Solie: /* Displaying an ASL Requester */

2014-04-25T14:48:38Z

Displaying an ASL Requester

← Older revision		Revision as of 14:48, 25 April 2014
Line 41:		Line 41:

	AslRequest() is always synchronous to the calling program. That is, control does not return to your program until the user makes a selection or cancels. AslRequest() returns TRUE, if the user selects a file (or a font). In that case the file (or font) name that the user selected is returned in the requester data structure. AslRequest() returns FALSE if the user cancels the requester or the requester failed for some reason.		AslRequest() is always synchronous to the calling program. That is, control does not return to your program until the user makes a selection or cancels. AslRequest() returns TRUE, if the user selects a file (or a font). In that case the file (or font) name that the user selected is returned in the requester data structure. AslRequest() returns FALSE if the user cancels the requester or the requester failed for some reason.

			The contents of an ASL requester data structure are preserved across calls to AslRequest(). So, until the requester is freed, tag settings and user selections will remain in the data structure unless they are altered by tags in subsequent calls to AslRequest(). This is very useful because it allows the requester to remember and redisplay the user's previous selections. However, this also means that the programmer must assure that any addresses passed in ASL tags remain valid, or are refreshed on each call to AslRequest().

			Generally, options that you wish to specify only once, such as the initial position and size, should be specified as tags when you allocate the requester. Options that you wish to control for each use of the requester should be passed as tags each time the requester is opened with AslRequest().

	== Freeing an ASL Requester ==		== Freeing an ASL Requester ==

Steven Solie: /* Creating an ASL Requester */

2014-04-25T14:46:05Z

Creating an ASL Requester

← Older revision		Revision as of 14:46, 25 April 2014
Line 29:		Line 29:

	The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either a FileRequester structure or a FontRequester structure. You specify the type of requester you want for AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: either ASL_FileRequest, to ask for a FileRequester structure, or ASL_FontRequest, to ask for a FontRequester structure.		The first function you should call is AllocAslRequest(). This allocates the main data structure you will use, either a FileRequester structure or a FontRequester structure. You specify the type of requester you want for AllocAslRequest() by setting the type argument. This can be one of two values defined in <libraries/asl.h>: either ASL_FileRequest, to ask for a FileRequester structure, or ASL_FontRequest, to ask for a FontRequester structure.

			Both AllocAslRequest() and AslRequest() accept a TagItem array or tag list as an argument. The tag list is used to initialize or alter the values in the requester data structure.

			A single TagItem consists of a tag name and an associated tag value. Tag items that apply to the asl.library are defined in <libraries/asl.h>.

	Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function call. Do not create the data structure yourself. The values in this structure are for ''read access only''. Any changes to them must be performed only through asl.library function calls.		Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function call. Do not create the data structure yourself. The values in this structure are for ''read access only''. Any changes to them must be performed only through asl.library function calls.

Steven Solie: /* Creating an ASL Requester */

2014-04-25T14:43:22Z

Creating an ASL Requester

← Older revision		Revision as of 14:43, 25 April 2014
Line 31:		Line 31:

	Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function call. Do not create the data structure yourself. The values in this structure are for ''read access only''. Any changes to them must be performed only through asl.library function calls.		Whichever requester type you use, you must allocate the requester structure with the AllocAslRequest() function call. Do not create the data structure yourself. The values in this structure are for ''read access only''. Any changes to them must be performed only through asl.library function calls.

			== Displaying an ASL Requester ==

	Once you have set up a requester structure with AllocAslRequest(), call AslRequest() to make the requester appear on screen. AslRequest() takes the requester data structure as an argument using it as a specification for the requester that it creates on screen.		Once you have set up a requester structure with AllocAslRequest(), call AslRequest() to make the requester appear on screen. AslRequest() takes the requester data structure as an argument using it as a specification for the requester that it creates on screen.

			AslRequest() is always synchronous to the calling program. That is, control does not return to your program until the user makes a selection or cancels. AslRequest() returns TRUE, if the user selects a file (or a font). In that case the file (or font) name that the user selected is returned in the requester data structure. AslRequest() returns FALSE if the user cancels the requester or the requester failed for some reason.

			== Freeing an ASL Requester ==

			When you have finished with a requester use the FreeAslRequest() function to deallocate the requester data structure.

	== Common Tags Used by All Requester Types ==		== Common Tags Used by All Requester Types ==