Intuition Special Functions - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:29:48Z

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

← Older revision		Revision as of 19:29, 26 January 2025
Line 9:		Line 9:
	It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not change any variables and IntuitionBase will remain static during the access. The call LockIBase() will lock the state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to IntuitionBase.		It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not change any variables and IntuitionBase will remain static during the access. The call LockIBase() will lock the state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to IntuitionBase.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	ULONG LockIBase( ULONG dontknow );		ULONG LockIBase( ULONG dontknow );
	</syntaxhighlight>		</syntaxhighlight>
Line 17:		Line 17:
	Every call to LockIBase() must be matched by a subsequent call to UnlockIBase():		Every call to LockIBase() must be matched by a subsequent call to UnlockIBase():

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID UnlockIBase( ULONG ibLock );		VOID UnlockIBase( ULONG ibLock );
	</syntaxhighlight>		</syntaxhighlight>
Line 39:		Line 39:
	The AllocRemember() call takes three arguments:		The AllocRemember() call takes three arguments:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	APTR AllocRemember( struct Remember **rememberKey, ULONG size, ULONG flags );		APTR AllocRemember( struct Remember **rememberKey, ULONG size, ULONG flags );
	</syntaxhighlight>		</syntaxhighlight>
Line 51:		Line 51:
	The FreeRemember() call is as follows:		The FreeRemember() call is as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID FreeRemember( struct Remember **rememberKey, LONG reallyForget );		VOID FreeRemember( struct Remember **rememberKey, LONG reallyForget );
	</syntaxhighlight>		</syntaxhighlight>
Line 61:		Line 61:
	To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the ''remember key''.		To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the ''remember key''.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Remember *rememberKey = NULL;		struct Remember *rememberKey = NULL;
	</syntaxhighlight>		</syntaxhighlight>
Line 67:		Line 67:
	Call AllocRemember() with the address of the remember key, along with the memory requirements for the specific allocation. Multiple allocations may be made before a call to FreeRemember().		Call AllocRemember() with the address of the remember key, along with the memory requirements for the specific allocation. Multiple allocations may be made before a call to FreeRemember().

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR \| MEMF_PRIVATE);		memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR \| MEMF_PRIVATE);
	if (memBlockA == NULL)		if (memBlockA == NULL)
Line 85:		Line 85:
	To free memory that has been allocated, simply call FreeRemember() with the correct remember key.		To free memory that has been allocated, simply call FreeRemember() with the correct remember key.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	IIntuition->FreeRemember(&rememberKey, TRUE);		IIntuition->FreeRemember(&rememberKey, TRUE);
	</syntaxhighlight>		</syntaxhighlight>
Line 95:		Line 95:
	The Remember structure is defined in <intuition/intuition.h> as follows:		The Remember structure is defined in <intuition/intuition.h> as follows:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	struct Remember		struct Remember
	{		{
Line 117:		Line 117:
	=== An Example of Remembering ===		=== An Example of Remembering ===

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	/*		/*
	** RememberTest - Illustrates the use of AllocRemember() and FreeRemember().		** RememberTest - Illustrates the use of AllocRemember() and FreeRemember().
Line 264:		Line 264:
	The function CurrentTime() gets the current time values. To use this function, first declare the variables Seconds and Micros. Then, when the application call the function, the current time is copied into the argument pointers.		The function CurrentTime() gets the current time values. To use this function, first declare the variables Seconds and Micros. Then, when the application call the function, the current time is copied into the argument pointers.

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	VOID CurrentTime( ULONG seconds, ULONG micros );		VOID CurrentTime( ULONG seconds, ULONG micros );
	</syntaxhighlight>		</syntaxhighlight>

Steven Solie at 18:03, 4 November 2015

2015-11-04T18:03:24Z

← Older revision		Revision as of 18:03, 4 November 2015
Line 1:		Line 1:
	== Intuition Special Functions ==		== Intuition Special Functions ==

	There are several Intuition topics which, while not large enough to fill ~~chapters~~ of their own, nonetheless deserve to be discussed. The subjects covered here include locking IntuitionBase, the Intuition memory functions AllocRemember() and FreeRemember(), using sprites with Intuition, and Intuition's special internal functions.		There are several Intuition topics which, while not large enough to fill articles of their own, nonetheless deserve to be discussed. The subjects covered here include locking IntuitionBase, the Intuition memory functions AllocRemember() and FreeRemember(), using sprites with Intuition, and Intuition's special internal functions.

	== Locking IntuitionBase ==		== Locking IntuitionBase ==
Line 305:		Line 305:
	== Function Reference ==		== Function Reference ==

	The following are brief descriptions of the Intuition functions discussed in this ~~chapter~~. See the SDK for details on each function call.		The following are brief descriptions of the Intuition functions discussed in this article. See the SDK for details on each function call.

	{\| class="wikitable"		{\| class="wikitable"

Steven Solie at 19:24, 14 March 2014

2014-03-14T19:24:23Z

← Older revision		Revision as of 19:24, 14 March 2014
Line 1:		Line 1:
	{{CodeReview}}
	== Intuition Special Functions ==		== Intuition Special Functions ==

Steven Solie: /* An Example of Remembering */

2014-03-14T19:24:08Z

An Example of Remembering

Show changes

Steven Solie: /* The Remember Structure */

2014-03-14T19:15:00Z

The Remember Structure

← Older revision		Revision as of 19:15, 14 March 2014
Line 96:		Line 96:
	The Remember structure is defined in <intuition/intuition.h> as follows:		The Remember structure is defined in <intuition/intuition.h> as follows:

			<syntaxhighlight>
	<pre>
	struct Remember		struct Remember
	{		{
Line 103:		Line 103:
	UBYTE *Memory;		UBYTE *Memory;
	};		};
			</syntaxhighlight>
	</pre>

	Generally, the Remember structure is handled only by the system. Here are its fields:		Generally, the Remember structure is handled only by the system. Here are its fields:

Steven Solie: /* Intuition Helps You Remember */

2014-03-14T19:14:36Z

Intuition Helps You Remember

← Older revision		Revision as of 19:14, 14 March 2014
Line 40:		Line 40:
	The AllocRemember() call takes three arguments:		The AllocRemember() call takes three arguments:

			<syntaxhighlight>
	<pre>
	APTR AllocRemember( struct Remember **rememberKey, ULONG size, ULONG flags );		APTR AllocRemember( struct Remember **rememberKey, ULONG size, ULONG flags );
			</syntaxhighlight>
	</pre>

	The rememberKey is the address of a pointer to a Remember structure. Note that this is a double indirection, not just a simple pointer. The size is the size, in bytes, of the requested allocation. The flags argument is the specification for the memory allocation. These are the same as the specifications for the Exec AllocMem() function described in [[Exec_Memory_Allocation\|Exec Memory Allocation]].		The rememberKey is the address of a pointer to a Remember structure. Note that this is a double indirection, not just a simple pointer. The size is the size, in bytes, of the requested allocation. The flags argument is the specification for the memory allocation. These are the same as the specifications for the Exec AllocMem() function described in [[Exec_Memory_Allocation\|Exec Memory Allocation]].
Line 52:		Line 52:
	The FreeRemember() call is as follows:		The FreeRemember() call is as follows:

			<syntaxhighlight>
	<pre>
	VOID FreeRemember( struct Remember **rememberKey, LONG reallyForget );		VOID FreeRemember( struct Remember **rememberKey, LONG reallyForget );
			</syntaxhighlight>
	</pre>

	Set the rememberKey argument to the address of a pointer to a Remember structure. This is the same value that was passed to previous calls to AllocRemember(). The reallyForget argument is a boolean that should be set to TRUE. If TRUE, then both the link nodes and the memory blocks are freed. If FALSE, then only the link nodes are freed. Again, applications should avoid using the FALSE value since it can lead to highly fragmented memory.		Set the rememberKey argument to the address of a pointer to a Remember structure. This is the same value that was passed to previous calls to AllocRemember(). The reallyForget argument is a boolean that should be set to TRUE. If TRUE, then both the link nodes and the memory blocks are freed. If FALSE, then only the link nodes are freed. Again, applications should avoid using the FALSE value since it can lead to highly fragmented memory.

Steven Solie: /* Locking IntuitionBase */

2014-03-14T19:14:06Z

Locking IntuitionBase

← Older revision		Revision as of 19:14, 14 March 2014
Line 10:		Line 10:
	It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not change any variables and IntuitionBase will remain static during the access. The call LockIBase() will lock the state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to IntuitionBase.		It is necessary to inform Intuition that an application is about to examine IntuitionBase so that Intuition will not change any variables and IntuitionBase will remain static during the access. The call LockIBase() will lock the state of IntuitionBase so that it may be examined. During the time that the application has IntuitionBase locked, all Intuition input processing is frozen. Make every effort to examine IntuitionBase and release the lock as quickly as possible. The values in IntuitionBase are read-only. Applications should never write values to IntuitionBase.

			<syntaxhighlight>
	<pre>
	ULONG LockIBase( ULONG dontknow );		ULONG LockIBase( ULONG dontknow );
			</syntaxhighlight>
	</pre>

	LockIBase() is passed a ULONG (dontknow in the prototype above) indicating the Intuition lock desired. For all foreseeable uses of the call this value should be 0. LockIBase() returns a ULONG, that must be passed to UnlockIBase() later to allow IntuitionBase to change once again.		LockIBase() is passed a ULONG (dontknow in the prototype above) indicating the Intuition lock desired. For all foreseeable uses of the call this value should be 0. LockIBase() returns a ULONG, that must be passed to UnlockIBase() later to allow IntuitionBase to change once again.
Line 18:		Line 18:
	Every call to LockIBase() must be matched by a subsequent call to UnlockIBase():		Every call to LockIBase() must be matched by a subsequent call to UnlockIBase():

			<syntaxhighlight>
	<pre>
	VOID UnlockIBase( ULONG ibLock );		VOID UnlockIBase( ULONG ibLock );
			</syntaxhighlight>
	</pre>

	Set the ibLock argument to the value returned by the previous call to LockIBase().		Set the ibLock argument to the value returned by the previous call to LockIBase().

Steven Solie: /* Current Time Values */

2013-05-23T19:46:19Z

Current Time Values

← Older revision		Revision as of 19:46, 23 May 2013
Line 270:		Line 270:
	== Current Time Values ==		== Current Time Values ==

		⚫	The function CurrentTime() gets the current time values. To use this function, first declare the variables Seconds and Micros. Then, when the application call the function, the current time is copied into the argument pointers.

			<syntaxhighlight>
		⚫	VOID CurrentTime( ULONG seconds, ULONG micros );
			</syntaxhighlight>

		⚫	See the DOS library Autodocs for more information on functions dealing with the date and time. The DOS library includes such functions as DateToStr(), StrToDate(), SetFileDate() and CompareDates().
⚫	The function CurrentTime() gets the current time values. To use this function, first declare the variables Seconds and Micros. Then, when the application call the function, the current time is copied into the argument pointers.

⚫	~~<pre>~~VOID CurrentTime( ULONG seconds, ULONG micros );~~</pre>~~
⚫	See the DOS library Autodocs ~~in the ''AmigaDOS Manual''~~ for more information on functions dealing with the date and time. The DOS library includes such functions as DateToStr(), StrToDate(), SetFileDate() and CompareDates().

	== Using Sprites in Intuition Windows and Screens ==		== Using Sprites in Intuition Windows and Screens ==

Steven Solie: /* How to Remember */

2013-05-23T19:43:57Z

How to Remember

← Older revision		Revision as of 19:43, 23 May 2013
Line 62:		Line 62:
	To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the ''remember key''.		To use Intuition's memory functions, first create an anchor for the memory to be allocated by declaring a variable that is a pointer to a Remember structure and initializing that pointer to NULL. This variable is called the ''remember key''.

			<syntaxhighlight>
	<pre>
	struct Remember *rememberKey = NULL;		struct Remember *rememberKey = NULL;
			</syntaxhighlight>
	</pre>

	Call AllocRemember() with the address of the remember key, along with the memory requirements for the specific allocation. Multiple allocations may be made before a call to FreeRemember().		Call AllocRemember() with the address of the remember key, along with the memory requirements for the specific allocation. Multiple allocations may be made before a call to FreeRemember().

			<syntaxhighlight>
	<pre>
	memBlockA = AllocRemember(&~~amp;~~rememberKey, SIZE_A, MEMF_CLEAR \| ~~MEMF_PUBLIC~~);		memBlockA = IIntuition->AllocRemember(&rememberKey, SIZE_A, MEMF_CLEAR \| MEMF_PRIVATE);
	if (memBlockA == NULL)		if (memBlockA == NULL)
	{		{
	/* error: allocation failed */		/* error: allocation failed */
	~~printf~~(~~"~~Memory allocation failed.\n~~"~~);		IDOS->Printf("Memory allocation failed.\n");
	}		}
	else		else
	{		{
	/* use the memory here */		/* use the memory here */
	~~printf~~(~~"~~Memory allocation succeeded.\n~~"~~);		IDOS->Printf("Memory allocation succeeded.\n");
	}		}
			</syntaxhighlight>
	</pre>

	AllocRemember() actually performs two memory allocations per call, one for the memory requested and the other for a Remember structure. The Remember structure is filled in with data describing the allocation, and is linked into the list to which the ''remember key'' points.		AllocRemember() actually performs two memory allocations per call, one for the memory requested and the other for a Remember structure. The Remember structure is filled in with data describing the allocation, and is linked into the list to which the ''remember key'' points.
Line 86:		Line 86:
	To free memory that has been allocated, simply call FreeRemember() with the correct remember key.		To free memory that has been allocated, simply call FreeRemember() with the correct remember key.

			<syntaxhighlight>
	<pre>
	~~VOID~~ FreeRemember(&~~amp;~~rememberKey, TRUE);		IIntuition->FreeRemember(&rememberKey, TRUE);
			</syntaxhighlight>
	</pre>

	This will free all the memory blocks previously allocated with AllocRemember() in a single call.		This will free all the memory blocks previously allocated with AllocRemember() in a single call.

Steven Solie: /* Function Reference */

2012-11-26T19:43:38Z

Function Reference

← Older revision		Revision as of 19:43, 26 November 2012
Line 314:		Line 314:
	The following are brief descriptions of the Intuition functions discussed in this chapter. See the SDK for details on each function call.		The following are brief descriptions of the Intuition functions discussed in this chapter. See the SDK for details on each function call.

		⚫	{\| class="wikitable"
	<table>
			! Function
⚫	~~<tr~~ class="~~header~~">
			! Description
	<th align="left">'''Function'''</th>
			\|-
	<th align="left">'''Description'''</th>
		⚫	\| AllocRemember()
	</tr>
		⚫	\| Allocate memory and track the allocation.
	<tr class="odd">
			\|-
⚫	~~<td~~ ~~align="left">~~AllocRemember()~~</td>~~
		⚫	\| FreeRemember()
⚫	~~<td~~ ~~align="left">~~Allocate memory and track the allocation.~~</td>~~
		⚫	\| Free memory allocated with AllocRemember().
	</tr>
			\|-
	<tr class="even">
			\| LockIBase()
⚫	~~<td~~ ~~align="left">~~FreeRemember()~~</td>~~
		⚫	\| Lock IntuitionBase for reading.
⚫	~~<td~~ ~~align="left">~~Free memory allocated with AllocRemember().~~</td>~~
			\|-
	</tr>
			\| UnlockIBase()
	<tr class="odd">
		⚫	\| Unlock IntuitionBase when done reading.
	<td align="left">LockIBase()</td>
			\|-
⚫	~~<td~~ ~~align="left">~~Lock IntuitionBase for reading.~~</td>~~
			\| CurrentTime()
	</tr>
		⚫	\| Get the system time in seconds and micro-seconds.
	<tr class="even">
			\|-
	<td align="left">UnlockIBase()</td>
			\| SetPrefs()
⚫	~~<td~~ ~~align="left">~~Unlock IntuitionBase when done reading.~~</td>~~
		⚫	\| An Intuition internal function you should try to avoid.
	</tr>
			\|}
	<tr class="odd">
	<td align="left">CurrentTime()</td>
⚫	~~<td~~ ~~align="left">~~Get the system time in seconds and micro-seconds.~~</td>~~
	</tr>
	<tr class="even">
	<td align="left">SetPrefs()</td>
⚫	~~<td~~ ~~align="left">~~An Intuition internal function you should try to avoid.~~</td>~~
	</tr>
	</table>