AmigaOS Documentation Wiki - User contributions [en]

RealTime Library

2026-04-13T07:11:45Z

Daniel Jedlicka: Unified parameter reference style.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 1200 Hz, so clock pulses are delivered approximately every 0.83 ms. This is good enough even for timing-critical applications such as MIDI sequencing.

There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_AlarmSigTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (player != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(player,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up Player structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a Player with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_AlarmSigTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState(); [[#More About Conductors|see below]]. This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct Player *player, Tag tag, ...);
</syntaxhighlight>

The ''player'' parameter indicates which Player structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks) whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (player != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(player);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pl->pl_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 1200 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pl->pl_Userdata)) < pl->pl_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by Player structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct Player *player, int32 newstate, int32 ti);
</syntaxhighlight>

The ''player'' parameter is a pointer to a Player structure that is linked to the Conductor you want to change. The ''ti'' parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CONDSTATE_STOPPED || The clock is not running
|-
| CONDSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CONDSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Players) that are ready.
|-
| CONDSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their Player to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Player has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CONDSTATE_LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Player is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T07:08:22Z

Daniel Jedlicka: Fixed internal link.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 1200 Hz, so clock pulses are delivered approximately every 0.83 ms. This is good enough even for timing-critical applications such as MIDI sequencing.

There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_AlarmSigTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (player != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(player,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up Player structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a Player with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_AlarmSigTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState(); [[#More About Conductors|see below]]. This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct Player *player, Tag tag, ...);
</syntaxhighlight>

The player parameter indicates which Player structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks) whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (player != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(player);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pl->pl_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 1200 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pl->pl_Userdata)) < pl->pl_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by Player structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct Player *player, int32 newstate, int32 ti);
</syntaxhighlight>

The player parameter is a pointer to a Player structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CONDSTATE_STOPPED || The clock is not running
|-
| CONDSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CONDSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Players) that are ready.
|-
| CONDSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their Player to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Player has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CONDSTATE_LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Player is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T07:05:41Z

Daniel Jedlicka: Minor corrections

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 1200 Hz, so clock pulses are delivered approximately every 0.83 ms. This is good enough even for timing-critical applications such as MIDI sequencing.

There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_AlarmSigTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (player != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(player,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up Player structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a Player with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_AlarmSigTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState(); [[More About Conductors|see below]]. This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct Player *player, Tag tag, ...);
</syntaxhighlight>

The player parameter indicates which Player structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks) whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (player != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(player);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pl->pl_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 1200 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pl->pl_Userdata)) < pl->pl_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by Player structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct Player *player, int32 newstate, int32 ti);
</syntaxhighlight>

The player parameter is a pointer to a Player structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CONDSTATE_STOPPED || The clock is not running
|-
| CONDSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CONDSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Players) that are ready.
|-
| CONDSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their Player to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Player has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CONDSTATE_LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Player is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T06:59:52Z

Daniel Jedlicka: Corrected wrong information in the More About Conductors section.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 1200 Hz, so clock pulses are delivered approximately every 0.83 ms. This is good enough even for timing-critical applications such as MIDI sequencing.

There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_AlarmSigTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (player != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(player,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up Player structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a Player with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_AlarmSigTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState(); see below. This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct Player *player, Tag tag, ...);
</syntaxhighlight>

The player parameter indicates which Player structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks) whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (player != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(player);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pl->pl_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 1200 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pl->pl_Userdata)) < pl->pl_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by Player structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct Player *player, int32 newstate, int32 ti);
</syntaxhighlight>

The player parameter is a pointer to a Player structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CONDSTATE_STOPPED || The clock is not running
|-
| CONDSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CONDSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Players) that are ready.
|-
| CONDSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their Player to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Player has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CONDSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Player is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T06:53:06Z

Daniel Jedlicka: Corrected wrong information in the Getting Clock Ticks section.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 1200 Hz, so clock pulses are delivered approximately every 0.83 ms. This is good enough even for timing-critical applications such as MIDI sequencing.

There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_AlarmSigTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (player != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(player,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up Player structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a Player with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_AlarmSigTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState(); see below. This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct Player *player, Tag tag, ...);
</syntaxhighlight>

The player parameter indicates which Player structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks) whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (player != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(player, CONDSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(player);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pl->pl_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 1200 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct Player *pl)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pl->pl_Userdata)) < pl->pl_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct PlayerInfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (PlayerInfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each PlayerInfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the PlayerInfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T06:34:17Z

Daniel Jedlicka: Removed references to struct PlayerInfo because it's in fact called Player.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a Player is set up by each client application that wants to get timing information from the Conductor. There is typically one Player for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Player structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single Player structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a Player structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Player structure you want to create. (A complete list of all the tags available can be found in the Autodoc for the SetPlayerAttrs() function.) It returns a pointer to the Player structure. Here’s a fragment showing how to set up a Player:

<syntaxhighlight lang="C" line>
struct Player *player = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (player != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(player);
}
</syntaxhighlight>

In the code above, a Player will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their Players to "My_conductor".

When your application finishes, you should delete any Players you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the Players attached to a Conductor are deleted).

Once you have a Player and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 600 Hz so clock pulses are delivered approximately every 1.66 ms. There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_SignalTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (pPlayerInfo != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(pPlayerInfo,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up PlayerInfo structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a PlayerInfo with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_SignalTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState() (discussed below). This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct PlayerInfo *pi, Tag tag, ...);
</syntaxhighlight>

The pi parameter indicates which PlayerInfo structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is
requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks)
whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (pPlayerInfo != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(pPlayerInfo);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pi>pi_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When
Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 600 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pi->pi_Userdata)) < pi->pi_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct PlayerInfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (PlayerInfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each PlayerInfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the PlayerInfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

RealTime Library

2026-04-13T06:27:43Z

Daniel Jedlicka: /* Conductors and Players */ - fixed section heading

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Players =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a PlayerInfo is set up by each client application that wants to get timing information from the Conductor. There is typically one PlayerInfo for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and PlayerInfo structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single PlayerInfo structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a PlayerInfo structure you call CreatePlayer():

<syntaxhighlight lang="C" line>
struct PlayerInfo *pi = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the PlayerInfo structure you want to create. (A complete list of all the tags available can be found in the Autodoc for SetPlayerAttrs().) It returns a pointer to the PlayerInfo. Here’s a fragment showing how to set up a PlayerInfo:

<syntaxhighlight lang="C" line>
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (pPlayerInfo != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(pPlayerInfo);
}
</syntaxhighlight>

In the code above, a PlayerInfo will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their PlayerInfos to "My_conductor".

When your application finishes, you should delete any PlayerInfos you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the PlayerInfos attached to a Conductor are deleted).

Once you have a PlayerInfo and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 600 Hz so clock pulses are delivered approximately every 1.66 ms. There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight lang="C" line>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_SignalTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (pPlayerInfo != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(pPlayerInfo,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up PlayerInfo structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a PlayerInfo with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_SignalTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState() (discussed below). This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight lang="C" line>
BOOL result = SetPlayerAttrs(struct PlayerInfo *pi, Tag tag, ...);
</syntaxhighlight>

The pi parameter indicates which PlayerInfo structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is
requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks)
whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight lang="C" line>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (pPlayerInfo != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(pPlayerInfo);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pi>pi_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When
Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight lang="C" line>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 600 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pi->pi_Userdata)) < pi->pi_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight lang="C" line>
int32 res = IRealTime->SetConductorState(struct PlayerInfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (PlayerInfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each PlayerInfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the PlayerInfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

GadTools Library

2024-12-07T07:59:40Z

Daniel Jedlicka: Added note that GadTools menus are now replaced by the Menu Class.

== GadTools Library ==

Originally, programming even straightforward user interfaces in [[Intuition_Library|Intuition]] could be rather complicated, and certainly difficult for first-time programmers. The GadTools toolkit was introduced in AmigaOS 2.x to simplify the task. It provided relatively easy-to-use, higher-level chunks to build [http://en.wikipedia.org/wiki/Graphical_user_interface GUIs] from, and to help programmers through what used to be a difficult chore.

{{Note|title=Note|text=As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended. Prefer using the object-oriented GUI programming framework based on [[BOOPSI]].}}

== Elements of GadTools ==

GadTools is the easy way to program gadgets and menus. With GadTools, the system handles the detail work required to control gadgets and menus so the application uses less code and simpler data structures.

Another key benefit of GadTools is its standardized and elegant look. All applications that use GadTools will share a similar appearance and behavior. Users will appreciate a sense of instant familiarity even the first time they use a product.

GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.

GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See [[Intuition_Gadgets|Intuition Gadgets]] and [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]] for more information.

=== GadTools Tags ===

Many of the GadTools functions use TagItem arrays or ''tag lists'' to pass information across the function interface. These tag-based functions come in two types, one that takes a pointer to an array of tag items and one that takes a variable number of tag item arguments directly in the function call. In general, the second form, often called the ''varargs'' form because the call takes a variable number of arguments, is provided for convenience and is internally converted to the first form. When looking through the Autodocs or other Amiga reference material, the documentation for both forms is usually available in the array-based function description.

All GadTools tags begin with a leading "GT". In general, they also have a two-letter mnemonic for the kind of gadget in question. For example, slider gadgets recognize tags such as "GTSL_Level". The GadTools tags are defined in <libraries/gadtools.h>. Certain GadTools gadgets also recognize other Intuition tags such as GA_Disabled and PGA_Freedom, which can be found in <intuition/gadgetclass.h>.

For more information on tags and tag-based functions, be sure to see the [[Utility_Library|Utility Library]].

== GadTools Gadgets ==

[[GadTools Gadgets]] are now largely superseded by [[BOOPSI Gadgets|gadgets]] based on the object-oriented [[BOOPSI - Object Oriented Intuition|BOOPSI framework]].

== GadTools Menus ==

[[GadTools Menus]] are now largely superseded by [[Intuition Menu Class|menus]] based on the object-oriented [[BOOPSI - Object Oriented Intuition|BOOPSI framework]].

== Function Reference ==

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

{| class="wikitable"
! Function
! Description
|-
| CreateGadgetA() CreateGadget()
| Allocate GadTools gadget.
|-
| FreeGadgets()
| Free all GadTools gadgets.
|-
| GT_SetGadgetAttrsA() GT_SetGadgetAttrs()
| Update gadget.
|-
| CreateContext()
| Create a base for adding GadTools gadgets.
|-
| CreateMenusA() CreateMenus()
| Allocate GadTools menu structures.
|-
| FreeMenus()
| Free menus allocated with CreateMenus().
|-
| LayoutMenuItemsA() LayoutMenuItems()
| Format GadTools menu items.
|-
| LayoutMenusA() LayoutMenus()
| Format GadTools menus.
|-
| GT_GetIMsg()
| GadTools gadget compatible version of GetMsg().
|-
| GT_ReplyIMsg()
| GadTools gadget compatible version of ReplyMsg().
|-
| GT_FilterIMsg()
| Process GadTools gadgets with GetMsg()/ReplyMsg().
|-
| GT_PostFilterIMsg()
| Process GadTools gadgets with GetMsg()/ReplyMsg().
|-
| GT_RefreshWindow()
| Display GadTools gadget imagery after creation.
|-
| GT_BeginRefresh()
| GadTools gadget compatible version of BeginRefresh().
|-
| GT_EndRefresh()
| GadTools gadget compatible version of EndRefresh().
|-
| DrawBevelBoxA() DrawBevelBox()
| Draw a 3D box.
|-
| GetVisualInfoA() GetVisualInfo()
| Get drawing information for GadTools.
|-
| FreeVisualInfo()
| Free drawing information for GadTools.
|}

Libraries

2024-12-07T07:50:03Z

Daniel Jedlicka: Moved the Menu Class page to the BOOPSI section where it really belongs.

== Introduction ==

A library is a set of related functions and data. For example, the AmigaOS's DOS library contains functions for accessing files and directories, and the Intuition library contains the graphical user interface functions.

There are three types of libraries: '''dynamically-loaded shared libraries''', '''dynamically linked libraries''', and '''static libraries'''. Shared libraries are shared by the running programs – only one copy of a library exists in the memory, no matter how many programs are using it. All AmigaOS's libraries are shared libraries. The shared library files can be recognized from the '''.library''' suffix.

A dynamically linked library is attached to a program during the load time, just before the program is executed. Linked library functions can't be shared by programs, and several copies of the library functions may exist in the memory. The linked library files can be recognized from the '''.so''' suffix.

A static library is like a linked library except it is attached permanently to a program when it is created. This makes it impossible for the user to update the library the program is using. Static libraries are supplied with programming languages.

== Shared Libraries ==
=== AmigaDOS ===

[[AmigaDOS Introduction]]

[[DOS Library]]
:[[AmigaDOS Data Structures|Data Structures]]
:[[Program Startup]]
:[[Basic Input and Output Programming]]
:[[Executing External Programs]]
:[[Cooperative Record Locking]]
:[[Notification]]
:[[Path Name Handling]]
:[[Pattern Matching]]
:[[Multiple Assigns]]
:[[AmigaDOS Packets|Packets]]
:[[AmigaDOS Vector-Port|Vector-Port]]
:[[Hard and Soft Links]]
:[[Writing a UserShell]]
:[[AmigaDOS Device Input and Output|Device Input and Output]]

=== User Interface Libraries ===

[[Intuition Library]]
:[[Intuition Screens|Screens]]
::[[Custom_Screen_Type|Custom Screen Type]]
::[[Public_Screen_Type|Public Screen Type]]
:[[Intuition Windows|Windows]]
::[[Window Types|Types]]
::[[Window Structures and Functions|Structures and Functions]]
::[[Window Communication|Communicating with Intuition]]
::[[Window Display Preservation|Display Preservation]]
:[[Intuition Gadgets|Gadgets]]
::[[Boolean_Gadget_Type|Boolean Gadget Type]]
::[[Proportional_Gadget_Type|Proportional Gadget Type]]
::[[String_Gadget_Type|String Gadget Type]]
:[[Intuition Menus|Menus]]
::[[Intuition Classic Menus|Classic Menus]]
::[[Intuition Context Menus|Context Menus]]
:[[Intuition Requesters|Requesters]]
:[[Intuition Alerts|Alerts]]
:[[Intuition Images, Line Drawing and Text|Images, Line Drawing and Text]]
::[[Intuition Images|Images]]
::[[Intuition Borders|Borders]]
::[[Intuition Text|Text]]
:[[Intuition Input and Output Methods|Input and Output Methods]]
:[[Intuition Mouse|Mouse]]
:[[Intuition Keyboard|Keyboard]]
:[[Intuition Pointer|Pointer]]
:[[Intuition Special Functions|Special Functions]]
:[[BOOPSI - Object Oriented Intuition]]
::[[BOOPSI Gadgets]]
::[[BOOPSI Images]]
::[[Intuition Menu Class|BOOPSI Menus]]
::[[BOOPSI Class Reference]]

[[Workbench Library]]

[[Icon Library]]

[[Locale Library]]

[[GadTools Library]]
:[[GadTools Menus]]
:[[GadTools Gadgets]]

[[ASL Library]]
:[[ASL File Requester|File Requester]]
:[[ASL Font Requester|Font Requester]]
:[[ASL Screen Mode Requester|Screen Mode Requester]]

[[Application Library]]
:[[PrefsObjects]]

[[Preferences]]

=== Graphics Libraries ===

[[Graphics Library]]
:[[Display Database]]
:[[Graphics Primitives|Primitives]]
::[[Classic Graphics Primitives|Classic Primitives]]
:[[Graphics Sprites, Bobs and Animation|Sprites, Bobs and Animation]]
::[[Hardware Sprites]]
::[[Virtual Sprites|Virtual Sprites (VSprites)]]
::[[Blitter Objects|Blitter Objects (Bobs)]]
:[[Graphics Library and Text|Text]]
:[[Graphics Regions|Regions]]
:[[Graphics Composited Video|Composited Video]]
:[[Graphics Video Overlay|Video Overlay]]
:[[Graphics Minterms|Minterms]]

[[Layers Library]]

=== Additional Libraries ===

[[AmigaGuide Library]]

[[Camd Library]]

[[Commodities Exchange Library]]

[[Datatypes Library]]
:[[Writing Datatype Classes]]

[[IFFParse Library]]
:[[Parsing IFF]]
:[[Writing IFF]]

[[Keymap Library]]

[[Newlib Library]]

[[PThreads Library]]

[[RealTime Library]]

[[Translator Library]]

[[DiskIO Library|Disk I/O Library]]

=== 68k Libraries ===

[[Math Libraries]]

=== Third-Party Libraries ===

[[Expat Library]]

[[Filesysbox Library]]

== Linked Libraries ==

=== Audio Libraries ===
libao

libogg

libvorbis

libvorbisenc

libvorbisfile

=== C/C++ Programming Language Libraries ===
libc

libgcc

libgcov

libicudata

libicuuc

libstdc++

=== Compression Libraries ===
libz

libbz2

=== Database Libraries ===
libsqlite

=== Dynamic Linking Libraries ===
libdl

=== File System Libraries ===
libntfs

=== File Transfer Libraries ===
libcurl

libssl

=== Graphics Libraries ===
libcairo

libfontconfig

libfreetype

libjpeg

libpixman

libpng

libpng12

libSDL

libSDL_gfx

=== Parallel Execution Libraries ===
libpthread

=== Python Programming Language Libraries ===
libpython

=== XML Libraries ===
libexpat

libxml

libxslt

== Static Libraries ==

[[Linker Libraries]]

RealTime Library

2023-04-06T08:42:05Z

Daniel Jedlicka: Fixed typos that probably resulted from OCR.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and PlayerInfos =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a PlayerInfo is set up by each client application that wants to get timing information from the Conductor. There is typically one PlayerInfo for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and PlayerInfo structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single PlayerInfo structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a PlayerInfo structure you call CreatePlayer():

<syntaxhighlight>
struct PlayerInfo *pi = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the PlayerInfo structure you want to create. (A complete list of all the tags available can be found in the Autodoc for SetPlayerAttrs().) It returns a pointer to the PlayerInfo. Here’s a fragment showing how to set up a PlayerInfo:

<syntaxhighlight>
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (pPlayerInfo != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(pPlayerInfo);
}
</syntaxhighlight>

In the code above, a PlayerInfo will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their PlayerInfos to "My_conductor".

When your application finishes, you should delete any PlayerInfos you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the PlayerInfos attached to a Conductor are deleted).

Once you have a PlayerInfo and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 600 Hz so clock pulses are delivered approximately every 1.66 ms. There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_SignalTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (pPlayerInfo != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(pPlayerInfo,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up PlayerInfo structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a PlayerInfo with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_SignalTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState() (discussed below). This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight>
BOOL result = SetPlayerAttrs(struct PlayerInfo *pi, Tag tag, ...);
</syntaxhighlight>

The pi parameter indicates which PlayerInfo structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is
requested using the PLAYER_AlarmTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks)
whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (pPlayerInfo != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(pPlayerInfo);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pi>pi_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When
Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 600 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pi->pi_Userdata)) < pi->pi_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating – see below)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight>
int32 res = IRealTime->SetConductorState(struct PlayerInfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (PlayerInfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock does not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each PlayerInfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the PlayerInfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

Application Library

2020-02-09T20:10:09Z

Daniel Jedlicka: /* Minimum Application Library Support */

== Introduction ==

The Application Library is a multipurpose auxiliary library that provides various functions related to the development and use of applications. The very concept of ''application'' is a relatively recent addition to AmigaOS. Before, the system only distinguished between different types of program on a very low level, seeing them as either [[Exec_Tasks|tasks]] or [[AmigaDOS_Data_Structures#Process_Data_Structures|processes]]. This distinction might have been useful in the past when tasks (which require fewer resources in return for not being able to access DOS functions) could improve system performance. But it can hardly make a difference on today’s hardware so the trade-offs are no longer worth it. Nowadays it makes more sense to discriminate between programs that operate without the user even noticing (e.g. drivers, handlers, filesystems and other ''background services''), and genuine full-blown ''applications'' with [[UI_Style_Guide_Glossary#GUI|GUI]] and all.

AmigaOS alone cannot make such a distinction: it uses the Application Library as a mediator through which applications introduce themselves to the system. This process is called [[#Registering the Application|application registration]], during which the application receives a [[#Application Identifiers|unique identifier]] and is added to a public list among other applications. Once registered, the application can make use of the library’s many features:

* It can send/receive messages to/from other registered applications. The library supports a set of common [[#Control Messages|control messages]] (commands) such as those telling an application to quit, iconify or bring its window to front. But it also allows [[#Custom Messages|custom messages]] designed for an application’s particular needs; in this respect the Application Library provides an alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]] control.

* It can turn into a “watchdog” and get notified when other applications register.

* It can use [[PrefsObjects]], an XML-based, object-oriented system for handling program preferences. Before AmigaOS 4.x no real standard existed for storing preferences: some developers used icon tooltypes, some used proprietary formats, text or binary. The Application Library provides a format that is human-readable and easily editable in a simple text editor; that is comprehensive enough to cover even very complex settings structures; and that is fully controllable via the library, without the need to laboriously implement data parsing and verification.

* It can notify the user about, for example, completed tasks via automatic [[#Pop-up Notifications (Ringhio Messages)|pop-up messages]]. These represent a practical, less obtrusive alternative to traditional requesters.

* It can easily create and manage lists of recently-used documents.

* It can register as a ''unique application'', preventing other instances of itself from running.

* It can show its icon or display the current program state in taskbar-like applications, such as AmiDock.

* It can control the behaviour of screen-blankers. Applications that don’t want to be disturbed may prevent the blanker from kicking in, or tell other applications to “keep quiet”.

=== Frequently Asked Questions ===

{| class="wikitable"
|-
|''Q: Should my programs register with the Application Library?''
|A: Yes, that would make a lot of sense. Apart from access to the handy features mentioned above, the implementation of certain library features may improve the behaviour of your application within the AmigaOS ecosystem.
|-
|''Q: After registering with the library, will my application become controlled by the OS or by other applications?''
|A: No. The registration process alone does not turn on any features. There is a recommendation to allow a [[#Minimum Application Library Support|minimum degree of control]], but in the end it is the programmer who decides what functionality offered by the library will be provided and supported in his/her application. That also includes the scope of external control: if you don't want your application to be controlled beyond a certain limit, your code will simply not react to certain incoming [[#Control Messages|control messages]].
|-
|''Q: Doesn't the Application Library duplicate functionality already present in commodities?''
|A: No. The only similarity between the two is that programs register with some system library, which then acts as a control centre. [[Commodities_Exchange_Library|Commodities]] provide a way to install custom input handlers into the [[Input_Device|Input Device]]'s event stream. The Application Library's field and scope of operation is completely different (and much wider).
|-
|''Q: Why is this a library? Wouldn't it be wiser to implement it as a class, like MUI does it?''
|A: This would tie the functionality to the object-oriented (BOOPSI) API – applications designed using [[GUI_Programming#The_Two_Frameworks|other APIs or toolkits]] would not be able to use it.
|-
|''Q: Can a program be registered both as an application and as a commodity?''
|A: Yes, that's possible – although few programs would probably benefit from that. Exceptions include application managers and taskbars (e.g. AmiDock), which may need to control other applications and, at the same time, behave like a commodity.
|-
|''Q: Being XML-based, do the PrefsObjects introduce any overhead to the operating system?''
|A: Hardly any. The [[PrefsObjects]] .xml preference files are, typically, only read when the application starts and written at user request, so there is minimum overhead involved. Accessing the prefs file during program runtime doesn't put any strain on the OS either, as the Application Library caches the file in a pre-parsed format in memory.
|}

=== Minimum Application Library Support ===

In the foreseeable future, AmigaOS will feature an application manager to control running applications. (A third-party solution called [http://wiki.amiga.org/index.php?title=Exchanger Exchanger] is already available.) The idea is to provide a single, universal control point for both commodities and applications. In order to allow easy, consistent and predictable program control, developers are encouraged to [[#Registering the Application|register their applications]] and implement the following suggested minimum Application Library support:

* Provide a short [[#Description|description]] for a better identification of the application.
* Tell the OS whether your application supports iconification, that is, hiding/showing its GUI. If iconification is supported:
** set the REGAPP_HasIconifyFeature registration tag to TRUE;
** make the application respond to the [[#Control Messages|APPLIBMT_Hide and APPLIBMT_Unhide]] control messages;
** update the APPATTR_Hidden attribute accordingly each time your application iconifies or uniconifies.
* Allow the application to be shut down externally in a safe and graceful manner in reaction to the [[#Control Messages|APPLIBMT_Quit]] message.

Not implementing this suggested minimum means that the application manager will be unable to control your application properly and consistently (some of the manager's control buttons or menu items may appear ineffective). This could cause confusion on the part of the users and degrade their AmigaOS experience.

== Library Opening Chores ==

{{Note|title=Note|text=Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2. This is due to changes in the Application Library API which had broken standard tag support until version 2 interfaces were introduced.}}

Just like other AmigaOS libraries, the Application Library must be opened before it is used. Further, at least one of its interfaces must be obtained, depending on the functionality you require. The Application Library has two interfaces, called “application” and “prefsobjects”. You always need to obtain the “application” interface because it provides access to most library functions including application registration. You’ll only need to open the “prefsobjects” interface if you intend to make use of the PrefsObjects preferences system.

<syntaxhighlight>
struct Library *ApplicationBase = NULL;
struct ApplicationIFace *IApplication = NULL;
struct PrefsObjectsIFace *IPrefsObjects = NULL;

if ( (ApplicationBase = IExec->OpenLibrary("application.library", 52)) )
{
IApplication = (struct ApplicationIFace *) IExec->GetInterface(ApplicationBase,
"application", 2, NULL);
IPrefsObjects = (struct PrefsObjectsIFace *) IExec->GetInterface(ApplicationBase,
"prefsobjects", 2, NULL);
}

if ( !ApplicationBase || !IApplication || !IPrefsObjects )
{
/* handle library opening error */
}
</syntaxhighlight>

Note that there is no interface called “main” like older, single-interface libraries have. The number in the GetInterface() call above refers to the version of the interface. Library interfaces are not backwards or forwards compatible so they must be specified precisely. '''Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2.''' This is due to certain changes in the Application Library API.

When your application has run its course, don’t forget to clean up and close both the library and its interface(s):

<syntaxhighlight>
IExec->DropInterface((struct Interface *)IPrefsObjects);
IExec->DropInterface((struct Interface *)IApplication);
IExec->CloseLibrary(ApplicationBase);
</syntaxhighlight>

== Registering the Application ==

Application registration is a simple process during which a program informs AmigaOS that it should be treated as an application, and provides some basic information about itself: the program name, an associated URL address, or a short description. Also, certain application-related properties can be set at registration time (although some of these may be provided or changed later). Registration typically takes place at program startup; unregistration is normally done at the end of program runtime.

*hint* Avoid using the _ underscore character in the registered name. These may cause "charsetconvert" errors when the system boots up later.

=== Application Identifiers ===

A successfully registered application receives a numeric identifier, which in this documentation will be referred to as ''appID''. The identifier is public: any registered application can obtain another application’s appID (see [[#Finding Applications|Finding Applications]] below) and use it to communicate with the respective application. AppIDs are unique integer numbers: the library generates them incrementally on a per-registration basis. They are never assigned again during the same AmigaOS session, which prevents programs from incidentally addressing the wrong application after the original appID holder unregisters.

Apart from the numeric appID an application can be referred to by its name (that is, a string-type identifier). As programs can get registered in an arbitrary order (and the same application will have a different appID each time), it is the name identifier that other applications must use to retrieve the correct appID. To construct a unique name, the Application Library uses a special naming scheme that combines:

* the application name;
* an instance count (if more than one instance of the same application is started);
* a URL identifier (for example, the domain name of the application’s homepage – optional).

The same naming scheme is used by the library’s PrefsObjects system to create the name of the preferences file.

=== Registration Functions ===

Now let’s say we have a program, a media player called Audio Monster created by the fictitious software company SuperCoders, Inc. The piece of C code to handle its registration (and unregistration) might look like this:

<syntaxhighlight>
uint32 appID;

appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
TAG_END);

if (!appID)
{
/* report registration error and quit */
}

/*
do whatever your program does
*/

IApplication->UnregisterApplication(appID, NULL);
</syntaxhighlight>

Note that we’ve had to alter the application name to “AudioMonster”; it is because the Application Library doesn’t allow spaces in application names. According to the naming scheme (outlined in the previous section) the application will now become registered under the name “AudioMonster.supercoders.com”. (Should a previous instance of Audio Monster be already running, the library will automatically append an instance counter to the application name: the second instance will therefore be called “AudioMonster_1.supercoders.com”, the third will register as “AudioMonster_2.supercoders.com”, and so on.)

Also note that the URL identifier is just the domain name, i.e. without the “www.” part. The identifier is only used to distinguish between applications, not to access their homepages. The domain name is, therefore, sufficient; the resulting name identifier needn’t be long and quirky.

After calling UnregisterApplication() the program will be removed from the public list, and Application Library features will no longer be available.

== Application Attributes ==

An application is described by a set of ''attributes''. There are attributes that describe the application's properties or feature set, indicate its current state, or determine its behaviour. Some attributes are only specified at registration time and cannot be altered once they are set, while others can be changed freely (as long as the application remains registered, of course). The general recommendation is to specify at registration time all properties that are not going to change during program lifetime: i.e. define all "static" application features in one place.

=== Description ===
The REGAPP_Description tag, used in the registration example code above, tells the system what the application is all about. Although the description is an optional attribute, it is recommended to always provide it, as it will allow application manager or taskbar programs to provide meaningful information to the user. Keep the description short, matter-of-fact and serious.

The application description cannot be changed after registration.

=== Uniqueness ===
A program can register as a ''unique application'', thus only allowing one instance of itself to run. While the multitasking nature and tradition of AmigaOS would suggest not imposing such limits, there sometimes can be good reasons to do so. For example, the developer of the Audio Monster player might decide to make his/her program a unique application because the user would most likely gain nothing from playing several media files at the same time. Multiple program instances would only compete for screen space and system resources, possibly jeopardizing OS performance on lower-specification computers.

The following function call will register Audio Monster as a unique application:

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_UniqueApplication, TRUE,
TAG_END);
</syntaxhighlight>

If the user now tries to launch a second instance of the program, it will fail on RegisterApplication() and the library will send a [[#Special Messages|special message]] to the first instance informing it about the attempt. It is the developer’s responsibility to react to this message in a sensible way. Do not show error messages here: the user doesn’t need to know (or care) that the application is unique, so an error message would scold them for doing nothing wrong. The recommended behaviour is to bring the first instance to view and activate its window.

Quite logically, uniqueness is an attribute that cannot be changed after registration.

=== Feature Set / Control Scope ===
Different applications can implement different control features, and can be designed for a different scope of external control. For example, a text editor may respond to a [[#Control Messages|control message]] (command) that tells it to create a new, blank, unnamed document, whereas in a media player such a command would be best ignored. Similarly, a simple tool with no configuration capability would want to stay clear of messages that control program settings. It is always good manners to inform the system about the scope of control your application supports, as other applications may query about (and rely on) this information when sending control messages. Always set the following boolean tags to TRUE in the RegisterApplication() call if your application implements support for the respective feature (the default value is FALSE):

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_HasIconifyFeature
|The application supports iconification and uniconification.
|Set to TRUE if your application responds to the APPLIBMT_Hide and APPLIBMT_Unhide messages.
|-
|REGAPP_HasPrefsWindow
|The application has a dedicated Preferences (Settings) window.
|Set to TRUE if your application responds to the APPLIBMT_OpenPrefs message.
|-
|REGAPP_CanCreateNewDocs
|The application can create new documents (projects).
|Set to TRUE if your application responds to the APPLIBMT_NewBlankDoc message.
|-
|REGAPP_CanPrintDocs
|The application can print documents.
|Set to TRUE if your application responds to the APPLIBMT_PrintDoc message.
|}

These four attributes can be changed after registration.

=== Receiving Notifications ===

The Application Library can send certain notification messages that may be of interest to special-purpose programs like application managers, taskbars or screen blankers. If you are developing such a program, you may want to register for the following notifications:

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_AppNotifications
|Receive notifications about application registration/unregistration, icon type changes, GUI state changes (hidden/unhidden), and changes in the last used applications/documents list.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to application managers and taskbar-like programs.
|-
|REGAPP_BlankerNotifications
|Receive notifications concerning blanker activity.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to screen blankers.
|}

Other types of application should not normally ask to receive these notifications: they would only increase traffic along their input stream.

These two attributes can be changed after registration.

=== Changing Application Attributes ===

Certain attributes describe "dynamic" application properties and, as such, can be set or changed after registration. Some of these are ''state attributes'' that need to be updated each time your program changes state (shows/hides its GUI, or enters the game mode; see below in the table). Some are not really attributes but, rather, commands that invoke an application-related action.

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|APPATTR_AllowsBlanker
|Same as REGAPP_AllowsBlanker above.
|You may want to be able to enable/disable blanking dynamically during application runtime – this what the APPATTR_AllowsBlanker tag is for. For example, a presentation program may allow blankers while the presentation is being worked on, and disable them when the presentation is started.
|-
|APPATTR_AppOpenedDocument
|Adds a new entry to the application's Last Used Documents list.
|Set this tag each time your application has successfully opened a named document or project. The parameter to this tag is a pointer to the name string (i.e. a STRPTR).
|-
|APPATTR_AppNotifications APPATTR_BlankerNotifications
|Same as the two corresponding [[#Receiving Notifications|registration tags]] above.
|
|-
|APPATTR_CanCreateNewDocs APPATTR_CanPrintDocs APPATTR_HasIconifyFeature APPATTR_HasPrefsWindow
|Same as the four corresponding [[#Feature Set / Control Scope|registration tags]] above.
|Prefer setting these properties at registration time.
|-
|APPATTR_ClearLastUsedDocs
|Clears the application's list of last used documents.
|Set this tag to TRUE to clear the list. (Note that this is not really an attribute but, rather, a command.)
|-
|APPATTR_FlushPrefs
|
|
|-
|APPATTR_Hidden
|A boolean program-state attribute indicating whether the application is currently iconified (hidden) or not.
|Update this attribute each time your application GUI changes state, as application managers may query about (and rely on) this information.
|-
|APPATTR_IconType
|Changes the application icon type.
|
|-
|APPATTR_MainPrefsDict
|Allows changing the application's Prefs dictionary.
|
|-
|APPATTR_NeedsGameMode
|A boolean program-state attribute informing the system (and other applications) that the program is about to enter, or has left, the game mode.
|By the "game mode" we understand a mode in which an application doesn't want to be "disturbed" by other applications. It normally assumes full screen operation, and possibly taking over the audio system. Games or presentation programs are examples of applications that may want to implement the game mode, in which other programs are simply asked to “keep quiet”: not try to play sounds, open windows, requesters, etc. This feature assumes discipline and cooperation on the part of other applications; please use it moderately and only enter the game mode when it is really needed. Also note that setting APPATTR_NeedsGameMode to TRUE does not guarantee that other applications will comply.
|-
|APPATTR_SavePrefs
|Same as REGAPP_SavePrefs above.
|
|}

The function to set or change application attributes is SetApplicationAttrs(). It is very similar to SetAttrs() used in Intuition programming, only the first parameter is not a pointer to a BOOPSI object but an application identifier. The appID is followed by a tag list, so several attributes can be set at a time. The following example call will inform the system that the application has iconified (or otherwise hidden its GUI) and that the screen blanker can now come to front freely (assuming that the blanker was forbidden before for some reason). The result value indicates whether the call was successful or not:

<syntaxhighlight>
BOOL result;

result = IApplication->SetApplicationAttrs(appID,
APPATTR_Hidden, TRUE,
APPATTR_AllowsBlanker, TRUE,
TAG_END);
</syntaxhighlight>

== Finding Applications ==

The Application Library maintains a public list of all registered applications. Certain special-purpose programs – ''application managers'' – will read this list (also keeping track of all subsequent registrations and unregistrations) and offer some degree of control: display information about applications and/or send commands telling them to do something. Quite naturally, most programs will not (nor are they supposed to!) act as managers but a need to talk to another application may arise. How do you find it, then?

Finding an application basically means obtaining its appID: it is an identifier as well as a “contact address” for the library's messaging system. To do this you need to know at least one of the following:

* the application name, ie. the one under which it was registered via RegisterApplication();
* the application name identifier, ie. the unique combination of the application’s name, instance number (should there be more instances running) and URL identifier – see [[#Application Identifiers|Application identifiers]] above;
* the pathname pointing to the program file on disk, e.g. “Work:Utils/AudioMonster”.

Based on this information, the respective piece of code that will find our application in the system might look like this:

<syntaxhighlight>
uint32 appID;

/* if you only know the application name */
appID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster",
TAG_END);

/* if you know the application name identifier */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster.supercoders.com",
TAG_END);

/* if you specifically want to talk to the second running instance */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster_1.supercoders.com",
TAG_END);

/* if you know the pathname to the program file */
appID = IApplication->FindApplication(FINDAPP_FileName, "Work:Utils/AudioMonster",
TAG_END);
</syntaxhighlight>

Once you have obtained the appID you can start communicating with the respective application.

== Messaging ==

Messages are used extensively in AmigaOS: the inner workings of Exec or Intuition actually involve a good deal of message passing. But it’s not just the operating system that needs to communicate. Modern software applications often want to talk to other running applications. Regardless of whether this communication will, in real use, entail a simple command-driven action or an intricate exchange of data, AmigaOS provides the necessary means: inter-program communication is supported on the low level (through Exec Library’s [[Exec Messages and Ports|messages and ports]]) as well as on the high level (using the ARexx-language scripting features). The Application Library has introduced yet another means of communication, which can be seen as lying somewhere in between the two levels.

Provided that you know its appID, you can send messages to any running application that is ready to accept them. You can even send a message to all applications at once! Basic application control can be achieved via a set of [[#Control Messages|predefined messages]] that correspond to common program commands and functions (such as New, Open, Print, Iconify or Quit). But the library also supports [[#Custom Messages|custom messages]], thus allowing for more sophisticated control or information exchange. The extent and complexity of messaging is fully up to the programmer: your application will only send/receive messages that you will implement (it has already been mentioned in the [[#Frequently Asked Questions|Frequently Asked Questions]] section above that registration alone does not magically turn on any features).

Furthermore, apart from this “invisible”, abstract communication taking place between application ports, you can use the library to provide real and visible information in the form of pop-up notification messages. However, as these are different and not really within the scope of the Application Library messaging framework, they are dealt with in a [[#Pop-up Notifications (Ringhio Messages)|separate section]] of this document.

{{Note|Before we get any further with Application Library messages, it must be made clear that they should not be confused with the similarly-named ''AppMessages''. The latter are a completely different breed, governed by the Workbench Library. They represent a specific way of communication between the Workbench desktop environment and running applications. It’s strictly one-way communication because Workbench can send AppMessages to applications but applications cannot send AppMessages to Workbench. (If you want to learn more about the use of AppMessages, consult the [[Workbench Library|Workbench Library]] section of the AmigaOS documentation wiki).
}}

=== Data Structures ===

Rather than introduce yet another system for communication, the Application Library builds upon the existing [[Exec_Messages_and_Ports|Exec messaging framework]]. Programmers will, therefore, find working with Application Library messages rather familiar. For instance, the library uses data structures that are in fact extensions of the standard Exec message structure. Also, the usual procedure of [[Exec_Messages_and_Ports#Getting_a_Message|GetMsg()]] and [[Exec_Messages_and_Ports#Replying|ReplyMsg()]] takes place when processing incoming Application Library messages (see section [[#Message Handling|Message Handling]] below) – although the library implements its own method for [[#Sending Messages|sending messages]].

The following three structures are defined for carrying Application Library message data:

<syntaxhighlight>
struct ApplicationMsg
{
struct Message msg;
uint32 senderAppID; // the appID of the sender application
uint32 type; // identifies the type of message
};

struct ApplicationOpenPrintDocMsg
{
struct ApplicationMsg almsg;
STRPTR fileName;
};

struct ApplicationCustomMsg
{
struct ApplicationMsg almsg;
STRPTR customMsg;
};
</syntaxhighlight>

As you can see, structure ''ApplicationMsg'' contains a standard ''[[Exec_Messages_and_Ports#Messages|struct Message]]'', the other fields are used for Application Library-specific data. The other two structures are mere extensions of the basic one: ''ApplicationOpenPrintDocMsg'' is used by certain [[#Control Messages|control messages]] that require a pointer to a filename; the ''ApplicationCustomMsg'' structure is used for [[#Custom Messages|custom messages]].

Upon message arrival you identify the message by reading the “type” field of the respective data structure. Similarly, if you want to [[#Sending Messages|send a message]] to an application you specify it in the “type” field.

=== Control Messages ===

The Application Library allows registered applications to send messages that control other applications. There is a set of predefined messages (or rather, commands) that can be sent to a running application, telling it – for example – that it should come to front, quit, open a document, create a new one, and so on. As these actions are common program functions, the library offers a practical and easy-to-implement way to control applications externally. The following control messages (commands) are currently provided:

{| class="wikitable"
!Message name
!Description
!Implementation notes
|-
|APPLIBMT_Quit
|The application is asked to shut down itself and quit.
|Basically, upon receiving this message you should react as if your main program window received the WMHI_CLOSEWINDOW event. When implementing support for APPLIBMT_Quit, the programmer is required to design the program exit sequence in such a way that no unexpected data loss can occur (for example, by displaying a confirmation requester that allows the user to save work or cancel the quit command).
|-
|APPLIBMT_ForceQuit
|Same as before but this time the application shall quit immediately, without asking for saving documents etc.
|Providing this command as part of the Application Library messaging framework was surely meant well but there is an inherent risk: a malevolent application could hamper the use of other applications by sending them this message and making them quit prematurely. So implement APPLIBMT_ForceQuit with care, or don't implement it at all. The official AmigaOS application manager will never try to send APPLIBMT_ForceQuit in order to shut down running applications.
|-
|APPLIBMT_Hide
|The application shall hide its interface and iconify on the Workbench screen.
|rowspan="2"|An application that supports APPLIBMT_Hide and APPLIBMT_Unhide is expected to register itself with REGAPP_HasIconifyFeature set to TRUE. Basically, upon receiving this message you should react as if your main program window received the WMHI_ICONIFY / WMHI_UNICONIFY event.
|-
|APPLIBMT_Unhide
|The application shall come back from the iconified (hidden) state.
|-
|APPLIBMT_ToFront
|The application window shall come to front.
|Programmatically that entails calling the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. See the end of the [[#Message Handling|Message Handling]] section for a note on APPLIBMT_ToFront.
|-
|APPLIBMT_OpenPrefs
|The application shall open its preferences window.
|Only implement if your application has a dedicated Preferences (Settings) window. An application that supports APPLIBMT_OpenPrefs is expected to register itself with the REGAPP_HasPrefsWindow set to TRUE.
|-
|APPLIBMT_ReloadPrefs
|The application shall reload its preferences.
|Whatever this command is useful for.
|-
|APPLIBMT_NewBlankDoc
|The application shall open a new, blank document or project.
|Applications such as web browsers can, too, make use of this command to open new program windows. An application that supports APPLIBMT_NewBlankDoc is expected to register itself with the REGAPP_CanCreateNewDocs set to TRUE.
|-
|APPLIBMT_OpenDoc
|The application shall try to open a specific document or project.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above).
|-
|APPLIBMT_PrintDoc
|The application shall try to print a specific document.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above). An application that supports APPLIBMT_PrintDoc is expected to register itself with the REGAPP_CanPrintDocs set to TRUE.
|}

An application will only react to messages that are implemented and supported. If you [[#Sending Messages|send a message]] to an application that is registered but does not perform any Application Library event handling, there will be no reaction at all. Further, many applications will only implement a subset of the available control commands: if a program does not have a Print function, an APPLIBMT_PrintDoc message will quite logically be ignored. There is no rule saying which or how many control messages should be implemented but you are encouraged to provide the [[#Minimum Application Library Support|minimum suggested support]] as outlined above. Implement the rest according to your application’s features and needs, and to the highest standards of security.

=== Custom Messages ===

In contrast to a [[#Control Messages|control message]] (see above), a custom message has no meaning or purpose predefined by the library. It is a simple text string the actual meaning of which is determined by the application. There is some undeniable beauty in this concept. For instance, the application can define a set of “publicly available” commands that call a corresponding function whenever a particular command (text string) arrives from another application. This kind of external control is very easy to implement and represents a practical alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]], while requiring less setup. Also, sender applications need not care about internals (such as knowing the ARexx port name) – all it takes is to [[#Finding Applications|find]] the receiver application and [[#Sending Messages|send a message]] to it.

The pointer to the message text string is contained in a special [[#Data Structures|data structure]], ''struct ApplicationCustomMsg''.

=== Special Messages ===

There are also some special messages that an application can receive from the library or another running application:

{| class="wikitable"
! Message name !! Description !! Implementation notes
|-
| APPLIBMT_Unique || If an application is registered as [[#Uniqueness|unique]] and the user attempts to start a second instance of the program, the attempt will fail and the library will send an APPLIBMT_Unique message to the first instance. || All unique applications should listen for this message and react to it: not doing so might leave the user puzzled as to why the program hasn’t started. The recommended reaction is to bring the first instance to view and focus. This may entail a couple of steps, like uniconifying (if the program is iconified at the moment), swapping screen (if the program runs on a dedicated screen), bringing the program window to front, and activating it. Basically, the APPLIBMT_Unique message should be treated in the same way as the APPLIBMT_ToFront message.
|-
| APPLIBMT_GameModeEntered || Sent to all currently running applications if another application enters the “game mode” – that is, a state in which it doesn’t want to be disturbed. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to TRUE.
|-
| APPLIBMT_GameModeLeft || Informs all running application that the sender has left the game mode. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to FALSE.
|}

=== Message Handling ===

You already know that messaging in AmigaOS takes place between [[Exec_Messages_and_Ports#Message_Ports|message ports]]. Being a superset of standard Exec messages, Application Library notifications (be they predefined [[#Control Messages|control messages]], [[#Custom Messages|custom messages]] or [[#Special Messages|special messages]]) are, too, sent to a message port. We’ll call this dedicated port – in order to distinguish it from other ports possibly used by the program – the ''notification port''. The port is automatically created by the library at registration time and freed as part of the UnregisterApplication() call. Messages arriving at the port are meant to be processed within the program’s main event loop, together with other events (such as Intuition’s [[Intuition_Input_and_Output_Methods#Receiving_Input_Events_from_Intuition|IDCMP messages]]). To process incoming messages you first need to obtain the notification port pointer from the library and then set the port’s signal bit. The signal bit is used to identify messages as Application Library notifications.

A simplified event loop code could look like the one below. Note that this example loop only waits for and processes Application Library messages. In real use you'll also want to handle other message types, such as input from the user interface (IDCMP events) or ARexx commands.

<syntaxhighlight>
void event_loop(uint32 appID)
{
struct MsgPort *notificationPort = NULL;
struct ApplicationMsg *appLibMsg = NULL;
struct ApplicationCustomMsg *customMsg = NULL;
uint32 appLibSignal = 0, sigGot = 0;
BOOL done = FALSE;

/* Obtain pointer to Application Library's notification port and set the signal bit. */
IApplication->GetApplicationAttrs(appID, APPATTR_Port, &notificationPort, TAG_END);
appLibSignal = (1L << notificationPort->mp_SigBit);

/* Go into the event loop. */
while (!done)
{
/* Wait for a signal to arrive. */
sigGot = IExec->Wait(appLibSignal);

/* Process all Application Library messages. */
if ( sigGot & appLibSignal )
{
/* Obtain pointer to the message. */
while ( (appLibMsg = (struct ApplicationMsg *) IExec->GetMsg(notificationPort)) )
{
/* Identify the type of message. */
switch (appLibMsg->type)
{
case APPLIBMT_Quit:
case APPLIBMT_ForceQuit:
done = TRUE;
break;

case APPLIBMT_ToFront:
/* Make the program window come to front. */
break;

case APPLIBMT_Hide:
/* Iconify the program. */
break;

case APPLIBMT_Unhide:
/* Uniconify the program. */
break;

/* Process the custom message as you like.
Here we just use printf() to output the message text. */
case APPLIBMT_CustomMsg:
customMsg = (struct ApplicationCustomMsg *) appLibMsg;
printf("The message text is: %s\n", customMsg-> customMsg);
break;

/*
Process any other Application Library messages.
*/

}
/* Return the processed message to the sender so that it can be freed. */
IExec->ReplyMsg( (struct Message *) appLibMsg);
}
}
}
</syntaxhighlight>

Like all [[Exec_Messages_and_Ports#Messages|Exec messages]] obtained via the GetMsg() function, Application Library messages must be [[Exec_Messages_and_Ports#Replying|replied to]], i.e. returned to the sender after they have been processed. This is what the last command does in the code above. Remember that all message resources are freed after ReplyMsg() so should you need to use the message data (for example, the custom message text string) beyond the event loop, you must copy it to a memory storage of your own.

Also remember that the notifications are addressed to an abstract ''application'' – this makes them rather different from IDCMP messages, which are always sent to a particular ''window'' (Intuition doesn't know what an application is). Whereas Intuition stops sending IDCMP messages as soon as the window becomes closed/iconified, the Application Library keeps passing messages as long as the application is registered, regardless of program window state. So be smart in your code when processing Application Library notifications: check for the availability of the program window and perform uniconification when necessary. For example, this following piece of code

<syntaxhighlight>
/* Don't do this!!! */
case APPLIBMT_ToFront:
IIntuition->ScreenToFront(win->WScreen);
IIntuition->WindowToFront(win);
IIntuition->ActivateWindow(win);
break;
</syntaxhighlight>

is broken because if an APPLIBMT_ToFront command were sent to your iconified application, there would be no window to refer to. You need to check for iconified state first, uniconify the window if needed, and only then call the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. The mistake of referencing a non-existing window is as silly as it is easy to make!

=== Sending Messages ===

While incoming notifications are [[#Message Handling|processed]] pretty much like normal Exec messages, the Application Library implements its own method for message sending. It takes three simple steps to send a message to another application:

# Prepare the respective [[#Data Structures|data structure]]: specify the type of message and supply the sender's [[#Application Identifiers|identifier]] (appID).
# [[#Finding Applications|Find the receiver]] application.
# Send a message to it via the SendApplicationMsg() function.

For example, if you want to tell the Audio Monster application to quit, you send it an APPLIBMT_Quit message like this:

<syntaxhighlight>
struct ApplicationMsg appMsg; // message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Step 1: Prepare the message data structure. */
appMsg.senderAppID = appID; // identifier of the sender
appMsg.type = APPLIBMT_Quit; // type of message

/* Step 2: Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Step 3: Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
&appMsg,
APPLIBMT_Quit);
}
</syntaxhighlight>

Should you want to send your message to all currently registered applications at once, just use a receiver appID of 0.

Sending [[#Custom Messages|custom messages]] is done in a similar fashion, the only difference is that you must use a dedicated [[#Data Structures|data structure]] instead of the generic ''struct ApplicationMsg''. As our Audio Monster application is a media player, it may as well have defined a set of commands for external control, one of them being “Start playback”. Now if another application wants to tell Audio Monster to start playing, it will need to send the custom message like this:

<syntaxhighlight>
struct ApplicationCustomMsg customMsg; // custom message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Prepare the message data structure. */
customMsg.almsg.senderAppID = appID; // identifier of the sender
customMsg.almsg.type = APPLIBMT_CustomMsg; // type of message
customMsg.customMsg = "Start playback"; // message text

/* Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
(struct ApplicationMsg *) &customMsg,
APPLIBMT_CustomMsg);
}
</syntaxhighlight>

== Pop-up Notifications (Ringhio Messages) ==

As from the introduction of the Ringhio server in AmigaOS 4.1 Update 1, registered applications can inform the user via notifications displayed in a small pop-up box. These are sometimes called ''Ringhio messages'' because the server provides means through which the messages are communicated visually (in other words, Ringhio handles the actual display of messages sent by the Application Library). [[File:RinghioNotification.png|frame|Ringhio notification example]] The pop-ups function similarly to [[Intuition Requesters|requesters]] in that they show a text message; but unlike requesters, Ringhio messages do not require user interaction or acknowledgement. They just show up briefly and disappear – which makes them great for informing about less significant, matter-of-fact events such as that a certain task has been completed (this is especially helpful if the application is hidden or runs on a different screen, as the user is kept informed about something that is currently beyond his/her visual control).

Of all the types of Application Library messages, pop-up notifications are surely the easiest to program. They don’t require any setup or event handling; all it takes is a single function call:

<syntaxhighlight>
uint32 result;

result = IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
TAG_END);
</syntaxhighlight>

The first parameter is your application’s appID received from the [[#Registration Functions|registration function]]. The APPNOTIFY_Title tag specifies a short heading for the pop-up box while APPNOTIFY_Text contains the actual message text. Certain limits to text length apply to ensure that the pop-up remains easy to read: 64 characters for the heading (title) and 128 characters for the text (160 characters as of Ringhio 53.23). This particular message will display on the frontmost public screen (as specified in the APPNOTIFY_PubScreenName tag), which may as well be the right setting for most applications. You can of course provide any other public screen name – or you can call Notify() without this tag and let the library use the default, which is the [[Public_Screen_Type#The_Default_Public_Screen_and_Workbench|Workbench screen]].

The result value shows whether the call was successful; 0 means that an error has occurred and Ringhio failed to display the pop-up. Depending on the significance of the message, you may want to react upon the failure and inform the user through other means of communication, such as a requester.

The look and position of the pop-up box is configurable from the Notifications editor located in the Prefs drawer on your system partition. This is Ringhio’s preferences editor: as we have explained above, it is Ringhio that is responsible for the actual display of notification messages. The pop-up box can also show a small custom image (like the one in the picture above) to make the message more easily identifiable as related to a particular application. The maximum size of the image is 32x32 pixels. It can be any format, provided that there is a datatype for it installed in the system. Being application-specific, these images logically cannot be configured system-wide through the Notifications editor; instead, they are specified as part of the Notify() call. Note that a full path to the image file must be provided:

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "All right, ma!",
TAG_END);
</syntaxhighlight>

But what is this APPNOTIFY_BackMsg thing? It has been mentioned above that notification messages do not require user interaction: they display some text and go away. Nevertheless, Ringhio can send the application a [[#Custom Messages|custom message]] (called “back message” – hence the name of the tag) if the user has double-clicked on the message box. As the code snippet shows, this custom message takes the form of a text string (within the Application Library messaging context, [[#Custom Messages|custom messages]] are always text strings). It is sent to the same event stream, and is supposed to be processed within the same event loop, as other Application Library messages – see the [[#Message Handling|Message Handling]] section for how to go about it.

Whether receiving a “back message” would be useful for a particular application, and whether it would make sense to react upon it, is decided by the programmer. The reaction (if any – often none is needed) should be sensible and logical. Make sure not to misuse the feature! Note that Ringhio messages are not requesters, and double-clicking on the message box does not really equal pressing a requester button. Therefore, receiving the message could be interpreted as the user’s acknowledgement of what Ringhio has said, but never as a selection of an option. Do not use Ringhio to request input via the back-message feature: the text of the message should be a statement, not a question or an offer of choice. Considering this logic, the double click means “I understand”; it doesn't mean “Yes” or “No”.

If the text string provided in the APPNOTIFY_BackMsg tag is an URL, the feature works rather differently. Instead of sending the message to the event stream, this particular URL is opened in your default web browser. Because the process is done through the Launch Handler, your system should be recent enough to have it (the Launch Handler was introduced in AmigaOS 4.1 Update 1). The following piece of code will open Audio Monster’s homepage if the user double-clicks on the Ringhio box. The last in the tag list, APPNOTIFY_CloseOnDC, causes the message box to disappear right after the double click.

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "URL:http://www.supercoders.com",
APPNOTIFY_CloseOnDC, TRUE,
TAG_END);
</syntaxhighlight>

=== Pop-up Message Style Guide ===

* Keep the message text short. Give the user chance to read the entire message before it disappears.
* Do not use pop-up messages to report errors. An error is usually a serious situation, and as such it cannot be dismissed by simply displaying an automatic message (which can easily get missed or overlooked).
* Use the pop-up message facility with moderation. Displaying the messages too frequently might hamper the workflow, and would most probably annoy the user.

== Function Reference ==

The following are brief descriptions of the Application Library functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| FindApplication()
| Searches for a previously registered application.
|-
| FreeApplicationList()
| Frees the list of applications generated by GetApplicationList().
|-
| GetAppLibAttrs()
| Obtains global Application Library attributes.
|-
| GetApplicationAttrs()
| Obtains attributes of a registered application.
|-
| GetApplicationList()
| Obtains the list of all currently registered applications.
|-
| LockApplicationIcon()
| Attempts to lock an application icon.
|-
| Notify()
| Displays a pop-up message box.
|-
| RegisterApplication()
| Registers an application.
|-
| SendApplicationMsg()
| Sends a message to a registered application.
|-
| SetAppLibAttrs()
| Sets or changes global Application Library attributes.
|-
| SetApplicationAttrs()
| Sets or changes application attributes.
|-
| UnlockApplicationIcon()
| Unlocks an application icon.
|-
| UnregisterApplication()
| Unregisters an application.
|}

RealTime Library

2018-12-30T21:04:42Z

Daniel Jedlicka: Fixed spelling, added two sub-headings.

The RealTime Library provides a convenient, higher-level interface to underlying hardware timers that is easy to use. The library also provides for the distribution of timing pulses to an unlimited number of client applications on a priority basis, thus supporting multitasking in the most robust manner possible.

= Conductors and Playerlnfos =

The RealTime Library uses the Conductor structure to manage timing. There can be any number of Conductor structures, each of which represents a separate and independent timing context (i.e. a group of applications that want to be synced together).

Each Conductor can have one or more client applications. A second structure called a PlayerInfo is set up by each client application that wants to get timing information from the Conductor. There is typically one Playerlnfo for each task that wants to get timing information (a task could have more than one but this would be unusual).

Both the Conductor and Playerlnfo structures are dynamic. You never create these structures by allocating and initializing them yourself. The system provides the functions to do this for you. Also, the structures are read-only. To change the fields within these structures, use the system-provided functions and tags.

An application will usually create a single PlayerInfo structure and then attach it to a Conductor. If the Conductor does not yet exist, it will be created by the system. To create a PlayerInfo structure you call CreatePlayerO:

<syntaxhighlight>
struct PlayerInfo *pi = IRealTime->CreatePlayer(Tag tag, ...);
</syntaxhighlight>

This call takes a list of tag items that describe the attributes of the Playerlnfo structure you want to create. (A complete list of all the tags available can be found in the Autodoc for SetPlayerAttrs().) It returns a pointer to the PlayerInfo. Here’s a fragment showing how to set up a PlayerInfo:

<syntaxhighlight>
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
TAG_END);

if (pPlayerInfo != NULL )
{
// Your real-time application goes here...

IRealTime->DeletePlayer(pPlayerInfo);
}
</syntaxhighlight>

In the code above, a PlayerInfo will be created with the name of "My_player". It will be attached to the Conductor structure named "My_conductor". If a Conductor structure named "My_conductor" does not already exist, the system will create one. Other applications could also attach their PlayerInfos to "My_conductor".

When your application finishes, you should delete any PlayerInfos you have created by calling DeletePlayer(). The Conductor will be automatically deleted by the system (however, this won’t happen until '''all''' the PlayerInfos attached to a Conductor are deleted).

Once you have a PlayerInfo and Conductor set up, you can obtain timing pulses for your application. Timing pulses come from underlying timer chips and are passed to your application through the Conductor.

= Getting Clock Ticks =

The RealTime Library uses a tick frequency of 600 Hz so clock pulses are delivered approximately every 1.66 ms. There are two ways to get this timing information:

* An alarm's signal
* A clock tick callback hook

== Using the alarm facility ==

You can ask the RealTime Library to signal your task at some future time by using its alarm facility. This allows you to operate asynchronously. For instance, you could start a group of MIDI notes playing and set the realtime alarm to signal you when they should be stopped, then go on to some other job such as preparing the next group of notes before calling Wait() on the alarm signal.

The fragment below shows how to set up the library’s alarm clock to signal the calling task at time = 1000 ticks (the fragment assumes that the RealTime Library interface is already obtained).

<syntaxhighlight>
// This fragment assumes the that IRealTime is already obtained.
int8 midiSignal = IExec->AllocSignal(-1); // Allocate a wake-up signal bit
if (midiSignal != -1)
{
struct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_SignalTask, IExec->FindTask(NULL),
PLAYER_AlarmSigBit, midiSignal,
TAG_END);

if (pPlayerInfo != NULL)
{
// Start the realtime clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
BOOL timerr = IRealTime->SetPlayerAttrs(pPlayerInfo,
PLAYER_AlarmTime, 1000,
PLAYER_Ready, TRUE,
TAG_END);
if (timerr)
{
// You could do some other job before
// calling Wait() on the alarm signal.
IExec->Wait(1UL << midiSignal);
}
else IDOS->Print("Couldn't set alarm\n");
}
else IDOS->Printf("Couldn't start clock\n");
}
else IDOS->Printf("Couldn't set up PlayerInfo structure.\n");
}
else IDOS->Printf("Couldn't allocate signal.\n");
</syntaxhighlight>

In the fragment above, the calling task requests a PlayerInfo with an alarm clock feature by passing the PLAYER_AlarmSigBit tag to CreatePlayer() The ti_Data field of this tag contains the signal bit that will be set by the RealTime Library when the alarm goes off. The PLAYER_SignalTask tag indicates which task will be signaled.

The realtime clock is then started by calling SetConductorState() (discussed below). This is important since any alarm requests made when the clock is stopped will be ignored.

Finally, the alarm time is set by calling SetPlayerAttrs(). The parameters to this call are:
<syntaxhighlight>
BOOL result = SetPlayerAttrs(struct PlayerInfo *pi, Tag tag, ...);
</syntaxhighlight>

The pi parameter indicates which Playerlnfo structure is to have its attributes changed. The Tag items indicate the attributes and their new values. If the change is made successfully, then TRUE is returned. FALSE indicates failure. In the fragment above, a wake-up time is
requested using the PLAYER_A1armTime tag. Also, the calling task indicates to the Conductor that it is ready by using the PLAYER_Ready tag (more on this below).

At this point, the call to Wait(1UL << midiSignal) causes the task to sleep until time = 1000 ticks.

== Using the clock tick callback facility ==

The discussion so far has concentrated on the alarm facility of the RealTime Library. An even finer level of control over time is available using the clock tick callback hook facility. Instead of setting an alarm to signal your task at some future time, the hook facilities allow your application code to be invoked whenever Conductor time is updated.

The realtime clock is driven by an interrupt that simply increments the base time and then uses software interrupts to distribute the time to any Conductors. By using a callback hook, you can have your custom code invoked at the software interrupt level (before tasks)
whenever Conductor time is refreshed.

To set up a callback hook, you use the PLAYER_Hook tag with the address of a standard Hook structure as defined in <utilities/hook.h>. This structure contains the address of the code you want to be invoked whenever the RealTime Library updates your Conductor. Here’s a code fragment showing how this is done:

<syntaxhighlight>
struct Task *My_task;
int8 My_signal;

uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi);

int main()
{
// ...Open the RealTime Library and do other set up here...

struct Hook My_hook;
My_hook.h_Entry = (HOOKFUNC)My_hookFunc;

uint32 ticks = 1000;
stuct PlayerInfo *pPlayerInfo = IRealTime->CreatePlayer(
PLAYER_Name, "My_player",
PLAYER_Conductor, "My_conductor",
PLAYER_Hook, &My_hook,
PLAYER_UserData, &ticks,
TAG_END);

if (pPlayerInfo != NULL)
{
My_task = IExec->FindTask(NULL); // Initialize these globals so that
My_signal = IExec->AllocSignal(-1); // the hook function can signal us.
if (My_signal != -1)
{
// Start the clock running.
int32 res = IRealTime->SetConductorState(pPlayerInfo, CLOCKSTATE_RUNNING, 0);
if (!res)
{
// ...your code goes here...
IExec->Wait(1UL << My_signal | SIGBREAKF_CTRL_C);
}

IExec->FreeSignal(My_signal);
}

IRealTime->DeletePlayer(pPlayerInfo);
}

// ...Close the library, etc...
}
</syntaxhighlight>

In the code above the function named My_hookFunc() will be called by the RealTime Library whenever it updates Conductor time.

Here’s the callback hook function itself. This simply compares Conductor time to a variable, ticks, whose address is pointed to by pi>pi_UserData. Notice how this address was filled in using the PLAYER_UserData tag in the call to SetPlayerAttrs() in main() above. When
Conductor time equals or exceeds ticks, the hook function signals the main task.

<syntaxhighlight>
// Hook code called whenever the RealTime Library updates Conductor time.
// Normally this is 600 times/sec.
uint32 My_hookFunc(struct Hook *hook, struct pmTime *msg, struct PlayerInfo *pi)
{
switch (msg->pmt_Method)
{
case PM_TICK:
// Test whether Conductor time has exceeded the number in *ticks*.
// If it has, then signal the parent task.
if ((*uint32*)(pi->pi_Userdata)) < pi->pi_Source->cdt_ClockTime)
IExec->Signal(My_task, 1UL << My_signal);
break;

default:
break;
}

return 0;
}
</syntaxhighlight>

= More About Conductors =

It is the job of the Conductor to act as middleman between the Amiga's timing hardware and client tasks represented by PlayerInfo structures. Each Conductor keeps track of:
* an Exec list of all its client players
* the state of the conductor (i.e. running, stopped, paused, locating)
* what time it is relative to start time
* whether the Conductor is using the Amiga’s internal hardware for its timing pulses or an external source

As shown in the examples above, the "state" of the Conductor can be changed at any time by calling SetConductorState(). If the call succeeds, zero is returned:

<syntaxhighlight>
int32 res = IRealTime->SetConductorState(struct Playerlnfo *pi, int32 newstate, int32 ti);
</syntaxhighlight>

The pi parameter is a pointer to a PlayerInfo structure that is linked to the Conductor you want to change. The ti parameter is a time offset used for special cases (typically set to zero). The ''newstate'' parameter is one of the following:
{| class="wikitable"
| CLOCKSTATE_STOPPED || The clock is not running
|-
| CLOCKSTATE_PAUSED || To the RealTime Library, this is exactly the same as stopped. This is provided as a convenience to those applications that wish to make a distinction between the two.
|-
| CLOCKSTATE_RUNNING || The clock is running and time pulses are being distributed to any client applications (Playerlnfos) that are ready.
|-
| CLOCKSTATE_LOCATE || This is the same as running with one exception: the clock docs not actually start until ''all'' client applications have indicated that they are ready by setting the PLAYER_Ready attribute of their PlayerInfo to TRUE. This allows applications that cannot start immediately to set up before timing pulses actually begin.
|}

The difference between locating and running requires some explanation. Each Playerlnfo has a "ready bit" which is used to tell the RealTime Library that the player is ready to receive ticks. This bit is reset each time the library relocates the clock to a new time.

The reason for the ready bit is that some applications need to find the appropriate location in the multimedia sequence or score before they can start playing at the new location. In some cases this can take a considerable amount of time. Hence, CLOCKSTATE__LOCATE is used with the ready bit to allow all players that are sharing a timing context to be synchronized together.

Players can set the state of their ready bit by using the PLAYER_Ready tag attribute either when the Playerlnfo is created with CreatePlayer() or later with SetPlayerAttrs(). See the first code fragment above for an example of this.

BOOPSI 101

2018-06-02T20:02:37Z

Daniel Jedlicka: Minor corrections (typos, dead link).

In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs()''' instead of '''SetAttrs()'''), but the concepts remain the same.

== Creating an Object ==

The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:

<syntaxhighlight>
Object *object = NewObject(Class *cl, ClassID classID, Tag tag1, ...);
Object *object = NewObjectA(Class *cl, ClassID classID, const struct TagItem *tags);
</syntaxhighlight>

As mentioned previously (see [[BOOPSI#BOOPSI_and_Tags|BOOPSI and Tags]]), the '''NewObject()''' function has a variant that uses predefined tag lists ('''NewObjectA()'''), but here we will continue with the more commonly used stack-based variant.

In general, BOOPSI objects are "black boxes". This means the inner workings of BOOPSI objects are not visible to the application programmer, so the programmer does not know what goes on inside it. This really means the inner workings of these objects are none of your business. Unless otherwise documented, only use an object pointer as a handle to the object.

To create an object, '''NewObject()''' first needs to know whether we are creating an object from a public or private class. Typically any objects created from system gadgets are all public classes. In such cases, the '''cl''' argument (a class pointer) would be set to NULL and '''classID''' argument set to the public name of the class (a text string like "requesterclass" or "string.gadget"). If one wanted to create an object of a private class, the '''cl''' argument would be a pointer to that class and the '''classID''' would be ignored.

Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:

<syntaxhighlight>
GA_Left, 100,
REQ_TitleText, "Testing...",
WA_DragBar, TRUE,
</syntaxhighlight>

In the case of our requester example, we can use the '''NewObject{}''' function along with a "stack" of "tags" containing basic parameters to create a new requester object like this:

<syntaxhighlight>
reqobj = IIntuition->NewObject(NULL,"requester.class",
REQ_Type, REQTYPE_INFO,
REQ_TitleText, "Requesters Example",
REQ_BodyText, buffer,
TAG_END);
</syntaxhighlight>

If successful, the variable '''reqobj''' will contain a pointer to new a BOOPSI requester object. If unsuccessful, '''reqobj''' will be NULL. This is a place for a developer to apply some error trapping when an object couldn't be created - maybe our application ran out of memory? Maybe some of the parameters (tags) were invalid?

Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.

== Passing messages to an Object ==

To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):

<syntaxhighlight>
ULONG IDoMethod(Object *myobject, ULONG methodID, ...);
ULONG IDoMethodA(Object *myobject, Msg boopsimessage);
</syntaxhighlight>

The return value is class-dependent. The first argument to both of these functions points to the object that will receive the BOOPSI message.

'''IDoMethod()''' then depends on the class and method being used for the contents of the rest of the message. Those elements may include a method name, tags, text or pointers. The class documentation will described those as well as whether the class expects any certain order of tags, etc.

For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:

<syntaxhighlight>
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
</syntaxhighlight>

In this case, the '''RM_OPENREQ''' method of the Requester Class expects the elements of its '''orRequest''' structure. The class docs point us to a header file that explains we need to start with the '''MethodID''' and then pointers to a tag list, window and a screen structures. In our simple example above, we are passing no arguments, so our call has three NULL's for these elements.

When one calls ''IDoMethod()''' with the '''RM_OPENREQ''' method on a requester object, the requester appears and the application waits for the user input. Given the simple "information" style requester we created (with default buttons), the result will simply numerically indicate which button was selected by the user.

With the '''IDoMethodA()''' variant, all of the above arguments have to be combined into a complete BOOPSI Message structure, '''boopsimessage'''. Again the layout of depends on the class and method. Every method's message starts off with a '''Msg''' (from <intuition/classusr.h>) and is followed by the class specific tags:

<syntaxhighlight>
typedef struct {
ULONG MethodID; /* Method-specific data may follow this field */
} *Msg;
</syntaxhighlight>

As mentioned above, there are variants of the '''IDoMethod()''' functions for specific uses, such as the '''DoGadgetMethod()''' function. In that case, the function passes additional information pertinent to GUI gadget objects.

== Setting an Object's Attributes ==

Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:

<syntaxhighlight>
uint32 IIntuition->SetAttrs( Object * object, Tag tag1, ... );
uint32 IIntuition->SetAttrsA( Object * object, const struct TagItem * tagList );
</syntaxhighlight>

In each case we have to provide a pointer to our object and then tag pairs with the Attribute identifiers and the replacement values. As an example, we can use the '''SetAttrs()''' function to reset the type and contents of our requester object from above and reuse the object to open a second, different requester for the user.

<syntaxhighlight>
strcpy(buffer,"default string");
result = IIntuition->SetAttrs( reqobj,
REQ_Type, REQTYPE_STRING,
REQ_BodyText, "please enter some text",
REQS_Buffer, buffer,
REQS_MaxChars, sizeof(buffer) - 1,
TAG_END);
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
</syntaxhighlight>

With these changes, we've converted our simple requester with a couple buttons into a string requester. For any attributes we did not reset here, the previous settings or the default values of the class will continue to be used.

Not all object attributes can be set with '''SetAttrs()''' and this is dependent on each class. For more information about which attributes can be set in specific classes, see the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] and the class AutoDocs and look for those attributes with a '''OM_SET''' listed as an "applicability".

Again there is variant of the '''SetAttrs()''' function to be used with BOOPSI GUI gadgets: '''SetGadgetAttrs()'''.

== Getting an Object's Attributes ==

Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':

<syntaxhighlight>
uint32 attr = GetAttr(uint32 attrID, Object *object, uint32 *storage);
</syntaxhighlight>

We start by specifying the '''attrID''' is the attribute's identifier we are interested in, we then have to identify object to get the attribute from ('''object'''), and finally provide an area that will hold the value of the attribute. This function returns a 0 if the object doesn't recognize or return the attribute, otherwise it returns some non-zero value, the meaning of which depends on the class. In most cases, GetAttr() returns a 1 when it is successful.

In the case of our requester example, there are only a few attributes to which values can be obtained. The following example will obtain the result code from the last use of the object:

<syntaxhighlight>
uint32 lastresult;
result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
</syntaxhighlight>

Another example of the '''GetAttr''' function would be to retrieve the value a user provided in an Interger type requester. This information could be restrieved like this:

<syntaxhighlight>
int32 userInt;
result = IIntuition->GetAttr(REQI_Number, reqobj,&userInt);
</syntaxhighlight>

While the simple requester class is not a great example for getting a lot of attributes, BOOPSI provides a second pair of functions that uses taglists for obtaining multiple attributes in one call: '''GetAttrs()''' and '''GetAttrsA''':

<syntaxhighlight>
uint32 retval = GetAttrs(Object *object, Tag tag1, ...);
uint32 retval = GetAttrsA(Object *object, struct TagItem *attrs);
</syntaxhighlight>

As with the previous tag functions mentioned above, these functions are the same except for how the tag list is handled. In the case of each tag pair, the value will be set to the current value in the object queried.

As with setting attributes, not all object attributes are obtainable using the '''GetAttr()''' function, depending on each class. For more information about which attributes can be obtained in specific classes, see the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] and the class AutoDocs and look for those attributes with a '''OM_GET''' listed as an "applicability".

Unlike when creating and setting attributes on BOOPSI GUI gadgets, there are no GUI gadgets specific versions of the '''GetAttr''' family of functions. Instead, the '''GetAttr''' functions can also be used to obtain GUI gadget attributes where they are available (see the Class Reference and autodocs).

== Disposing of an Object ==

When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':

<syntaxhighlight>
void DisposeObject(Object *obj);
</syntaxhighlight>

As usual, we use a pointer to our object to indicate the object to be disposed.

In the case of our requester example, we would simply call:

<syntaxhighlight>
IIntuition->DisposeObject(reqobj);
</syntaxhighlight>

In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.

== What About the BOOPSI Messages and Methods? ==

In the above sections of this page, the functions used reflect BOOPSI messages and the underlying basic "methods" performed by a BOOPSI object. In the [[BOOPSI#OOP_Overview|"OOP Overview"]] section we see how these saw how these common methods are practically universal to all BOOPSI classes. The above functions simply provide a wrapper for those common methods like this:

{| class="wikitable"
| NewObject() || OM_NEW
|-
| SetAttrs()/SetGadgetAttrs() || OM_SET
|-
| GetAttr() || OM_GET
|-
| DisposeObject() || OM_DISPOSE
|}

These methods are defined on the rootclass level, so all BOOPSI classes inherit them. The Intuition functions that correspond to these methods take care of constructing and sending a BOOPSI message with the appropriate method ID and parameters.

One last function had a more direct relationship to operation and methods of BOOPSI objects - in this case, causing our requester object to present itself :

{| class="wikitable"
| IDoMethod() || RM_OPENREQ
|}

Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.

== Example Program ==

Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.

<syntaxhighlight>
/* Requesters Example
gcc -o Requesters Requesters.c -lauto
quit
*/

/*
*
************************************************************
**
** Created by: CodeBench 0.31 (20.5.2013)
**
** Project: OS4ex-Requesters
**
** A simple requester.class example used to demonstrate functionality.
**
** File: Requesters
**
** Date: 20-04-2013 20:43:23
**
** Version: 02
**
************************************************************
*
*/

/* includes
*/
#include <exec/exec.h>
#include <dos/dos.h>
#include <intuition/intuition.h>
#include <classes/requester.h>

#include <proto/intuition.h>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/requester.h>

#include <string.h>

/* declarations
*/
Object *reqobj;
struct orRequest reqmsg;
char buffer[100];
uint32 result = 0;

int main()
{

/* create a new requester object
*/
strcpy(buffer,"Welcome to your\nfirst BOOPSI requester");

reqobj = IIntuition->NewObject(NULL,"requester.class",
REQ_Type, REQTYPE_INFO,
REQ_TitleText, "Requesters Example",
REQ_BodyText, buffer,
TAG_END);

// Was the requester object created?
if (reqobj)
{
IDOS->Printf(" Requester object created\n");
/* tell the object to show itself
*/
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
// How did things go?
if (result)
IDOS->Printf(" Req #1 - result code = %ld\n",result);
else
IDOS->Printf(" Req #1 - result = 0\n");

/* reset object characteristics
*/

strcpy(buffer,"default string");
result = IIntuition->SetAttrs( reqobj,
REQ_Type, REQTYPE_STRING,
REQ_BodyText, "please enter some text",
REQS_Buffer, buffer,
REQS_MaxChars, sizeof(buffer) - 1,
TAG_END);

/* tell object to show itself again
*/
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
// Did we get a good response?
if (result>0)
{
IDOS->Printf(" Req #2 - result code = %ld\n",result);
IDOS->Printf(" Req #2 - result text = %s\n",buffer);
}
else
IDOS->Printf(" Req #2 - result = 0\n");

/* Lets check some object attributes
*/
uint32 lastresult;

result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
// Did we get some value?
if (result>0)
IDOS->Printf(" Last result code = %ld\n",lastresult);
else
IDOS->Printf(" This result = 0\n");

/* Dispose of our requester object
*/
IIntuition->DisposeObject(reqobj);
}
else
IDOS->Printf(" ERROR: Failed to create Requester object\n");

return RETURN_OK;
}
</syntaxhighlight>

BOOPSI 101

2018-06-02T19:45:39Z

Daniel Jedlicka: Fixed the size of chapter headings.

In this section we will explore a simple example of creating, interacting with and disposing a simple BOOPSI object - a requester window. With these simple objects you can see the basic operations that are common to almost all BOOPSI objects. When using BOOPSI gadget objects there may be some changes in syntax (f.e., using '''SetGadgetAttrs()''' instead of '''SetAttrs()'''), but the concepts remain the same.

== Creating an Object ==

The Intuition functions '''NewObject()''' / '''NewObjectA()''' create a BOOPSI object using either "stack" of tags or predefined a tag list and returns a pointer to a new BOOPSI object:

<syntaxhighlight>
Object *object = NewObject(Class *cl, ClassID classID, Tag tag1, ...);
Object *object = NewObjectA(Class *cl, ClassID classID, const struct TagItem *tags);
</syntaxhighlight>

As mentioned previously (see [[BOOPSI#OOPSI_and_Tags|BOOPSI and Tags]]), the '''NewObject()''' function has a variant that uses predefined tag lists ('''NewObjectA()'''), but here we will continue with the more commonly used stack based variant.

In general, BOOPSI objects are "black boxes". This means the inner workings of BOOPSI objects are not visible to the application programmer, so the programmer does not know what goes on inside it. This really means the inner workings of these objects are none of your business. Unless otherwise documented, only use an object pointer as a handle to the object.

To create an object, '''NewObject()''' first needs to know whether we are creating an object from a public or private class. Typically any objects created from system gadgets are all public classes. In such cases, the '''cl''' argument (a pointer) would be set to NULL and '''classID''' argument set to the text name of the class (like "requesterclass" or "string.gadget"). If one wanted to create an object of a private class, the '''cl''' argument would be a pointer to that class and the '''classID''' would be ignored.

Regardless of whether the tag list is defined elsewhere or within this function call, some list of "tags" is next proivided to define the characteristics of the new object. Each "tag" consists of a pair of values - each with specifically named "attribute" and it's proposed "value". Some general examples of such tags might be:

<syntaxhighlight>
GA_Left, 100,
REQ_TitleText, "Testing...",
WA_DragBar, TRUE,
</syntaxhighlight>

In the case of our requester example, we can use the '''NewObject{}''' function along with a "stack" of "tags" containing basic parameters to create a new requester object like this:

<syntaxhighlight>
reqobj = IIntuition->NewObject(NULL,"requester.class",
REQ_Type, REQTYPE_INFO,
REQ_TitleText, "Requesters Example",
REQ_BodyText, buffer,
TAG_END);
</syntaxhighlight>

If successful, the variable '''reqobj''' will contain a pointer to new a BOOPSI requester object. If unsuccessful, '''reqobj''' will be NULL. This is a place for a developer to apply some error trapping when an object couldn't be created - maybe our application ran out of memory? maybe some of the parameters (tags) were invalid?

Once the requester object has been created, we still won't see anything yet. Our new object is waiting in the wings for a BOOPSI message to show itself. This leads us to the next sections where we interact with the object we created.

== Passing messages to an Object ==

To communicate with BOOPSI objects we send "BOOPSI Messages". Unlike traditional AmigaOS "Messages" used by the Exec, ARexx and for interprocess communications, BOOPSI messages are different and frequently rely on tag lists for their content. To "send" a BOOPSI Message to an existing object, we use the '''IDoMethod''' function (or its tag list based variant):

<syntaxhighlight>
ULONG IDoMethod(Object *myobject, ULONG methodID, ...);
ULONG IDoMethodA(Object *myobject, Msg boopsimessage);
</syntaxhighlight>

The return value is class-dependent. The first argument to both of these functions points to the object that will receive the BOOPSI message.

'''IDoMethod()''' then depends on the class and method being used for the contents of the rest of the message. Those elements may include a method name, tags, text or pointers. The class documentation will described those as well as whether the class expects any certain order of tags, etc.

For a simple example, we can ask the BOOPSI requester object '''reqobj''' (created above) to show itself by sending this message:

<syntaxhighlight>
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
</syntaxhighlight>

In this case, the '''RM_OPENREQ''' method of the Requester Class expects the elements of its '''orRequest''' structure. The class docs point us to a header file that explains we need to start with the '''MethodID''' and then pointers to a tag list, window and a screen structures. In our simple example above, we are passing no arguments, so our call has three NULL's for these elements.

When one calls ''IDoMethod()''' with the '''RM_OPENREQ''' method on a requester object, the requester appears and the application waits for the user input. Given the simple "information" style requester we created (with default buttons), the result will simply numerically indicate which button was selected by the user.

With the '''IDoMethodA()''' variant, all of the above arguments have to be combined into a complete BOOPSI Message structure, '''boopsimessage'''. Again the layout of depends on the class and method. Every method's message starts off with a '''Msg''' (from <intuition/classusr.h>) and is followed by the class specific tags:

<syntaxhighlight>
typedef struct {
ULONG MethodID; /* Method-specific data may follow this field */
} *Msg;
</syntaxhighlight>

As mentioned above, there are variants of the '''IDoMethod()''' functions for specific uses, such as the '''DoGadgetMethod()''' function. In that case, the function passes additional information pertinent to GUI gadget objects.

== Setting an Object's Attributes ==

Every BOOPSI object is defined by a number of attributes. In the above example we defined our requester when we created the object with '''NewObject()'''. But an object's attributes are not necessarily static. An application can use the '''SetAttrs()''' function to change or set other attributes on an object:

<syntaxhighlight>
uint32 IIntuition->SetAttrs( Object * object, Tag tag1, ... );
uint32 IIntuition->SetAttrsA( Object * object, const struct TagItem * tagList );
</syntaxhighlight>

In each case we have to provide a pointer to our object and then tag pairs with the Attribute identifiers and the replacement values. As an example, we can use the '''SetAttrs()''' function to reset the type and contents of our requester object from above and reuse the object to open a second, different requester for the user.

<syntaxhighlight>
strcpy(buffer,"default string");
result = IIntuition->SetAttrs( reqobj,
REQ_Type, REQTYPE_STRING,
REQ_BodyText, "please enter some text",
REQS_Buffer, buffer,
REQS_MaxChars, sizeof(buffer) - 1,
TAG_END);
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
</syntaxhighlight>

With these changes, we've converted our simple requester with a couple buttons into a string requester. For any attributes we did not reset here, the previous settings or the default values of the class will continue to be used.

Not all object attributes can be set with '''SetAttrs()''' and this is dependent on each class. For more information about which attributes can be set in specific classes, see the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] and the class AutoDocs and look for those attributes with a '''OM_SET''' listed as an "applicability".

Again there is variant of the '''SetAttrs()''' function to be used with BOOPSI GUI gadgets: '''SetGadgetAttrs()'''.

== Getting an Object's Attributes ==

Just as we can set attributes of an existing BOOPSI object, we also have the ability to get the current settings from a object's attributes. Inquiring about a specific setting is done using the BOOPSI function '''GetAttr()''':

<syntaxhighlight>
uint32 attr = GetAttr(uint32 attrID, Object *object, uint32 *storage);
</syntaxhighlight>

We start by specifying the '''attrID''' is the attribute's identifier we are interested in, we then have to identify object to get the attribute from ('''object'''), and finally provide an area that will hold the value of the attribute. This function returns a 0 if the object doesn't recognize or return the attribute, otherwise it returns some non-zero value, the meaning of which depends on the class. In most cases, GetAttr() returns a 1 when it is successful.

In the case of our requester example, there are only a few attributes to which values can be obtained. The following example will obtain the result code from the last use of the object:

<syntaxhighlight>
uint32 lastresult;
result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
</syntaxhighlight>

Another example of the '''GetAttr''' function would be to retrieve the value a user provided in an Interger type requester. This information could be restrieved like this:

<syntaxhighlight>
int32 userInt;
result = IIntuition->GetAttr(REQI_Number, reqobj,&userInt);
</syntaxhighlight>

While the simple requester class is not a great example for getting a lot of attributes, BOOPSI provides a second pair of functions that uses taglists for obtaining multiple attributes in one call: '''GetAttrs()''' and '''GetAttrsA''':

<syntaxhighlight>
uint32 retval = GetAttrs(Object *object, Tag tag1, ...);
uint32 retval = GetAttrsA(Object *object, struct TagItem *attrs);
</syntaxhighlight>

As with the previous tag functions mentioned above, these functions are the same except for how the tag list is handled. In the case of each tag pair, the value will be set to the current value in the object queried.

As with setting attributes, not all object attributes are obtainable using the '''GetAttr()''' function, depending on each class. For more information about which attributes can be obtained in specific classes, see the [[BOOPSI_Class_Reference|BOOPSI Class Reference]] and the class AutoDocs and look for those attributes with a '''OM_GET''' listed as an "applicability".

Unlike when creating and setting attributes on BOOPSI GUI gadgets, there are no GUI gadgets specific versions of the '''GetAttr''' family of functions. Instead, the '''GetAttr''' functions can also be used to obtain GUI gadget attributes where they are available (see the Class Reference and autodocs).

== Disposing of an Object ==

When an application is finally done with an object, it has to dispose of the object. To dispose of an object, use the Intuition function '''DisposeObject()''':

<syntaxhighlight>
void DisposeObject(Object *obj);
</syntaxhighlight>

As usual, we use a pointer to our object to indicate the object to be disposed.

In the case of our requester example, we would simply call:

<syntaxhighlight>
IIntuition->DisposeObject(reqobj);
</syntaxhighlight>

In many cases - complex gadget GUI's being the prime example - when a BOOPSI object has connect "child" objects and it is disposed, then all children are also disposed. An example would be a window object and all the gadgets within that window. In any case, you must be careful not to dispose of an object that already been disposed.

== What About the BOOPSI Messages and Methods? ==

In the above sections of this page, the functions used reflect BOOPSI messages and the underlying basic "methods" performed by a BOOPSI object. In the [[BOOPSI#OOP_Overview|"OOP Overview"]] section we see how these saw how these common methods are practically universal to all BOOPSI classes. The above functions simply provide a wrapper for those common methods like this:

{| class="wikitable"
| NewObject() || OM_NEW
|-
| SetAttrs()/SetGadgetAttrs() || OM_SET
|-
| GetAttr() || OM_GET
|-
| DisposeObject() || OM_DISPOSE
|}

These methods are defined on the rootclass level, so all BOOPSI classes inherit them. The Intuition functions that correspond to these methods take care of constructing and sending a BOOPSI message with the appropriate method ID and parameters.

One last function had a more direct relationship to operation and methods of BOOPSI objects - in this case, causing our requester object to present itself :

{| class="wikitable"
| IDoMethod() || RM_OPENREQ
|}

Of course, in the case of different classes and objects, the method would change with how the '''IDoMethod''' function was called on those objects.

== Example Program ==

Below is the complete example program that includes the above excerpts. This program will create a requester object, display a requester with buttons and one with a string gadget and print the results in the shell.

<syntaxhighlight>
/* Requesters Example
gcc -o Requesters Requesters.c -lauto
quit
*/

/*
*
************************************************************
**
** Created by: CodeBench 0.31 (20.5.2013)
**
** Project: OS4ex-Requesters
**
** A simple requester.class example used to demonstrate functionality.
**
** File: Requesters
**
** Date: 20-04-2013 20:43:23
**
** Version: 02
**
************************************************************
*
*/

/* includes
*/
#include <exec/exec.h>
#include <dos/dos.h>
#include <intuition/intuition.h>
#include <classes/requester.h>

#include <proto/intuition.h>
#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/requester.h>

#include <string.h>

/* declarations
*/
Object *reqobj;
struct orRequest reqmsg;
char buffer[100];
uint32 result = 0;

int main()
{

/* create a new requester object
*/
strcpy(buffer,"Welcome to your\nfirst BOOPSI requester");

reqobj = IIntuition->NewObject(NULL,"requester.class",
REQ_Type, REQTYPE_INFO,
REQ_TitleText, "Requesters Example",
REQ_BodyText, buffer,
TAG_END);

// Was the requester object created?
if (reqobj)
{
IDOS->Printf(" Requester object created\n");
/* tell the object to show itself
*/
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
// How did things go?
if (result)
IDOS->Printf(" Req #1 - result code = %ld\n",result);
else
IDOS->Printf(" Req #1 - result = 0\n");

/* reset object characteristics
*/

strcpy(buffer,"default string");
result = IIntuition->SetAttrs( reqobj,
REQ_Type, REQTYPE_STRING,
REQ_BodyText, "please enter some text",
REQS_Buffer, buffer,
REQS_MaxChars, sizeof(buffer) - 1,
TAG_END);

/* tell object to show itself again
*/
result = IIntuition->IDoMethod( reqobj, RM_OPENREQ, NULL, NULL, NULL );
// Did we get a good response?
if (result>0)
{
IDOS->Printf(" Req #2 - result code = %ld\n",result);
IDOS->Printf(" Req #2 - result text = %s\n",buffer);
}
else
IDOS->Printf(" Req #2 - result = 0\n");

/* Lets check some object attributes
*/
uint32 lastresult;

result = IIntuition->GetAttr(REQ_ReturnCode, reqobj,&lastresult);
// Did we get some value?
if (result>0)
IDOS->Printf(" Last result code = %ld\n",lastresult);
else
IDOS->Printf(" This result = 0\n");

/* Dispose of our requester object
*/
IIntuition->DisposeObject(reqobj);
}
else
IDOS->Printf(" ERROR: Failed to create Requester object\n");

return RETURN_OK;
}
</syntaxhighlight>

UserDoc:Main

2018-01-25T21:07:37Z

Daniel Jedlicka: /* AmigaOS platform targets */

== Welcome to AmigaOS ==

AmigaOS was born in 1985 and delivered what contemporary personal computer operating systems could only dream of. As the first "multimedia" operating system, it was trivial for AmigaOS computers to display animations while playing music and reading data from disks. Such multimedia and multitasking finesse drew many people to this system. Some of them are famous: [http://www.amigahistory.co.uk/warhol.html Andy Warhol], Sir Arthur C. Clarke, [http://www.polyphoto.com/upchug/AEcastro.html NASA], Hollywood and the TV broadcasting industry, and many others that thought [http://www.youtube.com/watch?v=PWeO5IkCssk only Amiga makes it possible].

Today many people still think AmigaOS has something special that makes it more interesting and rewarding than other systems. This system allows the user to control the computer, not the other way around. It is a system you fully understand that is easier and more flexible to use. In other words, AmigaOS is '''more fun'''.

=== AmigaOS: The flexible operating system ===
AmigaOS is an operating system: a collection of efficient programs written to start the computer, let the user control the computer, and present feedback to the user.

AmigaOS is designed with ease of use and flexibility in mind. To begin with, AmigaOS provides a clear view of your computer, your applications and files. A number of methods are available to let your computer serve you, whether graphically with a mouse, using the "Shell" command line, or by some other means the user prefers.

AmigaOS strives to avoid stupid limitations that can be found on other systems. AmigaOS users can organise their files the way they like. There are few limits on file hierarchy, locations and file names. Drives don't have to be named with a letter or cryptic names (such as C:, or sda1), your files don't have to reside in your "Documents" folder and your hard drives aren't hidden from you. If you're not writing to drives and you want to "shut down", why wait for the OS to allow that? With AmigaOS, just hit the power switch. Done.

An Amiga does not start with pre-installed applications serving some sales conglomerate, marketing organization or their big brother. AmigaOS does not do actions behind the user's back. As unique as it is today, the AmigaOS computer serves the user and not the other way around. With one of the largest proportions of user-programmers around, the trustworthy AmigaOS user-friendly ethic is mirrored in AmigaOS applications.

Since the first versions more than twenty-five years ago, AmigaOS has also been designed to serve efficiently. Optimizing applications and OS code has always been the goal of programmers and developers of this operating system. The result is an operating system and applications that take less space on your hard drives, waste less time loading, consume less memory, require less processing power, and respond more quickly to the user.

And every update of AmigaOS doesn't demand you must buy newer, more powerful hardware. AmigaOS currently runs on twenty year old 200MHz computers or brand new dual core 1,800MHz computers. It's the user's choice how they want to '''enjoy''' AmigaOS.

=== Some AmigaOS features ===
Here are some of the features of AmigaOS that make it easy to control your computer. Some of these concepts were copied by other operating systems which tend to show they are the correct way of doing things.

* '''Small footprint:''' AmigaOS can work with 64 MB of memory. On disk, a default installation only takes around 200 MB. The smaller footprint translates into a more responsive user experience given any hardware.

* '''Straightforward operating system design:''' With a clear layout and easy to understand names (Classes, Libs, Fonts, Prefs, Storage, etc.), you can easily understand what everything in AmigaOS is and what it does for you. Nothing is hidden from the user and the user is not restricted by AmigaOS.

*'''User configurable graphic interface:''' Using the provided "preferences editors," the user can dramatically reconfigure how AmigaOS looks, sounds, runs and responds to every user whim.

* '''File recognition based on file content:''' You can name a file '''whatever you want''', even without an extension. Examples: "my file" or "picture of Jay in Santa Clara". There is no need to add an extension to explain what the file is, like ".txt" or ".jpg". AmigaOS really examines the '''file content''' to recognise what type of file it is.

* '''Logical assignments:''' Easily set and use logical names names for directories located anywhere on your system. For example, "Auto:" can point to your directory "car show pictures" buried on your media drive.

* '''Ram disk concept:''' On AmigaOS there is a special disk called the '''Ram disk''' which represents a part of your computer memory. This area is not fixed. It automatically grows whenever you store files in it. For example, it's a great place to unpack files to install from there, greatly speeding up the installation.

* '''Command line and graphical user interfaces:''' Both the the graphical user interface (GUI) and command line interface (where you type commands into a window with the keyboard) can be used to manage AmigaOS, its programs and files. Both interfaces are intergated with each other so you can easily use command lines from the GUI or open graphical elements from a command line.

*'''ARexx Ports:''' Throughout AmigaOS and third party programs, "ARexx" message ports let one application talk with others so that apps work together to serve the user. AmigaOS also provides the lightweight ARexx and modern Python programming languages that can control AmigaOS and applications with ARexx ports.

* '''Resident Commands:''' Commands can be made resident, i.e., they are kept in memory so that they can be reused with no loading time.

* '''Restart only the operating system:''' if you feel the need to restart the system, you can do so by restarting '''only AmigaOS''' and not the whole computer.

=== AmigaOS platform targets ===

While the original versions of AmigaOS ran on computers of the eighties using Motorola 68k series CPU chips, the current AmigaOS runs on computers using PowerPC processor chips [http://www.amigaos.net/content/72/supported-hardware hardware]. These can be older Amiga computers (also called "Classic Amigas") with PPC "accelerator cards" or new generation Amiga PPC computers.

In this guide, we will concentrate on the current AmigaOS running on the supported hardware:

* [[AmigaOne A1222]] model by [http://www.a-eon.com A-EON Technology Ltd]

* [[AmigaOne X5000]] model by [http://www.a-eon.com A-EON Technology Ltd]

* [[AmigaOne X1000]] model by [http://www.a-eon.com A-EON Technology Ltd]

* [[AmigaOne 500]], Sam460, Sam440ep and Sam440ep-Flex models by [http://www.acube-systems.com ACube Systems]

* [[Pegasos II]] model by [http://www.bplan-gmbh.de bplan GmbH]

* [[AmigaOne XE and MicroA1-C]] models by [http://en.wikipedia.org/wiki/Eyetech Eyetech Group Ltd].

* [[Classic Amiga]] 4000(T), 3000(T) and 1200 models by Commodore Business Machines (when equipped with PowerPC accelerator cards).

== How does AmigaOS work? - Concepts ==

In this page we will discuss [[UserDoc:How AmigaOS Works|how AmigaOS works]]:

* [[UserDoc:How_AmigaOS_Works#The_most_important_components|The most important components]] (Exec, AmigaDOS, Intuition...)
* [[UserDoc:How_AmigaOS_Works#How_is_my_data_stored.3F|how files and data are stored]]
* [[UserDoc:How_AmigaOS_Works#All_AmigaOS_components|all AmigaOS components are described]]
* [[UserDoc:How_AmigaOS_Works#AmigaOS_boot_procedure|how AmigaOS is booted on your Amiga computer]]
* [[Workbench/Prefs|AmigaOS settings programs]]
* ...

== How to use AmigaOS? ==

AmigaOS is a collection of components that oversee the computer hardware & data and provide the user with easy, understandable tools to manage and use them.

In the following [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS pages]] we will discuss the basic concepts:

* how to use AmigaOS
* what the AmigaOS graphic user interface is composed of
* what interfaces AmigaOS provides, including the [[UserDoc:Workbench|Workbench]], the [[UserDoc:Shell|Shell]] or scripting languages.

From the introduction page, you can continue with more detailed pages on the [[UserDoc:Workbench|Workbench]] and the [[AmigaDOS manual]] . Now let's start with this [[UserDoc:Introduction to AmigaOS|Introduction to AmigaOS]].

== Manuals ==

[[UserDoc:AmigaOS File Systems|AmigaOS File Systems]] - AmigaOS File Systems

[[AmigaOS Manual]] - AmigaOS Manual

[[Bars & Pipes Professional]] - MIDI Sequencer

AmigaOS Manual: AmigaDOS Command Reference

2017-12-28T20:26:52Z

Daniel Jedlicka: Fixed a few typos and other problems reported by OldFart.

The commands in this chapter are executed from the Shell window. They are described in alphabetic order; however, some commands reserved for system use appear together at the end of the chapter.

= Command Documentation =

Each command documented in this manual is shown with the format, arguments, options, symbols, and abbreviations required for proper use.

This chapter and Chapter 7 provide command specifications for the AmigaDOS commands and the Workbench programs accessible through the Shell using the following standard outline:

; Format
: All the arguments and options accepted by a command. The special characters that indicate the particular type of argument are described on page 6-6.

; Template
: An optional on-line reminder of the command's format that is embedded in the program's code. Entering a command followed by a space and a question mark (for example, DIR ?) displays the template. A complete description of the template notation is found on page 6-8.

; Location
: The directory where the command is normally stored.

; Examples
: A sample use of the command. Examples are displayed in the courier typeface to distinguish them from normal text. The 1> represents the Shell prompt; do not type it as part of the example command. Lines in the example not prefaced by 1> represent the output of a command. Command names and keywords are shown in all upper case letters and file and directory names usually have the first letter in upper case; however, they do not need to be entered that way. Press Return to execute the command line.

Separate commands and arguments with spaces. Use punctuation only when required in the syntax of specific commands.

== Format ==

The following lists the characters that indicate the type of argument shown in format listings. Do not use these characters as part of the command.

{| class="wikitable"
| < > || Angle brackets indicate where additional information, such as a file name, must be included. This argument is required if it is not surrounded by square brackets. (For example, [<filename>]; see below.)
|-
| [ ] || Square brackets enclose optional arguments and keywords. Although not required, these arguments and keywords are accepted by the command.
|-
| { } || Braces enclose items that can be given once or repeated any number of times. For example, {<args>} indicates that several items can be given for this argument.
|-
| <nowiki>|</nowiki> || Vertical bars separate lists of options from which you can choose only one. For example, <nowiki>[OPT R|S|RS]</nowiki> indicates a choice of the R option, the S option, or both options.
|-
| <n> || A numeric value is expected by the argument.
|-
| KEYWORD || Italics indicate that the argument's keyword is required if you include that argument.
|-
| ... || An ellipsis (...) after a string argument indicates that the string must be the final argument on the command line. Including a comment is not allowed. The remainder of the command line is taken as the desired string. Quotation marks are not needed around the string, even if it contains spaces. If you enter quotation marks, they are part of the string. If you specify the keyword, you can put leading and trailing spaces in the string.
|-
| command line indentation || On command lines that are long enough to wrap to the next line, this manual shows the wrapped lines as indented for documentation purposes only. In practice, the wrapped lines align with the first character of the Shell prompt.
|}

The format for the COPY command illustrates the use of these conventions:

COPY [FROM] {<name | pattern>} [TO]<name | pattern>[ALL]
[QUIET] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO]
[COM] [NOREQ]

The [FROM] keyword is optional. If it is not specified, the command reads the file name ir pattern to copy by ist position on the command line.

The {<name | pattern>} argument must be provided. You must substitute either a file name or pattern. The braces indicate that more than one name or pattern can be given.

The [TO] keyword is optional. If it is not specified, the command reads the file name or device to copy to by its position on the command line.

The <name | pattern> argument must be provided. You can specify only one destination.

The [ALL], [QUIET], [CLONE], [DATES], [NOPRO], [COM], and [NOREQ] arguments are optional.

The [BUF | BUFFER=<n>] argument is optional. If given, the keyword is required, but you can use either BUF or BUFFER with the numerical argument. For example, both BUF=5 and BUFFER=5 are acceptable. The numerical argument can also be entered without the equals sign; spaces are optional.

== Template ==

The Template is built into the system to serve as an on-line reminder of a command's syntax and to let you run the command from the Template line by providing a prompt at which you enter the command's arguments.

Display the Template by entering a question mark (?) after a command. The Shell assumes that you wish to run the command and it expects you to enter the command's arguments after the colon following the display. For example:

1> TYPE ?
FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S:

Pressing Return executes the command if it does not require any arguments to run properly. Entering the arguments and their respective keywords and then pressing Return also executes the command. If a command requires arguments and you do not supply them or if you enter anything other than the required arguments, pressing Return results in a non-fatal error message. Remember that you do not need to enter the entire format for a command at this prompt, just the required arguments.

The Templates are listed with the arguments separated by commas, followed by a slash (/), and a capital letter indicating the type of argument. These slash/letter combinations are displayed to remind you of the command's particular requirements and are not entered as part of the command. The following table explains the notation:

{| class="wikitable"
! Template Notation !! Format Equivalent !! Meaning
|-
| argument/A || <name> || The argument is always required.
|-
| option/K || KEYWORD || The option's keyword is required if the argument is given.
|-
| option/S || [KEYWORD] || The option works as a switch. The name of the option must be entered to specify it. Most options are switches.
|-
| value/N || <n> || The argument is numeric.
|-
| argument/M || {<name>} || Multiple items are accepted for this argument. Although there is no limit to the number of possible arguments, they must be provided before the next argument or option.
|-
| string/F || argument... || The string must be the final argument on the command line; the remainder of the command line is taken as the desired string.
|-
| = || KYWD <nowiki>|</nowiki> KEYWORD || Two different forms of the keyword are equivalent and either are accepted. The equals sign is not entered as part of the command.
|}

The Template for the COPY command illustrates the use of arguments:

FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,
CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S

FROM/M indicates that the argument is required and more than one argument is acceptable.

TO/A indicates that the argument is required.

ALL/S, QUIET/S, CLONE/S, DATES/S, NOPRO/S, COM/S, and NOREQ/S indicate that the keywords act as switches. If the keyword is present in the line, the option is used.

BUF=BUFFER/K/N indicates that the BUF or BUFFER keyword (/K) is required to specify this numerical (/N) argument. Both BUF and BUFFER are acceptable keywords (=).

Keywords and their arguments can be linked with an equals sign (=) to ensure correct assignments in complex cases. For example, BUF=20.

= Command Listing =

== ADDBUFFERS ==

Instructs the file system to add or display cache buffers for a drive.

; Format
: ADDBUFFERS <drive> [<n>]

; Template
: DRIVE/A,BUFFERS/N

; Location
: C:

ADDBUFFERS adds <n> buffers to the list of buffers available for <drive>. Although adding buffers speeds disk access, each additional buffer reduces free memory by approximately 512 bytes. The default buffer allocation is 5 for sloppy drives and 30 for hard disk partitions.

The amount of extra available memory dictates the number of buffers you can add. There is no fixed upper limit; however, adding too many buffers reduces overall system performance by taking RAM away from other system functions. Specifying a negative number subtracts that many buffers from the current allocation. The minimum number of buffers is one; however, using only one is not recommended.

Twenty buffers are recommended for a floppy drive in a 512 KB system. Use the default value recommended by the HDToolBox program for hard disks. (Display this value by selecting the Advanced Options gadget on the Partitioning screen.)

If only the <drive> argument is specified, ADDBUFFERS displays the number of buffers currently allocated for that drive.

; Example:
1> ADDBUFFERS DF0:
DF0: has 5 buffers

A further example of ADDBUFFERS appears in Chapter 8.

== ADDNETINTERFACE ==

Makes network interfaces known to the protocol stack.

== ADDNETROUTE ==

Adds message routing paths.

== ALIAS ==

Sets or displays command aliases.

; Format
: ALIAS [<name>] [<string...>]

; Template
: NAME,STRING/F

; Location
: Internal

ALIAS creates aliases, or alternative names, for AmigaDOS commands. ALIAS can be used to abbreviate frequently used commands or replace standard command names with different names.

When AmigaDOS encounters <name>, it replaces it with the defined <string>, integrate the result with the rest of the command line, and attempts to interpret and execute the resulting line as an AmigaDOS command <Name> is the alias for the command and <string> is the command to be substituted for the alias.

An alias must be entered at the beginning of the command line. You can enter arguments after the alias, but you cannot create an alias to represent a series of command arguments. For example, in the following command line:

1> NEWSHELL WINDOW=CON:0/250/640/150/2SHELL/CLOSE

the WINDOW argument cannot be replaced with an alias.

You can substitute a file name or other instruction within an alias by placing square brackets ([ ]) with nothing between them in the <string>. Any argument entered after the alias is inserted at the brackets.

ALIAS <name> displays the <string> for that alias. Entering ALIAS alone lists all current aliases.

Aliases are local to the Shell in which they are defined. If you create another Shell with the NEWSHELL command, it shares the same aliases as its parent Shell. However, if you create another Shell with the Execute Command menu item, it des not recognize aliases created in your original Shell. A global lais that is recognized by all Shells can be crated by inserting the alias in the Shell-startup file.

To remove an ALIAS, use the UNALIAS command.

; Example 1:
1> ALIAS d1 DIR DF1:

Entering d1 displays a directory of the contents of the disk in DF1:; as if you entered DIR DF1:.

; Example 2:

1> ALIAS hex TYPE [ ] HEX

creates an alias called HEX that displays the contents of a specified file in hexadecimal format. The empty brackets indicate where the file name is inserted in this example. Entering:

1> hex Myfile

displays the contents of Myfile in hexadecimal format.

See also: UNALIAS. Further examples of using ALIAS appear in Chapter 8.

== ARP ==

Address resolution display control.

== ASK ==

Gets yes or no user input during script file execution.

; Format
: ASK <prompt>

; Template
: PROMPT/A

; Location
: Internal

ASK is used in scripts to write the string specified by <prompt> to the current window and then wait for keyboard input. Valid keyboard responses are Y (yes), N (no), and Return (no). Selecting Y sets the condition flag to 5 (WARN). Selecting N or pressing Return sets the condition flag to 0. Check the response using an IF statement.

If the <prompt> contains spaces, it must be enclosed in quotation marks.

; Example:

Assume a script contained the following commands:

ASK Continue?
IF WARN
ECHO Yes
ELSE
ECHO No
ENDIF

At the ASK command, Continue? Is displayed on the screen. If Y is pressed, Yes is displayed on the screen. If N or a Return alone is pressed, No is displayed.

See also: IF, ELSE, ENDIF, REQUESTCHOICE, WARN

== ASSIGN ==

Controls assignment of logical device names to files or directories.

; Format
: ASSIGN [<name>:] [{<target>}] [LIST] [EXISTS] [DISMOUNT] [DEFER] [PATH] [ADD] [REMOVE] [VOLS] [DIRS] [DEVICES]

; Template
: NAME,TARGET/M,LIST/S,EXISTS/;,DISMOUNT/S,DEFER/S,PATH/S,ADD/S,REMOVE/S,VOLS/S,DIRS/S,DEVICES/S

; Location
: C:

ASSIGN allows references to files or directories with short, convenient logical device names, rather than their usual names or complete paths. The ASSIGN command can create assignments, remove assignments, or list some or all current assignments.

If the <name> and {<target>} arguments are given, ASSIGN assigns the given logical name to the specified target. Each time the assigned logical device name is referred to, AmigaDOS accesses the specified target. If the <name> given is already assigned to a file or directory, the new target replaces the previous one. A colon must be included after the <name> argument.

If only the <name> argument is given, any existing ASSIGN of a file or directory to that logical device name is cancelled.

You can assign several logical device names to the same target by using multiple ASSIGN commands.

You can assign one logical device name to several targets by specifying each file or directory after the <name> argument or by using several ASSIGN commands with the ADD option. Specifying the ADD option does not replace any existing target assigned to <name>. This target is added to the ASSIGN list and the system searches for all the targets when <name> is encountered. If the first target is not available, ASSIGN uses the next target added.

The REMOVE option deletes a target name from the ASSIGN list.

If no arguments are given with ASSIGN or if the LIST keyword is used, a list of all current assignments is displayed. If the VOLS, DIRS, or DEVICES switch is specified, ASSIGN limits the display to volumes, directories, or devices.

When the EXISTS keyword is entered with a logical device name, AmigaDOS searches the ASSIGN list for that name and displays the volume and directory assigned to that device. If the device name is not found, the condition flag is set to 5 (WARN).

When the {<target>} argument is given, AmigaDOS immediately looks for that file or directory. If the ASSIGN commands are part of the User-startup, the targets must be present on a mounted disk during the boot procedure. If an assigned target cannot be found, a requester asks for the volume containing it. However, using the DEFER and PATH options make the system wait until the target is needed before searching for it.

{{Note|The assigned name does not have to retain the name of the file or directory and it does not have to be in upper case. For example, the name CLIPS: or Clips: can be assigned to the Ram Disk:Clipboards directory.}}

The DEFER option creates a late-binding ASSIGN. This ASSIGN takes effect when the assigned object is first referenced, rather than when the assignment is made. When the DEFER option is used, the disk containing the assigned target is not needed until the object is called. The assignment then remains valid until explicitly changed.

If you ASSIGN FONTS: to DF0:Fonts with the DEFER option, the system associates FONTS: with the disk that is in DF0: when FONTS: is referred to. For example, if you have a Workbench disk in DF0: at the time the FONTS: directory is needed, the system associates FONTS: with that particular Workbench disk. If you later remove that Workbench disk and insert another disk containing a Fonts directory, the system specifically requests the original Workbench disk the next time FONTS: is needed.

The PATH option creates a non-binding ASSIGN. A non-binding ASSIGN acts like a DEFERed ASSIGN, except that is re-evaluated each time the assigned name is referenced. For example, if you assign FONTS: to DF0:Fonts with the PATH option, any disk in DF0: is searched when FONTS: is referenced. As long as the disk contains a Fonts directory, it satisfies the ASSIGN. You cannot assign multiple directories with the PATH option.

Floppy disk only system users can find that using the PATH option eliminates the need to reinsert the original Workbench disk used to boot the system. As long as the drive you assigned with the PATH option contains a disk with the assigned directory name, the system uses that disk.

The DISMOUNT option disconnects a volume or device from the list of mounted devices. You must provide the device name in the argument. DISMOUNT removes the name form the list, but does not free resources. You cannot cancel a DISMOUNT without rebooting. DISMOUNT is meant for use by software developers only and can cause a software failure if not used carefully.

; Example 1:

1> ASSIGN FONTS: MyFonts:Fontdir

assigns the FONTS: directory to Fontdir on MyFonts:

; Example 2:

1> ASSIGN LIST
Volumes:
Ram Disk [Mounted]
Workbench [Mounted]
MyFonts [Mounted]

Directories:
LOCALE Workbench:Locale
KEYMAPS Workbench:Devs/Keymaps
PRINTERS Workbench:Devs/Printers
REXX Workbench:S
CLIPS Ram Disk:Clipboards
ENV Ram Disk:Env
T Ram Disk:T
ENVARC Workbench:Prefs/Env-Archive
SYS Workbench:
C Workbench:C
S Workbench:S
L Workbench:L
FONTS MyFonts:Fontdir
DEVS Workbench:Devs
LIBS Workbench:Libs
+ Workbench:Classes

Devices:
PIPE AUX RAM CON
RAW PAR SER PRT DF0

Shows a typical list of all current assignments. The plus sign indicates any additional directories with the same assignment.

; Example 3:

1> ASSIGN FONTS: EXISTS
FONTS: MyFonts:FontDir

is an inquiry into the assignment of FONTS:. AmigaDOS responds by showing that FONTS: is assigned to the FontDir directory of the MyFonts volume. The return code is set to 0 if it exists or to 5 if it does not.

; Example 4:

1> ASSIGN LIBS: SYS:Libs BigAssem:Libs ADD

is a multiple-directory assignment that creates a search path containing two Libs directories. Specifying ADD keeps the standard SYS:Classes assignment from being removed. These directories are searched in sequence each time LIBS: is invoked.

; Example 5:

1> ASSIGN DEVS:

removes the DEVS: assignment from the system.

; Example 6:

1> ASSIGN WorkDisk: DF0: DEFER
1> ASSIGN WorkDisk: EXISTS
WorkDisk <DF0:>

sets up a late-binding assignment of the logical device WorkDisk:. Until the first time you refer to the name WorkDisk:, you do not need to insert it in DF0: ASSIGN shows DF0: enclosed in angle brackets to indicate that it is DEFERred. After the first reference to WorkDisk:, the volume name of the disk that was in DF0: replaces <DF0:>.

; Example 7:

1> ASSIGN C: DF0:C PATH
1> ASSIGN C: EXISTS
C [Df0: C]

references the C directory fo the disk that is in DF0: when a command is searched for. ASSIGN shows DF0:C in square brackets to indicate that it is a non-binding ASSIGN.

; Example 8:

1> ASSIGN LIBS: Zcad:Libs ADD

adds Zcad:Libs to the list of directories assigned as LIBS:.

; Example 9:

1> ASSIGN LIBS: Zcad:Libs REMOVE

removes Zcad:Libs from the list of directories assigned as LIBS:.

For more examples using ASSIGN, see Chapter 8.

== AVAIL ==

Reports the amount of Chip and Fast memory available.

; Format
: AVAIL [VHIP | FAST | TOTAL] [FLUSH]

; Template
: CHIPS/S,FAST/S,TOTAL/S,FLUSH/S

; Location
: C:

AVAIL gives a summary of the system RAM, both Chip and Fast. For each memory type, AVAIL reports the total amount of memory, how much is available, how much is currently in use, and the largest contiguous memory block not yet allocated.

Unless you want a complete summary, use the CHIP, FAST, and/or TOTAL options to have AVAIL display only the number of free bytes of Chip, Fast, or Total RAM available.

The FLUSH option frees memory by removing all unused libraries, devices, fonts, catalogs.

; Example 1:
1> AVAIL
Type Available In-Use Maximum Largest
chip 233592 282272 515864 76792
fast 341384 182896 524280 197360
total 574976 465168 1040144 197360

A complete summary of system RAM is displayed.

; Example 2:
1> AVAIL CHIP
233592

The number of free bytes of Chip RAM is displayed.

See Chapter 8 for more examples using AVAIL.

== BREAK ==

Sets attention flags in the specified process.

; Format
: BREAK <process> [ALL | C | D | E | F]

; Template
: PROCESS/A/N,ALL/S,C/S,D/S,E/S,F/S

; Location
: C:

BREAK sets the specified attention flags in the <process> indicated. Use the STATUS command to display the current process numbers. C sets the Ctrl+C flag, D sets the Ctrl+D flag, and so on, ALL sets all the flags from Ctrl+C to Ctrl+F. By default, only the Ctrl+C flag is set.

BREAK acts the same as selecting the relevant process by clicking in its window and pressing the appropriate Ctrl+key combinations.

Ctrl+C is the default for sending a BREAK signal to halt a process. A process that has been aborted this way displays ***Break in the Shell window. Ctrl+D halts execution of a script file. The STATUS command displays the current process numbers. Ctrl+E is undefined.

Ctrl+F is used by programs that open windows to activate their window and bring it to the front of all windows. Not all programs respond to Ctrl+F.

; Example 1:
1> BREAK 7

sets the Ctrl+C attention flag of process 7. This is the same as selecting process 7 and pressing Ctrl+C.

; Example 2:
1> BREAK 5 D

sets the Ctrl+D attention flag of process 5.

See also: STATUS

== BUILDMAPTABLE ==

Creates a binary mapping table to Unicode for diskfont.library from ASCII mapping table.

== CD ==

Sets or displays the current directory.

; Format
: CD [<dir | pattern>]

; Template
: DIR

; Location
: Internal

CD with no arguments displays the name of the current directory. When a valid directory name is given, CD makes the named directory the current directory.

You must specify a complete path to the directory since CD does not search through the disk for it. If CD cannot find the specified directory in the current directory or in the given path, a Can't find <directory> message is displayed.

To move up a level in the filing hierarchy to the parent directory of the current directory, enter CD followed by a space and a single slash (/). You can move to another directory in the parent at the same time by including its name after the slash. If the current directory is a root directory, CD / has no effect. Use multiple slashes with no spaces between them to refer to additional higher levels.

To move directly to the root directory of the current device, use CD followed by a space and a colon; for example, CD :

AmigaDOS supports an implied CD so that the CD command itself can often be left out. Enter the directory name, path, colon, or slashes at the prompt.

CD also supports pattern matching. When a directory matching the specified pattern is found, it becomes the current directory. If more than one directory matches the given pattern, an error message is displayed. You cannot use pattern matching with implied CD. For more information an pattern matching, see Chapter 3.

; Example 1:
1> CD DF1:Work

sets the current directory to the Work directory on the disk in drive DF1:.

; Example 2:
1> CD SYS:Com/Basic

makes the subdirectory Basic in the Com directory the current directory.

; Example 3:
1> //

using the implied CD, moves up two levels in the directory structure.

; Example 4:
1> CD SYS:Li#?

uses the #? pattern to match with the LIBS: directory.

For more examples using the CD command, see Chapter 8.

== CHANGETASKPRI ==

Changes the priority of a currently running process.

; Format
: CHANGETASKPRI <priority> [PROCESS <process number>]

; Template
: PRI=PRIORITY/A/N,PROCESS/K/N

; Location
: C:

CHANGETASKPRI changes the priority of the specified Shell process. If no process is specified, the current Shell process is assumed. Any shell process started from <process number> inherits its priority.

Use the STATUS command to display the current process numbers.

The range of acceptable values for <priority> is the integers from -128 to 127, with higher values yielding a higher priority (a greater proportion of CPU time is allocated). However, do not enter values above +10 to avoid disrupting important system tasks.

; Example:
1> CHANGETASKPRI 4 Process 2

The priority of Process 2 is changed to 4. Any shell process started from this Shell also has a priority of 4. They have priority over any other user tasks created without using CHANGETASKPRI (those tasks have a priority of 0).

See also: STATUS. For another example for using CHANGETASKPRI, see Chapter 8.

== CHARSETCONVERT ==

Converts a text file from one charset into another.

== CLIP ==

Reads or writes any clipboard unit.

== CONFIGURENETINTERFACE ==

Configure network interface parameters.

== COPY ==

Copies files or directories.

; Format
: COPY [FROM] {<name | pattern>} [TO] <name> [ALL] [quiet] [BUF | BUFFER=<n>] [CLONE] [DATES] [NOPRO] [COM] [NOREQ]

; Template
: FROM/M,TO/A,ALL/S,QUIET/S,BUF=BUFFER/K/N,CLONE/S,DATES/S,NOPRO/S,COM/S,NOREQ/S

; Location
: C:

COPY copies the file or directory specified with the FROM argument to the file or directory specified by the TO argument. You can copy several items at once by giving more than one name/pattern in the FROM argument; they should be separated by spaces. If the FROM argument is a pattern or consists of multiple names, the TO argument must be a directory.

If a TO file name already exists, COPY overwrites the TO file with the FROM file. You can use a pair of double quotation marks ("") to refer to the current directory. When used as the FROM argument, "" copies all the files in the current directory. Do not put any spaces between the double quotation marks.

If the FROM argument is a directory, only the directory's files are copied; its subdirectories are not copied. Use the ALL option to copy the complete directory, including its files, subdirectories, and the subdirectories' files. It is possible to create a directory as you copy if you are copying more than one file. To give the new directory a name, specify the directory name as the last component in the TO argument's path. This can be any name, including the same name as the original if it is a different path.

COPY prints to the screen the name of each file as it is copied. This can be overridden by the QUIET option.

The BUF= option is used to set the number of 512-byte buffers used during the copy. (Default is 128 buffers, 64 KB of RAM.) Limit the number of buffers when copying to RAM:. BUF=0 uses a buffer the same size as the file to be copied.

By default, COPY gives a TO file the timestamp of when the copy was made, rather than that of the original file. Also by default, comments attached to the original FROM file are not copied and the protection bits of the FROM file are copied to the TO file. You can override these defaults using the following:

{| class="wikitable"
| CLONE || The timestamp, comments, and protection bits of the FROM file are copied to the TO file.
|-
| DATES || The timestamp of the FROM file is copied to the TO file.
|-
| COM || Any comment attached to the FROM file is copied to the TO file.
|-
| NOPRO || The protection bits of the FROM file are not copied to the TO file. The TO file is given standard protection bits or r, w, e, and d.
|}

COPY displays a requester if the COPY cannot continue. When the NOREQ option is given, all requesters are suppressed. Use this in scripts to prevent a COPY failure from stopping the script to wait for a response. With the NOREQ option, the COPY command is aborted and the script continues.

; Example 1:
1> COPY File1 TO :Work/File2

copies File1 in the current directory to the Work directory in the root of the current device, renaming it File2.

; Example 2:
1> COPY Chapter#? TO DF1:Backup

copies all the files whose names start with Chapter in the current directory to the Backup directory on the disk in DF1:. The Backup directory is created if it does not already exist.

; Example 3:
1> COPY Work:Test TO ""

copies the files in the Test directory on Work to the current directory; subdirectories in Test are not copied.

; Example 4:
1> COPY Work:Test TO DF0:Test ALL

copies all the files and any subdirectories of the Test directory on Work to the Test directory on DF0:. If a Test directory does not already exist on DF0:, COPY creates one.

; Example 5:
1> COPY DF0: TO DF1: ALL QUIET

copies all files and directories on the disk in DF0: to DF1:, without displaying on the screen any file/directory names as they are copied. (For disks less than half full, this can be faster than DiskCopy.)

For more examples using COPY, see Chapter 8.

== COUNTLINES ==

Counts how many lines a file is made of.

== CPU ==

Adjusts various options of the microprocessor installed in your Amiga. The command also shows the processor and options that are currently enabled.

; Format
: CPU [CACHE | NONCACHE] [BURST | NOBURST] [DATACAHCE | NODATACACHE] [DATABURST | NODATABURST] [INSTCACHE | NOINSTCACHE] [INSTBURST | NOINSTBURST] [FASTROM | NOFASTROM] [TRAP | NOTRAP] [COPYBACK | NOCOPYBACK] [EXTERNALCACHE | NOEXTERNALCACHE] [NOMMUTEST] [CHECK 68010 | 68020 | 68030 | 68040 | 68881 | 68882 | 68851 | MMU | FPU]

; Template
: CACHES/S,BURST/S,NOCACHE/S,NOBURST/",DATACACHE/S,NODATACHE/S,DATABURST/S,NODATABURST/S,INSTCACHE/S,NOINSTCACHE/S,INSTBURST/S,NOINSTBURST/S,COPYBACK/S,NOCOPYBACK/S,EXTERNALCACHE/S,NOEXTERNALCACHE/S,FASTROM/S,NOFASTROM/S,TRAP/S,NOTRAP/S,NOMMUTEST/S,CHECK/K

; Location
: C:

Many options only work with certain members of the 680x0 processor family. The 68020 has a special type of memory known as instruction cache. When instruction cache is used, instructions are executed more quickly. The 68030 and 68040 have two types of cache memory: instruction and data.

If mutually exclusive options are specified, the safest option is used. Availability of the following options depends on the type of microprocessor present.

{| class="wikitable"
| CACHE || Turns on all caches.
|-
| NOCACHE || Turns off all caches.
|-
| BURST || Turns on burst mode for both data and instructions.
|-
| NOBURST || Turns off burst mode for data and instructions.
|-
| DATACACHE || Turns on data cache.
|-
| NODATACACHE || Turns off data cache.
|-
| DATABURST || Turns on burst mode for data.
|-
| NODATABURST || Turns off burst mode for data.
|-
| INSTCACHE || Turns on instruction cache.
|-
| NOINSTCACHE || Turns off instruction cache.
|-
| INSTBURST || Turns on burst mode for instructions.
|-
| NOINSTBURST || Turns off burst mode for instructions.
|-
| FASTROM || With a processor having a supported MMU, copies the system ROM into 32-bit RAM, making access to operating system functions significantly faster. CPU then write-protects the RAM area so that the data cannot be changed.
|-
| NOFASTROM || Turns off FASTROM.
|-
| TRAP || This option is for developers only.
|-
| NOTRAP || This option is for developers only.
|-
| COPYBACK || Turns on 68040 copyback cache.
|-
| NOCOPYBACK || Turns off 68040 copyback cache.
|-
| EXTERNALCACHE || Turns on external cache.
|-
| NOEXTERNALCACHE || Turns off external cache.
|-
| NOMMUTEST || Allows the MMU settings to be changed without checking to see if an MMU is currently in use.
|}

The CHECK option, when given with a keyword (68010, 68020, 68030, 68040, 68881, 68882, or 68851, MMU, FPU) checks for the presence of the processor indicated by the keyword.

; Examples:
1> CPU
System: 68030 68881 (INST: Cache Burst) (DATA: Cache NoBurst)

1> CPU NODATACACHE FASTROM
System: 68030 68881 FastRom (INST: Cache Burst)
(DATA: NoCache NoBurst)

1> CPU NOBURST DATACACHE NOINSTCACHE
System: 68030 68881 (INST: NoCache NoBurst) (DATA: Cache NoBurst)

== CUT ==

Cuts some characters or words from a string.

== DATE ==

Displays or sets the system date and/or time.

; Format
: DATE [<day>] [<date>] [<time>] [TO | VER <filename>]

; Template
: DAY,DATE,TIME,TO=VER/K

; Location
: C:

DATE with no argument displays the currently set system time and date, including the day of the week. Time is displayed using a 24-hour clock.

DATE <date> sets only the date. The format for entry and display of <date> is DD-MMM-YY (day-month-year). The hyphens between the arguments are required. A leading zero in the date is not necessary. The number or the first three letters of the month (in English) must be used, as well as the last two digits of the year.

If the date is already set, you can reset it by specifying a day name. You can also use tomorrow or yesterday as the <day> argument. You cannot specify a day name to change the date to more than seven days into the future.

DATE <time> sets the time. The format for entry and display of <time> is HH:MM:SS (hours:minutes:seconds). Seconds is optional.

If your Amiga does not have a battery backed-up hardware clock and you do not set the date, when the system boots it sets the date to the date of the most recently created file on the boot disk.

If you specify the TO or VER option, followed by a file name, the output of the DATE command is sent to that file, overwriting any existing contents.

Adjustments made with DATE only change the software clock and do not survive powering off the system. To set the battery backed-up hardware clock from the Shell, you must set the date and use SETCLOCK SAVE.

Although DATE accepts and displays the date and time in a single format, programs such as Clock display the date and time according to your Locale country setting.

; Example 1:
1> DATE
6-Sep-92

; Example 2:
1> DATE 6-sep-92

sets the date to September 6, 1992. The time is not reset.

; Example 3:
1> DATE tomorrow

resets the date to one day ahead.

; Example 4:
1> DATE TO Fred

sends the current date to the file Fred.

; Example 5:
1> DATE 23:00

sets the current time to 11:00 p.m.

; Example 6:
1> DATE 1-jan-02

sets the date to January 1st, 2002. The earliest date you can set is January 1, 1978.

== DELETE ==

Deletes files or directories.

; Format
: DELETE {<name | pattern>} [ALL] [QUIET] [FORCE]

; Template
: FILE/M/A,ALL/S,QUIET/S,FORCE/S

; Location
: C:

DELETE attempts to erase the specified items. You can delete multiple items at the same time by listing them individually or by using a wildcard to delete a specific set of files matching a pattern. The pattern can specify directory levels, as well as names. To abort a multiple-item DELETE, press Ctrl+C. A multiple-item DELETE aborts if and when it finds something that cannot be removed; for example, a file is delete-protected or in use. A pattern matching DELETE removes everything it can and lists the items that it did not delete, if any.

{{Note|AmigaDOS does not request confirmation of deletions. Do not use pattern matching to delete things if you are not familiar with the procedure; deleted items cannot be recovered, unless you have an up-to-date backup of the items deleted.}}

An error message warns you that you cannot delete directories that still contain files. Override this using the ALL option. DELETE ALL deletes the named directory, its subdirectories, and all files.

File names are displayed on the screen as they are deleted. To suppress the screen output, use the QUIET option.

If the d (deletable) protection bit of a file or directory has been cleared, that item cannot be deleted unless the FORCE option is used.

; Example 1:
1> DELETE Old-file

deletes the file named Old-file in the current directory.

; Example 2:
1> DELETE Work/Prog1 Work/Prog2 Work

deletes the files Prog1 and Prog2 in the Work directory and then deletes the Work directory if it contains no other files.

; Example 3:
1> DELETE T#?/#?(1|2)

deletes all the files that end in 1 or 2 in directories that start with T.

; Example 4:
1> DELETE DF1:#? ALL FORCE

deletes all the files on DF1:, even those set as not deletable.

See also: PROTECT. For more examples using DELETE, see Chapter 8.

== DELETENETROUTE ==

Deletes a message routing path currently in use.

== DIR ==

Displays a sorted list of the files in a directory.

; Format
: DIR [<dir | pattern>] [OPT A | I | AI | D | F] [ALL] [DIRS] [FILES] [INTER]

; Template
: DIR,OPT/K,ALL/S,DIRS/S,FILES/S,INTER/S

; Location
: C:

DIR displays the file and directory names contained in the specified directory or the current directory. Directories are listed first, followed by an alphabetical list of the files in two columns. Pressing Ctrl+C aborts a directory listing.

The options are:
{| class="wikitable"
| ALL || Displays all subdirectories and their files.
|-
| DIRS || Displays only directories.
|-
| FILES || Displays only files.
|-
| INTER || Enters an interactive listing mode.
|}

The ALL, DIRS, FILES, and INTER keywords supersede the OPT A, D, F, and I options, respectively. The older keywords are retained for compatibility with earlier versions of AmigaDOS. Do not use OPT with the full keywords - ALL, DIRS, FILES, or INTER.

Interactive listing mode stops after each name to display a question mark at which you can enter commands. The acceptable responses are shown below:

{| class="wikitable"
| Press Return || Displays the next name on the list.
|-
| E || Enters a directory; the files in that directory are displayed.
|-
| B || Goes back one directory level.
|-
| DEL or DELETE || Deletes a file or empty directory. DEL does not refer to the Del key; enter the letters D, E, and L.
|-
| T || Types the contents of a file.
|-
| C or COMMAND || Allows you to enter additional AmigaDOS commands.
|-
| Q || Quits interactive editing.
|-
| ? || Displays a list of the available interactive-mode commands.
|}

The COMMAND option allows almost any AmigaDOS command to be executed during the interactive directory list. To issue a command, enter C (or COMMAND) at the question mark prompt. DIR asks you for the command. Enter the desired command, then press Return. The command is executed and DIR continues. You can also combine the C and the command on one line by putting the command in quotation marks following the C.

For example,

? C "type prefs.info hex"

is equivalent to pressing Q to exit interactive listing mode and return to a regular Shell prompt, then entering:

1> TYPE Prefs.info HEX

to display the Prefs.info file on the screen in hexadecimal format.

Formatting a disk from the DIR interactive mode is not recommended since the format takes place immediately, without any confirmation requesters appearing. Do not start another interactive DIR from interactive mode since it results in garbled output.

; Example 1:
1> DIR Workbench:

displays a list of the directories and files on the Workbench disk.

; Example 2:
1> DIR MyDisk:#?.memo

displays all the directories and files on MyDisk that end in .memo.

; Example 3:
1> DIR Extras: ALL

displays the complete contents of the Extras drawer: all directories, all subdirectories, and all files, including those in the subdirectories.

; Example 4:
1> DIR Workbench: DIRS

displays only the directories on Workbench.

; Example 5:
1> DIR Workbench: INTER

begins an interactive list of the contents of the Workbench disk.

For more examples using DIR, see Chapter 8.

== DISKCHANGE ==

Informs the Amiga that you have changed a disk in a disk drive.

; Format
: DISKCHANGE <device>

; Template
: DRIVE/A

; Location
: C:

You must use the DISKCHANGE command to inform the system when you change disks or cartridges in 5.25 inch floppy disk drives or removable media drives without automatic diskchange hardware.

; Example:

If a requester asks you to insert a new disk into your 5.25 inch drive, known as DF2:, you must insert the disk and then enter:

1> DISKCHANGE DF2:

AmigaDOS then recognizes the new disk and you can proceed.

== DISMOUNT ==

Shuts down a file system device and all its associated volumes.

== ECHO ==

Displays a string.

; Format
: ECHO [<string>] [NOLINE] [FIRST <n>] [LEN <n>] [TO <filename>]

; Template
: /M,LINE/S,FIRST/K/N,LEN/K/N,TO/K

; Location
: Internal

ECHO writes the specified string to the current output window or device. By default the string is sent to the screen, but if you use the TO option, you can send the string to any specified device or file.

When the NOLINE option is specified, ECHO does not automatically move the cursor to the next line after printing the string.

The FIRST and LEN options allow the echoing of a substring. FIRST <n> indicate the character position from which to begin the echo; LEN <n> indicates the number of characters of the substring to echo, beginning with the FIRST character. If the FIRST option is omitted and only the LEN keyword is given, the substring printed consists of the rightmost <n> characters of the main string. For example, if your string is 20 characters long and you specify LEN 4, the 17th, 18th, 19th and 20th characters of the string are echoed.

; Examples:

1> ECHO "hello out there!"

hello out there!

1> ECHO "hello out there!" NOLINE FIRST 0 LEN 5 hello1>

For further examples using the ECHO command, see Chapter 8.

== ED ==

Edits text files (a screen editor).

; Format
: ED [FROM] <filename> [Size <n>] [WITH <filename>] [WINDOW <window specification>] [TABS <n>] [WIDTH | COLS <n>] [HEIGHT | ROWS <n>]

; Template
: FROM/A,SIZE/N,WITH/K,WINDOW/K,TABS/N,WIDTH=COLS/N,HEIGHT=ROWS/N

; Location
: C:

See [[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#ED|ED]] for more information. See Chapter 8 for an example using ED.

== EDIT ==

Edits text files by processing the source file sequentially (a line editor).

; Format
: EDIT [FROM] <filename> [[TO <filename>] [WITH <filename>] [VER <filename>] [OPT P <lines> | W <chars> | P<lines>W<chars>] [WIDTH <chars>] [PREVIOUS <lines>]

; Template
: FROM/A,TO,WITH/K,VER/K,OPT/K,WIDTH/N,PREVIOUS/N

; Location
: C:

See [[AmigaOS_Manual:_AmigaDOS_Using_the_Editors#EDIT|EDIT]] for more information.

== ELSE ==

Specifies an alternative for an IF statement in a script file.

; Format
: ELSE

; Template
: (none)

; Location
: Internal

ELSE must be used in conjunction with the IF command. ELSE is used in an IF block of a script to specify an alternative action if the IF condition is not true. If the IF condition is not true, execution of the script jumps from the IF line to the line after ELSE; all intervening commands are skipped. If the IF condition is true, the commands immediately following the IF statement are executed up to the ELSE. Then, execution skips to the ENDIF statement that concludes the IF block.

; Example:

Assume a script, called Display, contains the following block:

IF exists picfile
MultiView picfile
ELSE
ECHO "picfile is not in this directory"
ENDIF

If picfile can be found in the current directory, the MultiView program is executed and picfile is displayed on the screen.

If picfile cannot be found in the current directory, the script skips to the ECHO command. The following message is displayed in the Shell window:

picfile is not in this directory

See also: IF, ENDIF, EXECUTE

== ENDCLI ==

Ends a Shell process.

; Format
: ENDCLI

; Template
: (none)

; Location
: Internal

ENDCLI ends a Shell process.

See also: ENDSHELL

== ENDIF ==

Terminates an IF block in a script file.

; Format
: ENDIF

; Template
: (none)

; Location
: Internal

ENDIF must be used when an IF commands is used. ENDIF is used in scripts at the end of an IF block. If the IF condition is not true or if the true-condition commands are executed and an ELSE is encountered, the execution of the script skips to the next ENDIF command. Every IF statement must be terminated by an ENDIF.

The ENDIF applies to the most recent IF or ELSE command.

See also: IF, ELSE. For examples using the ENDIF command, see Chapter 8.

== ENDSHELL ==

Ends a Shell process.

; Format
: ENDSHELL

; Template
: (none)

; Location
: Internal

ENDSHELL ends a Shell process and closes the Shell window.

The Shell process can also be ended by ENDCLI, by clicking on the close gadget, or by pressing CTRL+\.

Use ENDSHELL only when the Workbench or another Shell is running. If you quit the Workbench and you close your only Shell, you cannot communicate with the Amiga without rebooting.

The Shell window cannot close if any process that were launched from the Shell and not detached are still running. Even though the window stays open, the Shell does not accept new input. You must terminate those processes before the window closes. For example, if you opened an editor from the Shell, the Shell window does not close until you exit the editor.

For examples using the ENDSHELL command, see Chapter 8.

== ENDSKIP ==

Terminates a SKIP block in a script file.

; Format
: ENDSKIP

; Template
: (none)

; Location
: Internal

ENDSKIP is used in scripts to terminate the execution of a SKIP block. A SKIP block allows you to jump over intervening commands if a certain condition is met. When an ENDSKIP is encountered, execution of the script resumes at the line following the ENDSKIP. The condition flag is set to 5 (WARN).

See also: SKIP

== EVAL ==

Evaluates integer or Boolean expressions.

; Format
: EVAL <value1> {[<operation>] [<value2>]} [TO <file>] [LFORMAT=<string>]

; Template
: VALUE1/A,OP,VALUE2/M,TO/K,LFORMAT/K

; Location
: C:

EVAL is used to evaluate and print the answer of an integer expression. The fractional portion of input values and final results, if any, is truncated (cut off). If a non-integer is given as an input value, evaluation stops at the decimal point.

<Value1> and <value2> can be decimal (the default), hexadecimal, or octal numbers. Hexadecimal numbers are indicated by either a leading Ox or #x. Octal numbers are indicated by either a leading 0 or a leading #. Alphabetical characters are indicated by a leading single quotation mark (`) and are evaluated as their ASCII equivalent.

The LFORMAT keyword specifies the formatting string used to print the answer. You can use %X (hexadecimal), %O (octal), %N (decimal), or %C (character). The %X and %O options require a number of digits using the LFORMAT keyword, you can specify to print a new line by including *N in your string.

The supported operations and their corresponding symbols are shown in the following table.

{| class="wikitable"
| addition || +
|-
| subtraction || -
|-
| multiplication || *
|-
| division || /
|-
| modulo || mod, M, m, or %
|-
| bitwise AND || &
|-
| bitwise OR || <nowiki>|</nowiki>
|-
| bitwise NOT || ~
|-
| left shift || Ish, L, or l
|-
| right shift || rsh, R, or r
|-
| negation || -
|-
| exclusive OR || xor, X, or x
|-
| bitwise equivalence || eqv, E, or e
|}

EVAL can be used in scripts as a counter for loops. In that case, use the TO option to send the output of EVAL to a file.

Parentheses can be used in the expressions.

; Example 1:
1> EVAL 64 / 8 + 2
10

; Example 2:
1> EVAL 0x5f / 010 LFORMAT="The answer is %X4*N"
The answer is 000B
1>

This divides hexadecimal 5f (95) by octal 10 (8), yielding 000B, the integer portion of the decimal answer 11.875. (The 1> prompt appears immediately after the 000B if *N is not specified in the LFORMAT string.)

For more examples using the EVAL command, see Chapter 8.

== EXECUTE ==

Executes a script with optional argument substitution.

; Format
: EXECUTE <script> [{<arguments>}]

; Template
: FILE/A

; Location
: C:

EXECUTE is used to run scripts of AmigaDOS commands. The lines in the script are executed as if they had been entered at a Shell prompt. If the s protection bit of a file is set and the file is in the search path, enter only the file name; the EXECUTE command is not needed.

You can use parameter substitution in scripts by including special keywords in the script. When these keywords are used, you can pass variables to the script by including the variable in the EXECUTE command line. Before the script is executed, AmigaDOS checks the parameter names in the script against any arguments given on the command line. If any match, AmigaDOS substitutes the values specified on the command line for the parameter name in the script. You can also specify default values for AmigaDOS to use if no variables are given. If you have not specified a variable and there is no default specified in the script, then the value of the parameter is empty (no substitution is made).

The allowable keywords for parameter substitution are explained in Chapter 5. Each keyword command line must be prefaced with a dot character (.).

See also: IF, SKIP, FAILAT, LAB, ECHO, RUN, QUIT. For examples using the EXECUTE command, see Chapter 8.

== FAILAT ==

Instructs a command sequence not to fail unless a given error condition is returned.

; Format
: FAILAT [<n>]

; Template
: RCLIM/N

; Location
: Internal

Commands indicate that they have failed by setting a nonzero return code. The return code, normally 5, 10, or 20, indicates the severity of the error. A return code greater than or equal to a certain limit, the fail limit, terminates a sequence of non-interactive commands (commands specified after RUN or in a script).

Use the FAILAT command to alter the fail limit RCLIM (Return Code Limit) from its initial value of 10. If you increase the limit, you indicate that certain classes of error should not be regarded as fatal and that execution of subsequent commands can proceed after the error. The argument must be a positive number. The fail limit is reset to the initial value of 10 on exit from the command sequence.

If the argument is omitted, the current fail limit is displayed.

; Example:

Assume a script contains the following lines:

COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."

If MyFile cannot be found, the scripts is aborted and the following message appears in the Shell window:

COPY: object not found
COPY failed returncode 20:

However, if you changed the return code limit to higher than 20, the script continues even if the COPY command fails. For example, if you changed the script to read:

FAILAT 21
COPY DF0:MyFile to RAM:
ECHO "MyFile being copied."

Even if MyFile cannot be found, the script continues. The following message appears in the Shell window:

COPY: object not found
MyFile being copied.

See also: ECHO, EXECUTE.

== FAULT ==

Prints the messages for the specified error numbers.

; Format
: FAULT {<n>}

; Template
: /N/M

; Location
: Internal

FAULT prints the messages corresponding to the error numbers supplied. As many error numbers, separated by spaces, as you want can be specified to print at the same time.

; Example:

If you receive the error message:

Error when opening DF1:TestFile 205

and need more information, enter:

1> FAULT 205
FAULT 205: object not found

This tells you that the error occurred because TestFile could not be found on DF1:.

A complete list of error messages appears in Appendix A.

== FILENOTE ==

Attaches a comment to a file.

; Format
: FILENOTE [FILE] <file | pattern> [COMMENT <comment>] [ALL] [QUIET]

; Template
: FILE/A,COMMENT,ALL/S,QUIET/S

; Location
: C:

FILENOTE attaches an optional comment of up to 79 characters to the specified file or to all files matching the given pattern.

If the <comment> includes spaces, it must be enclosed in double quotation marks. To include double quotation marks in a filenote, each literal quotation mark must be immediately preceded by an asterisk (*) and the entire comment must be enclosed in quotation marks, regardless of whether the commend contains any spaces.

If the <comment> argument is omitted, any existing filenote is deleted from the named file.

Creating a comment with FILENOTE is the same as entering a comment into the Comment gadget of an icon's Information window. Changes made with FILENOTE are reflected in the Information window, and vice versa.

Use the LIST command to view comments made with FILENOTE. If a file has comments, LIST displays them below the file name.

When a existing file is copied to (specified as the TO argument of a COPY command), it is overwritten, but its original comment is retained. Any comment attached to a FROM file is not copied unless the CLONE or COM option of COPY is specified.

If the ALL option is given, FILENOTE adds the <comment> to all the files and subdirectories matching the pattern entered. If the QUIET options is given, screen output is suppressed.

; Example 1:
1> FILENOTE Sonata "allegro non troppo"

attaches the filenote allegro non troppo to the Sonata file.

; Example 2:
1> FILENOTE Toccata "*"presto*""

attaches the filenote "presto" to the Toccata file.

== FILESIZE ==

Collects information on the size of files stored on a disk.

== FTP ==

ARPANET file transfer program.

== GET ==

Gets the value of a local variable.

; Format
: GET <name>

; Template
: NAME/A

; Location
: Internal

GET is used to retrieve and display the value of a local environment variable. The value is displayed in the current window.

Local environment variables are only recognized by the Shell in which they are created or by any Shells created from a NEWSHELL command executed in the original Shell. If you open an additional Shell by opening the Shell icon or by using the Execute Command menu item, previously created local environment variables are not available.

; Example:
1> GET editor
Extras:Tools/MEmacs

See also: SET

== GETENV ==

Gets the value of a global variable.

; Format
: GETENV <name>

; Template
: NAME/A

; Location
: Internal

GETENV is used to retrieve and display the value of a global environment variable. The value is displayed in the current window. Global variables are stored in ENV: and are recognized by all Shells.

; Example:
1> GETENV editor
Extras:Tools/MEmacs

See also: SETENV

== GETNETSTATUS ==

Queries whether the network is operational.

== GROUP ==

Changes the access rights of a file or directory.

== HELP ==

Text based help command.

== HI ==

Halts all ARexx programs.

== HISTORY ==

Display, recall, or store the command line history.

== ICONX ==

{{Note| ICONX is used only as a default tool in a project icon and cannot be used as a Shell command.}}

Allows execution of a script file of AmigaDOS commands from an icon.

; Format
: ICONX

; Template
: (none)

; Location
: C:

To use ICONX, create or copy a project icon for the script. Open the icon's Information window and change the Default Tool of the icon to C:ICONX and select Save to store the changed .info file. The script can then be executed by double-clicking on the icon.

When the icon is opened, ICONX changes the current directory to the directory containing the project icon before executing the script. A console window can be opened on the Workbench screen if the script produces output.

Several Tool Types can be specified in the script icon. The WINDOW Tool Type provides an alternate window specification for the input/output window. By default, the window's specification is:

WINDOW=CON:0/50//80/IconX/AUTO/WAIT/CLOSE

The AUTO option opens a window only if there is output created by the script. If a window opens, the WAIT option forces it to remain open after the script terminates until you specifically close it. The CLOSE option gives the window a close gadget.

The WAIT Tool Type (not to be confused with the WAIT option of the WINDOW Tool Type) specifies the number of seconds the input/output window should remain open after the script terminates. If you use this option the default input/output window cannot be closed before the WAIT period has expired. There is also a DELAY Tool Type that works in very similar way, except that its parameter is in 1/50th of a second, instead of in seconds.

The STACK Tool Type specifies the number of bytes to use for stack during script execution. If this Tool Type is not provided, the default 4096 bytes is used.

Finally, the USERSHELL Tool Type runs the script file using the current Use Shell instead of the normal ROM Shell. You must specify USERSHELL=YES. User Shells are third party shells that you can purchase and install in your system to replace the standard Amiga Shell environment that comes with the operating system.

Extended selection passes files that have icons to the script. Their file names appear to the script as keywords. To use this facility, the .KEY keyword must appear at the start of the script. In this case, the AmigaDOS EXECUTE command is used to execute the script file.

See also: EXECUTE. For examples using the ICONX command, see Chapter 8.

== IF ==

Evaluates conditional operations in script files.

; Format
: IF [NOT] [WARN | ERROR | FAIL] [<string> EQ| GT | GE <string>] [VAL] [EXISTS <filename>]

; Template
: NOT/S,WARN/S,ERROR/S,FAIL/S,EQ/K,GT/K,GE/K,VAL/S,EXISTS/K

; Location
: Internal

In a script file, IF, when its conditional is true, carries out all the subsequent commands until an ENDIF or ELSE command is found. IF must be used in conjunction with ENDIF, however, ELSE is optional. When the conditional is not true, execution skips directly to the ENDIF or to an ELSE. The conditions and commands in IF and ELSE blocks can span more than one line before their corresponding ENDIFs.

Nested Ifs jump to the matching ENDIF.

The additional keywords are as follows:
{| class="wikitable"
| NOT || Reverses the interpretation of the result.
|-
| WARN || True if previous return code is greater than or equal to 5.
|-
| ERROR || True if previous return codes is greater than or equal to 10; only available if FAILAT is set to greater than 10.
|-
| FAIL || True if previous return code is greater than or equal to 20; only available if FAILAT is set to greater than 20.
|-
| <a> GT || True if the test of a is greater than the text of b (disregarding case). Use NOT GT for less than.
|-
| <a> GE || True if the text of a is greater than or equal to the text of b (disregarding case). Use NOT GE for less than or equal to.
|-
| <a> EQ || True if the text of a and b is identical (disregarding case).
|-
| VAL || Specifies a numeric comparison.
|-
| EXISTS <file> || True if the file exists.
|}

If more than one of the three condition-flag keywords (WARN, ERROR, FAIL) are given, the one with the lowest value is used.

You can use local or global variables with IF by prefacing the variable name with a $ character.

; Example 1:
IF EXISTS Work/Prog
TYPE Work/Prog HEX
ELSE
ECHO "It's not here"
ENDIF

AmigaDOS displays the file Work/Prog if it exists in the current directory. Otherwise, AmigaDOS displays the message It's not here and continues after the ENDIF.

; Example 2:
IF ERROR
SKIP errlab
ENDIF
ECHO "No error"
LAB errlab

If the previous command produces a return code greater than or equal to 10, AmigaDOS skips over the ECHO command to the errlab label.

See also: EXECUTE, FAILAT, LAB, QUIET, SKIP. For more examples using the IF command, see Chapter 8.

== INFO ==

Gives information about mounted devices.

; Format
: INFO [<device>]

; Template
: DEVICE

; Location
: C:

INFO displays a line of information about each mounted storage device, including floppy disk drive and hard disk partitions. Listed are the unit name, maximum size of the disk, the used and free space in blocks, the percentage of the disk that is full, the number of soft disk errors that have occurred, the status of the disk, and the name of the disk.

With the <device> argument, INFO provides information on the specified device or volume only.

; Example:
1>INFO

Unit Size Used Free Full Errs Status Name
DF0: 879K 1738 20 98% 0 Read Only Workbench
DF1: 879K 418 1140 24% 0 Read/Write Text-6

Volumes available:
Workbench [Mounted]
Text-6 [Mounted]

== INSTALL ==

Writes or inspects a boot blocks on a formatted floppy disk or PCMCIA card, specifying whether it should be bootable.

; Format
: INSTALL [DRIVE] <DF0: | DF1: | DF2: | DF3: | CC0:> [NOBOOT] [CHECK] [FFS]

; Template
: DRIVE/A,NOBOOT/S,CHECK/S,FFS/S

; Location
: C:

INSTALL clears a floppy disk's or PCMCIA memory card's boot block area and writes a valid boot onto it. INSTALL does not affect any files or directories on the disk or card. The necessary files and directories must still be present on a device to boot from it successfully.

The NOBOOT option removes the boot block from an AmigaDOS disk or card, making it not bootable.

The CHECK option checks for valid boot code. It reports whether a disk or card is bootable and whether standard Amiga boot code is present on the media. This is useful in detecting some viruses.

The FFS switch is ignored. It remains part of the template to ensure compatibility with earlier scripts and programs.

; Example 1:
1> INSTALL DF0: CHECK
No bootblock installed

indicates that there is a non-bootable floppy in DF0:.

; Example 2:
1> INSTALL DF0:

makes the disk in drive DF0: a bootable disk.

; Example 3:
1> INSTALL DF0: CHECK
Appears to be FFS bootblock

indicates that there is a bootable FFS floppy in DF0:.

== IPF ==

Alters packet filtering lists for IP packet input and output.

== IPSTAT ==

Reports on packet filter statistics and filter list.

== IPMON ==

Monitors /dev/ipl for logged packets.

== IPNAT ==

Defines NAT (Network Address Translation) rules.

== JOIN ==

Concatenates two or more files into a new file.

; Format
: JOIN [FILE] <file | pattern>} AS | TO <filename>

; Template
: FILE/M/A,AS=TO/K/A

; Location
: C:

JOIN copies all the listed files, in the order given, to one new file. This destination file cannot have the same name as any of the source files. You must supply a destination file name. The original files remain unchanged. Any number of files can be JOINed in one operation.

TO can be used as a synonym for AS.

; Example:
1> JOIN Part1 Part2 Part3 AS Textfile

For another example using JOIN, see Chapter 8.

== LAB ==

Specified a label in a script file.

; Format
: LAB [<string>]

; Template
: (none)

; Location
: Internal

LAB is used in script to define a label that is searched for by the SKIP command. The label <string> can be of any length, but must be alphanumeric. No symbols are allowed. If the <string> contains spaces, it must be enclosed in quotation marks.

See also: SKIP, IF, EXECUTE. For more examples using LAB, see Chapter 8.

== LIST ==

Lists specified information about directories and files.

; Format
: LIST [{<dir | pattern | filename>}] [P | PAT <pattern>] [KEYS] [DATES] [NODATES] [TO <name>] [DUB <string>] [SINCE <date>] [UPTO <date>] [QUICK] [BLOCK] [NOHEAD] [FILES] [DIRS] [LFORMAT <string>] [ALL]

; Template
: DIR/M,P=PAT/K,KEYS/S,DATES/S,NODATES/S,TO/K,SUB/K,SINCE/K,UPTO/K,QUICK/S,BLOCK/S,NOHEAD/S,FILES/S,DIRS/S,LFORMAT/K,ALL/S

; Location
: C:

LIST displays information about the contents of the current directory. If you specify a <dir>, <pattern>, or <filename> argument, LIST displays information about the specified directory, all directories or files that match the pattern, or the specified file, respectively. The PAT argument lets you specify an additional pattern to match.

Unless other options are specified, LIST displays the following:
{| class="wikitable"
| name || The name of the file or directory.
|-
| size || The size of the file in bytes. If there is nothing in this file, the field reads "empty". For directories, this entry reads "Dir".
|-
| protection || The protection bits that are set for this file are shown as letters. The clear (unset) bits are shown as hyphens. Most files show the default protection bits, ----rwed for readable/writable/executable/deletable. See the PROTECT command for more on protection bits.
|-
| date and time || The date and time the file was created or last changed.
|-
| comment || The comment, if any, placed on the file using the FILENOTE command. It is preceded by a colon (:).
|}

LIST uses the following options to change the way the output is displayed:
{| class="wikitable"
| KEYS || Displays the block number of each file header or directory.
|-
| DATES || Displays dates. (For example, DD-MMM-YY is the USA default).
|-
| NODATES || Does not display date and time information.
|-
| TO <name> || Specifies an output file or device for LIST; by default, LIST outputs to the current window.
|-
| SUB <string> || Lists only files containing the substring <string>.
|-
| SINCE <date> || Lists only files timestamped on or after the specified date.
|-
| UPTO <date> || Lists only files timestamped on or before the specified date.
|-
| QUICK || Lists only the names of files and directories.
|-
| BLOCK || Displays file sizes in 512-byte blocks, rather than bytes.
|-
| NOHEAD || Suppresses printing of the header and summary information.
|-
| FILES || Lists files only (no directories).
|-
| DIRS || Lists directories only (no files).
|-
| LFORMAT || Defines a string to specially format LIST output.
|-
| ALL || Lists the contents of all directories and subdirectories.
|}

The LFORMAT option modifies the output of LIST and can be used as a quick method of generating script files. When using LFORMAT, specify an output format string; this string is output for each file or directory normally listed. It can contain any text you specify, plus the usual LIST output information. When LFORMAT is specified, the QUICK and NOHEAD options are automatically selected. To save the output, you must redirect it to a file by using the > operator or specifying a TO file. (For examples using the LIST LFORMAT option, see Chapter 8.)

The available substitution operators are:
{| class="wikitable"
| %A || Prints file attributes (protection bits).
|-
| %B || Prints size of file in blocks.
|-
| %C || Prints any comments attached to the file.
|-
| %D || Prints the date associated with the file.
|-
| %E || Prints just the file extension.
|-
| %K || Prints the file key block number.
|-
| %L || Prints the length of the file in bytes.
|-
| %M || Prints the file name only, omitting any extension.
|-
| %N || Prints the name of the file.
|-
| %P || Prints the file parent path.
|-
| %S || Superseded by %N and %P; still functional.
|-
| %T || Prints the time associated with the file.
|}

You can put a length specifier and/or a justification specifier between the percent sign (%) and the field specifier. To specify left justification, place a minus sign (-) before the length specifier. Otherwise, the information displayed is right justified.

The default output of the LIST command uses the following specification:

%-24 %7L %A %D %T

; Example 1:
> LIST Dirs

Prefs Dir ----rwed 27-Jun-93 11:43:59
T Dir ----rwed 16-Jul-93 11:37:43
Trashcan Dir ----rwed 21-Jun-93 17:54:20

Only the directories in the current directory, in this case SYS:, are listed. (A shortened version of the typical output is shown above.)

; Example 2:
1> LIST LI#? TO RAM:Libs.file

LIST searches for any directories or files that start with LI. The output of LIST is sent to Libs.file in RAM:.

; Example 3:
1> LIST DF0:Documents UPTO 09-Oct-90

Only the files or directories in the Documents directory of DF0: that have not been changed since October 9, 1990 are listed.

For further examples using the LIST command, see Chapter 8.

== LOADMONDRVS ==

Starts monitor drivers.

== LOADRESOURCE ==

Preloads resources into memory to avoid excessive disk swaps.

; Format
: LOADRESOURCE {<name>} [LOCK | UNLOCK]

; Template
: NAME/M,LOCK/S,UNLOCK/S

; Location
: C:

LOADRESOURCE reduces the need for excessive disk swaps on floppy-only systems by preloading the following of resources into memory:
{| class="wikitable"
| Libraries || Specify the path name to the library.
|-
| Devices || Specify the path name to the device; you cannot LOCK devices into memory.
|-
| Fonts || Specify the path name to the exact font file to be loaded.
|-
| Catalogs || Specify a path name as LOCALE:Catalogs/<language>/Sys/<catalog>.
|}

The {<name>} option specifies the paths of the resources to load. The LOCK option tells the command to lock resources, such as libraries, fonts, and catalogs, into memory. This prevents the system from flushing the resource from RAM if memory is low. Although you can preload devices into memory using LOADRESOURCE, you cannot force them to stay in memory using the LOCK option. The UNLOCK option tells the command to unlock the resource from memory, allowing it to be flushed from RAM.

Entering LOADRESOURCE with no options lists all the LOCKed resources in RAM.

; Example 1:
LOADRESOURCE LIBS:asl.library

loads asl.library into memory. The system can flush this library from RAM the next time it runs low on memory, unless the LOCK option is included in the command line.

; Example 2:
LOADRESOURCE FONTS:topaz/11

loads the Topaz 11 font into memory.

; Example 3:
LOADRESOURCE LOCALE:Catalogs/English/Sys/monitors.catalog

is a valid path name.

== LOADWB ==

Starts Workbench.

; Format
: LOADWB [-DEBUG] [DELAY] [CLEANUP] [NEWPATH]

; Template
: -DEBUG/S,DELAY/S,CLEANUP/S,NEWPATH/S

; Location
: C:

LOADWB starts the Workbench. Normally, this is in the Startup-sequence file that starts Workbench when booting. If you close the Workbench, LOADWB can restart it from a Shell.

The -DEBUG option makes a special developer menu, Debug, available in the Workbench menu bar. If the DELAY option is specified, LOADWB waits three seconds before executing to allow disk activity time to stop. The CLEANUP option automatically performs a cleanup of the initial disk window.

Workbench snapshots the current paths in effect when the LOADWB command is executed. It uses these paths for each Shell started from Workbench. NEWPATH allows you to specify a new path that is snapshot from the current Shell.

; Example 1:

If you quit the Workbench and are working through a Shell, enter:

1> LOADWB

to return the Workbench. Entering LOADWB when the Workbench is already loaded has no effect.

; Example 2:

1> PATH DF2:bin ADD
1> LOADWB NEWPATH

loads the Workbench. Any Shells started from the icon have the same path as the Shell used to run the LOADWB NEWPATH command.

== LOCK ==

Sets the write-protect status of a device.

; Format
: LOCK <drive> [ON | OFF] [<passkey>]

; Template
: DRIVE/A,ON/S,OFF/S,PASSKEY

; Location
: C:

LOCK sets or unsets the write-protect status of a device or partition. The LOCK remains on until the system is rebooted or until the LOCK is turned off with the LOCK OFF command.

An optional passkey can be specified. If the passkey is used to lock a hard disk partition, the same passkey must be specified to unlock the partition. The passkey can be any number of characters long.

; Example:
1> LOCK Work: ON SecretCode

The Work partition is locked. You can read the contents of Work with commands such as DIR, LIST, or MORE but you cannot alter the contents of the partition. If you try to edit the contents of a file on Work, a requester indicates that Work is write-protected. For example, if you try to create a new directory by entering the following:

1> MAKEDIR WORK:Test

the following message appears:

Can't create directory Work:Test
Disk is write-protected

To unlock the partition, enter:

1> LOCK Work: OFF SecretCode

Locking a device is only good for the duration of the current session. Resetting or turning off the Amiga cancels the lock.

== LOGVIEWER ==

Captures any debug or notification messages sent by bsdsocket.library or its clients.

== MAGTAPE ==

Retensions, rewinds, or skips forward SCSI (Small Computer System Interface) tapes.

; Format
: MAGTAPE [DEVICE <device name>] [UNIT <n>] [RET | RETENSION] [REW | REWIND] [SKIP <n>]

; Template
: DEVICE/K,UNIT/N/K,RET=RETENSION/S,REW=REWIND/S,SKIP/N/K

; Location
: C:

By default, MAGTAPE uses SCSI device unit 4. To change the default, you must use both the DEVICE and UNIT keywords.

The RET | RETENSION option runs the tape to the end and rewinds it. The REW | REWIND option rewinds the tape. The SKIP <n> option skips <n> files on the tape.

MAGTAPE tests to see if the unit is ready before sending the command. If your tape is not on-line, repeat the command.

; Example:
1> MAGTAPE DEVICE second_scsi.device UNIT 0 REW

== MAKEDIR ==

Creates a new directory.

; Format
: MAKEDIR {<name}

; Template
: NAME/M

; Location
: C:

MAKEDIR creates new, empty directories with the names you specify. The command works within only one directory level at a time, so any directories on the given paths must already exist. The command fails of a directory or a file of the same name already exists in the directory in which you attempt to create a new one.

MAKEDIR does not create a drawer icon for the new directory.

; Example 1:
1> MAKEDIR Tests

creates a directory called Tests in the current directory.

; Example 2:
1> MAKEDIR DF1:Xyz

creates a directory Xyz in the root directory of the disk in DF1:.

; Example 3:
1> CD DF0:
1> MAKEDIR Documents Payables Orders

creates three directories on the disk in DF0:: Documents, Payables, and Orders.

For more examples using MAKEDIR, see Chapter 8.

== MAKELINK ==

Creates a link between files.

; Format
: MAKELINK [FROM] <file> [TO] <file> [HARD] [FORCE]

; Template
: FROM/A,TO/A,HARD/S,FORCE/S

; Location
: C:

MAKELINK creates a FROM file, known as a link, that is a pointer to another file, the TO file, on the disk. When an application or command falls the FROM file, the TO file is used. By default, MAKELINK supports hard links: the FROM file and TO file must be on the same volume.

Normally, MAKELINK does not support directory links. To create a directory link, you must use the FORCE option. If MAKELINK detects that you are creating a circular link, such as a link to a parent directory, a Link loop not allowed message is issued.

== MD5SUM ==

Calculates and compares checksums of files.

== MOUNT ==

Makes a device connected to the system available.

; Format
: MOUNT {device} [FROM <filename>]

; Template
: DEVICE/M,FROM/K

; Location
: C:

MOUNT reads a device's configuration parameters from a file. It then uses the parameter information to mount the devices or make them available to the system. Multiple devices can be mounted with a single command. The {device} argument specifies the names of the devices to be mounted.

MOUNT can process either DOSDrivers mount files or a traditional multiple-entry MountList file, depending on which of the following three ways the arguments are specified:

# Given a device name, MOUNT tries to find a mount file of that name in DEVS:DOSDrivers, then in SYS:Storage/DOSDrivers, and finally as an entry in DEVS:MountList. This method is best if you have only one configuration for that device on your system.
# Given a path, MOUNT looks for a mount file in that location. Wildcards may be used to mount multiple devices; as in MOUNT DEVS:DOSDrivers/~(#?.info). Use this method when you have mount files stored somewhere other than the DOSDrivers drawers or if you have several mount file to process at once.
# Given the FROM keyword and a path, MOUNT specifies the location of a MountList file to process. Use this method if you have a MountList stored somewhere other than DEVS: or if you have several MountLists.

{{Note|A mount file's icon Tool Types, if any, override parameters of the same name in the mount file itself.}}

; Example 1:
1> MOUNT PIPE:

This looks for the mount file DEVS:DOSDrivers/PIPE and processes it if found. If DEVS:DOSDrivers/PIPE does not exist, MOUNT looks for SYS:Storage/DOSDrivers/PIPE. If this also fails, then MOUNT looks for a PIPE: entry in DEVS:MountList.

; Example 2:
1> MOUNT Work:Devices/PIPE

This looks for a PIPE mount file in Work:Devices.

; Example 3:
1> MOUNT PIPE: FROM SYS:Mydevs/MountList

This scans for a PIPE entry in SYS:Mydevs/MountList.

See Appendix B for further information on MountLists.

== MOUNTINFO ==

Creates mount files for file systems.

== MOVE ==

Moves files or directories.

== NETLOGVIEWER ==

Captures any debug or notification messages sent by bsdsocket.library or its clients.

== NETSHUTDOWN ==

Shuts down the network in an orderly fashion.

== NEWCLI ==

Opens a new Shell window.

; Format
: NEWCLI [<window specification>] [FROM <filename>]

; Template
: WINDOW,FROM

; Location
: Internal

NEWCLI starts a new Shell process. It is the same as using the NEWSHELL command.

== NEWSHELL ==

Opens a new Shell window.

; Format
: NEWSHELL [<window specification>] [FROM <filename>]

; Template
: WINDOW,FROM

; Location
: Internal

The new Shell window becomes the currently-selected window and process. The new window has the same current directory, prompt string, path, local environment variables, and stack size as the one from which it is invoked. However, each Shell window is independent, allowing separate input, output, and program execution.

The window can be sized, dragged, zoomed, and depth-adjusted like most other Amiga windows.

To create a custom window, you can include the <window specification> argument. Specify the initial dimensions, location, and title of the window with this <window specification> syntax:

CON:x/y/width/height/title/options

where:
{| class="wikitable"
| x || Is the number of pixels from the left edge of the screen to the left border of the Shell window. Use a value (//) to specify the minimum possible pixels.
|-
| y || Is the number of pixels from the top of the screen to the top of the Shell window. Use no value (//) to specify the minimum possible pixels.
|-
| width || Is the width of the Shell window, in pixels. Use no value (//) to specify the full width of the screen.
|-
| height || Is the height of the Shell window, in pixels. Use no value (//) to specify minimum possible height.
|-
| title || Is the text that appears in the Shell window title bar.
|}

Use slashes to separate the parameters and options. If any spaces appear in the specification argument, the entire argument must be enclosed in double quotation marks (").

The allowable options are:
{| class="wikitable"
| AUTO || The window automatically appears when the program needs input or produces output. With the Shell window, it opens for input immediately. The window can only be closed with the ENDSHELL command. Selecting the Shell's close gadget closes the window, but it re-opens immediately since it is expecting input.
|-
| ALT || The window appears in the specified size and position when the zoom gadget is clicked. The four parameters must be separated with slashes (for example, ALT30/30/200/200).
|-
| BACKDROP || The window appears on the backdrop, behind all the Workbench windows. This Shell window cannot be brought to the front of the screen; you have to resize the Workbench windows to see it.
|-
| CLOSE || The window has all the standard gadgets, including a close gadget. This is the default for Shell windows, but you must specify it to get a standard Shell if you use the WINDOW argument.
|-
| INACTIVE || The window opens, but is not made the active window.
|-
| NOBORDER || The window opens without any left or bottom window border. Only the zoom, depth, and sizing gadgets are available.
|-
| NOCLOSE || The window does not have a close gadget. If you open a console normally, there is no close gadget. If you open a console using the AUTO option, there is automatically a close gadget on the window.
|-
| NODEPTH || The window has no window depth gadget.
|-
| NODRAG || The window cannot be dragged. It has zoom, depth and sizing gadgets, but no close gadget.
|-
| NOSIZE || The window only has a depth gadget.
|-
| SCREEN || The window opens on a public screen. The screen must already exist. You must specify the name of the screen after the SCREEN keyword.
|-
| SIMPLE || If you enlarge the window, the text expands to fill the newly available space, allowing you to see text that had been scrolled out of the window. This is the default for standard Shells.
|-
| SMART || If you enlarge the window, the text does not expand to fill the newly available space. This saves memory.
|-
| WAIT || The window can only be closed by selecting the close gadget or entering Ctrl+\. If WAIT is the only option, there is no close gadget.
|}

NEWSHELL uses the default startup file S:Shell-startup, unless a FROM file name is specified. S:Shell-startup is a standard AmigaDOS script file. For example, you can have several different Shell-startup files, each having different command aliases. You can call such customized Shell environments with FROM.

The NEWCLI command has the same effect as NEWSHELL; it invokes a new Shell process.

; Example 1:
1> NEWSHELL

opens a new Shell window with the default window specification.

; Example 2:
1> NEWSHELL "CON://640/200/My Shell/CLOSE"

A window starting in the upper left corner of the screen and measuring 640 pixels wide and 200 pixels high opens. The window is titled My Shell and it has a close gadget. The entire argument is enclosed in quotation marks because the title contains a space. If you add the command to your User-startup file, a Shell window opens automatically when your Amiga is booted.

; Example 3:
1> NEWSHELL FROM S:Programming.startup

opens a new Shell, but instead of executing the Shell-startup file, the Programming.startup file is executed. You can have aliases and prompt commands in the Programming.startup file that are used only when you are programming.

For more examples using NEWSHELL, see Chapter 8.

== NVGETVAR ==

Prints the value of all or a named UBoot environment variable.

== OWNER ==

Changes the ownership of a file or directory.

== PATH ==

Controls the directory list that the Shell searches to find commands.

; Format
: PATH [{<dir>}] [ADD] [SHOW] [RESET] [REMOVE] [QUIET]

; Template
: PATH/M,ADD/S,SHOW/S,RESET/S,REMOVE/S,QUIET/S

; Location
: Internal

PATH lets you see, add to, or change the search path the AmigaDOS follows when looking for a command or program to execute. When a directory is in the search path, you do not need to specify the complete path to any command within that directory. Entering the name alone makes AmigaDOS look through the directories in the search path until it finds the file.

{{Note|The search path is only relevant when AmigaDOS is searching for a command or program to execute. Full path specifications are always necessary in arguments for commands such as COPY and DELETE.}}

Enter the PATH command alone or with the SHOW option to display directory names in the current search path. Normally, when PATH is displaying the directory names, a requester appears if a volume that is part of the search path cannot be found. For example, if you add a floppy disk to the search path and then remove that disk from the disk drive, a requester asks you to insert the disk.

If you specify the QUIET option, PATH does not display requesters for volumes that are not currently mounted. If PATH encounters an unmounted volume, it displays the message device (or volume) is not mounted . The names of any directories on that volume included in the PATH are not displayed.

The ADD option specifies directory to be added to the current PATH. You can add any number of directories with one PATH ADD command (the ADD keyword is optional); names of the directories must be separated by at least one space. When you issue the PATH command, AmigaDOS searches for each of the ADDed directories.

To replace the existing search path with a new one, use PATH RESET followed by the names of the new directories. The existing search path, except for the current directory and C:, is erased and the new one is substituted.

The REMOVE option eliminates the named directory from the search path.

; Example:
1> PATH EXTRAS:Tools ADD

adds the Tools directory in the Extras drawer to the search path of the Shell. If the EXTRAS: is not in a disk drive, a requester asks you to insert it in any drive.

If you remove EXTRAS: from the drive and enter:

1> PATH

a list of directories in the search path is displayed. A requester asks you to insert EXTRAS:. If you enter:

1> PATH QUIET

the list of directories in the search path is displayed. However, when the path comes to Extras:Tools, the error message appears in the list.

See also: ASSIGN. For more examples using PATH, see Chapter 8.

== PATHPART ==

Splits and assembles directory and file names.

== PING ==

Sends ICMP ECHO_REQUEST packets to network hosts.

== PIPE ==

Connects input and output streams of Shell commands.

== POPCD ==

Returns the directory last recently saved with the PUSHCD command.

== PROMPT ==

Changes the prompt string of the current Shell.

; Format
: PROMPT [<prompt>]

; Template
: PROMPT

; Location
: Internal

PROMPT allows you to customize the prompt string, the text printed by the Shell at the beginning of a command line. The prompt string can contain any characters, including escape sequences.

This manual shows the prompt string as 1>.

The default prompt string is:

"%N.%S>"

which displays the Shell number, a period, the current directory, a right angle-bracket, and a space. Entering PROMPT without a string argument resets the prompt to this default.

The substitutions available for the <prompt> string are:

{| class="wikitable"
| %N || Displays the process number for the Shell.
|-
| %S || Displays the current directory.
|-
| %R || Displays the return code for the last operation.
|}

A space is not automatically added to the end of the string. If you want a space between the prompt and typed-in text, place it in the string, and enclose the string in double quotation marks,

You can embed commands in the prompt string by enclosing the command in back apostrophes (`).

; Example 1:

1> PROMPT %N
1

Only the Shell number is shown. The > is removed from the prompt.

; Example 2:

1> PROMPT "%N.%S.%R>"
1.Work:Snim.0>

The Shell number, current directory, and return code of the previous command are shown. A space is included after the >.

For more examples using the PROMPT command, see Chapter 8.

== PROTECT ==

Changes the protection bits of a file or directory.

; Format
: PROTECT [FILE] <file | pattern> [FLAGS][+ | -] [<flags>] [ADD | SUB] [ALL] [QUIET]

; Template
: FILE/A,FLAGS,ADD/S,SUB/S,ALL/S,QUIET/S

; Location
: C:

All files and directories have a series of protection bits (attributes) stored with them that control their properties. These bits can be altered to indicate the type of file and the operations permitted. PROTECT is used to set or clear the protection bits. For directories, only the d bit is significant.

The protection bits are represented by letters:
{| class="wikitable"
| s || The file is a script.
|-
| p || The file is a pure command and can be made resident.
|-
| a || The file has been archived.
|-
| r || The file can be read.
|-
| w || The file can be written to (altered).
|-
| e || The file is executable (a program).
|-
| d || The file or directory can be deleted. (Files within a delete-protected directory can still be deleted.)
|}

Use the LIST command to see the protection bits associated with a file. The protection field is displayed with set (on) bits shown by their letters and clear (off) bits shown by hyphens. For example, a file that is readable, writable, and deletable has ----rw-d in the protection field.

To specify the entire protection field at the same time, enter the letters of the bits you want set as the FLAGS argument without any other keywords. The named bits are set and all the others are cleared.

The symbols + and - (or the equivalent keywords ADD and SUB) are used to control specific bits without affecting the state of unspecified bits. Follow + or - with the letters of the bits to set or clear, respectively, and only those bits are changed. There is no space after the symbol or between the letters. The order of the letters does not matter. ADD and SUB work similarly, but there must be a space between the keyword and the letters. You cannot both set and clear bits in the same command.

The ALL options adds or removes the specified protection bits from all the files and subdirectories matching the pattern entered. The QUIET option suppresses the screen output.

; Example 1:
1> PROTECT DF0:Memo +rw

sets only the protection bits r (readable) and w (writable) of the file Memo on DF0:. No other protection bits are changed.

; Example 2:
1> PROTECT L:#? e SUB

clears the e (executable) protection bit from all the files in the L: directory.

; Example 3:
1> PROTECT Work:Paint rwed

The protection status of Paint becomes "----rwed".

== PUSHCD ==

Saves the current directory on a stack and optionally changes it.

== QUIT ==

Exits from a script file with a specified return code.

; Format
: QUIT [<return code>]

; Template
: RC/N

; Location
: Internal

QUIT stops the execution of the script at the specified return code. The default return code is zero. We recommend you use the standard return code values of 5, 10, and 20.

; Example:

ASK "Do you want to stop now?"
IF WARN
QUIT 5
ENDIF
ECHO "OK"
ECHO "The script is continuing."

If you press Y at the prompt, the script is aborted, since WARN is equal to a return code of 5. If you press N or press Return:

OK
The script is continuing.

Is displayed in the Shell window.

== REBOOT ==

Reboots your Amiga.

== RECORDER ==

Captures console output and stores it in a file.

== RELABEL ==

Changes the volume name of the disk in the given drive to the specified name.

; Format
: RELABEL [DRIVE] <drive> [NAME] <name>

; Template
: DRIVE/A,NAME/A

; Location
: C:

Volume names are set when disks are initially formatted. RELABEL allows you to change a disk's volume name to any name specified.

On floppy-only systems with one drive, be sure to specify the disks by volume name instead of drive name.

; Examples:
1> RELABEL Workbench: MyDisk

changes the name of the Workbench disk to MyDisk. No colon is necessary after the second name.

1> RELABEL DF2: DataDisk

changes the name of the disk in DF2: to DataDisk.

== REMRAD ==

Removes the recoverable RAM disk.

; Format
: REMRAD [<device>] [FORCE]

; Template
: DEVICE,FORCE/S

; Location
: C:

REMRAD allows you to remove the recoverable RAM disk (usually mounted as RAD:) from memory without powering off the system. If you have mounted more than one recoverable RAM disk, use the DEVICE specification.

REMRAD instructs RAD: to delete all of its files and become inactive. However, the RAD: RAM_0 disk icon does not disappear. The next time the Amiga is rebooted. RAD: is removed from memory completely and the icon is no longer displayed.

If the device is in use when the REMRAD command is given, the operation aborts with a device in use message. To remove it if it is in use, you must use the FORCE option.

== RENAME ==

Changes the name of or moves a file or directory.

; Format
: RENAME [FROM] {<name} [TO | AS] <name>

; Template
: FROM/A/M,TO=AS/A,QUIET/S

; Location
: C:

RENAME renames the FROM file or directory with the specified TO name. The FROM and TO files or directories must be on the same volume. If the name refers to a directory, RENAME changes the directory name without changing the names of the files or subdirectories in that directory. When there are multiple items in the FROM argument, the TO argument must be a directory.

If you rename a directory or if you use RENAME to give a file another directory name, AmigaDOS changes the position of that directory or file in the filing system hierarchy. This effectively moves the items.

; Example 1:
1> RENAME Work/Ex1 AS :Test/Ex2

renames the file Ex1 as Ex2 and moves it from the Work directory to the Test directory. The Test directory must exist in the root directory for this command to work.

; Example 2:
1> RENAME 3.doc 5.doc a.doc TO Docs

moves the 3.doc, 5.doc, and a.doc files to the Docs directory. The Docs directory must already exist.

== REQUESTCHOICE ==

Allows AmigaDOS and ARexx scripts to use custom requesters.

; Format
: REQUESTCHOICE >TITLE> <body> {<gadgets>} [PUBSCREEN <public screen name>]

; Template
: TITLE/A,BODY/A,GADGETS/A/M,PUBSCREEN/K

; Location
: C:

The <title> argument specifies the title of the requester.

The <body> argument specifies the text of the requester. Linefeeds can be embedded using *N.

The <gadgets> argument specifies the text for the different gadgets. The gadget labels are separated with spaces.

The number of the selected gadget is printed as a result to the console. For evaluation in a script file, you can redirect this output into an environment variable. If the requester cannot be opened, the command generates a return code of 20.

The PUBSCREEN argument allows the requester to open its window on a public screen.

; Example:

1> RequestChoice >ENV:rcnum "New Title" "This is my requester*nSelect a gadget" "OK" "Maybe" "Cancel"

[[File:DosFig6-1.png|center|frame|Sample RequestChoice Requester]]

ENV:rcnum contains 0, 1, or 2 after a gadget is selected. The script can use this value to control its later execution.

== REQUESTFILE ==

Allows AmigaDOS and ARexx scripts to use a file requester.

; Format
: REQUESTFILE [Drawer <drawer name>] [FILE <file>] [PATTERN <pattern>] [TITLE <title>] [POSITIVE <text>] [NEGATIVE <text>] [ACCEPTPATTERN <pattern>] [REJECTPATTERN <pattern>] [SAVEMODE] [MULTISELECT] [DRAWERSONLY] [NOICONS] [PUBSCREEN <public screen name>]

; Template
: DRAWER,FILE/K,PATTERN/K,TITLE/K,POSITIVE/K,NEGATIVE/K,ACCEPTPATTERN/K,REJECTPATTERN/K,SAVEMODE/S,MULTISELECT/S,DRAWERSONLY/S,NOICONS/S,PUBSCREEN/K

; Location
: C:

When entered with no arguments, a file requester with OK, Volumes, Parent, and Cancel buttons is created. Ist Drawer and File gadgets are empty and it displays the contents of the current directory.

The DRAWER argument specifies the initial contents of the Drawer gadget.

The FILE option specifies the initial contents of the File gadget.

The PATTERN option allows the use of a standard AmigaDOS pattern. It includes a Pattern gadget in the requester and specifies the initial contents of the gadget. If this option is not provided, the file requester does not have any Pattern gadget.

The TITLE option specifies the title of the requester.

The POSITIVE option specifies the text to appear in the positive (left) choice in the file requester.

The NEGATIVE option specifies the text to appear in the negative (right) choice in the file requester.

The ACCEPTPATTERN option specifies a standard AmigaDOS pattern. Only files matching this pattern are displayed in the file requester.

The REJECTPATTERN option specifies a standard AmigaDOS pattern. Files matching this pattern are not displayed in the file requester.

If SAVEMODE is specified, the requester is used for writing files to disk. If MULTISELECT is specified, the requester allows multiple files to be selected at once. If DRAWERSONLY is specified, the requester does not have a File gadget. This effectively turns the file requester into a directory requester. If NOICONS is specified, the requester does not display icons (.info files).

The selected files are returned on the command line, enclosed in double quotation marks and separated with spaces. The command generates a return code of 0 if you select a file or 5 if you cancel the requester.

The PUBSCREEN argument allows the requester to open its window on a public screen.

; Example:
1> REQUESTFILE DRAWER Devs: TITLE "My Req" NOICONS

[[File:DosFig6-2.png|center|frame|Sample RequestFile Requester]]

== REQUESTSTRING ==

Allows AmigaDOS and ARexx scripts to use custom string requesters.

== RESIDENT ==

Displays and modifies the list of resident commands.

; Format
: RESIDENT [<resident name>] [<filename>] [REMOVE] [ADD] [REPLACE] [PURE | FORCE] [SYSTEM]

; Template
: NAME,FILE,REMOVE/S,ADD/S,REPLACE/S,PURE=FORCE/S,SYSTEM/S

; Location
: Internal

RESIDENT loads a command into memory and adds it to the resident list maintained by the Shell. This allows the command to be executed without reloading it from disk each time. If RESIDENT is invoked with no options, it lists the programs on the resident list.

To be made resident, a command should be pure, meaning that it is both re-entrant and re-executable. A re-entrant command can properly support independent use by two or more programs at the same time. A re-executable command dies not have to be reloaded to be executed again. Commands that have these characteristics are called pure and have the p (pure) protection bit set.

The following commands cannot be made resident: BINDDRIVERS, CONCLIP, IPREFS, LOADRESOURCE, LOADWB, and SETPATCH.

LIST the C: directory to check for the presence of the p protection bit to determine which commands are pure.

Many of the commands in the C: directory, as well as the MORE command in Utilities, are pure commands and can be made resident. If a command does not have its pure bit set, it probably cannot be made resident safely. (Setting the pure bit does not make a command or program pure.)

The REPLACE option is the default option and does not need to be explicitly stated. If no <resident name> is specified (for example, only a file name is specified), RESIDENT uses the file name portion as the name on the resident list. The full path to the file must be used.

If a <resident name> is specified and RESIDENT finds a program with that name already on the list, it attempts to replace the command. That <resident name> must be used to reference the resident version of the command. The replacement succeeds only if the already-resident command is not in use.

To override REPLACEment and make several versions of a command resident simultaneously, use the ADD option, giving a different <resident name> for each version loaded.

If the System option is specified, the command is added to the system portion of the resident list and becomes available as a system component. Any commands added to the resident list with the SYSTEM option cannot be removed. To list these files on the RESIDENT list, you must specify the SYSTEM option.

The PURE option forces RESIDENT to load commands that are not marked as pure and use them to test the pureness of other commands and programs. Use the PURE option with caution. Be sure the programs that you make RESIDENT meet the criteria to be resident or be careful to use the command in only one process at a time.

The availability of internal commands can also be controlled with RESIDENT. To deactivate an Internal command (for example, if an application has its own command of the same name), use RESIDENT <command> REMOVE. The command can be reactivated with the REPLACE option.

; Example 1:
1> RESIDENT C:COPY

makes the COPY command resident (replaces any previous version).

; Example 2:
1> RESIDENT Copy2 DF1:C/COPY ADD

adds another version of COPY to the resident list, under the name Copy2.

; Example 3:
1> RESIDENT Xdir DF1:C/Xdir PURE

makes an experimental, non-pure version of the DIR command resident.

; Example 4:
1> RESIDENT CD REMOVE

makes the Internal CD command unavailable.

; Example 5:
1> RESIDENT CD REPLACE

restores the CD command to the system.

See also: PROTECT, LIST.

== ROADSHOWCONTROL ==

Displays and changes the internal configuration options of the TCP/IP stack.

== RUN ==

Executes commands as background processes.

; Format
: RUN <command...> [{+ <command>}]

; Template
: COMMAND/F

; Location
: Internal

RUN is used to start background processes. A background process does not open its own window for input or output and does not take over the parent Shell.

RUN attempts to execute the <command> and any arguments entered on the command line. You can RUN multiple command lines by separating them with plus signs (+). If you press Return after a plus sign, RUN interprets the next line as a continuation of the same command line.

To make it possible to close the Shell window in which the process was started, redirect the output of RUN with RUN >NIL: <command>.

A new background Shell has the same search path and command stack size as the Shell from which RUN is given.

You can RUN commands stored to the resident list. Resident commands are checked before commands in the command path. A Shell started with RUN NEWSHELL uses the default startup file, S:Shell-startup.

; Example 1:
1> RUN COPY Text TO PRT:+
DELETE Text +
ECHO "Printing finished"

prints the Text file by copying it to the printer device, deletes it, then displays the given message. Plus signs string together the command lines, causing each command to be run after the previous command finishes.

; Example 2:
1> RUN EXECUTE Comseq

executes, in the background, all the commands in the script file Comseq.

For more examples using the RUN command, see Chapter 8.

== RX ==

Launches an ARexx program.

== RXC ==

Closes the ARexx resident process.

== RXLIB ==

Manages and lists ARexx function libraries and hosts.

== RXSET ==

Manages or lists the Clip List.

== SEARCH ==

Looks for the specified text string in the files of the specified directories.

; Format
: SEARCH [FROM] {<name | pattern>} [SEARCH] <string | pattern> [ALL] [NONUM] [QUIET] [QUICK] [FILE] [PATTERN]

; Template
: FROM/M,SEARCH/A,ALL/S,NONUM/S,QUIET/S,QUICK/S,FILE/S,PATTERN/S

; Location
: C:

SEARCH looks through all the files in the FROM directory for the string given in the SEARCH string. (The FROM and SEARCH keywords are optional.) If the ALL switch is given, SEARCH also looks through all the subdirectories of the FROM directory. SEARCH displays the name of the file being searched and any line that contains the text sought. You must place quotation marks around any search text containing a space. The search is not case-sensitive.

The options are:
{| class="wikitable"
| NONUM || Line numbers are not printed with the strings.
|-
| QUIET || Searches quietly; file names being searched are not displayed.
|-
| QUICK || Use a more compact output format.
|-
| FILE || Looks for a file by the specified name, rather than for a string in the file.
|-
| PATTERN || Uses pattern matching to search for the string.
|}

SEARCH leaves a 0 in the condition flag if the object is found, and a 5 (WARN) otherwise. To abandon the search of the current file and continue to the next file, if any, press Ctrl+D. SEARCH is aborted when Ctrl+C is pressed.

; Examples
1> SEARCH DEVS: DOSDrivers globvec
DOSDrivers (dir)
PIPE..
6 GlobVec =-1
PIPE.info

1> SEARCH utilities #?.info FILE
Workbench:Utilities/Clock.info
Workbench:Utilities/MultiView.info

== SET ==

Sets a local vaiable.

; Format
: SET [<name>] [<string...>]

; Template
: NAME,STRING/F

; Location
: Internal

SET with no arguments lists the current local variables.

SET with <name> and <string> arguments creates a new environment variable. The first word after SET is taken as the <name>. Everything else on the command line is taken as the <string> argument. Quotation marks are not required.

An environment variable created with SET is local to the Shell in which it was created. If you create a new Shell with the NEWSHELL command, that Shell also recognizes any variables created in its parent Shell. However, if you create a new Shell with the Execute Command Workbench menu item or by opening the Shell icon, variables created with SET are not recognized in the new Shells.

You can call environment variables in a script or on a command line by placing a dollar sign ($) in front of the variable name.

To remove a local variable definition, use the UNSET command.

; Examples:
1> SET Origin This process launched from icon

creates the local variable Origin that sores a reminder that a Shell was invoked from an icon rather than a NEWSHELL.

1> ECHO $Origin
This process launched from icon

See also: GET, UNSET

== SETCLOCK ==

Sets or reads the battery backed-up hardware clock.

; Format
: SETCLOCK LOAD | SAVE | RESET

; Template
: LOAD/S,SAVE/S,RESET/S

; Location
: C:

SETCLOCK SAVE sets the date and time of the battery backed-up hardware clock (if your system has one) from the current system time, which is set with the Time editor or with the DATE command. SETCLOCK SAVE is typically used after a DATE command.

SETCLOCK LOAD sets the current system time from the battery backed-up clock. This is done automatically during the boot process.

The RESET option resets the clock completely. Use this option if the clock is accidentally turned off or LOAD and SAVE do not appear to work correctly.

; Example:
1> DATE 22-Jan-93 07:15:25
1> SETCLOCK SAVE

saves the date, January 22, 1993, and the time, 7:15 a.m., to the battery backed-up hardware clock. When the system is booted, the system clock is set with the time saved in the hardware clock.

Some Amiga models do not have battery backed-up clocks unless an expansion unit has been installed.

See also: DATE

== SETDATE ==

Change the timestamp of a file or directory.

; Format
: SETDATE <file | pattern> [<weekday>] [<date>] [<time>] [ALL]

; Template
: FILE/A,WEEKDAY,DATE,TIME,ALL/S

; Location
: C:

SETDATE changes the timestamp, the date and time of the creation or last change, of a file or directory. SETDATE <file> changes the date/time of the file to the current system date/time. SETDATE ALL changes the date and time of all the files and subdirectories matching the pattern entered.

The system clocks are not affected by SETDATE.

You can use output from the DATE command as input to SETDATE.

; Example 1:
1> SETDATE TestFile

changes the date and time associated with TestFile to the current date and time.

; Example 2:
1> SETDATE TestFile 01-04-91 13:45:32

Changes the date and time associated with TestFile to April 1, 1991, 1:45 p.m.

See also: DATE

== SETENV ==

Sets a global variable.

; Format
: SETENV [<name>] [<string...>]

; Template
: NAME,STRING/F

; Location
: Internal

SETENV with no arguments lists the current global variables.

SETENV with <name> and <string> arguments creates a new global environment variable. The first word after SETENV is taken as the <name>. Everything else on the command line is taken as the <string> argument. Quotation marks are not required.

Global variables are stored in the ENV: directory and are available to all processes. However, if a local variable (defined by SET) and a global variable share the same name, the local variable is used.

Environment variables are called by scripts or other commands by including a dollar sign ($) in front of the variable name.

To remove a global variable definition, use the UNSETENV command.

; Example 1:
1> SETENV Editor Extras:Tools/MEmacs

creates the environment variable Editor That can be used with the MORE utility. This specifies the editor as MEmacs, located in the Tools drawer of EXTRAS:. The variable Editor is available in any Shell.

; Example 2:
1> SETENV Editor C:ED

same as above, only the editor specified is ED.

1> ECHO $Editor
C:ED

See also: GETENV, UNSETENV

== SETFONT ==

Changes the font of the current Shell.

; Format
: SETFONT <size> [SCALE] [PROP] [ITALIC] [BOLD] [UNDERLINE]

; Template
: NAME/A,SIZE/N/A,SCALE/S,PROP/S,ITALIC/S,BOLD/S,UNDERLINE/S

; Location
: C:

SETFONT lets you change the font used in a particular Shell window, overriding the System Default Text setting specified in the Font editor. SETFONT is only effective in the window in which it is invoked.

You must specify both a font name and a size when using the SETFONT command. The other options are:
{| class="wikitable"
| SCALE || Enables bitmap font scaling.
|-
| PROP || Allows proportional fonts.
|-
| ITALIC || The font is italic.
|-
| BOLD || The font is boldface.
|-
| UNDERLINE || The font is underlined.
|}

Invoking SETFONT clears the Shell window of its current contents and displays a new prompt, in the new font, at the top of the window. Using proportional fonts in a Shell window is not recommended because the variable character spacing prevents columns of information from lining up and makes editing the command line difficult.

; Example:
1> SETFONT topaz 11 BOLD UNDERLINE

The Shell window clears and the new prompt is in 11 point Topaz, underlined and boldface.

== SETFONTCHARSET ==

Adds charset tag and version string to a FontContentsHeader file.

== SETKEYBOARD ==

Sets the keymap for the Shell.

; Format
: SETKEYBOARD <keymap name>

; Template
: KEYMAP/A

; Location
: C:

SETKEYBOARD specifies the keymap used by the current Shell. The available files are listed below:

{| class="wikitable"
! Keymap !! Keyboard
|-
| cdn || Canadian Français
|-
| ch1 || Suisse
|-
| ch2 || Schweiz
|-
| d || Deutsch
|-
| dk || Dansk
|-
| e || Español
|-
| f || Français
|-
| gb || British
|-
| i || Italiana
|-
| n || Norsk
|-
| po || Português
|-
| s || Svenskt
|-
| usa || American
|-
| usa2 || Dvorak
|}

To specify the same permanent keymap, use the Preferences Input editor to save your choice.

; Example:

To change to a French Canadian keymap, enter:

1> SETKEYBOARD cdn

The keymap file must be in the KEYMAPS: directory for SETKEYBOARD to find it.

== SHOWNETSTATUS ==

Displays various information about the status of the network configuration.

== SKIP ==

Skips to a label when executing script files.

; Format
: SKIP [<label>] [BACK]

; Template
: LABEL,BACK/S

; Location
: Internal

SKIP is used in scripts to allow you to skip ahead in the script to a <label> defined by a LAB statement. If no <label> is specified, SKIP jumps to the next LAB statement.

SKIP always searches forward from the current line of the file. However, when the BACK option is used, SKIP starts searching for the label from the beginning of the file. This allows SKIPs to points prior to the SKIP command.

You can only SKIP as far back as the last EXECUTE statement. If there are no EXECUTE statements in a script, you SKIP back to the beginning of the file.

If SKIP does not find the label specified, the command sequence terminates and the message Label <label> not found by Skip is displayed.

; Example:
Assume you have the following script, called CheckFile:

.KEY name
IF exists <name>
SKIP message
ELSE
ECHO "<name> is not in this directory."
QUIT
ENDIF
LAB message
ECHO "The <name> file exists."

You can run the script by entering:

1> EXECUTE CheckFile Document

If the Document file exists in the current directory, the execution of the script SKIPs ahead to the LAB command. The message:

The Document file exists.

Is displayed in the Shell window.

If the Document file is not in the current directory, the execution of the script jumps to the line after the ELSE statement, displaying the message:

Document is not in this directory.

See also: EXECUTE, LAB. For more examples using the SKIP command, see Chapter 8.

== SORT ==

Alphabetically sorts the lines of a file.

; Format
: SORT [FROM] <file | pattern> [TO] <filename> [COLSTART <n>] [CASE] [NUMERIC]

; Template
: FROM/A,TO/A,COLSTART/K,CASE/S,NUMERIC/S

; Location
: C:

SORT sorts the FROM file alphabetically, line-by-line, sending the sorted results to the TO file. SORT assumes the file is a normal text file in which lines are separated by line feeds. SORT normally disregards case. If the CASE switch is given, upper-cased items are output first.

The COLSTART keyword specifies the character column at which the comparison begins. SORT starts comparing the lines from that point, wrapping around to the beginning of the line if the compared lines match to the end.

When the NUMERIC option is specified, the lines are interpreted as numbers from the first column reading to the right, stopping at the first non-numeric character. Lines not beginning with numbers are treated as 0. The lines are output in numerical order. CASE is ignored when NUMERIC is specified.

; Example:
1> SORT DF0:Glossary TO DF0:Glossary.alpha

sorts the lines in the Glossary file, arranges them alphabetically, and outputs them to a next file called Glossary.alpha. The case of the words is disregarded.

For more examples using the SORT command, see Chapter 8.

== STACK ==

Displays or sets the stack size within the current Shell.

; Format
: STACK [[SIZE] <stack size>]

; Template
: SIZE/N

; Location
: Internal

A Shell uses a certain amount of stack, a special area in memory allocated for it. Each Shell has a specific stack size. If a program causes a system failure, changing the Shell's stack size may solve the problem. Commands performing operations consisting of multiple levels can require additional stack space.

Stack sizes typically range from 4096 to 40000 bytes. If the stack size is too small, a system failure can occur. If the stack size is too large, it can use too much memory.

{{Note|A software failure message is displayed if you run out of stack space. Increase the stack space for the Shell that caused the error.}}

Entering the STACK command with no arguments displays the current stack size.

== STATUS ==

Lists information about Shell processes.

; Format
: STATUS [<process>] [FULL] [TCB] [CLI | ALL] [COM | COMMAND <command>]

; Template
: PROCESS/N,FULL/S,TCB/S,CLI=ALL/S,COM=COMMAND/K

; Location
: C:

STATUS without any arguments lists the numbers of the current Shell processes and the program or command running in each. The <process> argument specifies a process number, limiting STATUS to giving information about that process only.

For information on the stack size, global vector size, priority, and the current command for each process, use the FULL keyword. The TCB keyword is similar, omitting the command information. The CLI=ALL keyword gives only the command information.

STATUS searches for a command when you use the COMMAND option. STATUS scans the Shell list, looking for the specified <command>. If the command is found, the Shell's process number is output, and the condition flag is set to 0. Otherwise, the flag is set to 5 (WARN).

; Example 1:
1> STATUS 1
Process 1: Loaded as command: status

; Example 2:
1> STATUS 1 FULL
Process 1: stk 4000, gv 150, pri 0 Loaded as command: status

; Example 3:
1> STATUS >RAM:Xyz COMMAND=COPY
1> BREAK <RAM:Xyz >NIL: ?

sends a break to the process executing COPY.

== SWAPCD ==

Interchanges the current directory and a stacked directory.

== TCC ==

Closes the ARexx tracing console window.

== TCO ==

Opens the ARexx tracing console window.

== TCP-HANDLER ==

Access network resources through AmigaDOS.

== TCPDUMP ==

Dumps traffic on a network.

== TE ==

Clears the ARexx global tracing flag.

== TEE ==

Sends data from the standard input to the standard output and prints it to the console.

== TRACEROUTE ==

Prints the network route packets.

== TS ==

Starts ARexx's interactive tracing.

== TYPE ==

Displays the contents of a file.

; Format
: TYPE {<file | pattern>} [TO <name>] [OPT H | N] [HEX | NUMBER]

; Template
: FROM/A/M,TO/K,OPT/K,HEX/S,NUMBER/S

; Location
: C:

TYPE outputs the contents of the named file to the current window if no destination is given or to a specified output file. The TO keyword types information to a specified file. If more than one file name is specified, the file names are typed in sequence.

The OPT H and OPT N options are also available by the HEX and NUMBER keywords, respectively. However, the two options are mutually exclusive. The HEX option types the file as columns of hexadecimal numbers, with an ASCII character interpretation column. The NUMBER option numbers the lines as they are output.

To pause output, press the Space bar. To resume output, press Backspace, Return, or Ctrl+X. To stop output, press Ctrl+C (***Break is displayed).

; Example:
1> TYPE S:Startup-sequence

The contents of the Startup-sequence file in the S: directory are displayed on the screen.

For more examples using TYPE, see Chapter 8.

== UNALIAS ==

Removes an alias.

; Format
: UNALIAS [<name>]

; Template
: NAME

; Location
: Internal

UNALIAS removes the named alias from the alias list. With no arguments, UNALIAS lists the current aliases.

See also: ALIAS

== UNSET ==

Removes a local variable.

; Format
: UNSET [<name>]

; Template
: NAME

; Location
: Internal

UNSET removes the named local variable from the variable list for the current process. With no arguments, UNSET lists the current variables.

See also: SET

== UNSETENV ==

Removes a global variable.

; Format
: UNSETENV [<name>]

; Template
: NAME

; Location
: Internal

UNSETENV removes the named global variable from the current variable list. With no arguments, UNSETENV lists the current variables.

See also: SETENV

== UPTIME ==

Tells how long the system has been running.

== VERSION ==

Finds software version and revision numbers.

; Format
: VERSION [<library | device | file>] [<version #>] [<revision #>] [<unit #>] [FILE] [INTERNAL] [RES] [FULL]

; Template
: NAME,VERSION/N,REVISION/N,UNIT/N,FILE/S,INTERNAL/S,FULL/S

; Location
: C:

VERSION finds the version and revision number of a library, device, command, or Workbench disk. VERSION can also test for a specific version/revision and set the condition flags if the version/revision is greater.

VERSION with no <library | device | file> argument prints the Kickstart version number and the Workbench version number and sets the two corresponding environment variables. If a name is specified, VERSION attempts to open the library, device, drive, or file and read the version information. Specify a device name, such as DF0: or DH0:, to get the version of the file system used by a drive.

When a <version #> or a <revision #> is specified, VERSION sets the condition flag to 0 if the version and revision number of the Kickstart, library, or device driver is greater than or equal to the specified values. Otherwise, the flag is set to 5 (WARN). If a revision number is not specified, no comparison on the revision number is performed.

The <unit #> option is obsolete and is retained for compatibility with older programs.

The FILE option forces VERSION to ignore libraries or device drivers currently loaded. This allows you to get the version number of a .library or .device file on disk when a library or device of that name is already in memory or available in LIBS:. The RES option gets the version of Resident commands. Built-in Shell commands have the same version string as the Shell. INTERNAL is also obsolete and retained for compatibility. The FULL option prints out the complete version of the string, including the date.

; Examples:
1> VERSION
Kickstart 40.70 Workbench 44.1

1> VERSION Alpha:Libs/xyz.library FILE FULL
xyz.library 1.13 (05/24/93)

== WAIT ==

Waits for the specified time.

; Format
: WAIT [<n>] [SEC | SECS |MIN | MINS] [UNTIL <time>]

; Template
: /N,SEC=SECS/S,MIN=MINS/S,UNTIL/K

; Location
: C:

WAIT is used in command sequences or after RUN to wait for a certain period of time or until a specific time. The default waiting period is one second.

The <n> argument specifies the number of seconds or minutes to wait. These options are mutually exclusive; you can only enter seconds or minutes.

Use the keyword UNTIL to wait until a particular time of the day, given in the format HH:MM.

; Example 1:
1> WAIT 10 MINS

waits ten minutes.

; Example 2:
1> WAIT UNTIL 21:15

waits until 9:15 p.m.

== WAITFORPORT ==

Waits for public message port to appear.

== WBINFO ==

Opens Workbench information windows from a Shell.

== WBRUN ==

Runs programs from Shell as if they were executed from the Workbench.

== WBSTARTUPCTRL ==

Manipulates the startup configuration of Workbench.

== WHICH ==

Searches the command path for a particular item.

; Format
: WHICH <command> [NORES] [RES] [ALL]

; Template
: FILE/A,NORES/S,RES/S,ALL/S

; Location
: C:

WHICH lets you find a specific command, program, or directory by entering its name. If the named item is in the search path, WHICH displays the complete path to that item. WHICH lists resident commands as RESIDENT and internal commands as INTERNAL.

Normally, WHICH searches the resident list, the current directory, the command paths, and the C: directory. If the item is not found, WHICH sets the condition flag to 5 (WARN), but does not print any error message.

If the NORES option is specified, the resident list is not searched. If the RES option is specified, only the resident list is searched.

The ALL switch continues the search through the full search path, finding and listing all locations of a command or program. It can, however, lead to multiple listings of the same command if that command is reached by more than one route (such as C: and the current directory).

; Examples:
1> WHICH avail
C:Avail

1> WHICH C:
Workbench:C

1> WHICH alias
INTERNAL alias

== WHY ==

Prints an error message explaining why the previous command failed.

; Format
: WHY

; Template
: (none)

; Location
: Internal

When a command fails, the screen displays a brief message. This message typically includes the name of the file, if that was the problem, but provides no details. If the reason for a failure is not evident, enter WHY for a more complete explanation.

= System Commands =

System commands are required for normal system operation. They are used by the standard Startup-sequence or called automatically by the system for applications. The user does not typically invoke these commands.

== ADDDATATYPES ==

Builds a list of data types that datatypes.library can understand.

; Format
: ADDDATATYPES [FILES] {filenames} [QUIET] [REFRESH]

; Template
: FILES/M,QUIET/S,REFRESH/S

; Location
: C:

Data type descriptors are stored in DEVS:DataTypes. These descriptors allow programs such as MultiView to interpret different data file types. ADDDATATYPES can also be called by application installation scripts to add their own data types to the list.

The FILES argument specifies the names of the data type descriptors to add to the existing list of data type descriptors.

Specifying the QUIET option suppresses error and output messages.

Specifying the REFRESH option scans the DEVS:DataTypes directory for new or changed data type descriptors.

== BINDDRIVERS ==

Binds device drivers to hardware.

; Format
: BINDDRIVERS

; Template
: (none)

; Location
: C:

BINDDRIVERS loads and runs device drivers for add-on hardware. These devices are automatically configured by the expansion library if their device drivers are in the SYS:Expansion directory.

The BINDDRIVERS command must appear in the Startup-sequence file to configure the hardware when the system is booted.

== CONCLIP ==

Moves data between console windows and the Clipboard.

; Format
: CONCLIP [CLIPUNIT | UNIT <unit number>] [OFF]

; Template
: CLIPUNIT=UNIT/N,OFF/S

; Location
: C:

CONCLIP is called from the standard Startup-sequence. It keeps track of the information that has been cut to the Clipboard.

The CLIPUNIT option allows you to specify the clipboard device unit number to use. Specify any unit from 0 to 255. The default number is 0. We recommend that this option be used only by advanced users or programmers who wish to use different units for different data, such as one for text and another for graphics. Run the command from the Shell, specifying the new unit number. The next time you copy and paste, that Clipboard unit is used.

Using the OFF option with Shell, MEmacs, and ED causes these commands to stop interacting with the system Clipboard during cutting and pasting operations. We recommend that you do not use this option.

== IPREFS ==

Communicates Preferences information stored in the individual editor files to the operating system.

; Format
: IPREFS

; Template
: (none)

; Location
: C:

IPREFS reads the individual system Preferences files and passes the information to the system. IPREFS is generally run in the Startup-sequence after the Preferences files are copied to ENV:. Each time a user selects Save or Use from within an editor, IPREFS is notified and passes the information to the system. If necessary, IPREFS resets Workbench to implement those changes. If any Shell, project, or tool windows are open, IPREFS displays a requester asking you to close them.

== SETPATCH ==

Makes ROM patches in system software.

; Format
: SETPATCH [QUIET] [NOCACHE] [REVERSE]

; Template
: QUIET/S,NOCACHE/S,REVERSE/S

; Location
: C:

SETPATCH installs temporary modifications to the operating system. It must be run at the beginning of the Startup-sequence file. Updated versions of SETPATCH are made available when necessary as AmigaDOS development continues.

If QUIET is specified, no output is sent to the screen.

NOCACHE prevents data caching from being activated on some 68030 and 68040 systems.

REVERSE stores patches in reverse order. This option is useful for CDTV developers only.

Programming AmigaOS 4: DOS - The Data Administrator

2017-12-20T08:21:01Z

Daniel Jedlicka: Fixed a few typos, updated info on filesystems.

''This article was adapted from Amiga Future magazine's series on developing for AmigaOS.''

The file names that have become long thanks to AmigaOS 4 can make some of the old software/data administration sweat. We would like to show you this time what has changed in DOS.

The interface name for the dos.library is "IDOS" and its type is "struct DOSIFace *". Unlike other interface names all letters are in upper case and not only the first one. However, you don't need to open the interface itself. That's the job of the startup code. Only if you program libraries/devices or BOOPSI gadgets and data types must you take care of it yourself. So much about the pre-conditions.

== Long names ==

Thanks to more modern filesystems (see [[UserDoc:AmigaOS_File_Systems|this table]] for an overview), file- and directory names are no longer limited to 30 characters in length. Also, absolute path statements may now be longer than the original maximum of 254 characters (a limit of BSTR). When in the past only names with up to 30 characters were allowed, you could create many directory depths before you hit the limit. Now this is possible very quickly, at least in theory. You should keep this in mind when you create local buffers in order to fill them, for example by using IDOS->NameFromLock(). This function would cause the error code ERROR_LINE_TOO_LONG (from dos/errors.h) if the buffer is too small.

Old file managers such as FileMaster or MaxonTools may have problems dealing with longer file names, which are then displayed incomplete; you may also face problems when manipulating such files. Modern file management tools like Filer, Workbench Explorer or DirMeUp are already prepared for long filenames.

The developer of the dos.library suggests a buffer length of at least 1024 characters. This length will probably never be reached in reality. Who on Earth would enter a path statement in the Shell window that stretches for 10 lines (80 column mode)?

[[File:AF105_grab_dos-prefs_eng.png|frame|center]]

== Normal file operations ==

Nothing has changed regarding the normal file operations apart from the possibility to use long names. Nevertheless we would like to broach this subject, as misunderstandings keep happening in reality. Initially AmigaDOS offered only "LowLevel" file operations such as IDOS->Read() and IDOS->Write(). With Kickstart 2.0 the buffered file operations were also added. You can recognise them on the "F" in front: IDOS->FRead(), IDOS->FWrite() etc. Be careful not to switch between direct reading/writing and buffered reading/writing. DOS creates here an IDOS->FFlush(), if buffered data must be saved, but the whole thing is not really nice. The speed is also affected when reading as well as when buffering content that has already been read as it must always be discarded and positioned back into the file. An IDOS->Seek() is a very "expensive" file operation and therefore ideally entirely avoided, at least backward. In practice it is therefore better to simply read over data that is not needed instead of skipping it with "seek"! In the first examples "CopyFile.c" different DOS commands are used to read and write files.

<syntaxhighlight>
/* CopyFile.c
*
* gcc -o CopyFile CopyFile.c
*/

#include <exec/types.h>
#include <dos/dos.h>
#include <dos/rdargs.h>
#include <proto/dos.h>
#include <proto/utility.h>

int main()
{
int res = RETURN_ERROR;
struct RDArgs *readargs;
int32 rargs[3];

IUtility->ClearMem(rargs, sizeof(rargs));

if((readargs = IDOS->ReadArgs("FROM/A,TO/A", rargs, NULL)))
{
uint8 *fromfile = (UBYTE *) (rargs[0]);
uint8 *tofile = (UBYTE *) (rargs[1]);
BPTR fhin, fhout;
uint8 buffer[1024];
int32 readbyte;

if((fhin = IDOS->Open(fromfile, MODE_OLDFILE)))
{
if((fhout = IDOS->Open(tofile, MODE_NEWFILE)))
{
res = RETURN_OK;
while((readbyte = IDOS->Read(fhin, buffer, sizeof(buffer))))
{
if(IDOS->Write(fhout, buffer, readbyte) != readbyte)
{
IDOS->PrintFault(IDOS->IoErr(), tofile);
res = RETURN_FAIL;
break;
}
}
IDOS->Close(fhout);
}
else IDOS->PrintFault(IDOS->IoErr(), tofile);
IDOS->Close(fhin);
}
else IDOS->PrintFault(IDOS->IoErr(), fromfile);

IDOS->FreeArgs(readargs);
}
else IDOS->PrintFault(IDOS->IoErr(), NULL);

if(res == RETURN_OK) IDOS->Printf("Copy successful\n");

return res;
}
</syntaxhighlight>

[[File:AF105_grab_CopyFile.png|frame|center]]

== Create directories ==

So far it has been quite arduous to create whole hierarchies of directories and sub-directories. Backup programs or the like are the usual candidates here. Now it is possible to create a complete path with a single command. In reference to IDOS->CreateDir() the new function is called IDOS->CreateDirTree(). The relative or absolute path entry is expected. You should keep in mind here that the last directory name must be entered without the concluding slash "/". This is possible in the shell-command "MakeDir", because the command makes sure that it is removed. If parts of the path already exist, there will be no error. Only if a directory of the path can't be created, the function will return with an error code. A possible error source is, for instance, a file with the name of the drawer that is to be created. A FileLock is returned to the last directory, which is cleared with IDOS->UnLock() by the program. As usual, we've created a short sample program "CreateDir.c". IDOS->ReadArgs() is also used for parsing the command line in the source code and IDOS->PrintFault() for error reports.

<syntaxhighlight>
/* CreateDir.c
*
* gcc -o CreateDir CreateDir.c
*/

#include <exec/types.h>
#include <dos/dos.h>
#include <dos/rdargs.h>

#include <proto/dos.h>
#include <proto/utility.h>

int main()
{
int res = RETURN_ERROR;
struct RDArgs *readargs;
int32 rargs[2];
BPTR fh;

IUtility->ClearMem(rargs, sizeof(rargs));

if((readargs = IDOS->ReadArgs("DRAWER/A/M", rargs, NULL)))
{
if(rargs[0])
{
/* run through the list of arguments, */
CONST_STRPTR *drawer = (CONST_STRPTR *) rargs[0];
while(*drawer)
{
/* create directory with full path when not exists */
if((fh = IDOS->CreateDirTree(*drawer)))
{
IDOS->Printf("Path <%s> created successfully\n",*drawer);
IDOS->UnLock(fh);
}
else IDOS->PrintFault(IDOS->IoErr(), *drawer);

drawer++;
}
}

IDOS->FreeArgs(readargs);
}
else IDOS->PrintFault(IDOS->IoErr(),NULL);

return res;
}
</syntaxhighlight>

[[File:AF105_grab_createdir.png|frame|center]]

== Date ==

So far there has been no direct possibility to get from the second-based timestamp (as used by ITimer->GetSysTime()) to the AmigaDOS timestamp (based on days/minutes/ticks). Both new functions in charge of this task are IDOS->DateStampToSeconds() and IDOS->SecondsToDateStamp(). The result is a uint32-value with the seconds or a TimeStamp structure with the Amiga-values. However, you must keep in mind that the ANSI-C Timer functions can't be mixed with the AmigaDOS-Timer functions! ANSI-C has been delivering the seconds since 1.1.1970, while DOS uses the 1.1.1978 as its basis. So it becomes clear that if you mix them you will get the wrong results. We've created a practical example under "CurrentTime.c", which also uses the timer.device, but we'll get back to it in another part of this workshop. You should also keep in mind that the "struct timerequest" has been renamed in "TimeRequest" as "devices/timer.h" so there won't be any collisions/mixups with the structure with the same name in the C-libraries. If you want to use the old names (e.g. when porting), you can turn them on per Define __USE_OLD_TIMEVAL__.

<syntaxhighlight>
/* CurrentTime.c
*
* gcc -o CurrentTime CurrentTime.c
*/

#include <exec/types.h>
#include <exec/io.h>
#include <exec/memory.h>
#include <devices/timer.h>
#include <dos/datetime.h>

#include <proto/exec.h>
#include <proto/dos.h>

uint32 GetSysTime()
{
uint32 res = 0;
struct TimeRequest *timerio;
struct MsgPort *timerport;

if((timerport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END)))
{
if((timerio = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_ReplyPort, timerport,
ASOIOR_Size, sizeof(struct TimeRequest), TAG_END)))
{
if(IExec->OpenDevice("timer.device", UNIT_MICROHZ, (struct IORequest *)timerio, 0) == 0)
{
/* send synchron command to device */
timerio->Request.io_Command = TR_GETSYSTIME;
IExec->DoIO((struct IORequest *) timerio);

/* we will retunr only seconds, microseconds are ignored */
res = timerio->Time.Seconds;

IExec->CloseDevice((struct IORequest *) timerio);
}
else IDOS->Printf("Error: cannot open timer.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, timerio);
}
else IDOS->Printf("Erro: cannot create IORequest\n");

IExec->FreeSysObject(ASOT_PORT, timerport);
}
else IDOS->Printf("Error: cannot create MsgPort\n");

return( res );
}

int main()
{
const ULONG act = GetSysTime();
struct DateStamp ds = {0};

IDOS->SecondsToDateStamp(act, &ds);
IDOS->Printf("%ld seconds have elapsed since 1.1.1978\n", act);
IDOS->Printf("or %ld days, %ld minutes and %ld ticks\n", ds.ds_Days, ds.ds_Minute, ds.ds_Tick);

TEXT daystr[LEN_DATSTRING], timestr[LEN_DATSTRING];
struct DateTime dt = { ds.ds_Days, ds.ds_Minute, ds.ds_Tick, FORMAT_DEF, 0, NULL, daystr, timestr };
IDOS->DateToStr(&dt);
IDOS->Printf("Today is %s at %s o'clock\n", daystr, timestr);

return 0;
}
</syntaxhighlight>

[[File:AF105_grab_currenttime.png|frame|center]]

The function to calculate the second timestamp is new: IDOS->AddDates() and IDOS->SubtractDates(). The first one, adds two dates and returns the result in the first argument. In the second one an Argument1 ? Argument2 is calculated and the result is stored again in Argument1. Both functions return DOSTRUE if valid parameters are used.

== Notification ==

By using notifications you can get informed about changes in the files or directories. Interestingly enough you can monitor files that still don't exist. But as soon as you create them, you will get a change notification. You can select between Signal or Message Type, but the latter is recommended. Then you will get the message type 'struct NotifyMessage'. With nm_NReq.nr_Name you can determine the name of the monitored file/directory. The short example "SignalNotification.c" shows you how the function IDOS->StartNotify() is used in practice.

<syntaxhighlight>
/* SignalNotification.c
*
* gcc -o SignalNotification SignalNotification.c
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <dos/dos.h>
#include <dos/dosasl.h>
#include <dos/notify.h>
#include <dos/rdargs.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/utility.h>

int main()
{

struct RDArgs *readargs;
int32 rargs[2];
uint32 signr;

IUtility->ClearMem(rargs, sizeof(rargs));

if((readargs = IDOS->ReadArgs("FILENAME/A", rargs, NULL)))
{
STRPTR filename = (STRPTR) (rargs[0]);

if((signr = IExec->AllocSignal(-1)) != -1)
{
struct NotifyRequest notifyrequest = {0};

/* Send a signal to our task when file/directory are changed */
/* NRF_NOTIFY_INITIAL = send immediately a signal when file/directory are exist */
notifyrequest.nr_Name = filename;
notifyrequest.nr_Flags = NRF_SEND_SIGNAL | NRF_NOTIFY_INITIAL;
notifyrequest.nr_stuff.nr_Signal.nr_Task = (struct Task *) IExec->FindTask(NULL);
notifyrequest.nr_stuff.nr_Signal.nr_SignalNum = signr;

if((IDOS->StartNotify(&notifyrequest)) == DOSTRUE)
{
for(;;)
{
const ULONG signal = IExec->Wait(1L << signr | SIGBREAKF_CTRL_C);

if(signal & (1L << signr))
{
/* we have notification */
IDOS->Printf("Notification from '%s' !\n",notifyrequest.nr_FullName);
}

if(signal & SIGBREAKF_CTRL_C)
{
/* CTRL-C = quit program */
IDOS->EndNotify(&notifyrequest);
IDOS->PrintFault(ERROR_BREAK,NULL);
break;
}
}
}
else IDOS->PrintFault(ERROR_NOT_IMPLEMENTED,NULL);

IExec->FreeSignal(signr);
}
else IDOS->Printf("Error: there is no signal available\n");

IDOS->FreeArgs(readargs);
}
else IDOS->PrintFault(IDOS->IoErr(), NULL);

return 0;
}
</syntaxhighlight>

[[File:AF105_grab_signalnotification.png|frame|center]]

That's for the theory that was applicable to the old FastFileSystem (FFS). But some issues arise with AmigaOS 4 and the new FastFileSystem2. But let me make a digression and write about the file system. Let's assume that we have a dir1, then a dir2 and in it a file3 in the RAMDisk. If the file3 is changed or something new is created in the dir2, the file3 (i.e. the newly created one) will get the current timestamp. Furthermore, the superordinate directory dir2 will also get the current timestamp. The novelty with AmigaOS 4 (and in theory also the correct thing) is that this process goes all the way to the root directory. So the dir1 gets the current timestamp too. The advantage is obvious; you must only take a look at the root directory of the data storage medium to realise when and in what directory something has been change. Whether this has happened one level down or five levels down is irrelevant at this point. The user can click himself through the directories to get to the changed content. Also backup programs with the rule "everything since '.'" can work more expeditiously and must not search all directories.

The whole things becomes problematic in practice with the notifications. Let's suppose, we're monitoring the dir1 and change the file3. Before AmigaOS 4 we wouldn't have got a notification about the change. Since AmigaOS 4, however, we get the change notification, although strictly speaking nothing has changed in the monitored directory. At the moment is not known how this dilemma will be solved. The developers presume that it's better if one notification too many occurs than one notification too few. But the user might be confused, if, for example, the list in the file viewer keeps being re-configured without seeing a change afterwards.

== Virtual drives ==

Various virtual drives have been integrated with AmigaOS 4. This way you can address a CDROM-Image (ISO file) over ICD0: as if it were a burned CD. Using a comfortable GUI (DiskImageGUI) you can 'create' and delete the images. The whole thing works also with ADF files that are addressed as IDF0:. Also ENV: is no longer re-copied in the RAM-Disk, but administered with its own handler and synchronised with ENVARC: on the hard disk. Another drive is URL: with two different options. You can basically start a web-browser with it and display an Internet site (HTTP). Alternatively the displayed file can also lie locally on the hard disk (FILE). The second option is opening the mail program. You can configure the whole thing by using the "URLOpen" Prefs-program.

[[File:AF105_grab_url-prefs_eng.png|frame|center]]

<syntaxhighlight>
BPTR handle = IDOS->Open("URL:http://www.amigafuture.de", MODE_OLDFILE);
BPTR handle = IDOS->Open("URL:file=Work:docs/demo.html", MODE_OLDFILE);
BPTR handle = IDOS->Open("URL:mailto.name@amigafuture.de", MODE_OLDFILE);

if (handle) IDOS->Close(handle);
</syntaxhighlight>

To check whether the URL device is registered you can use the following Block Code:

<syntaxhighlight>
APTR oldwin = IDOS->SetProcWindow((APTR)-1);
handle = IDOS->Open("URL:NIL:",MODE_OLDFILE);
IDOS->SetProcWindow(oldwin);

if(handle)
{
IDOS->Close(handle);
/* URL-Device can be used */
}
</syntaxhighlight>

== Obsolete ==

With AmigaOS 4 functions from the dos.library have been dropped out or are reported as "DEPRECATED" when compiling. Some of them are, for example, Examine() or Seek(). The reason for this is that these functions can handle files with a maximum of 2 GByte size (because of the data type int). Completely new functions have been created here as supplement. Let's take a brief look at them. With Examine() you can request information about a file or a directory. It has been replaced with ExamineObject(). Its counterpart is FreeDosObject(DOS_EXAMINEDATA) that you use to deallocate the object. The structure ExamineData contains comparable values like the old FileInfoBlock, but values about the file size are available as 64 bit Integer. In order to go through directories using ExAll/ExNext/ExAllEnd you can now use the ExamineDir() function that gives you the next entry with each request. You need an administration block created with ObtainDirContext() which helps you define the result data and which you can deallocate with ReleaseDirContext(). Instead, with Seek() you position with ChangeFilePosition() in the file and with GetFilePosition() you request the current position. To change the file size you need ChangeFileSize() instead of SetFileSize(). Keep in mind that the function of the physical data blocks must be set up on the hard disk and hence it can take a while in very large areas until the function returns. The SetOwnerInfo() function for file rights supplements the so far used SetOwner() function if you need it at all. With Execute() you have several options to replace it. System() or RunCommand() are the candidates to use. System() is thanks to its tag list far easier to handle. By using CreateProc() you can create new processes; this function must be replaced with CreateNewProc() or you can resort directly to System(). "NewDosFunctions.c" shows an example with the new functions.

<syntaxhighlight>
/* NewDosFunctions.c
*
* gcc -o NewDosFunctions NewDosFunctions.c
*/

#include <exec/types.h>
#include <proto/dos.h>
#include <stdlib.h>

int main(int argc, char *argv[])
{

BPTR lock;
BPTR fh;
struct ExamineData *ed;
struct ExamineData *edata;
APTR context;

if((lock = IDOS->Lock("",SHARED_LOCK)))
{
if((ed = IDOS->ExamineObjectTags(EX_FileLockInput, lock, TAG_END)))
{
IDOS->Printf("Directory <%s> ...\n", ed->Name);

if((context = IDOS->ObtainDirContextTags(EX_FileLockInput,lock,
EX_DoCurrentDir,TRUE,
EX_DataFields,EXF_ALL,
TAG_END)))
{
while((edata = IDOS->ExamineDir(context)))
{
if( EXD_IS_LINK(edata) )
{
IDOS->Printf("%s [link]\n",edata->Name);
IDOS->Printf(" File is linked to <%s>\n", edata->Link);
}
else if ( EXD_IS_DIRECTORY(edata) )
{
IDOS->Printf("%s [directory]\n", edata->Name);
}
else if( EXD_IS_FILE(edata) )
{
IDOS->Printf("%s [file]\n", edata->Name);
}
}

if(IDOS->IoErr() != ERROR_NO_MORE_ENTRIES)
{
IDOS->Printf("Directory scan error\n");
}
}
else IDOS->Printf("Can't create context\n");

IDOS->ReleaseDirContext(context);
}
else IDOS->Printf("Can't examine object\n");

IDOS->FreeDosObject(DOS_EXAMINEDATA, ed);

IDOS->UnLock(lock);
}
else IDOS->Printf("Can't lock current dir\n");

if((fh = IDOS->Open("datei", MODE_NEWFILE)))
{
IDOS->ChangeFilePosition(fh, 100, OFFSET_BEGINNING);

IDOS->ChangeFileSize(fh, 1024, OFFSET_BEGINNING);

IDOS->Close(fh);
}
else IDOS->Printf("Can't open file <datei>\n");

return 0;
}
</syntaxhighlight>

[[File:AF105_grab_newdosfunctions.png|frame|center]]

The description of the old functions has been stored in "dos.obsolete.doc". You can still compile old sources with these functions without any problems. At some point in the future they certainly won't be used any more; at the latest then you must adjust the code. Above all, when creating new sources or revising existing sources you should switch to the new functions.

== Forbidden ==

We would also like to mention the Exit() functions that can lead to a compiling error, as they no longer exist. You can simply replace them with exit() for the Runtime library.

You must relocate formatted file outputs via VFWritef() to VFPrintf(). The greater difference lies in the format string, as it was coded in the old function as a BCPL string and is therefore not directly compatible with the RawDoFmt() placeholders.

== Functions ==

New (selected) functions in the dos.library:
int32 AddDates(struct DateStamp *to, CONST struct DateStamp *from) : Adds dates
BPTR CreateDirTree(STRPTR path) : creates old directory trees
uint32 DateStampToSeconds(struct DateStamp *ds) : Converts a DateStamp structure into seconds
int32 DevNameFromLock(BPTR fh, STRPTR buffer, int32 buffersize) : Gives the device name (not the data carrier name !) to the assigned lock
int32 DosControl(struct TagItem *taglist) : Setting and reading DOS internals
BPTR ErrorOutput(void) : gives the error output stream (stderr)
int32 FixDateStamp(struct DateStamp *ds) : if necessary, it corrects the datestamp entries
BPTR GetCurrentDir(VOID) : gives a lock for the current directory
int32 GetSegListInfo(BPTR seglist, struct TagItem *taglist) : gives information about the loaded program segment
int32 HexToLong(STRPTR buffer, uint32 *val) : Transforms a hexadecimal number into a long value
int32 PutErrStr(STRPTR txt) : Text output in the error output stream
struct DateStamp * SecondsToDateStamp(uint32 sec, struct DateStamp *ds) : Converts seconds into a datestamp structure
BPTR SelectErrorOutput(BPTR fh) : Changes the error output stream
APTR SetProcWindow(APTR ) : sets the pr_WindowPtr
int32 SubtractDates(struct DateStamp *ds1, CONST struct DateStamp *ds2) : Subtracts dates
int32 WaitForData(BPTR stream, int32 data_direction, int32 timeout) : waits until the stream is ready to send/read (especially Pipes)

What has become deprecated:
LONG Seek(BPTR file, LONG position, LONG offset)
-> ChangeFilePosition()
LONG SetFileSize(BPTR fh, LONG pos, LONG mode)
->ChangeFileSize()
LONG SetOwner(CONST_STRPTR name, ULONG owner_info)
-> SetOwnerInfo()
LONG Examine(BPTR lock, struct FileInfoBlock *fib)
-> ExamineObject()
LONG ExamineFH(BPTR fh, struct FileInfoBlock *fib)
-> ExamineObject()
LONG ExAll(BPTR lock, struct ExAllData *buffer, LONG size, LONG data, struct ExAllControl *control)
-> ExamineDir()
LONG ExNext(BPTR lock, struct FileInfoBlock *fib)
-> ExamineDir()
VOID ExAllEnd(BPTR lock, struct ExAllData *buffer, LONG size, LONG data, struct ExAllControl *control)
-> ExamineDir()
struct MsgPort *CreateProc(CONST_STRPTR name, LONG pri, BPTR segList, LONG stackSize)
-> CreateNewProc()
struct MsgPort *DeviceProc(CONST_STRPTR name)
-> GetDeviceProc()
LONG ReadLink(struct MsgPort *port, BPTR lock, CONST_STRPTR path, STRPTR buffer, ULONG size)
-> ExamineObject()
LONG SetVBuf(BPTR fh, STRPTR buff, LONG type, LONG size);
-> SetFileHandleAttr
LONG Execute(CONST_STRPTR string, BPTR file, BPTR file2);
-> RunCommand()

What has become obsolete:
VOID Exit(LONG returnCode);
-> exit()
VOID VFWritef(BPTR fh, CONST_STRPTR format, LONG *argarray)
-> VFPrintf()
VOID FWritef(BPTR fh, CONST_STRPTR format, ...)
-> VFPrintf()
BPTR InternalLoadSeg(BPTR fh, BPTR table, const LONG *funcarray)
-> LoadHunk()
LONG InternalUnLoadSeg(BPTR seglist, VOID (*freefunc )())
-> UnLoadHunk()
BPTR LoadSeg(CONST_STRPTR name, BPTR hunktab, BPTR stream)
-> RunCommand

== Authors ==

Written by Michael Christoph and Aleksandra Schmidt-Pendarovska 
Copyright (c) 2013 Michael Christoph

UserDoc:AmigaOS File Systems

2017-12-20T07:37:01Z

Daniel Jedlicka:

{| class="wikitable"
|+ AmigaOS File System Table
!
! FastFileSystem (FFS)
! FastFileSystem 2 (FFS2)
! SmartFileSystem (SFS)
! SmartFileSystem 2 (SFS2)
! JXFS
! [[AmigaDOS_Vector-Port#New_Generation_File_System|New Generation File System]] (NGFS)
|-
| Bootable?
| Yes
| Yes
| Yes
| Yes
| No
| Yes, on AmigaOne X-1000 and later machines using amigaboot
|-
| DosType
| DOS\03 0x444f5303
| DOS\07 0x444f5307
| SFS\00 0x53465300
| SFS\02 0x53465302
| JXF\04 0x4A584604
| NGF\00 0x4E474600
|-
| Max. Filename Length
| 30 characters
| 107 characters
| 107 characters
| 107 characters
| 107 characters
| 255 characters (fewer if the filename is UTF-8 encoded)
|-
| Max. Partition Size
| 2 TB to 128 TB
| 2 TB to 128 TB
| 128 GB
| 1 TB
| 256 TB
| 100 EiB
|-
| Max. File Size
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 1 TB
| 256 TB
| 2^64 - 1 Bytes
|-
| Supported Block Size
| 512 to 32768
| 512 to 32768
| use 512
| use 512
| 512
| 256 to 65536 (auto selected)
|-
| Comments
| Legacy file system, not recommended for AmigaOS 4.x due to lack of long filename support. Can be used for bootloader partition in AmigaOS 4.x only setup.
| Current file system, bootable, can be used with AmigaOS 4.x, recovery tools available, not as fast as SFS, requires validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x, some recovery tools available. Fast, does not require validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x. Fast, does not require validation if disk error. No recovery tools.
| Fastest but not backwards compatible with some 68K legacy software. No recovery tools. Discontinued starting with 4.1 Final Edition.
| [[AmigaDOS_Vector-Port|Vector-port]]-based file system, full DOS compatibility. Journalling, full check/repair facility provided.
|}

* SFS\00 and SFS\02 support other block sizes but only 512 bytes should be used since it is slower with larger blocks. JXFS only supports 512 block size.
* Recovery tools are located in Media Toolbox in the SYS:System drawer. Always have a backup!

UserDoc:AmigaOS File Systems

2017-12-11T21:39:37Z

Daniel Jedlicka: Added information about NGFS.

{| class="wikitable"
|+ AmigaOS File System Table
!
! FastFileSystem (FFS)
! FastFileSystem 2 (FFS2)
! SmartFileSystem (SFS)
! SmartFileSystem 2 (SFS2)
! JXFS
! [[AmigaDOS_Vector-Port#New_Generation_File_System|NGFS]]
|-
| Bootable?
| Yes
| Yes
| Yes
| Yes
| No
| Yes, on AmigaOne X-1000 and later machines using amigaboot
|-
| DosType
| DOS\03 0x444f5303
| DOS\07 0x444f5307
| SFS\00 0x53465300
| SFS\02 0x53465302
| JXF\04 0x4A584604
| NGF\00 0x4E474600
|-
| Max. Filename Length
| 30 characters
| 107 characters
| 107 characters
| 107 characters
| 107 characters
| 255 characters (fewer if the filename is UTF-8 encoded)
|-
| Max. Partition Size
| 2 TB to 128 TB
| 2 TB to 128 TB
| 128 GB
| 1 TB
| 256 TB
| 100 EiB
|-
| Max. File Size
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 1 TB
| 256 TB
| 2^64 - 1 Bytes
|-
| Supported Block Size
| 512 to 32768
| 512 to 32768
| use 512
| use 512
| 512
| 256 to 65536 (auto selected)
|-
| Comments
| Legacy file system, not recommended for AmigaOS 4.x due to lack of long filename support. Can be used for bootloader partition in AmigaOS 4.x only setup.
| Current file system, bootable, can be used with AmigaOS 4.x, recovery tools available, not as fast as SFS, requires validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x, some recovery tools available. Fast, does not require validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x. Fast, does not require validation if disk error. No recovery tools.
| Fastest but not backwards compatible with some 68K legacy software. No recovery tools. Discontinued starting with 4.1 Final Edition.
| [[AmigaDOS_Vector-Port|Vector-port]]-based file system, full DOS compatibility. Journalling, full check/repair facility provided.
|}

* SFS\00 and SFS\02 support other block sizes but only 512 bytes should be used since it is slower with larger blocks. JXFS only supports 512 block size.
* Recovery tools are located in Media Toolbox in the SYS:System drawer. Always have a backup!

UserDoc:AmigaOS File Systems

2017-12-11T12:58:27Z

Daniel Jedlicka: Fixed spelling.

SFS\00 and SFS\02 support other block sizes but only 512 bytes should be used since it is slower with larger blocks. JXFS only supports 512 block size. Recovery tools are located in Media Toolbox in the SYS:System drawer. Always have a backup.

{| class="wikitable"
|+ AmigaOS File System Table
!
! FastFileSystem (FFS)
! FastFileSystem 2 (FFS2)
! SmartFileSystem (SFS)
! SmartFileSystem 2 (SFS2)
! JXFS
|-
| Bootable?
| Yes
| Yes
| Yes
| Yes
| No
|-
| DosType
| DOS\03 0x444f5303
| DOS\07 0x444f5307
| SFS\00 0x53465300
| SFS\02 0x53465302
| JXF\04 0x4A584604
|-
| Max. Filename Length
| 30 characters
| 107 characters
| 107 characters
| 107 characters
| 107 characters
|-
| Max. Partition Size
| 2 TB to 128 TB
| 2 TB to 128 TB
| 128 GB
| 1 TB
| 256 TB
|-
| Max. File Size
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 4 GB - 2 Bytes
| 1 TB
| 256 TB
|-
| Supported Block Size
| 512 to 32768
| 512 to 32768
| only 512
| only 512
| only 512
|-
| Comments
| Legacy file system, not recommended for AmigaOS 4.x due to lack of long filename support. Can be used for bootloader partition in AmigaOS 4.x only setup.
| Current file system, bootable, can be used with AmigaOS 4.x, recovery tools available, not as fast as SFS, requires validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x, some recovery tools available. Fast, does not require validation if disk error.
| Current file system, bootable, can be used with AmigaOS 4.x. Fast, does not require validation if disk error. No recovery tools.
| Fastest but not backwards compatible with some 68K legacy software. No recovery tools. Discontinued starting with 4.1 Final Edition.
|}

BattClock Resource

2017-12-06T12:03:47Z

Daniel Jedlicka: Polished the page, added OS4-updated example code by Doug Stastny, and removed the WIP banner.

== Introduction ==

The battery-backed clock (BattClock) keeps Amiga time while the system is powered off. The time from the BattClock is loaded into the Amiga system clock as part of the boot sequence.

The BattClock Resource component provides access to the BattClock. Three [[#Function reference|functions]] allow you to read the BattClock value, reset it and set it to a value you desire.

The [[Utility Library]] contains time functions which convert the number of seconds since 12:00 AM, January 1, 1978 to a date and time we can understand, and vice versa. You will find these functions useful when dealing with the BattClock. The example program below uses the Amiga2Date() utility function to convert the value returned by ReadBattClock(). See the [[Utility Library]] page for a discussion of the scope of the library, and the [[Autodocs:Main|autodocs]] for a listing of its functions.

{{Note|title=''So, you want to be a Time Lord?''|This resource will allow you to set the BattClock to any value you desire. Keep in mind that this time will endure a reboot and could adversely affect your system!}}

== Example ==

<syntaxhighlight>
#include <exec/types.h>
#include <dos/dos.h>
#include <utility/date.h>
#include <resources/battclock.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/battclock.h>
#include <proto/utility.h>

int main()
{
STRPTR ampm;
uint32 AmigaTime;
struct ClockData MyClock;
CONST CONST_STRPTR Days[] = {"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"};
CONST CONST_STRPTR Months[] = {"January", "February", "March", "April", "May", "June", "July", "August",
"September", "October", "November", "December"};

struct Library *BattClockBase = IExec->OpenResource(BATTCLOCKNAME);
struct BattClockIFace *IBattClock = (struct BattClockIFace *) IExec->GetInterface(BattClockBase, "main", 1, NULL);

if (IBattClock != NULL) {
/* Get number of seconds till now */
AmigaTime = IBattClock->ReadBattClock();

/* Convert to a ClockData structure */
IUtility->Amiga2Date(AmigaTime, &MyClock);
IDOS->Printf("\nRobin, tell everyone the BatDate and BatTime");

/* Print the Date */
IDOS->Printf("\n\nOkay Batman, the BatDate is ");
IDOS->Printf("%s, %s %ld, %ld", Days[MyClock.wday], Months[MyClock.month-1], MyClock.mday, MyClock.year);

/* Convert military time to normal time and set AM/PM */
if (MyClock.hour < 12) {
ampm = "AM"; /* hour less than 12, must be morning */
}
else {
ampm = "PM"; /* hour greater than 12,must be night */
MyClock.hour -= 12; /* subtract the extra 12 of military */
};

if (MyClock.hour == 0) {
MyClock.hour = 12; /* don't forget the 12s */
}

/* Print the time */
IDOS->Printf("\n the BatTime is ");
IDOS->Printf("%02ld:%02ld:%02ld %s\n\n", MyClock.hour, MyClock.min, MyClock.sec, ampm);

IExec->DropInterface((struct Interface*) IBattClock);
}
else
IDOS->Printf("Error: Unable to open the %s\n", BATTCLOCKNAME);

return 0;
}
</syntaxhighlight>

Additional programming information on the BattClock Resource can be found in the respective include files and in the BattClock Resource and Utility Library [[Autodocs:Main|autodocs]].

== Function reference ==

{| class="wikitable"
| ReadBattClock() || Read the time from the BattClock. Returns the time as the number of seconds since 12:00 AM, January 1, 1978.
|-
| ResetBattClock() || Reset the BattClock to 12:00 AM, January 1, 1978.
|-
| WriteBattClock() || Set the BattClock to the number of seconds you pass it relative to 12:00 AM, January 1, 1978.
|}

Wiki Author Credits

2017-12-03T11:53:01Z

Daniel Jedlicka: Added Douglas Stastny to the list

The following is a list of known contributors to this wiki:

* Adam Levin
* Alexandre Balaban
* [http://amigaak.org.nz/ Amiga Auckland]
* Andy Finkel
* Bart Whitebook
* Bill Borsari
* Bill Koester
* Bob Burns
* Bob Pariseau
* Bruce Barrett
* Bryce Nesbitt
* Carl Sassenrath
* Carolyn Scheppner
* Chris Green
* Chris Ludwig
* Chris Raymond
* Dale Luck
* Dan Baker
* [http://gtmooya.blogspot.com/ Daniel Hutchinson]
* Daniel Jedlicka
* Darius Taghavy
* Darren Greenwald
* Dave Berezowski
* Dave Lucas
* David Junod
* David Miller
* Don Cox
* Douglas Stastny
* Eric Cotton
* Ewout Walraven
* Frank Bunton, for his [http://aminet.net/package/docs/help/adosbegin AmigaDOS guide]
* Hans-Joerg Frieden
* James Jacobs
* [http://www.janneperaaho.arkku.net/ Janne Peräaho]
* Jerry Hartzler
* Jez San
* Jim Mackraz
* Joe Katz
* John Orr
* John Wiederhirn
* Karl Churchill
* Ken Farinsky
* Kevin Klop
* Larry Hildenbrand
* Leo Schwab
* [https://sites.google.com/site/takeaprogrammertolunch/ Lyle Hazelwood]
* Mark Barton
* Mark Ricci
* [http://wandel.ca/ Markus Wandel]
* Martin Taillefer
* Michael Sinz
* Nancy Rains
* Neil Kafferkey
* Neil Katin
* Olaf Barthel
* Paul Higginbottom
* Paul Sadlik
* Peter Cherna
* Philippe Ferrucci
* R.J. Mical
* Randell Jesup
* Ray Brand
* Rob Cranley
* Rob Peck
* Rob Wyesham
* Roman Kargin
* Sam Dicker
* Simon Archer
* Spencer Shanson
* Stan Shepard
* Steve Beats
* [http://www.solie.ca Steven Solie]
* Stuart Ferguson
* Susan Deyl
* Thomas Frieden
* Tom Pohorsky
* Tom Rokicki

Window Display Preservation

2017-12-03T11:50:19Z

Daniel Jedlicka: SuperBitMap Window Example: code rewritten for OS4 by Doug Stastny

= Preserving the Window Display =

The layers library is what allows the display and manipulation of multiple overlapping rectangles, or ''layers''. Intuition uses the layers library to manage its windows, by associating a layer to each window.

Each window is a virtual display. When rendering, the application does not have to worry about the current size or position of its window, and what other windows might be partly or fully obscuring its window. The window's RastPort is the handle to the its virtual display space. Intuition and graphics library rendering calls will recognize that this RastPort belongs to a layer, and act accordingly.

As windows are moved, resized, rearranged, opened, or closed, the on-screen representation changes. When part of a window which was visible now needs to appear in a new location, the layers library will move that imagery without involving the application. However, when part of a window that was previously obscured is revealed, or when a window is made larger, the imagery for the newly-visible part of the window needs to be redrawn. Intuition, through layers, offers three choices for how this is managed, trading off speed, memory usage, and application complexity.

* The most basic type of window is called ''Simple Refresh''. When any graphics operation takes place in this kind of window, the visible parts are updated, but rendering to the obscured parts is discarded. When the window arrangement changes to reveal a previously obscured part of such a window, the application must refresh that area.

* Alternately, a window may be made ''Smart Refresh'', which means that when rendering occurs, the system will not only update the visible parts of the window, but it will maintain the obscured parts as well, by using off-screen buffers. This means that when an obscured part of the window is revealed, the system will restore the imagery that belongs there. The application needs only to refresh parts of the window that appear when the window is made bigger. Smart Refresh windows use more memory than Simple Refresh windows (for the storage of obscured areas), but they are faster.

* The third kind of window is called ''SuperBitMap''. In such a window, the system can refresh the window even when it is sized bigger. For this to work, the application must store a complete bitmap for the window's maximum size. Such a window is more work to manage, and uses yet more memory. SuperBitMap windows are used less often than the other two types.

Intuition helps your application manage window refresh. First, Intuition will take care of redrawing the window border and any system and application gadgets in the window. Your application never has to worry about that. Second, Intuition will notify your application when it needs to refresh its window (by sending the IDCMP_REFRESHWINDOW event). Third, Intuition provides functions that restrict your rendering to the newly-revealed (damaged) areas only, which speeds up your refresh rendering and makes it look cleaner.

The Intuition, layers, and graphics libraries work together to make rendering into and managing windows easy. You obtain your windows through Intuition, which uses the Layers library to manage the overlapping, resizing, and re-positioning of the window layers. The layers library is responsible for identifying the areas of each window that are visible, obscured but preserved off-screen, or obscured and not preserved. The rendering functions in the graphics library and Intuition library know how to render into the multiple areas that layers library establishes.

Note that you may not directly manipulate layers on an Intuition screen. You cannot create your own layers on an Intuition screen, nor can you use the layers movement, sizing, or arrangement functions on Intuition windows. Use the corresponding Intuition calls instead. Some other Layers library calls (such as the locking calls) are sometimes used on Intuition screens and windows.

= Damage Regions =

The layers library and Intuition maintain a ''damage region'' for each window, which is the part of the window whose imagery is in need of repair, or refreshing. Several things can add areas of the window to the damage region:

* Revealing an obscured part of a Simple Refresh window adds that area to the damage region
* Sizing a Simple or Smart Refresh window bigger along either axis adds the new area to the damage region
* Resizing a Simple or Smart Refresh window (smaller or bigger) adds the old and new border areas, and the areas occupied by certain gadgets (those whose position or size depend on window size) to the damage region.

= Refreshing Intuition Windows =

When the user or an application performs an Intuition operation which causes damage to a window, Intuition notifies that window's application. It does this by sending a message of the class IDCMP_REFRESHWINDOW to that window's IDCMP.

In response to this message, your application should update the damaged areas. Rendering proceeds faster and looks cleaner if it is restricted to the damaged areas only. The BeginRefresh()/EndRefresh() pair achieve that. The application should call BeginRefresh() for the window, and then do its rendering. Any rendering that would have gone into undamaged areas of the window is automatically discarded; only the area in need of repair is affected. Finally, the application should call EndRefresh(), which removes the restriction on rendering, and informs the system that the damage region has been dealt with. Even if your application intends to do no rendering, it must at least call BeginRefresh()/EndRefresh(), to inform the system that the damage region is no longer needed. If your application never needs to render in response to a refresh event, it can avoid having to call BeginRefresh()/EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

Note that by the time that your application receives notification that refresh is needed, Intuition will have already refreshed your window's border and all gadgets in the window, as needed. Thus, it is unnecessary to use any of the gadget-refreshing functions in response to an IDCMP_REFRESHWINDOW event.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Avoid RefreshGList() or RefreshGadgets(), or you risk deadlocking the computer. Avoid calls that may lock the LayerInfo or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest() and EasyRequest(), and therefore all direct or indirect disk related DOS calls. See the [[Intuition_Gadgets|Intuition Gadgets]] section for more information on gadget restrictions with BeginRefresh() and EndRefresh().

== Simple Refresh ==

For a Simple Refresh window, only those pixels actually on-screen are maintained by the system. When part of a Simple Refresh window is obscured, the imagery that was there is lost. As well, any rendering into obscured portions of such a window is discarded.

When part of the window is newly revealed (either because the window was just made larger, or because that part used to be obscured by another window), the application must refresh any rendering it wishes to appear into that part. The application will learn that refresh is needed because Intuition sends an IDCMP_REFRESHWINDOW event.

== Smart Refresh ==

If a window is of the Smart Refresh type, then the system will not only preserve those pixels which are actually on-screen, but it will save all obscured pixels that are within the current window's size. The system will refresh those parts of the window revealed by changes in the overlapping with other windows on the screen, without involving the application. However, any part of the window revealed through the sizing of the window must be redrawn by the application. Again, Intuition will notify the application through the IDCMP_REFRESHWINDOW event.

Because the obscured areas are kept in off-screen buffers, Smart Refresh windows are refreshed faster than Simple Refresh windows are, and often without involving the application. Of course, for the same reason, they use more display memory.

== SuperBitMap Refresh ==

The SuperBitMap refresh type allows the application to provide and maintain bitmap memory for graphics in the window. The bitmap can be any size as long as the window sizing limits respect the maximum size of the bitmap.

SuperBitMap windows have their own memory for maintaining all obscured parts of the window up to the size of the defined bitmap, including those parts outside of the current window. Intuition will update all parts of the window that are revealed through changes in sizing and changes in window overlapping. The application never needs to redraw portions of the window that were revealed by sizing or positioning windows in the screen.

SuperBitMap windows require the application to allocate a bitmap for use as off-screen memory, instead of using Intuition managed buffers. This bitmap must be as large as, or larger than, the inner window's maximum dimensions (that is, the window's outside dimensions less the border sizes).

SuperBitMap windows are almost always WFLG_GIMMEZEROZERO, which renders the borders and system gadgets in a separate bitmap. If the application wishes to create a SuperBitMap window that is not GimmeZeroZero, it must make the window borderless with no system gadgets, so that no border imagery is rendered by Intuition into the application's bitmap.

= Intuition Refresh Events =

When using a Simple Refresh or a Smart Refresh windows, the program may receive refresh events, informing it to update the display. See the above discussion for information on when refresh events are sent.

A message of the class IDCMP_REFRESHWINDOW arrives at the IDCMP, informing the program of the need to update the display. The program must take some action when it receives a refresh event, even if it is just the acceptable minimum action described below.

On receiving a refresh event, BeginRefresh() must be called, then the program should redraw its display, and, finally, call EndRefresh(). The minimum required action is to call the BeginRefresh()/EndRefresh() pair. This allows Intuition and the Layers library keep things sorted and organized.

= Optimized Window Refreshing =

Bracketing the display updating in the BeginRefresh()/EndRefresh() pair automatically restricts all rendering to the "damaged" areas.

<syntaxhighlight>
VOID BeginRefresh( struct Window *window );
VOID EndRefresh ( struct Window *window, LONG complete );
</syntaxhighlight>

These functions makes sure that refreshing is done in the most efficient way, only redrawing those portions of the window that really need to be redrawn. The rest of the rendering commands are discarded.

Operations performed between the BeginRefresh()/EndRefresh() pair should be restricted to simple rendering. All of the rendering functions in Intuition library and Graphics library are safe. Calls to RefreshGadgets() are not permitted. Avoid calls that may lock the LayerInfo, or get complicated in Intuition, since BeginRefresh() leaves the window's layer or layers locked. Avoid AutoRequest(), and therefore all direct or indirect disk related DOS calls. See [[Intuition_Gadgets|Intuition Gadgets]] for more information on gadget restrictions with BeginRefresh()/EndRefresh().

Certain applications do not need to receive refresh events, and can avoid having to call BeginRefresh() and EndRefresh() by setting the WFLG_NOCAREREFRESH flag or the WA_NoCareRefresh tag in the OpenWindowTagList() call.

The EndRefresh() function takes a boolean value as an argument (complete in the prototype above). This value determines whether refreshing is completely finished. When set to FALSE, further refreshing may be performed between subsequent BeginRefresh()/ EndRefresh() pairs. Set the boolean to TRUE for the last call to EndRefresh().

It is critical that applications performing multiple BeginRefresh() and EndRefresh() pairs using EndRefresh(win,FALSE) hold layers locked through the entire process. The layer lock may only be released after the final call to EndRefresh(win,TRUE). See [[Layers_Library|Layers Library]] for more details.

The procedures outlined in this section take care of refreshing what is inside the window. Another function named RefreshWindowFrame() refreshes window borders, including the title region and gadgets:

<syntaxhighlight>
VOID RefreshWindowFrame( struct Window *window );
</syntaxhighlight>

Applications can use this function to update window borders after overwriting them with graphics.

= Setting up a SuperBitMap Window =

SuperBitMap windows are created by setting the WFLG_SUPER_BITMAP flag, or by specifying the WA_SuperBitMap tag in the OpenWindowTagList() call. A pointer to an allocated and initialized BitMap structure must be provided.

A SuperBitMap window requires the application to allocate and initialize its own bitmap. This entails allocating a BitMap structure, initializing the structure and allocating memory for the bit planes.

Allocate a BitMap structure with the Exec AllocMem() function. Then use the graphics function InitBitMap() to initialize the BitMap structure:

<pre>
VOID InitBitMap( struct BitMap *bitMap, LONG depth, LONG width, LONG height );
</pre>

InitBitMap() fills in fields in the BitMap structure describing how a linear memory area is organized as a series of one or more rectangular bit-planes.

Once you have allocated and initialized the BitMap structure, use the graphics library function AllocRaster() to allocate the memory space for all the bit planes.

<pre>
PLANEPTR AllocRaster( ULONG width, ULONG height );
</pre>

The example listed in the next section shows how to allocate a BitMap structure, initialize it with InitBitMap() and use AllocRaster() function to set up memory for the bitplanes.

= Graphics and Layers Functions for SuperBitMap Windows =

The portion of the bitmap showing within a SuperBitMap window is controlled by the application. Initially, the window shows the bitmap starting from its origin (0,0) and clipped to fit within the window layer. The visible portion of the bitmap can be scrolled around within the window using the layers library ScrollLayer() function:

<pre>
VOID ScrollLayer(LONG unused, struct Layer *layer, LONG dx, LONG dy)
</pre>

Pass this function a pointer to the window's layer in layer and the scroll offsets in dx and dy. (A pointer to the window's layer can be obtained from Window.RPort->Layer.)

When rendering operations are performed in a SuperBitMap window, any rendering that falls outside window boundaries is done in the application's bitmap. Rendering that falls within window bounds is done in the screen's bitmap. Before performing an operation such as a save on the application bitmap, the graphics library function SyncSBitMap() should be called:

<pre>
VOID SyncSBitMap(struct Layer *layer)
</pre>

Pass this function a pointer to the window's layer. SyncSBitMap() copies the window contents to the corresponding part of the application bitmap, bringing it up to date. (If no rendering operations have been performed this call is not necessary.)

Similarly, after making any changes to the application bitmap such as loading a new one, the window's layer should be locked and the CopySBitMap() function should be called.

<pre>
VOID CopySBitMap(struct Layer *)
</pre>

This function copies the new information in the appropriate area of the underlying bitmap to the window's layer.

For more information about bitmaps and layers, see the [[Graphics_Primitives|Graphics Primitives]] and [[Layers_Library|Layers Library]]. Also see the <graphics/clip.h>, <graphics/gfx.h>, <graphics/layers.h > files in the SDK.

== SuperBitMap Window Example ==

This example shows how to implement a superbitmap, and uses a host of Intuition facilities. Further reading of other Intuition, BOOPSI and graphics chapters may be required for a complete understanding of this example.

<syntaxhighlight>
/**
** lines.c -- Window SuperBitMap example.
**
** gcc -o lines lines.c
**
**/

#include <dos/dos.h>
#include <intuition/icclass.h>
#include <classes/window.h>
#include <gadgets/scroller.h>
#include <gadgets/layout.h>

#include <proto/intuition.h>
#include <proto/exec.h>
#include <proto/utility.h>
#include <proto/layers.h>
#include <proto/graphics.h>

#define WIDTH_SUPER (800)
#define HEIGHT_SUPER (600)
#define MINWIDTH (150)
#define MINHEIGHT (150)

#define LAYERXOFFSET(x) (x->RPort->Layer->Scroll_X)
#define LAYERYOFFSET(x) (x->RPort->Layer->Scroll_Y)

enum
{
WID_MAIN = 0,
WID_LAST
};

enum
{
OID_MAIN = 0,
OID_VPROP,
OID_HPROP,
OID_LAST
};

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

static struct Window *windows[WID_LAST];
static Object *objects[OID_LAST];
static struct Hook idcmphook;

/* Prototypes for our functions */

void initBorderProps(struct Screen *screen);
void doNewSize();
void doDrawStuff();
void doMsgLoop();
void superWindow(struct Screen *screen);
void slideBitMap(struct Window *win, int16 dX, int16 dY);

int main()
{
struct Screen *screen;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *) IExec->GetInterface(IntuitionBase,
"main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace *) IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace *) IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL) {
if ((screen = IIntuition->LockPubScreen(NULL)) != NULL) {
superWindow(screen);
IIntuition->UnlockPubScreen(NULL, screen);
}
}

IExec->DropInterface((struct Interface *) ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface *) IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface *) IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}

void IDCMPHook(struct Hook *hook, Object *object, struct IntuiMessage *msg)
{
if (msg->Class == IDCMP_IDCMPUPDATE) {
int16 dX = 0;
int16 dY = 0;
int32 pos;

struct Window *win = windows[WID_MAIN];
if (win != NULL) {
uint32 gadgetid = IUtility->GetTagData(GA_ID, 0, (struct TagItem *) msg->IAddress);
if (IIntuition->GetAttr(SCROLLER_Top, objects[gadgetid], (uint32 *) &pos)) {
switch (gadgetid) {
case OID_VPROP:
dY = pos - LAYERYOFFSET(win);
break;
case OID_HPROP:
dX = pos - LAYERXOFFSET(win);
break;
}
if (dX || dY) {
slideBitMap(win, dX, dY);
}
}
}
}
}

void superWindow(struct Screen *myscreen)
{
struct BitMap *bigBitMap = IGraphics->AllocBitMapTags(WIDTH_SUPER, HEIGHT_SUPER, myscreen->BitMap.Depth,
BMATags_Friend, myscreen->BitMap, BMATags_Displayable, TRUE, BMATags_Clear, 0, TAG_END);

if (bigBitMap != NULL) {
struct MsgPort *AppPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_DONE);

if ( AppPort != NULL )
{
idcmphook.h_Entry = (uint32 (*)())IDCMPHook;
idcmphook.h_SubEntry = NULL;

if ((objects[OID_MAIN] = IIntuition->NewObject(NULL, "window.class",
WA_ScreenTitle, "SuperBitmap",
WA_Title, "Lines",
WA_Activate, TRUE,
WA_DepthGadget, TRUE,
WA_DragBar, TRUE,
WA_CloseGadget, TRUE,
WA_SizeGadget, TRUE,
WA_Top, 10,
WA_Left, 10,
WA_MinWidth, MINWIDTH,
WA_MinHeight, MINHEIGHT,
WA_Width, MINWIDTH,
WA_Height, MINHEIGHT,
WA_IDCMP, IDCMP_NEWSIZE | IDCMP_IDCMPUPDATE,
WA_PubScreen, myscreen, WA_SuperBitMap, bigBitMap,
WA_NoCareRefresh, TRUE,
WA_GimmeZeroZero, TRUE,
WINDOW_IDCMPHook, &idcmphook,
WINDOW_IDCMPHookBits, IDCMP_IDCMPUPDATE,
WINDOW_HorizProp, 1,
WINDOW_VertProp, 1,
WINDOW_AppPort, AppPort, TAG_DONE)) != NULL) {
// Open the window.
if (windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN)) {
/* adjust props to represent portion visible */
doNewSize();
doDrawStuff();
/* process the window, return on IDCMP_CLOSEWINDOW */
doMsgLoop();
}
IIntuition->DisposeObject(objects[OID_MAIN]);
}
IExec->FreeSysObject(ASOT_PORT, AppPort);
}
IGraphics->FreeBitMap(bigBitMap);
}
}

void slideBitMap(struct Window *win, int16 Dx, int16 Dy)
{
ILayers->ScrollLayer(0, win->RPort->Layer, Dx, Dy);
}

/*
** Update the prop gadgets and bitmap positioning when the size changes.
*/

void doNewSize()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
IIntuition->GetAttr(WINDOW_HorizObject, objects[OID_MAIN], (uint32 *) &objects[OID_HPROP]);
if (objects[OID_HPROP]) {
if (win->GZZWidth >= WIDTH_SUPER)
slideBitMap(win, -LAYERXOFFSET(win), 0);
IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_HPROP], win, NULL,
GA_ID, OID_HPROP,
SCROLLER_Top, LAYERXOFFSET(win),
SCROLLER_Total, WIDTH_SUPER,
SCROLLER_Visible, win->GZZWidth,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}

IIntuition->GetAttr(WINDOW_VertObject, objects[OID_MAIN], (uint32 *) &objects[OID_VPROP]);
if (objects[OID_VPROP]) {
if (win->GZZHeight >= HEIGHT_SUPER)
slideBitMap(win, 0, -LAYERYOFFSET(win));

IIntuition->RefreshSetGadgetAttrs((APTR) objects[OID_VPROP], win, NULL,
GA_ID, OID_VPROP,
SCROLLER_Top, LAYERYOFFSET(win),
SCROLLER_Total, HEIGHT_SUPER,
SCROLLER_Visible, win->GZZHeight,
ICA_TARGET, ICTARGET_IDCMP,
TAG_DONE);
}
}
}

int16 RangeRand(uint32 maxValue)
{
static struct RandomState range = {0xFFFF, 0};
return IUtility->Random(&range) % maxValue;
}

void doDrawStuff()
{
struct Window *win = windows[WID_MAIN];
if (win != NULL) {
/* clear the bitplanes */
IGraphics->SetRast(win->RPort, 0);
IGraphics->SetDrMd(win->RPort, JAM1);
int16 x1, y1, x2, y2;
int16 pen, ncolors, deltx, delty;
ncolors = 1 << win->WScreen->BitMap.Depth;
deltx = RangeRand(6) + 2;
delty = RangeRand(6) + 2;
pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
x1 < WIDTH_SUPER; x1 += deltx, x2 -= deltx) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}

pen = RangeRand(ncolors - 1) + 1;
IGraphics->SetAPen(win->RPort, pen);
for (x1 = 0, y1 = 0, x2 = WIDTH_SUPER - 1, y2 = HEIGHT_SUPER - 1;
y1 < HEIGHT_SUPER; y1 += delty, y2 -= delty) {
IGraphics->Move(win->RPort, x1, y1);
IGraphics->Draw(win->RPort, x2, y2);
}
}
}

void doMsgLoop()
{
uint32 signal = 0;
BOOL done = FALSE;

// Obtain the window wait signal mask.
IIntuition->GetAttr(WINDOW_SigMask, objects[OID_MAIN], &signal);

// Input Event Loop
while (!done) {
uint32 wait = IExec->Wait(signal | SIGBREAKF_CTRL_C);
if ( wait & SIGBREAKF_CTRL_C ) {
done = TRUE;
break;
}

if ( wait & signal ) {
uint32 result = WMHI_LASTMSG;
int16 code = 0;
while ((result = IIntuition->IDoMethod(objects[OID_MAIN], WM_HANDLEINPUT, &code)) != WMHI_LASTMSG) {
switch (result & WMHI_CLASSMASK) {
case WMHI_NEWSIZE:
doNewSize();
doDrawStuff();
break;
case WMHI_CLOSEWINDOW:
windows[WID_MAIN] = NULL;
done = TRUE;
break;
case WMHI_ICONIFY:
IIntuition->IDoMethod(objects[OID_MAIN], WM_ICONIFY);
windows[WID_MAIN] = NULL;
break;
case WMHI_UNICONIFY:
windows[WID_MAIN] = (struct Window *) IIntuition->IDoMethod(objects[OID_MAIN], WM_OPEN);
doNewSize();
doDrawStuff();
break;
}
}
}
}
}
</syntaxhighlight>

Graphics Regions

2017-11-10T10:45:37Z

Daniel Jedlicka: Added links to library pages; fixed a few minor things

== Regions ==

Regions allow the application to install clipping rectangles into layers. A clipping rectangle is a rectangular area into which the graphics routines will draw. All drawing that would fall outside of that rectangular area is clipped (not rendered).

User clipping regions are linked lists of clipping rectangles created by an application program through the [[Graphics Library]] routines described below. By combining together various clipping rectangles, any arbitrary clipping shape can be created. Once the region is set up, you use the [[Layers Library]] call InstallClipRegion() to make the clipping region active in a layer.

Regions are safe to use with layers created by Intuition (i.e. windows).

The application can selectively update a custom-shaped part of a layer without disturbing any of the other layers that might be present.

{{Note|title=Never modify the DamageList of a layer directly|text=Use the routine InstallClipRegion() to add clipping to the layer. The regions installed by InstallClipRegion() are independent of the layer's DamageList and use of user clipping regions will not interfere with optimized window refreshing.}}

{{Note|title=Do not modify a region after it has been added|text=After a region has been added with InstallClipRegion(), the program may not modify it until the region has been removed with another call to InstallClipRegion().}}

=== Creating and Deleting Regions ===

You allocate a Region data structure with the NewRegion() call.

<syntaxhighlight>
struct Region *NewRegion( VOID );
</syntaxhighlight>

The NewRegion() function allocates and initializes a Region structure that has no drawable areas defined in it. If the application draws through a new region, nothing will be drawn as the region is empty. The application must add rectangles to the region before any graphics will appear.

Use DisposeRegion() to free the Region structure when you are done with it.

<syntaxhighlight>
VOID DisposeRegion( struct Region *region );
</syntaxhighlight>

DisposeRegion() returns all memory associated with a region to the system and deallocates all rectangles that have been linked to it.

{{Note|title=Don't forget to free your rectangles|text=All of the functions that add rectangles to the region make copies of the rectangles. If the program allocates a rectangle, then adds it to a region, it still must deallocate the rectangle. The call to DisposeRegion() will not deallocate rectangles ''explicitly allocated'' by the application.}}

=== Installing Regions ===

Use the function InstallClipRegion() to install the region.

<syntaxhighlight>
struct Region *InstallClipRegion( struct Layer *layer, struct Region *region );
</syntaxhighlight>

This installs a transparent clipping region to a layer. All subsequent graphics calls will be clipped to this region. The region must be removed with a second call to InstallClipRegion() before removing the layer.

<syntaxhighlight>
/*
** Sample installation and removal of a clipping region
*/
register struct Region *new_region ;
register struct Region *old_region ;

/* If the application owns the layer and has not installed a region,
** old_region will return NULL here.
*/
old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

/* draw into the layer or window */

if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
{
/* throw the used region away. This region could be saved and
** used again later, if desired by the application.
*/
ILayers->DisposeRegion(new_region) ;
}
</syntaxhighlight>

{{Note|title=A warning about InstallClipRegion()|text=The program must not call InstallClipRegion() inside of a Begin/EndRefresh() or Begin/EndUpdate() pair. The following code segment shows how to modify the user clipping region when using these calls. See the Autodoc for BeginRefresh() for more details.}}

<syntaxhighlight>
struct Region *new_region ;
struct Region *old_region ;

/* you have to have already setup the new_region and old_region */

IIntuition->BeginRefresh(window);
/* draw through the damage list */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the damage list and the new_region */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

/* put back the old region */
new_region = ILayers->InstallClipRegion(win->WLayer, old_region);

IIntuition->BeginRefresh(window);
IIntuition->EndRefresh(window, TRUE); /* remove the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the new_region only into the layer or window */
IIntuition->EndRefresh(window, FALSE);

/* finally get rid of the new region, old_region still installed */
if (NULL != (new_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
ILayers->DisposeRegion(new_region) ;
</syntaxhighlight>

=== Changing a Region ===

Regions may be modified by performing logical operations with rectangles, or with other regions.

{{Note|title=Reuse your rectangles|text=In all of the rectangle and region routines the clipping rectangle is copied into the region. This means that a single clipping rectangle (Rectangle structure) may be used many times by simply changing the ''x'' and ''y'' values. The application need ''not'' create a new instance of the Rectangle structure for each rectangle added to a region.}}

For instance:

<syntaxhighlight>
extern struct Region *RowRegion; /* created elsewhere */

int16 ktr;
struct Rectangle rect;

for (ktr = 1; ktr < 6; ktr++)
{
rect.MinX = 50;
rect.MaxX = 315;
rect.MinY = (ktr * 10) - 5;
rect.MaxY = (ktr * 10);

if (!IGraphics->OrRectRegion(RowRegion, &rect))
clean_exit(RETURN_WARN);
}
</syntaxhighlight>

==== Rectangles and Regions ====

There are four [[Graphics Library]] functions for changing a region through logical operations with a rectangle.

<syntaxhighlight>
BOOL OrRectRegion ( struct Region *region, struct Rectangle *rectangle );
VOID AndRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL XorRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL ClearRectRegion( struct Region *region, struct Rectangle *rectangle );
</syntaxhighlight>

OrRectRegion() modifies a region structure by '''OR''''ing a clipping rectangle into the region. When the application draws through this region (assuming that the region was originally empty), only the pixels within the clipping rectangle will be affected. If the region already has drawable areas, they will still exist, this rectangle is added to the drawable area.

AndRectRegion() modifies the region structure by '''AND''''ing a clipping rectangle into the region. Only those pixels that were already drawable and within the rectangle will remain drawable, any that are outside of it will be clipped in future.

XorRectRegion() applies the rectangle to the region in an '''exclusive-or''' mode. Within the given rectangle, any areas that were drawable become clipped, any areas that were clipped become drawable. Areas outside of the rectangle are not affected.

ClearRectRegion() clears the rectangle from the region. Within the given rectangle, any areas that were drawable become clipped. Areas outside of the rectangle are not affected.

==== Regions and Regions ====

As with rectangles and regions, there are four functions for combining regions with regions:

<syntaxhighlight>
BOOL AndRegionRegion( struct Region *srcRegion, struct Region *destRegion );
BOOL OrRegionRegion ( struct Region *srcRegion, struct Region *destRegion );
BOOL XorRegionRegion( struct Region *srcRegion, struct Region *destRegion );
VOID ClearRegion ( struct Region *region );
</syntaxhighlight>

AndRegionRegion() performs a logical '''AND''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever the regions drawable areas overlap. That is, where there are drawable areas in both region 1 '''AND''' region 2, there will be drawable areas left in the result region.

OrRegionRegion() performs a logical '''OR''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region.

XorRegionRegion() performs a logical '''exclusive-or''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region but not both. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region. But where there are drawable areas in both region 1 '''AND''' region 2, there will ''not'' be drawable areas left in the result region.

ClearRegion() puts the region back to the same state it was in when the region was created with NewRegion(), that is, no areas are drawable.

=== Regions Example ===

The following example shows the use of the [[Layers Library]] call InstallClipRegion(), as well as simple use of the [[Graphics Library]] regions functions.

<syntaxhighlight>
/* clipping.c */

/* Force use of new variable names to help prevent errors */
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/intuitionbase.h>
#include <graphics/displayinfo.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/layers.h>

#define MY_WIN_WIDTH (300)
#define MY_WIN_HEIGHT (100)

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

/*
** unclipWindow()
**
** Used to remove a clipping region installed by clipWindow() or
** clipWindowToBorders(), disposing of the installed region and
** reinstalling the region removed.
*/
void unclipWindow(struct Window *win)
{
struct Region *old_region;

/* Remove any old region by installing a NULL region,
** then dispose of the old region if one was installed.
*/
if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, NULL)))
IGraphics->DisposeRegion(old_region);
}

/*
** clipWindow()
** Clip a window to a specified rectangle (given by upper left and
** lower right corner.) the removed region is returned so that it
** may be re-installed later.
*/
struct Region *clipWindow(struct Window *win,
LONG minX, LONG minY, LONG maxX, LONG maxY)
{
struct Region *new_region;
struct Rectangle my_rectangle;

/* set up the limits for the clip */
my_rectangle.MinX = minX;
my_rectangle.MinY = minY;
my_rectangle.MaxX = maxX;
my_rectangle.MaxY = maxY;

/* get a new region and OR in the limits. */
if (NULL != (new_region = IGraphics->NewRegion()))
{
if (FALSE == IGraphics->OrRectRegion(new_region, &my_rectangle))
{
IGraphics->DisposeRegion(new_region);
new_region = NULL;
}
}

/* Install the new region, and return any existing region.
** If the above allocation and region processing failed, then
** new_region will be NULL and no clip region will be installed.
*/
return(ILayers->InstallClipRegion(win->WLayer, new_region));
}

/*
** clipWindowToBorders()
** clip a window to its borders.
** The removed region is returned so that it may be re-installed later.
*/
struct Region *clipWindowToBorders(struct Window *win)
{
return(clipWindow(win, win->BorderLeft, win->BorderTop,
win->Width - win->BorderRight - 1, win->Height - win->BorderBottom - 1));
}

/*
** Wait for the user to select the close gadget.
*/
VOID wait_for_close(struct Window *win)
{
struct IntuiMessage *msg;
BOOL done;

done = FALSE;

while (FALSE == done)
{
/* we only have one signal bit, so we do not have to check which
** bit broke the Wait().
*/
IExec->Wait(1L << win->UserPort->mp_SigBit);

while ( (FALSE == done) &&
(NULL != (msg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort))))
{
/* use a switch statement if looking for multiple event types */
if (msg->Class == IDCMP_CLOSEWINDOW)
done = TRUE;

IExec->ReplyMsg((struct Message *)msg);
}
}
}

/*
** Simple routine to blast all bits in a window with color three to show
** where the window is clipped. After a delay, flush back to color zero
** and refresh the window borders.
*/
VOID draw_in_window(struct Window *win, UBYTE *message)
{
IDOS->Printf("%s...", message);
IGraphics->SetRast(win->RPort, 3);
IDOS->Delay(200);
IGraphics->SetRast(win->RPort, 0);
IIntuition->RefreshWindowFrame(win);
IDOS->Printf("done\n");
}

/*
** Show drawing into an unclipped window, a window clipped to the
** borders and a window clipped to a random rectangle. It is possible
** to clip more complex shapes by AND'ing, OR'ing and exclusive-OR'ing
** regions and rectangles to build a user clip region.
**
** This example assumes that old regions are not going to be re-used,
** so it simply throws them away.
*/
VOID clip_test(struct Window *win)
{
struct Region *old_region;

draw_in_window(win,"Window with no clipping");

/* if the application has never installed a user clip region,
** then old_region will be NULL here. Otherwise, delete the
** old region (you could save it and re-install it later...)
*/
if (NULL != (old_region = clipWindowToBorders(win)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped to window borders");
unclipWindow(win);

/* here we know old_region will be NULL, as that is what we
** installed with unclipWindow()...
*/
if (NULL != (old_region = clipWindow(win,20,20,100,50)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped from (20,20) to (100,50)");
unclipWindow(win);

wait_for_close(win);
}

/*
** Open and close resources, call the test routine when ready.
*/
int main(int argc, char **argv)
{
struct Window *win;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL)
{
if (NULL != (win = IIntuition->OpenWindowTags(NULL,
WA_Width, MY_WIN_WIDTH,
WA_Height, MY_WIN_HEIGHT,
WA_IDCMP, IDCMP_CLOSEWINDOW,
WA_CloseGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
TAG_END)))
{
clip_test(win);

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the [[Graphics Library]] functions related to regions. See the SDK for details on each function call.

{| class="wikitable"
! Routine
! Description
|-
| LockLayerRom()
| Same as LockLayer(), from the [[Layers Library]].
|-
| UnlockLayerRom()
| Release LockLayerRom() lock.
|-
| AttemptLockLayerRom()
| Lock layer only if it is immediately available.
|-
| NewRegion()
| Create a new, empty region.
|-
| DisposeRegion()
| Dispose of an existing region and its rectangles.
|-
| AndRectRegion()
| ''And'' a rectangle into a region.
|-
| OrRectRegion()
| ''Or'' a rectangle into a region.
|-
| XorRectRegion()
| ''Exclusive-or'' a rectangle into a region.
|-
| ClearRectRegion()
| Clear a rectangular portion of a region.
|-
| AndRegionRegion()
| ''And'' two regions together.
|-
| OrRegionRegion()
| ''Or'' two regions together.
|-
| XorRegionRegion()
| ''Exclusive-or'' two regions together.
|-
| ClearRegion()
| Clear a region.
|}

Graphics Regions

2017-11-10T10:23:43Z

Daniel Jedlicka: Regions Example: a few more corrections and updates

== Regions ==

Regions allow the application to install clipping rectangles into layers. A clipping rectangle is a rectangular area into which the graphics routines will draw. All drawing that would fall outside of that rectangular area is clipped (not rendered).

User clipping regions are linked lists of clipping rectangles created by an application program through the graphics library routines described below. By combining together various clipping rectangles, any arbitrary clipping shape can be created. Once the region is set up, you use the layers library call InstallClipRegion() to make the clipping region active in a layer.

Regions are safe to use with layers created by Intuition (i.e., windows).

The application can selectively update a custom-shaped part of a layer without disturbing any of the other layers that might be present.

{{Note|title=Never Modify the DamageList of a Layer Directly|text=Use the routine InstallClipRegion() to add clipping to the layer. The regions installed by InstallClipRegion() are independent of the layer's DamageList and use of user clipping regions will not interfere with optimized window refreshing.}}

{{Note|title=Do Not Modify A Region After It Has Been Added|text=After a region has been added with InstallClipRegion(), the program may not modify it until the region has been removed with another call to InstallClipRegion().}}

=== Creating and Deleting Regions ===

You allocate a Region data structure with the NewRegion() call.

<syntaxhighlight>
struct Region *NewRegion( VOID );
</syntaxhighlight>

The NewRegion() function allocates and initializes a Region structure that has no drawable areas defined in it. If the application draws through a new region, nothing will be drawn as the region is empty. The application must add rectangles to the region before any graphics will appear.

Use DisposeRegion() to free the Region structure when you are done with it.

<syntaxhighlight>
VOID DisposeRegion( struct Region *region );
</syntaxhighlight>

DisposeRegion() returns all memory associated with a region to the system and deallocates all rectangles that have been linked to it.

{{Note|title=Don't Forget to Free Your Rectangles|text=All of the functions that add rectangles to the region make copies of the rectangles. If the program allocates a rectangle, then adds it to a region, it still must deallocate the rectangle. The call to DisposeRegion() will not deallocate rectangles ''explicitly allocated'' by the application.}}

=== Installing Regions ===

Use the function InstallClipRegion() to install the region.

<syntaxhighlight>
struct Region *InstallClipRegion( struct Layer *layer, struct Region *region );
</syntaxhighlight>

This installs a transparent clipping region to a layer. All subsequent graphics calls will be clipped to this region. The region must be removed with a second call to InstallClipRegion() before removing the layer.

<syntaxhighlight>
/*
** Sample installation and removal of a clipping region
*/
register struct Region *new_region ;
register struct Region *old_region ;

/* If the application owns the layer and has not installed a region,
** old_region will return NULL here.
*/
old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

/* draw into the layer or window */

if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
{
/* throw the used region away. This region could be saved and
** used again later, if desired by the application.
*/
ILayers->DisposeRegion(new_region) ;
}
</syntaxhighlight>

{{Note|title=A Warning About InstallClipRegion()|text=The program must not call InstallClipRegion() inside of a Begin/EndRefresh() or Begin/EndUpdate() pair. The following code segment shows how to modify the user clipping region when using these calls. See the Autodoc for BeginRefresh() for more details.}}

<syntaxhighlight>
struct Region *new_region ;
struct Region *old_region ;

/* you have to have already setup the new_region and old_region */

IIntuition->BeginRefresh(window);
/* draw through the damage list */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the damage list and the new_region */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

/* put back the old region */
new_region = ILayers->InstallClipRegion(win->WLayer, old_region);

IIntuition->BeginRefresh(window);
IIntuition->EndRefresh(window, TRUE); /* remove the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the new_region only into the layer or window */
IIntuition->EndRefresh(window, FALSE);

/* finally get rid of the new region, old_region still installed */
if (NULL != (new_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
ILayers->DisposeRegion(new_region) ;
</syntaxhighlight>

=== Changing a Region ===

Regions may be modified by performing logical operations with rectangles, or with other regions.

{{Note|title=Reuse Your Rectangles|text=In all of the rectangle and region routines the clipping rectangle is copied into the region. This means that a single clipping rectangle (Rectangle structure) may be used many times by simply changing the ''x'' and ''y'' values. The application need ''not'' create a new instance of the Rectangle structure for each rectangle added to a region.}}

For instance:

<syntaxhighlight>
extern struct Region *RowRegion; /* created elsewhere */

int16 ktr;
struct Rectangle rect;

for (ktr = 1; ktr < 6; ktr++)
{
rect.MinX = 50;
rect.MaxX = 315;
rect.MinY = (ktr * 10) - 5;
rect.MaxY = (ktr * 10);

if (!ILayers->OrRectRegion(RowRegion, &rect))
clean_exit(RETURN_WARN);
}
</syntaxhighlight>

==== Rectangles and Regions ====

There are four functions for changing a region through logical operations with a rectangle.

<syntaxhighlight>
BOOL OrRectRegion ( struct Region *region, struct Rectangle *rectangle );
VOID AndRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL XorRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL ClearRectRegion( struct Region *region, struct Rectangle *rectangle );
</syntaxhighlight>

OrRectRegion() modifies a region structure by '''OR''''ing a clipping rectangle into the region. When the application draws through this region (assuming that the region was originally empty), only the pixels within the clipping rectangle will be affected. If the region already has drawable areas, they will still exist, this rectangle is added to the drawable area.

AndRectRegion() modifies the region structure by '''AND''''ing a clipping rectangle into the region. Only those pixels that were already drawable and within the rectangle will remain drawable, any that are outside of it will be clipped in future.

XorRectRegion() applies the rectangle to the region in an '''exclusive-or''' mode. Within the given rectangle, any areas that were drawable become clipped, any areas that were clipped become drawable. Areas outside of the rectangle are not affected.

ClearRectRegion() clears the rectangle from the region. Within the given rectangle, any areas that were drawable become clipped. Areas outside of the rectangle are not affected.

==== Regions and Regions ====

As with rectangles and regions, there are four layers library functions for combining regions with regions:

<syntaxhighlight>
BOOL AndRegionRegion( struct Region *srcRegion, struct Region *destRegion );
BOOL OrRegionRegion ( struct Region *srcRegion, struct Region *destRegion );
BOOL XorRegionRegion( struct Region *srcRegion, struct Region *destRegion );
VOID ClearRegion ( struct Region *region );
</syntaxhighlight>

AndRegionRegion() performs a logical '''AND''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever the regions drawable areas overlap. That is, where there are drawable areas in both region 1 '''AND''' region 2, there will be drawable areas left in the result region.

OrRegionRegion() performs a logical '''OR''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region.

XorRegionRegion() performs a logical '''exclusive-or''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region but not both. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region. But where there are drawable areas in both region 1 '''AND''' region 2, there will ''not'' be drawable areas left in the result region.

ClearRegion() puts the region back to the same state it was in when the region was created with NewRegion(), that is, no areas are drawable.

=== Regions Example ===

The following example shows the use of the [[Layers Library]] call InstallClipRegion(), as well as simple use of the [[Graphics Library]] regions functions.

<syntaxhighlight>
/* clipping.c */

/* Force use of new variable names to help prevent errors */
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/intuitionbase.h>
#include <graphics/displayinfo.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/layers.h>

#define MY_WIN_WIDTH (300)
#define MY_WIN_HEIGHT (100)

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

/*
** unclipWindow()
**
** Used to remove a clipping region installed by clipWindow() or
** clipWindowToBorders(), disposing of the installed region and
** reinstalling the region removed.
*/
void unclipWindow(struct Window *win)
{
struct Region *old_region;

/* Remove any old region by installing a NULL region,
** then dispose of the old region if one was installed.
*/
if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, NULL)))
IGraphics->DisposeRegion(old_region);
}

/*
** clipWindow()
** Clip a window to a specified rectangle (given by upper left and
** lower right corner.) the removed region is returned so that it
** may be re-installed later.
*/
struct Region *clipWindow(struct Window *win,
LONG minX, LONG minY, LONG maxX, LONG maxY)
{
struct Region *new_region;
struct Rectangle my_rectangle;

/* set up the limits for the clip */
my_rectangle.MinX = minX;
my_rectangle.MinY = minY;
my_rectangle.MaxX = maxX;
my_rectangle.MaxY = maxY;

/* get a new region and OR in the limits. */
if (NULL != (new_region = IGraphics->NewRegion()))
{
if (FALSE == IGraphics->OrRectRegion(new_region, &my_rectangle))
{
IGraphics->DisposeRegion(new_region);
new_region = NULL;
}
}

/* Install the new region, and return any existing region.
** If the above allocation and region processing failed, then
** new_region will be NULL and no clip region will be installed.
*/
return(ILayers->InstallClipRegion(win->WLayer, new_region));
}

/*
** clipWindowToBorders()
** clip a window to its borders.
** The removed region is returned so that it may be re-installed later.
*/
struct Region *clipWindowToBorders(struct Window *win)
{
return(clipWindow(win, win->BorderLeft, win->BorderTop,
win->Width - win->BorderRight - 1, win->Height - win->BorderBottom - 1));
}

/*
** Wait for the user to select the close gadget.
*/
VOID wait_for_close(struct Window *win)
{
struct IntuiMessage *msg;
BOOL done;

done = FALSE;

while (FALSE == done)
{
/* we only have one signal bit, so we do not have to check which
** bit broke the Wait().
*/
IExec->Wait(1L << win->UserPort->mp_SigBit);

while ( (FALSE == done) &&
(NULL != (msg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort))))
{
/* use a switch statement if looking for multiple event types */
if (msg->Class == IDCMP_CLOSEWINDOW)
done = TRUE;

IExec->ReplyMsg((struct Message *)msg);
}
}
}

/*
** Simple routine to blast all bits in a window with color three to show
** where the window is clipped. After a delay, flush back to color zero
** and refresh the window borders.
*/
VOID draw_in_window(struct Window *win, UBYTE *message)
{
IDOS->Printf("%s...", message);
IGraphics->SetRast(win->RPort, 3);
IDOS->Delay(200);
IGraphics->SetRast(win->RPort, 0);
IIntuition->RefreshWindowFrame(win);
IDOS->Printf("done\n");
}

/*
** Show drawing into an unclipped window, a window clipped to the
** borders and a window clipped to a random rectangle. It is possible
** to clip more complex shapes by AND'ing, OR'ing and exclusive-OR'ing
** regions and rectangles to build a user clip region.
**
** This example assumes that old regions are not going to be re-used,
** so it simply throws them away.
*/
VOID clip_test(struct Window *win)
{
struct Region *old_region;

draw_in_window(win,"Window with no clipping");

/* if the application has never installed a user clip region,
** then old_region will be NULL here. Otherwise, delete the
** old region (you could save it and re-install it later...)
*/
if (NULL != (old_region = clipWindowToBorders(win)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped to window borders");
unclipWindow(win);

/* here we know old_region will be NULL, as that is what we
** installed with unclipWindow()...
*/
if (NULL != (old_region = clipWindow(win,20,20,100,50)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped from (20,20) to (100,50)");
unclipWindow(win);

wait_for_close(win);
}

/*
** Open and close resources, call the test routine when ready.
*/
int main(int argc, char **argv)
{
struct Window *win;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL)
{
if (NULL != (win = IIntuition->OpenWindowTags(NULL,
WA_Width, MY_WIN_WIDTH,
WA_Height, MY_WIN_HEIGHT,
WA_IDCMP, IDCMP_CLOSEWINDOW,
WA_CloseGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
TAG_END)))
{
clip_test(win);

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the graphics library functions related to regions. See the SDK for details on each function call.

{| class="wikitable"
! Routine
! Description
|-
| LockLayerRom()
| Same as LockLayer(), from layers library.
|-
| UnlockLayerRom()
| Release LockLayerRom() lock.
|-
| AttemptLockLayerRom()
| Lock layer only if it is immediately available.
|-
| NewRegion()
| Create a new, empty region.
|-
| DisposeRegion()
| Dispose of an existing region and its rectangles.
|-
| AndRectRegion()
| ''And'' a rectangle into a region.
|-
| OrRectRegion()
| ''Or'' a rectangle into a region.
|-
| XorRectRegion()
| ''Exclusive-or'' a rectangle into a region.
|-
| ClearRectRegion()
| Clear a rectangular portion of a region.
|-
| AndRegionRegion()
| ''And'' two regions together.
|-
| OrRegionRegion()
| ''Or'' two regions together.
|-
| XorRegionRegion()
| ''Exclusive-or'' two regions together.
|-
| ClearRegion()
| Clear a region.
|}

Graphics Regions

2017-11-10T10:02:40Z

Daniel Jedlicka: Regions Example: code corrections by Doug Stastny

== Regions ==

Regions allow the application to install clipping rectangles into layers. A clipping rectangle is a rectangular area into which the graphics routines will draw. All drawing that would fall outside of that rectangular area is clipped (not rendered).

User clipping regions are linked lists of clipping rectangles created by an application program through the graphics library routines described below. By combining together various clipping rectangles, any arbitrary clipping shape can be created. Once the region is set up, you use the layers library call InstallClipRegion() to make the clipping region active in a layer.

Regions are safe to use with layers created by Intuition (i.e., windows).

The application can selectively update a custom-shaped part of a layer without disturbing any of the other layers that might be present.

{{Note|title=Never Modify the DamageList of a Layer Directly|text=Use the routine InstallClipRegion() to add clipping to the layer. The regions installed by InstallClipRegion() are independent of the layer's DamageList and use of user clipping regions will not interfere with optimized window refreshing.}}

{{Note|title=Do Not Modify A Region After It Has Been Added|text=After a region has been added with InstallClipRegion(), the program may not modify it until the region has been removed with another call to InstallClipRegion().}}

=== Creating and Deleting Regions ===

You allocate a Region data structure with the NewRegion() call.

<syntaxhighlight>
struct Region *NewRegion( VOID );
</syntaxhighlight>

The NewRegion() function allocates and initializes a Region structure that has no drawable areas defined in it. If the application draws through a new region, nothing will be drawn as the region is empty. The application must add rectangles to the region before any graphics will appear.

Use DisposeRegion() to free the Region structure when you are done with it.

<syntaxhighlight>
VOID DisposeRegion( struct Region *region );
</syntaxhighlight>

DisposeRegion() returns all memory associated with a region to the system and deallocates all rectangles that have been linked to it.

{{Note|title=Don't Forget to Free Your Rectangles|text=All of the functions that add rectangles to the region make copies of the rectangles. If the program allocates a rectangle, then adds it to a region, it still must deallocate the rectangle. The call to DisposeRegion() will not deallocate rectangles ''explicitly allocated'' by the application.}}

=== Installing Regions ===

Use the function InstallClipRegion() to install the region.

<syntaxhighlight>
struct Region *InstallClipRegion( struct Layer *layer, struct Region *region );
</syntaxhighlight>

This installs a transparent clipping region to a layer. All subsequent graphics calls will be clipped to this region. The region must be removed with a second call to InstallClipRegion() before removing the layer.

<syntaxhighlight>
/*
** Sample installation and removal of a clipping region
*/
register struct Region *new_region ;
register struct Region *old_region ;

/* If the application owns the layer and has not installed a region,
** old_region will return NULL here.
*/
old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

/* draw into the layer or window */

if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
{
/* throw the used region away. This region could be saved and
** used again later, if desired by the application.
*/
ILayers->DisposeRegion(new_region) ;
}
</syntaxhighlight>

{{Note|title=A Warning About InstallClipRegion()|text=The program must not call InstallClipRegion() inside of a Begin/EndRefresh() or Begin/EndUpdate() pair. The following code segment shows how to modify the user clipping region when using these calls. See the Autodoc for BeginRefresh() for more details.}}

<syntaxhighlight>
struct Region *new_region ;
struct Region *old_region ;

/* you have to have already setup the new_region and old_region */

IIntuition->BeginRefresh(window);
/* draw through the damage list */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the damage list and the new_region */
/* into the layer or window */
IIntuition->EndRefresh(window, FALSE); /* keep the damage list */

/* put back the old region */
new_region = ILayers->InstallClipRegion(win->WLayer, old_region);

IIntuition->BeginRefresh(window);
IIntuition->EndRefresh(window, TRUE); /* remove the damage list */

old_region = ILayers->InstallClipRegion(win->WLayer, new_region);

IIntuition->BeginRefresh(window);
/* draw through the new_region only into the layer or window */
IIntuition->EndRefresh(window, FALSE);

/* finally get rid of the new region, old_region still installed */
if (NULL != (new_region = ILayers->InstallClipRegion(win->WLayer, old_region)))
ILayers->DisposeRegion(new_region) ;
</syntaxhighlight>

=== Changing a Region ===

Regions may be modified by performing logical operations with rectangles, or with other regions.

{{Note|title=Reuse Your Rectangles|text=In all of the rectangle and region routines the clipping rectangle is copied into the region. This means that a single clipping rectangle (Rectangle structure) may be used many times by simply changing the ''x'' and ''y'' values. The application need ''not'' create a new instance of the Rectangle structure for each rectangle added to a region.}}

For instance:

<syntaxhighlight>
extern struct Region *RowRegion; /* created elsewhere */

int16 ktr;
struct Rectangle rect;

for (ktr = 1; ktr < 6; ktr++)
{
rect.MinX = 50;
rect.MaxX = 315;
rect.MinY = (ktr * 10) - 5;
rect.MaxY = (ktr * 10);

if (!ILayers->OrRectRegion(RowRegion, &rect))
clean_exit(RETURN_WARN);
}
</syntaxhighlight>

==== Rectangles and Regions ====

There are four functions for changing a region through logical operations with a rectangle.

<syntaxhighlight>
BOOL OrRectRegion ( struct Region *region, struct Rectangle *rectangle );
VOID AndRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL XorRectRegion ( struct Region *region, struct Rectangle *rectangle );
BOOL ClearRectRegion( struct Region *region, struct Rectangle *rectangle );
</syntaxhighlight>

OrRectRegion() modifies a region structure by '''OR''''ing a clipping rectangle into the region. When the application draws through this region (assuming that the region was originally empty), only the pixels within the clipping rectangle will be affected. If the region already has drawable areas, they will still exist, this rectangle is added to the drawable area.

AndRectRegion() modifies the region structure by '''AND''''ing a clipping rectangle into the region. Only those pixels that were already drawable and within the rectangle will remain drawable, any that are outside of it will be clipped in future.

XorRectRegion() applies the rectangle to the region in an '''exclusive-or''' mode. Within the given rectangle, any areas that were drawable become clipped, any areas that were clipped become drawable. Areas outside of the rectangle are not affected.

ClearRectRegion() clears the rectangle from the region. Within the given rectangle, any areas that were drawable become clipped. Areas outside of the rectangle are not affected.

==== Regions and Regions ====

As with rectangles and regions, there are four layers library functions for combining regions with regions:

<syntaxhighlight>
BOOL AndRegionRegion( struct Region *srcRegion, struct Region *destRegion );
BOOL OrRegionRegion ( struct Region *srcRegion, struct Region *destRegion );
BOOL XorRegionRegion( struct Region *srcRegion, struct Region *destRegion );
VOID ClearRegion ( struct Region *region );
</syntaxhighlight>

AndRegionRegion() performs a logical '''AND''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever the regions drawable areas overlap. That is, where there are drawable areas in both region 1 '''AND''' region 2, there will be drawable areas left in the result region.

OrRegionRegion() performs a logical '''OR''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region.

XorRegionRegion() performs a logical '''exclusive-or''' operation on the two regions, leaving the result in the second region. The operation leaves drawable areas wherever there are drawable areas in either region but not both. That is, where there are drawable areas in either region 1 '''OR''' region 2, there will be drawable areas left in the result region. But where there are drawable areas in both region 1 '''AND''' region 2, there will ''not'' be drawable areas left in the result region.

ClearRegion() puts the region back to the same state it was in when the region was created with NewRegion(), that is, no areas are drawable.

=== Regions Example ===

The following example shows the use of the layers library call InstallClipRegion(), as well as simple use of the graphics library regions functions.

<syntaxhighlight>
/* clipping.c */

/* Force use of new variable names to help prevent errors */
#define INTUI_V36_NAMES_ONLY

#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/intuitionbase.h>
#include <graphics/displayinfo.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>
#include <proto/graphics.h>
#include <proto/layers.h>

#define MY_WIN_WIDTH (300)
#define MY_WIN_HEIGHT (100)

struct IntuitionIFace *IIntuition;
struct GraphicsIFace *IGraphics;
struct LayersIFace *ILayers;

/*
** unclipWindow()
**
** Used to remove a clipping region installed by clipWindow() or
** clipWindowToBorders(), disposing of the installed region and
** reinstalling the region removed.
*/
void unclipWindow(struct Window *win)
{
struct Region *old_region;

/* Remove any old region by installing a NULL region,
** then dispose of the old region if one was installed.
*/
if (NULL != (old_region = ILayers->InstallClipRegion(win->WLayer, NULL)))
IGraphics->DisposeRegion(old_region);
}

/*
** clipWindow()
** Clip a window to a specified rectangle (given by upper left and
** lower right corner.) the removed region is returned so that it
** may be re-installed later.
*/
struct Region *clipWindow(struct Window *win,
LONG minX, LONG minY, LONG maxX, LONG maxY)
{
struct Region *new_region;
struct Rectangle my_rectangle;

/* set up the limits for the clip */
my_rectangle.MinX = minX;
my_rectangle.MinY = minY;
my_rectangle.MaxX = maxX;
my_rectangle.MaxY = maxY;

/* get a new region and OR in the limits. */
if (NULL != (new_region = IGraphics->NewRegion()))
{
if (FALSE == IGraphics->OrRectRegion(new_region, &my_rectangle))
{
IGraphics->DisposeRegion(new_region);
new_region = NULL;
}
}

/* Install the new region, and return any existing region.
** If the above allocation and region processing failed, then
** new_region will be NULL and no clip region will be installed.
*/
return(ILayers->InstallClipRegion(win->WLayer, new_region));
}

/*
** clipWindowToBorders()
** clip a window to its borders.
** The removed region is returned so that it may be re-installed later.
*/
struct Region *clipWindowToBorders(struct Window *win)
{
return(clipWindow(win, win->BorderLeft, win->BorderTop,
win->Width - win->BorderRight - 1, win->Height - win->BorderBottom - 1));
}

/*
** Wait for the user to select the close gadget.
*/
VOID wait_for_close(struct Window *win)
{
struct IntuiMessage *msg;
SHORT done;

done = FALSE;
while (FALSE == done)
{
/* we only have one signal bit, so we do not have to check which
** bit broke the Wait().
*/
IExec->Wait(1L << win->UserPort->mp_SigBit);

while ( (FALSE == done) &&
(NULL != (msg = (struct IntuiMessage *)IExec->GetMsg(win->UserPort))))
{
/* use a switch statement if looking for multiple event types */
if (msg->Class == IDCMP_CLOSEWINDOW)
done = TRUE;

IExec->ReplyMsg((struct Message *)msg);
}
}
}

/*
** Simple routine to blast all bits in a window with color three to show
** where the window is clipped. After a delay, flush back to color zero
** and refresh the window borders.
*/
VOID draw_in_window(struct Window *win, UBYTE *message)
{
IDOS->Printf("%s...", message);
IGraphics->SetRast(win->RPort, 3);
IDOS->Delay(200);
IGraphics->SetRast(win->RPort, 0);
IIntuition->RefreshWindowFrame(win);
IDOS->Printf("done\n");
}

/*
** Show drawing into an unclipped window, a window clipped to the
** borders and a window clipped to a random rectangle. It is possible
** to clip more complex shapes by AND'ing, OR'ing and exclusive-OR'ing
** regions and rectangles to build a user clip region.
**
** This example assumes that old regions are not going to be re-used,
** so it simply throws them away.
*/
VOID clip_test(struct Window *win)
{
struct Region *old_region;

draw_in_window(win,"Window with no clipping");

/* if the application has never installed a user clip region,
** then old_region will be NULL here. Otherwise, delete the
** old region (you could save it and re-install it later...)
*/
if (NULL != (old_region = clipWindowToBorders(win)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped to window borders");
unclipWindow(win);

/* here we know old_region will be NULL, as that is what we
** installed with unclipWindow()...
*/
if (NULL != (old_region = clipWindow(win,20,20,100,50)))
IGraphics->DisposeRegion(old_region);
draw_in_window(win,"Window clipped from (20,20) to (100,50)");
unclipWindow(win);

wait_for_close(win);
}

/*
** Open and close resources, call the test routine when ready.
*/
int main(int argc, char **argv)
{
struct Window *win;

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);

struct Library *LayersBase = IExec->OpenLibrary("layers.library", 50);
ILayers = (struct LayersIFace*)IExec->GetInterface(LayersBase, "main", 1, NULL);

if (IIntuition != NULL && IGraphics != NULL && ILayers != NULL)
{
if (NULL != (win =IIntuition->OpenWindowTags(NULL,
WA_Width, MY_WIN_WIDTH,
WA_Height, MY_WIN_HEIGHT,
WA_IDCMP, IDCMP_CLOSEWINDOW,
WA_CloseGadget, TRUE,
WA_DragBar, TRUE,
WA_Activate, TRUE,
TAG_END)))
{
clip_test(win);

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface*)ILayers);
IExec->CloseLibrary(LayersBase);

IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary(GfxBase);

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the graphics library functions related to regions. See the SDK for details on each function call.

{| class="wikitable"
! Routine
! Description
|-
| LockLayerRom()
| Same as LockLayer(), from layers library.
|-
| UnlockLayerRom()
| Release LockLayerRom() lock.
|-
| AttemptLockLayerRom()
| Lock layer only if it is immediately available.
|-
| NewRegion()
| Create a new, empty region.
|-
| DisposeRegion()
| Dispose of an existing region and its rectangles.
|-
| AndRectRegion()
| ''And'' a rectangle into a region.
|-
| OrRectRegion()
| ''Or'' a rectangle into a region.
|-
| XorRectRegion()
| ''Exclusive-or'' a rectangle into a region.
|-
| ClearRectRegion()
| Clear a rectangular portion of a region.
|-
| AndRegionRegion()
| ''And'' two regions together.
|-
| OrRegionRegion()
| ''Or'' two regions together.
|-
| XorRegionRegion()
| ''Exclusive-or'' two regions together.
|-
| ClearRegion()
| Clear a region.
|}

Application Library

2017-10-25T13:52:28Z

Daniel Jedlicka: /* Message Handling */

== Introduction ==

The Application Library is a multipurpose auxiliary library that provides various functions related to the development and use of applications. The very concept of ''application'' is a relatively recent addition to AmigaOS. Before, the system only distinguished between different types of program on a very low level, seeing them as either [[Exec_Tasks|tasks]] or [[AmigaDOS_Data_Structures#Process_Data_Structures|processes]]. This distinction might have been useful in the past when tasks (which require fewer resources in return for not being able to access DOS functions) could improve system performance. But it can hardly make a difference on today’s hardware so the trade-offs are no longer worth it. Nowadays it makes more sense to discriminate between programs that operate without the user even noticing (e.g. drivers, handlers, filesystems and other ''background services''), and genuine full-blown ''applications'' with [[UI_Style_Guide_Glossary#GUI|GUI]] and all.

AmigaOS alone cannot make such a distinction: it uses the Application Library as a mediator through which applications introduce themselves to the system. This process is called [[#Registering the Application|application registration]], during which the application receives a [[#Application Identifiers|unique identifier]] and is added to a public list among other applications. Once registered, the application can make use of the library’s many features:

* It can send/receive messages to/from other registered applications. The library supports a set of common [[#Control Messages|control messages]] (commands) such as those telling an application to quit, iconify or bring its window to front. But it also allows [[#Custom Messages|custom messages]] designed for an application’s particular needs; in this respect the Application Library provides an alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]] control.

* It can turn into a “watchdog” and get notified when other applications register.

* It can use [[PrefsObjects]], an XML-based, object-oriented system for handling program preferences. Before AmigaOS 4.x no real standard existed for storing preferences: some developers used icon tooltypes, some used proprietary formats, text or binary. The Application Library provides a format that is human-readable and easily editable in a simple text editor; that is comprehensive enough to cover even very complex settings structures; and that is fully controllable via the library, without the need to laboriously implement data parsing and verification.

* It can notify the user about, for example, completed tasks via automatic [[#Pop-up Notifications (Ringhio Messages)|pop-up messages]]. These represent a practical, less obtrusive alternative to traditional requesters.

* It can easily create and manage lists of recently-used documents.

* It can register as a ''unique application'', preventing other instances of itself from running.

* It can show its icon or display the current program state in taskbar-like applications, such as AmiDock.

* It can control the behaviour of screen-blankers. Applications that don’t want to be disturbed may prevent the blanker from kicking in, or tell other applications to “keep quiet”.

=== Frequently Asked Questions ===

{| class="wikitable"
|-
|''Q: Should my programs register with the Application Library?''
|A: Yes, that would make a lot of sense. Apart from access to the handy features mentioned above, the implementation of certain library features may improve the behaviour of your application within the AmigaOS ecosystem.
|-
|''Q: After registering with the library, will my application become controlled by the OS or by other applications?''
|A: No. The registration process alone does not turn on any features. There is a recommendation to allow a [[#Minimum Application Library Support|minimum degree of control]], but in the end it is the programmer who decides what functionality offered by the library will be provided and supported in his/her application. That also includes the scope of external control: if you don't want your application to be controlled beyond a certain limit, your code will simply not react to certain incoming [[#Control Messages|control messages]].
|-
|''Q: Doesn't the Application Library duplicate functionality already present in commodities?''
|A: No. The only similarity between the two is that programs register with some system library, which then acts as a control centre. [[Commodities_Exchange_Library|Commodities]] provide a way to install custom input handlers into the [[Input_Device|Input Device]]'s event stream. The Application Library's field and scope of operation is completely different (and much wider).
|-
|''Q: Why is this a library? Wouldn't it be wiser to implement it as a class, like MUI does it?''
|A: This would tie the functionality to the object-oriented (BOOPSI) API – applications designed using [[GUI_Programming#The_Two_Frameworks|other APIs or toolkits]] would not be able to use it.
|-
|''Q: Can a program be registered both as an application and as a commodity?''
|A: Yes, that's possible – although few programs would probably benefit from that. Exceptions include application managers and taskbars (e.g. AmiDock), which may need to control other applications and, at the same time, behave like a commodity.
|-
|''Q: Being XML-based, do the PrefsObjects introduce any overhead to the operating system?''
|A: Hardly any. The [[PrefsObjects]] .xml preference files are, typically, only read when the application starts and written at user request, so there is minimum overhead involved. Accessing the prefs file during program runtime doesn't put any strain on the OS either, as the Application Library caches the file in a pre-parsed format in memory.
|}

=== Minimum Application Library Support ===

In the foreseeable future, AmigaOS will feature an application manager to control running applications. (A third-party solution called [http://wiki.amiga.org/index.php?title=Exchanger Exchanger] is already available.) The idea is to provide a single, universal control point for both commodities and applications. In order to allow easy, consistent and predictable program control, developers are encouraged to [[#Registering the Application|register their applications]] and implement the following suggested minimum Application Library support:

* Provide a short [[#Description|description]] for a better identification of the application.
* Tell the OS whether your application supports iconification, that is, hiding/showing its GUI. If iconification is supported:
** set the REGAPP_HasIconifyFeature registration tag to TRUE;
** make the application respond to the [[#Control Messages|APPLIBMT_Hide and APPLIBMT_Unhide]] control messages;
** update the APPATTR_Hidden attribute accordingly each time your application iconifies or uniconifies.
* Allow the application to be shut down externally in a safe and graceful manner in reaction to the [[#Control Messages|APPLIBMT_Quit]] message.

A failure to implement this suggested minimum will mean that the application manager will be unable to control your application properly and consistently. This may cause confusion on the part of the users and degrade their AmigaOS experience.

== Library Opening Chores ==

{{Note|title=Note|text=Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2. This is due to changes in the Application Library API which had broken standard tag support until version 2 interfaces were introduced.}}

Just like other AmigaOS libraries, the Application Library must be opened before it is used. Further, at least one of its interfaces must be obtained, depending on the functionality you require. The Application Library has two interfaces, called “application” and “prefsobjects”. You always need to obtain the “application” interface because it provides access to most library functions including application registration. You’ll only need to open the “prefsobjects” interface if you intend to make use of the PrefsObjects preferences system.

<syntaxhighlight>
struct Library *ApplicationBase = NULL;
struct ApplicationIFace *IApplication = NULL;
struct PrefsObjectsIFace *IPrefsObjects = NULL;

if ( (ApplicationBase = IExec->OpenLibrary("application.library", 52)) )
{
IApplication = (struct ApplicationIFace *) IExec->GetInterface(ApplicationBase,
"application", 2, NULL);
IPrefsObjects = (struct PrefsObjectsIFace *) IExec->GetInterface(ApplicationBase,
"prefsobjects", 2, NULL);
}

if ( !ApplicationBase || !IApplication || !IPrefsObjects )
{
/* handle library opening error */
}
</syntaxhighlight>

Note that there is no interface called “main” like older, single-interface libraries have. The number in the GetInterface() call above refers to the version of the interface. Library interfaces are not backwards or forwards compatible so they must be specified precisely. '''Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2.''' This is due to certain changes in the Application Library API.

When your application has run its course, don’t forget to clean up and close both the library and its interface(s):

<syntaxhighlight>
IExec->DropInterface((struct Interface *)IPrefsObjects);
IExec->DropInterface((struct Interface *)IApplication);
IExec->CloseLibrary(ApplicationBase);
</syntaxhighlight>

== Registering the Application ==

Application registration is a simple process during which a program informs AmigaOS that it should be treated as an application, and provides some basic information about itself: the program name, an associated URL address, or a short description. Also, certain application-related properties can be set at registration time (although some of these may be provided or changed later). Registration typically takes place at program startup; unregistration is normally done at the end of program runtime.

*hint* Avoid using the _ underscore character in the registered name. These may cause "charsetconvert" errors when the system boots up later.

=== Application Identifiers ===

A successfully registered application receives a numeric identifier, which in this documentation will be referred to as ''appID''. The identifier is public: any registered application can obtain another application’s appID (see [[#Finding Applications|Finding Applications]] below) and use it to communicate with the respective application. AppIDs are unique integer numbers: the library generates them incrementally on a per-registration basis. They are never assigned again during the same AmigaOS session, which prevents programs from incidentally addressing the wrong application after the original appID holder unregisters.

Apart from the numeric appID an application can be referred to by its name (that is, a string-type identifier). As programs can get registered in an arbitrary order (and the same application will have a different appID each time), it is the name identifier that other applications must use to retrieve the correct appID. To construct a unique name, the Application Library uses a special naming scheme that combines:

* the application name;
* an instance count (if more than one instance of the same application is started);
* a URL identifier (for example, the domain name of the application’s homepage – optional).

The same naming scheme is used by the library’s PrefsObjects system to create the name of the preferences file.

=== Registration Functions ===

Now let’s say we have a program, a media player called Audio Monster created by the fictitious software company SuperCoders, Inc. The piece of C code to handle its registration (and unregistration) might look like this:

<syntaxhighlight>
uint32 appID;

appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
TAG_END);

if (!appID)
{
/* report registration error and quit */
}

/*
do whatever your program does
*/

IApplication->UnregisterApplication(appID, NULL);
</syntaxhighlight>

Note that we’ve had to alter the application name to “AudioMonster”; it is because the Application Library doesn’t allow spaces in application names. According to the naming scheme (outlined in the previous section) the application will now become registered under the name “AudioMonster.supercoders.com”. (Should a previous instance of Audio Monster be already running, the library will automatically append an instance counter to the application name: the second instance will therefore be called “AudioMonster_1.supercoders.com”, the third will register as “AudioMonster_2.supercoders.com”, and so on.)

Also note that the URL identifier is just the domain name, i.e. without the “www.” part. The identifier is only used to distinguish between applications, not to access their homepages. The domain name is, therefore, sufficient; the resulting name identifier needn’t be long and quirky.

After calling UnregisterApplication() the program will be removed from the public list, and Application Library features will no longer be available.

== Application Attributes ==

An application is described by a set of ''attributes''. There are attributes that describe the application's properties or feature set, indicate its current state, or determine its behaviour. Some attributes are only specified at registration time and cannot be altered once they are set, while others can be changed freely (as long as the application remains registered, of course). The general recommendation is to specify at registration time all properties that are not going to change during program lifetime: i.e. define all "static" application features in one place.

=== Description ===
The REGAPP_Description tag, used in the registration example code above, tells the system what the application is all about. Although the description is an optional attribute, it is recommended to always provide it, as it will allow application manager or taskbar programs to provide meaningful information to the user. Keep the description short, matter-of-fact and serious.

The application description cannot be changed after registration.

=== Uniqueness ===
A program can register as a ''unique application'', thus only allowing one instance of itself to run. While the multitasking nature and tradition of AmigaOS would suggest not imposing such limits, there sometimes can be good reasons to do so. For example, the developer of the Audio Monster player might decide to make his/her program a unique application because the user would most likely gain nothing from playing several media files at the same time. Multiple program instances would only compete for screen space and system resources, possibly jeopardizing OS performance on lower-specification computers.

The following function call will register Audio Monster as a unique application:

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_UniqueApplication, TRUE,
TAG_END);
</syntaxhighlight>

If the user now tries to launch a second instance of the program, it will fail on RegisterApplication() and the library will send a [[#Special Messages|special message]] to the first instance informing it about the attempt. It is the developer’s responsibility to react to this message in a sensible way. Do not show error messages here: the user doesn’t need to know (or care) that the application is unique, so an error message would scold them for doing nothing wrong. The recommended behaviour is to bring the first instance to view and activate its window.

Quite logically, uniqueness is an attribute that cannot be changed after registration.

=== Feature Set / Control Scope ===
Different applications can implement different control features, and can be designed for a different scope of external control. For example, a text editor may respond to a [[#Control Messages|control message]] (command) that tells it to create a new, blank, unnamed document, whereas in a media player such a command would be best ignored. Similarly, a simple tool with no configuration capability would want to stay clear of messages that control program settings. It is always good manners to inform the system about the scope of control your application supports, as other applications may query about (and rely on) this information when sending control messages. Always set the following boolean tags to TRUE in the RegisterApplication() call if your application implements support for the respective feature (the default value is FALSE):

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_HasIconifyFeature
|The application supports iconification and uniconification.
|Set to TRUE if your application responds to the APPLIBMT_Hide and APPLIBMT_Unhide messages.
|-
|REGAPP_HasPrefsWindow
|The application has a dedicated Preferences (Settings) window.
|Set to TRUE if your application responds to the APPLIBMT_OpenPrefs message.
|-
|REGAPP_CanCreateNewDocs
|The application can create new documents (projects).
|Set to TRUE if your application responds to the APPLIBMT_NewBlankDoc message.
|-
|REGAPP_CanPrintDocs
|The application can print documents.
|Set to TRUE if your application responds to the APPLIBMT_PrintDoc message.
|}

These four attributes can be changed after registration.

=== Receiving Notifications ===

The Application Library can send certain notification messages that may be of interest to special-purpose programs like application managers, taskbars or screen blankers. If you are developing such a program, you may want to register for the following notifications:

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_AppNotifications
|Receive notifications about application registration/unregistration, icon type changes, GUI state changes (hidden/unhidden), and changes in the last used applications/documents list.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to application managers and taskbar-like programs.
|-
|REGAPP_BlankerNotifications
|Receive notifications concerning blanker activity.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to screen blankers.
|}

Other types of application should not normally ask to receive these notifications: they would only increase traffic along their input stream.

These two attributes can be changed after registration.

=== Changing Application Attributes ===

Certain attributes describe "dynamic" application properties and, as such, can be set or changed after registration. Some of these are ''state attributes'' that need to be updated each time your program changes state (shows/hides its GUI, or enters the game mode; see below in the table). Some are not really attributes but, rather, commands that invoke an application-related action.

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|APPATTR_AllowsBlanker
|Same as REGAPP_AllowsBlanker above.
|You may want to be able to enable/disable blanking dynamically during application runtime – this what the APPATTR_AllowsBlanker tag is for. For example, a presentation program may allow blankers while the presentation is being worked on, and disable them when the presentation is started.
|-
|APPATTR_AppOpenedDocument
|Adds a new entry to the application's Last Used Documents list.
|Set this tag each time your application has successfully opened a named document or project. The parameter to this tag is a pointer to the name string (i.e. a STRPTR).
|-
|APPATTR_AppNotifications APPATTR_BlankerNotifications
|Same as the two corresponding [[#Receiving Notifications|registration tags]] above.
|
|-
|APPATTR_CanCreateNewDocs APPATTR_CanPrintDocs APPATTR_HasIconifyFeature APPATTR_HasPrefsWindow
|Same as the four corresponding [[#Feature Set / Control Scope|registration tags]] above.
|Prefer setting these properties at registration time.
|-
|APPATTR_ClearLastUsedDocs
|Clears the application's list of last used documents.
|Set this tag to TRUE to clear the list. (Note that this is not really an attribute but, rather, a command.)
|-
|APPATTR_FlushPrefs
|
|
|-
|APPATTR_Hidden
|A boolean program-state attribute indicating whether the application is currently iconified (hidden) or not.
|Update this attribute each time your application GUI changes state, as application managers may query about (and rely on) this information.
|-
|APPATTR_IconType
|Changes the application icon type.
|
|-
|APPATTR_MainPrefsDict
|Allows changing the application's Prefs dictionary.
|
|-
|APPATTR_NeedsGameMode
|A boolean program-state attribute informing the system (and other applications) that the program is about to enter, or has left, the game mode.
|By the "game mode" we understand a mode in which an application doesn't want to be "disturbed" by other applications. It normally assumes full screen operation, and possibly taking over the audio system. Games or presentation programs are examples of applications that may want to implement the game mode, in which other programs are simply asked to “keep quiet”: not try to play sounds, open windows, requesters, etc. This feature assumes discipline and cooperation on the part of other applications; please use it moderately and only enter the game mode when it is really needed. Also note that setting APPATTR_NeedsGameMode to TRUE does not guarantee that other applications will comply.
|-
|APPATTR_SavePrefs
|Same as REGAPP_SavePrefs above.
|
|}

The function to set or change application attributes is SetApplicationAttrs(). It is very similar to SetAttrs() used in Intuition programming, only the first parameter is not a pointer to a BOOPSI object but an application identifier. The appID is followed by a tag list, so several attributes can be set at a time. The following example call will inform the system that the application has iconified (or otherwise hidden its GUI) and that the screen blanker can now come to front freely (assuming that the blanker was forbidden before for some reason). The result value indicates whether the call was successful or not:

<syntaxhighlight>
BOOL result;

result = IApplication->SetApplicationAttrs(appID,
APPATTR_Hidden, TRUE,
APPATTR_AllowsBlanker, TRUE,
TAG_END);
</syntaxhighlight>

== Finding Applications ==

The Application Library maintains a public list of all registered applications. Certain special-purpose programs – ''application managers'' – will read this list (also keeping track of all subsequent registrations and unregistrations) and offer some degree of control: display information about applications and/or send commands telling them to do something. Quite naturally, most programs will not (nor are they supposed to!) act as managers but a need to talk to another application may arise. How do you find it, then?

Finding an application basically means obtaining its appID: it is an identifier as well as a “contact address” for the library's messaging system. To do this you need to know at least one of the following:

* the application name, ie. the one under which it was registered via RegisterApplication();
* the application name identifier, ie. the unique combination of the application’s name, instance number (should there be more instances running) and URL identifier – see [[#Application Identifiers|Application identifiers]] above;
* the pathname pointing to the program file on disk, e.g. “Work:Utils/AudioMonster”.

Based on this information, the respective piece of code that will find our application in the system might look like this:

<syntaxhighlight>
uint32 appID;

/* if you only know the application name */
appID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster",
TAG_END);

/* if you know the application name identifier */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster.supercoders.com",
TAG_END);

/* if you specifically want to talk to the second running instance */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster_1.supercoders.com",
TAG_END);

/* if you know the pathname to the program file */
appID = IApplication->FindApplication(FINDAPP_FileName, "Work:Utils/AudioMonster",
TAG_END);
</syntaxhighlight>

Once you have obtained the appID you can start communicating with the respective application.

== Messaging ==

Messages are used extensively in AmigaOS: the inner workings of Exec or Intuition actually involve a good deal of message passing. But it’s not just the operating system that needs to communicate. Modern software applications often want to talk to other running applications. Regardless of whether this communication will, in real use, entail a simple command-driven action or an intricate exchange of data, AmigaOS provides the necessary means: inter-program communication is supported on the low level (through Exec Library’s [[Exec Messages and Ports|messages and ports]]) as well as on the high level (using the ARexx-language scripting features). The Application Library has introduced yet another means of communication, which can be seen as lying somewhere in between the two levels.

Provided that you know its appID, you can send messages to any running application that is ready to accept them. You can even send a message to all applications at once! Basic application control can be achieved via a set of [[#Control Messages|predefined messages]] that correspond to common program commands and functions (such as New, Open, Print, Iconify or Quit). But the library also supports [[#Custom Messages|custom messages]], thus allowing for more sophisticated control or information exchange. The extent and complexity of messaging is fully up to the programmer: your application will only send/receive messages that you will implement (it has already been mentioned in the [[#Frequently Asked Questions|Frequently Asked Questions]] section above that registration alone does not magically turn on any features).

Furthermore, apart from this “invisible”, abstract communication taking place between application ports, you can use the library to provide real and visible information in the form of pop-up notification messages. However, as these are different and not really within the scope of the Application Library messaging framework, they are dealt with in a [[#Pop-up Notifications (Ringhio Messages)|separate section]] of this document.

{{Note|Before we get any further with Application Library messages, it must be made clear that they should not be confused with the similarly-named ''AppMessages''. The latter are a completely different breed, governed by the Workbench Library. They represent a specific way of communication between the Workbench desktop environment and running applications. It’s strictly one-way communication because Workbench can send AppMessages to applications but applications cannot send AppMessages to Workbench. (If you want to learn more about the use of AppMessages, consult the [[Workbench Library|Workbench Library]] section of the AmigaOS documentation wiki).
}}

=== Data Structures ===

Rather than introduce yet another system for communication, the Application Library builds upon the existing [[Exec_Messages_and_Ports|Exec messaging framework]]. Programmers will, therefore, find working with Application Library messages rather familiar. For instance, the library uses data structures that are in fact extensions of the standard Exec message structure. Also, the usual procedure of [[Exec_Messages_and_Ports#Getting_a_Message|GetMsg()]] and [[Exec_Messages_and_Ports#Replying|ReplyMsg()]] takes place when processing incoming Application Library messages (see section [[#Message Handling|Message Handling]] below) – although the library implements its own method for [[#Sending Messages|sending messages]].

The following three structures are defined for carrying Application Library message data:

<syntaxhighlight>
struct ApplicationMsg
{
struct Message msg;
uint32 senderAppID; // the appID of the sender application
uint32 type; // identifies the type of message
};

struct ApplicationOpenPrintDocMsg
{
struct ApplicationMsg almsg;
STRPTR fileName;
};

struct ApplicationCustomMsg
{
struct ApplicationMsg almsg;
STRPTR customMsg;
};
</syntaxhighlight>

As you can see, structure ''ApplicationMsg'' contains a standard ''[[Exec_Messages_and_Ports#Messages|struct Message]]'', the other fields are used for Application Library-specific data. The other two structures are mere extensions of the basic one: ''ApplicationOpenPrintDocMsg'' is used by certain [[#Control Messages|control messages]] that require a pointer to a filename; the ''ApplicationCustomMsg'' structure is used for [[#Custom Messages|custom messages]].

Upon message arrival you identify the message by reading the “type” field of the respective data structure. Similarly, if you want to [[#Sending Messages|send a message]] to an application you specify it in the “type” field.

=== Control Messages ===

The Application Library allows registered applications to send messages that control other applications. There is a set of predefined messages (or rather, commands) that can be sent to a running application, telling it – for example – that it should come to front, quit, open a document, create a new one, and so on. As these actions are common program functions, the library offers a practical and easy-to-implement way to control applications externally. The following control messages (commands) are currently provided:

{| class="wikitable"
!Message name
!Description
!Implementation notes
|-
|APPLIBMT_Quit
|The application is asked to shut down itself and quit.
|Basically, upon receiving this message you should react as if your main program window received the WMHI_CLOSEWINDOW event. When implementing support for APPLIBMT_Quit, the programmer is required to design the program exit sequence in such a way that no unexpected data loss can occur (for example, by displaying a confirmation requester that allows the user to save work or cancel the quit command).
|-
|APPLIBMT_ForceQuit
|Same as before but this time the application shall quit immediately, without asking for saving documents etc.
|Providing this command as part of the Application Library messaging framework was surely meant well but there is an inherent risk: a malevolent application could hamper the use of other applications by sending them this message and making them quit prematurely. So implement APPLIBMT_ForceQuit with care, or don't implement it at all. The official AmigaOS application manager will never try to send APPLIBMT_ForceQuit in order to shut down running applications.
|-
|APPLIBMT_Hide
|The application shall hide its interface and iconify on the Workbench screen.
|rowspan="2"|An application that supports APPLIBMT_Hide and APPLIBMT_Unhide is expected to register itself with REGAPP_HasIconifyFeature set to TRUE. Basically, upon receiving this message you should react as if your main program window received the WMHI_ICONIFY / WMHI_UNICONIFY event.
|-
|APPLIBMT_Unhide
|The application shall come back from the iconified (hidden) state.
|-
|APPLIBMT_ToFront
|The application window shall come to front.
|Programmatically that entails calling the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. See the end of the [[#Message Handling|Message Handling]] section for a note on APPLIBMT_ToFront.
|-
|APPLIBMT_OpenPrefs
|The application shall open its preferences window.
|Only implement if your application has a dedicated Preferences (Settings) window. An application that supports APPLIBMT_OpenPrefs is expected to register itself with the REGAPP_HasPrefsWindow set to TRUE.
|-
|APPLIBMT_ReloadPrefs
|The application shall reload its preferences.
|Whatever this command is useful for.
|-
|APPLIBMT_NewBlankDoc
|The application shall open a new, blank document or project.
|Applications such as web browsers can, too, make use of this command to open new program windows. An application that supports APPLIBMT_NewBlankDoc is expected to register itself with the REGAPP_CanCreateNewDocs set to TRUE.
|-
|APPLIBMT_OpenDoc
|The application shall try to open a specific document or project.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above).
|-
|APPLIBMT_PrintDoc
|The application shall try to print a specific document.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above). An application that supports APPLIBMT_PrintDoc is expected to register itself with the REGAPP_CanPrintDocs set to TRUE.
|}

An application will only react to messages that are implemented and supported. If you [[#Sending Messages|send a message]] to an application that is registered but does not perform any Application Library event handling, there will be no reaction at all. Further, many applications will only implement a subset of the available control commands: if a program does not have a Print function, an APPLIBMT_PrintDoc message will quite logically be ignored. There is no rule saying which or how many control messages should be implemented but you are encouraged to provide the [[#Minimum Application Library Support|minimum suggested support]] as outlined above. Implement the rest according to your application’s features and needs, and to the highest standards of security.

=== Custom Messages ===

In contrast to a [[#Control Messages|control message]] (see above), a custom message has no meaning or purpose predefined by the library. It is a simple text string the actual meaning of which is determined by the application. There is some undeniable beauty in this concept. For instance, the application can define a set of “publicly available” commands that call a corresponding function whenever a particular command (text string) arrives from another application. This kind of external control is very easy to implement and represents a practical alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]], while requiring less setup. Also, sender applications need not care about internals (such as knowing the ARexx port name) – all it takes is to [[#Finding Applications|find]] the receiver application and [[#Sending Messages|send a message]] to it.

The pointer to the message text string is contained in a special [[#Data Structures|data structure]], ''struct ApplicationCustomMsg''.

=== Special Messages ===

There are also some special messages that an application can receive from the library or another running application:

{| class="wikitable"
! Message name !! Description !! Implementation notes
|-
| APPLIBMT_Unique || If an application is registered as [[#Uniqueness|unique]] and the user attempts to start a second instance of the program, the attempt will fail and the library will send an APPLIBMT_Unique message to the first instance. || All unique applications should listen for this message and react to it: not doing so might leave the user puzzled as to why the program hasn’t started. The recommended reaction is to bring the first instance to view and focus. This may entail a couple of steps, like uniconifying (if the program is iconified at the moment), swapping screen (if the program runs on a dedicated screen), bringing the program window to front, and activating it. Basically, the APPLIBMT_Unique message should be treated in the same way as the APPLIBMT_ToFront message.
|-
| APPLIBMT_GameModeEntered || Sent to all currently running applications if another application enters the “game mode” – that is, a state in which it doesn’t want to be disturbed. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to TRUE.
|-
| APPLIBMT_GameModeLeft || Informs all running application that the sender has left the game mode. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to FALSE.
|}

=== Message Handling ===

You already know that messaging in AmigaOS takes place between [[Exec_Messages_and_Ports#Message_Ports|message ports]]. Being a superset of standard Exec messages, Application Library notifications (be they predefined [[#Control Messages|control messages]], [[#Custom Messages|custom messages]] or [[#Special Messages|special messages]]) are, too, sent to a message port. We’ll call this dedicated port – in order to distinguish it from other ports possibly used by the program – the ''notification port''. The port is automatically created by the library at registration time and freed as part of the UnregisterApplication() call. Messages arriving at the port are meant to be processed within the program’s main event loop, together with other events (such as Intuition’s [[Intuition_Input_and_Output_Methods#Receiving_Input_Events_from_Intuition|IDCMP messages]]). To process incoming messages you first need to obtain the notification port pointer from the library and then set the port’s signal bit. The signal bit is used to identify messages as Application Library notifications.

A simplified event loop code could look like the one below. Note that this example loop only waits for and processes Application Library messages. In real use you'll also want to handle other message types, such as input from the user interface (IDCMP events) or ARexx commands.

<syntaxhighlight>
void event_loop(uint32 appID)
{
struct MsgPort *notificationPort = NULL;
struct ApplicationMsg *appLibMsg = NULL;
struct ApplicationCustomMsg *customMsg = NULL;
uint32 appLibSignal = 0, sigGot = 0;
BOOL done = FALSE;

/* Obtain pointer to Application Library's notification port and set the signal bit. */
IApplication->GetApplicationAttrs(appID, APPATTR_Port, &notificationPort, TAG_END);
appLibSignal = (1L << notificationPort->mp_SigBit);

/* Go into the event loop. */
while (!done)
{
/* Wait for a signal to arrive. */
sigGot = IExec->Wait(appLibSignal);

/* Process all Application Library messages. */
if ( sigGot & appLibSignal )
{
/* Obtain pointer to the message. */
while ( (appLibMsg = (struct ApplicationMsg *) IExec->GetMsg(notificationPort)) )
{
/* Identify the type of message. */
switch (appLibMsg->type)
{
case APPLIBMT_Quit:
case APPLIBMT_ForceQuit:
done = TRUE;
break;

case APPLIBMT_ToFront:
/* Make the program window come to front. */
break;

case APPLIBMT_Hide:
/* Iconify the program. */
break;

case APPLIBMT_Unhide:
/* Uniconify the program. */
break;

/* Process the custom message as you like.
Here we just use printf() to output the message text. */
case APPLIBMT_CustomMsg:
customMsg = (struct ApplicationCustomMsg *) appLibMsg;
printf("The message text is: %s\n", customMsg-> customMsg);
break;

/*
Process any other Application Library messages.
*/

}
/* Return the processed message to the sender so that it can be freed. */
IExec->ReplyMsg( (struct Message *) appLibMsg);
}
}
}
</syntaxhighlight>

Like all [[Exec_Messages_and_Ports#Messages|Exec messages]] obtained via the GetMsg() function, Application Library messages must be [[Exec_Messages_and_Ports#Replying|replied to]], i.e. returned to the sender after they have been processed. This is what the last command does in the code above. Remember that all message resources are freed after ReplyMsg() so should you need to use the message data (for example, the custom message text string) beyond the event loop, you must copy it to a memory storage of your own.

Also remember that the notifications are addressed to an abstract ''application'' – this makes them rather different from IDCMP messages, which are always sent to a particular ''window'' (Intuition doesn't know what an application is). Whereas Intuition stops sending IDCMP messages as soon as the window becomes closed/iconified, the Application Library keeps passing messages as long as the application is registered, regardless of program window state. So be smart in your code when processing Application Library notifications: check for the availability of the program window and perform uniconification when necessary. For example, this following piece of code

<syntaxhighlight>
/* Don't do this!!! */
case APPLIBMT_ToFront:
IIntuition->ScreenToFront(win->WScreen);
IIntuition->WindowToFront(win);
IIntuition->ActivateWindow(win);
break;
</syntaxhighlight>

is broken because if an APPLIBMT_ToFront command were sent to your iconified application, there would be no window to refer to. You need to check for iconified state first, uniconify the window if needed, and only then call the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. The mistake of referencing a non-existing window is as silly as it is easy to make!

=== Sending Messages ===

While incoming notifications are [[#Message Handling|processed]] pretty much like normal Exec messages, the Application Library implements its own method for message sending. It takes three simple steps to send a message to another application:

# Prepare the respective [[#Data Structures|data structure]]: specify the type of message and supply the sender's [[#Application Identifiers|identifier]] (appID).
# [[#Finding Applications|Find the receiver]] application.
# Send a message to it via the SendApplicationMsg() function.

For example, if you want to tell the Audio Monster application to quit, you send it an APPLIBMT_Quit message like this:

<syntaxhighlight>
struct ApplicationMsg appMsg; // message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Step 1: Prepare the message data structure. */
appMsg.senderAppID = appID; // identifier of the sender
appMsg.type = APPLIBMT_Quit; // type of message

/* Step 2: Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Step 3: Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
&appMsg,
APPLIBMT_Quit);
}
</syntaxhighlight>

Should you want to send your message to all currently registered applications at once, just use a receiver appID of 0.

Sending [[#Custom Messages|custom messages]] is done in a similar fashion, the only difference is that you must use a dedicated [[#Data Structures|data structure]] instead of the generic ''struct ApplicationMsg''. As our Audio Monster application is a media player, it may as well have defined a set of commands for external control, one of them being “Start playback”. Now if another application wants to tell Audio Monster to start playing, it will need to send the custom message like this:

<syntaxhighlight>
struct ApplicationCustomMsg customMsg; // custom message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Prepare the message data structure. */
customMsg.almsg.senderAppID = appID; // identifier of the sender
customMsg.almsg.type = APPLIBMT_CustomMsg; // type of message
customMsg.customMsg = "Start playback"; // message text

/* Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
(struct ApplicationMsg *) &customMsg,
APPLIBMT_CustomMsg);
}
</syntaxhighlight>

== Pop-up Notifications (Ringhio Messages) ==

As from the introduction of the Ringhio server in AmigaOS 4.1 Update 1, registered applications can inform the user via notifications displayed in a small pop-up box. These are sometimes called ''Ringhio messages'' because the server provides means through which the messages are communicated visually (in other words, Ringhio handles the actual display of messages sent by the Application Library). [[File:RinghioNotification.png|frame|Ringhio notification example]] The pop-ups function similarly to [[Intuition Requesters|requesters]] in that they show a text message; but unlike requesters, Ringhio messages do not require user interaction or acknowledgement. They just show up briefly and disappear – which makes them great for informing about less significant, matter-of-fact events such as that a certain task has been completed (this is especially helpful if the application is hidden or runs on a different screen, as the user is kept informed about something that is currently beyond his/her visual control).

Of all the types of Application Library messages, pop-up notifications are surely the easiest to program. They don’t require any setup or event handling; all it takes is a single function call:

<syntaxhighlight>
uint32 result;

result = IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
TAG_END);
</syntaxhighlight>

The first parameter is your application’s appID received from the [[#Registration Functions|registration function]]. The APPNOTIFY_Title tag specifies a short heading for the pop-up box while APPNOTIFY_Text contains the actual message text. Certain limits to text length apply to ensure that the pop-up remains easy to read: 64 characters for the heading (title) and 128 characters for the text (160 characters as of Ringhio 53.23). This particular message will display on the frontmost public screen (as specified in the APPNOTIFY_PubScreenName tag), which may as well be the right setting for most applications. You can of course provide any other public screen name – or you can call Notify() without this tag and let the library use the default, which is the [[Public_Screen_Type#The_Default_Public_Screen_and_Workbench|Workbench screen]].

The result value shows whether the call was successful; 0 means that an error has occurred and Ringhio failed to display the pop-up. Depending on the significance of the message, you may want to react upon the failure and inform the user through other means of communication, such as a requester.

The look and position of the pop-up box is configurable from the Notifications editor located in the Prefs drawer on your system partition. This is Ringhio’s preferences editor: as we have explained above, it is Ringhio that is responsible for the actual display of notification messages. The pop-up box can also show a small custom image (like the one in the picture above) to make the message more easily identifiable as related to a particular application. The maximum size of the image is 32x32 pixels. It can be any format, provided that there is a datatype for it installed in the system. Being application-specific, these images logically cannot be configured system-wide through the Notifications editor; instead, they are specified as part of the Notify() call. Note that a full path to the image file must be provided:

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "All right, ma!",
TAG_END);
</syntaxhighlight>

But what is this APPNOTIFY_BackMsg thing? It has been mentioned above that notification messages do not require user interaction: they display some text and go away. Nevertheless, Ringhio can send the application a [[#Custom Messages|custom message]] (called “back message” – hence the name of the tag) if the user has double-clicked on the message box. As the code snippet shows, this custom message takes the form of a text string (within the Application Library messaging context, [[#Custom Messages|custom messages]] are always text strings). It is sent to the same event stream, and is supposed to be processed within the same event loop, as other Application Library messages – see the [[#Message Handling|Message Handling]] section for how to go about it.

Whether receiving a “back message” would be useful for a particular application, and whether it would make sense to react upon it, is decided by the programmer. The reaction (if any – often none is needed) should be sensible and logical. Make sure not to misuse the feature! Note that Ringhio messages are not requesters, and double-clicking on the message box does not really equal pressing a requester button. Therefore, receiving the message could be interpreted as the user’s acknowledgement of what Ringhio has said, but never as a selection of an option. Do not use Ringhio to request input via the back-message feature: the text of the message should be a statement, not a question or an offer of choice. Considering this logic, the double click means “I understand”; it doesn't mean “Yes” or “No”.

If the text string provided in the APPNOTIFY_BackMsg tag is an URL, the feature works rather differently. Instead of sending the message to the event stream, this particular URL is opened in your default web browser. Because the process is done through the Launch Handler, your system should be recent enough to have it (the Launch Handler was introduced in AmigaOS 4.1 Update 1). The following piece of code will open Audio Monster’s homepage if the user double-clicks on the Ringhio box. The last in the tag list, APPNOTIFY_CloseOnDC, causes the message box to disappear right after the double click.

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "URL:http://www.supercoders.com",
APPNOTIFY_CloseOnDC, TRUE,
TAG_END);
</syntaxhighlight>

=== Pop-up Message Style Guide ===

* Keep the message text short. Give the user chance to read the entire message before it disappears.
* Do not use pop-up messages to report errors. An error is usually a serious situation, and as such it cannot be dismissed by simply displaying an automatic message (which can easily get missed or overlooked).
* Use the pop-up message facility with moderation. Displaying the messages too frequently might hamper the workflow, and would most probably annoy the user.

== Function Reference ==

The following are brief descriptions of the Application Library functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| FindApplication()
| Searches for a previously registered application.
|-
| FreeApplicationList()
| Frees the list of applications generated by GetApplicationList().
|-
| GetAppLibAttrs()
| Obtains global Application Library attributes.
|-
| GetApplicationAttrs()
| Obtains attributes of a registered application.
|-
| GetApplicationList()
| Obtains the list of all currently registered applications.
|-
| LockApplicationIcon()
| Attempts to lock an application icon.
|-
| Notify()
| Displays a pop-up message box.
|-
| RegisterApplication()
| Registers an application.
|-
| SendApplicationMsg()
| Sends a message to a registered application.
|-
| SetAppLibAttrs()
| Sets or changes global Application Library attributes.
|-
| SetApplicationAttrs()
| Sets or changes application attributes.
|-
| UnlockApplicationIcon()
| Unlocks an application icon.
|-
| UnregisterApplication()
| Unregisters an application.
|}

IFFParse Library

2017-10-15T19:14:44Z

Daniel Jedlicka: Fixed a typo, added two missing library interface pointers.

== IFFParse Library ==

The ''iffparse.library'' was created to help simplify the job of parsing IFF files. Unlike other IFF libraries, iffparse.library is not form-specific. This means that the job of interpreting the structure and contents of the IFF file is up to you. Previous IFF file parsers were either simple but not general, or general but not simple. IFFParse tries to be both simple ''and'' general.

== The Structure of IFF Files ==

Many people have a misconception that IFF means image files. This is not the case. IFF (short for Interchange File Format) is a method of portably storing structured information in machine-readable form. The actual information can be anything, but the manner in which it is stored is very specifically detailed. This specification is the IFF standard.

The IFF standard was originally designed in 1985 by Electronic Arts in conjunction with a committee of developers. The full standard along with file descriptions and sample code is available at [[IFF_Standard|IFF Standard]].

The goal of the IFF standard is to allow customers to move their own data between independently developed software products. The types of data objects to exchange are open-ended and currently include plain and formatted text, raster and structured graphics, fonts, music, sound effects, musical instrument descriptions, and animation. IFF addresses these needs by defining a standard for self-identifying file structures and rules for accessing these files.

=== Chunks: The Building Blocks of IFF ===

IFF files contain various types and amounts of data grouped in data ''chunks'', each starting with a four-letter ASCII identifier (the chunk ID) followed by a 32-bit length count (the chunk size). The identifier and length count make it possible for IFF readers to skip over chunks that they don’t understand or don’t care about, and extract only the information they need. It may be helpful to think of these chunks as the building blocks of an IFF file.

[[File:LibFig33-1.png|frame|center|The Chunk - The Building Block of IFF]]

The ‘CKID’ (chunk ID) characters of a real chunk will be a four letter identifier such as ‘BODY’ or ‘CMAP’, specifying the type and format of data stored in the chunk. Most chunks contain a simple defined grouping of byte, word, and long variables similar to the contents of a C structure. Others such as sound sample and bitmap image body chunks, contain a stream of compressed data.

Chunk writing is fairly straightforward with the one caveat that all chunks must be word-aligned. Therefore an odd-length chunk must be followed by a pad byte of zero (which is not counted in the size of the chunk). When chunks are nested, the enclosing chunk must state the total size of its composite contents (including any pad bytes).

{{Note|title=About Chunk Length|text=Every IFF data chunk begins with a 4-character identifier field followed by a 32-bit size field (these 8 bytes are sometimes referred to as the chunk header). The size field is a count of the rest of the data bytes in the chunk, ''not'' including any pad byte. Hence, the total space occupied by a chunk is given by its size field (rounded to the nearest even number) + 8 bytes for the chunk header}}

=== Composite Data Types ===

Standard IFF files generally contain a variable number of chunks within one of the standard IFF composite data types (which may be thought of as chunks which contain other chunks). The IFF specification defines three basic composite data types, ‘FORM’, ‘CAT ’, and ‘LIST’. A special composite data type, the ‘PROP’, is found only inside a LIST.

Usage of Composite IFF Types

{| class="wikitable"
| FORM || A grouping of chunks which describe one set of data
|-
| LIST || A grouping of the same type of FORMs with shared properties in a PROP
|-
| PROP || May appear in a LIST to define chunks shared by several FORMs
|-
| CAT || A concatenation of related FORMs or LISTs
|}

The special IFF composite data types, like simple chunks, start with a 4-character identifier (such as ‘FORM’), followed by a 32-bit length. But their data begins with a second 4-character identifier that tells you what type of data is in the composite. For example, a FORM ILBM contains chunks describing a bitmap image, and a FORM FTXT contains chunks describing formatted text.

It may help to think of each composite data type as a box containing chunks, the IFF building blocks. The following figure shows a diagram of a typical composite.

[[File:LibFig33-2.png|frame|center|The FORM – The Most Common IFF File Type]]

The example FORM in the previous figure is outlined below showing the size of chunks within the FORM. Notice that the size of a composite ''includes'' its second 4-character identifier (shown below as ‘NAME’).

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 22 (then 22 bytes of data, so chunk header + chunk size is 30)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

{{Note|text=In the example above, indentation represents the nesting of the chunks within the FORM. Real FORMs and chunks would have different four-character identifiers rather than ‘NAME’ and ‘CKID’.}}

Any odd-length chunks must have a pad byte of zero at the end of the chunk. As shown below, this pad byte is not counted in the size of the chunk but ''is'' counted in the size of any composite types (such as FORM) that contain an odd-length chunk. '''Warning:''' some IFF readers and writers do not deal with this properly.

. FORM 72 NAME (72 is the size of the FORM starting with the “N” of NAME)
. . CKID 21 (then 21 bytes of data, so chunk header + chunk size is 29)
. . 0 (pad byte of zero, size 1)
. . CKID 10 (then 10 bytes of data, so chunk header + chunk size is 18)
. . CKID 12 (then 12 bytes of data, so chunk header + chunk size is 20)

Most IFF files are of the composite type FORM. Generally, a FORM is a simple grouping of chunks that provide information about some data, and the data itself. Although some standard chunks have common usage within different FORMS, the identity and format of most chunks within a FORM are relative to the definition and specification of the FORM. For example, a CRNG chunk in a FORM ILBM may have a totally different format and contents than a chunk named CRNG in a different type of FORM.

One of the most popular IFF FORMs that has been defined is the ILBM standard. This is how most Amiga bitmap imagery is stored. Since this is the most common IFF file, it is used frequently as an example.

Here is the output of a program called “Sift.c” that displays a text description of the contents of an IFF file ([[#IFF Scanner Example|Sift.c]] is listed at the end of this article). The file shown below is a fairly simple ILBM.

. FORM 11068 ILBM
. . BMHD 20
. . CAMG 4
. . CMAP 12
. . BODY 10995

{{Note|title=Computing the Size of a FORM|text=The size of the FORM (11,068 bytes) is equal to the sum of the sizes stated in each chunk contained within the FORM, plus 8 bytes for the overhead of each chunk header (4 bytes for the 4-character chunk ID, and 4 bytes for the 32-bit chunk size), plus 4 bytes for the FORM’s own 4-character ID (‘ILBM’), plus 1 byte more for each pad byte that follow any odd-length chunks.}}

== Parsing an IFF File ==

Chunk reading requires a parser to scan each chunk and dispatch the proper access/conversion procedure. For a simple IFF file, such parsing may be relatively easy, consisting mainly reading in the data of desired chunks, and seeking over unwanted chunks (and the pad byte after odd-length chunks). Interpreting nested chunks is more complex, and requires a method for keeping track of the current context, i.e., the data which is still relevant at any particular depth into the nest. The original IFF specifications compare an IFF file to a C program. Such a metaphor can be useful in understanding the scope of of the chunks in an IFF file.

The IFFParse library addresses general IFF parsing requirements by providing a run-time library which can extract the chunks you want from an IFF file, with the ability to pass control to you when it reaches a chunk that requires special processing such as decompression. IFFParse also understands complex nested IFF formats and will keep track of the context for you.

=== Basic Functions and Structures of IFFParse Library ===

The structures and flags of the IFFParse library are defined in the include files <libraries/iffparse.h> and <libraries/iffparse.i>. IFF files are manipulated through a structure called an IFFHandle. Only some of the fields in the IFFHandle are publicly documented. The rest are managed internally by IFFParse. This handle is passed to all IFFParse functions, and contains the current parse state and position in the file. An IFFHandle is obtained by calling AllocIFF(), and freed through FreeIFF(). This is the only legal way to obtain and dispose of an IFFHandle.

The public portion of if IFFHandle is defined as follows:

<syntaxhighlight>
/*
* Structure associated with an active IFF stream.
* "iff_Stream" is a value used by the client's read/write/seek functions -
* it will not be accessed by the library itself and can have any value
* (could even be a pointer or a BPTR).
*/
struct IFFHandle {
ULONG iff_Stream;
ULONG iff_Flags;
LONG iff_Depth; /* Depth of context stack. */
/* There are private fields hiding here. */
};
</syntaxhighlight>

== Stream Management ==

A stream is a linear array of bytes that may be accessed sequentially or randomly. DOS files are streams. IFFParse uses Hook structures (defined in <utility/hooks.h>) to implement a general stream management facility. This allows the IFFParse library to read, write, and seek any type of file handle or device by using an application-provided hook function to open, read, write, seek and close the stream.

Built on top of this facility, IFFParse has two internal stream managers: one for unbuffered DOS files (AmigaDOS filehandles), and one for the Clipboard.

=== Initialization ===

As shown above, the IFFHandle structure contains the public field iff_Stream. This is a longword that must be initialized to contain something meaningful to the stream manager. IFFParse never looks at this field itself (at least not directly). Your iff_Stream may be an AmigaDOS filehandle, or an IFFParse ClipboardHandle, or a custom stream of any type if you provide your own custom stream handler (see the section on [[#Custom Stream Handlers|Custom Stream Handlers]]). You must initialize your IFFHandle structure’s iff_Stream to your stream, and then initialize the IFFHandle’s flags and stream hook.

Three sample initializations are shown here. In the case of the internal DOS stream manager, iff_Stream is an AmigaDOS filehandle as returned by Open():

<syntaxhighlight>
iff->iff_Stream = (ULONG) IDOS->Open ("filename", MODE_OLDFILE);
if(iff->iff_Stream) IIFFParse->InitIFFasDOS (iff); /* use internal DOS stream manager */
</syntaxhighlight>

In the case of the internal Clipboard stream manager, iff_Stream is a pointer to an IFFParse ClipboardHandle structure (the OpenClipboard() call used here is a function of iffparse.library, not the clipboard.device):

<syntaxhighlight>
iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard (PRIMARY_CLIP);
IIFFParse->InitIFFasClip (iff); /* use internal Clipboard stream manager */
</syntaxhighlight>

When using a custom handle such as an fopen() file handle, or a device other than the clipboard, you must provide your own flags and stream handler:

<syntaxhighlight>
iff->iff_Stream = (ULONG) OpenMyCustomStream("foo");
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
</syntaxhighlight>

IFFParse “knows” the seek capabilities of DOS and ClipboardHandle streams, so InitIFFasDOS() and InitIFFasClip() set the flags for you.

{{Note|title=You May Change the Seek Bits in iff_Flags|text=IFFParse sets IFFF_FSEEK | IFFF_RSEEK for DOS files. This is not always true (e.g., pipes). If you know that a DOS file has different seek characteristics, your application may correct the seek bits in iff_Flags after calling InitIFFasDOS().}}

When using InitIFF() to provide a custom handler, you must also provide flags to tell IFFParse the capabilities of your stream. The flags are:

; IFFF_FSEEK
: This stream has forward-seek capability only.

; IFFF_RSEEK
: This stream has random-seek capability. IFFF_RSEEK tends to imply IFFF_FSEEK, but it’s best to specify both.

If neither flag is specified, you’re telling IFFParse that it can’t seek through the stream.

After your stream is initialized, call OpenIFF():

<syntaxhighlight>
error = IIFFParse->OpenIFF (iff, IFFF_READ);
</syntaxhighlight>

Once you establish a read/write mode (by passing IFFF_READ or IFFF_WRITE), you remain in that mode until you call CloseIFF().

=== Termination ===

Termination is simple. Just call CloseIFF(iff). This may be called at any time, and terminates IFFParse’s transaction with the stream. The stream itself is not closed. The IFFHandle may be reused; you may safely call OpenIFF() on it again. You are responsible for closing the streams you opened. A stream used in an IFFHandle must generally remain open until you CloseIFF().

=== Custom Streams ===

A custom stream handler can allow you (and iffparse.library) to use your compiler’s own file I/O functions such as fopen(), fread() and fwrite(), rather than the lower-level AmigaDOS equivalents Open(), Read(), and Write(). A custom stream handler could also be used to read or write IFF files from an Exec device or an unusual handler or file system.

If you install your own stream handler function, iffparse.library will call your function whenever it needs to read, write, or seek on your file. Your stream handler function will then perform these stream actions for iffparse.library. See the “Custom Stream Handlers” section for more information on custom stream handlers.

== Parsing and Writing IFF ==

For information on parsing IFF see [[Parsing_IFF|Parsing IFF]].

For information on writing IFF see [[Writing_IFF|Writing IFF]].

== Context Functions ==

Internally, IFFParse maintains IFF nesting and scoping context via a ''context stack''. The PushChunk() and PopChunk() functions get their names from this basic idea of the iffparse.library. Direct access to this stack is not allowed. However, many functions are provided to assist in examining and manipulating the context stack.

{{Note|title=About the Context Stack|text=It is probably easier to think of a stack of blocks on a table in front of you when reading this discussion.}}

As the nesting level increases (as would happen when parsing a nested LIST or FORM), the depth of the context stack increases; new elements are added to the top. When these contexts expire, the ContextNodes are deleted and the stack shrinks.

=== Context Nodes ===

The current context is said to be the top element on the stack. Contextual information is stored in a structure called a ContextNode:

<syntaxhighlight>
struct ContextNode {
struct MinNode cn_Node;
LONG cn_ID;
LONG cn_Type;
LONG cn_Size; /* Size of this chunk */
LONG cn_Scan; /* # of bytes read/written so far */
/* There are private fields hiding here. */
};
</syntaxhighlight>

==== CurrentChunk() ====

You can obtain a pointer to the current ContextNode through the function CurrentChunk():

<syntaxhighlight>
currentnode = IIFFParse->CurrentChunk (iff);
</syntaxhighlight>

The ContextNode tells you the type, ID, and size of the currently active chunk. If there is no currently active context, NULL is returned.

==== ParentChunk() ====

To find the parent of a context, you call ParentChunk() on the relevant ContextNode:

<syntaxhighlight>
parentnode = IIFFParse->ParentChunk(currentnode);
</syntaxhighlight>

If there is no parent context, NULL is returned.

=== The Default Context ===

When you first obtain an IFFHandle through AllocIFF(), a hidden default context node is created. You cannot get direct access to this node through CurrentChunk() or ParentChunk(). However, using StoreLocalItem(), you can store information in this context.

=== Context-Specific Data: LocalContextItems ===

ContextNodes can contain application data specific to that context. These data objects are called LocalContextItems. LocalContextItems (LCIs) are a grey-box structure which contain a type, ID and identification field. LCIs are used to store context-sensitive data. The format of this data is application-defined. A ContextNode can contain as many LCIs as you want.

[[File:LibFig33-3.png|frame|center|IFFParse Context Stack]]

The previous figure shows the relationship between the IFFHandle, the ContextNodes, and the LCIs. The IFFHandle is the root of the tree, so to speak. ContextNodes “grow” out of the IFFHandle. In turn, LCIs "grow" out of the ContextNodes. What grows out of an LCI is client-defined.

==== AllocLocalItem() ====

To create an LCI, you use the function AllocLocalItem():

<syntaxhighlight>
lci = IIFFParse->AllocLocalItem (type, id, ident, datasize);
</syntaxhighlight>

If successful, you will be returned a pointer to an LCI having the specified type, ID, and identification values; and with datasize bytes of buffer space for your application to use.

==== LocalItemData() ====

To get a pointer to an LCIs data buffer, you use LocalItemData():

<syntaxhighlight>
buf = IIFFParse->LocalItemData (lci);
</syntaxhighlight>

You may read and write the buffer to your heart’s content; it is yours. You should not, however, write beyond the end of the buffer. The size of the buffer is what you asked for when you called AllocLocalItem().

=== Storing LCIs ===

Once you’ve created and initialized an LCI, you’ll want to attach it to a ContextNode. Though a ContextNode can have many LCIs, a given LCI can be linked to only one ContextNode. Once linked, an LCI cannot be removed from a ContextNode (this may change in the future). Storing an LCI in a ContextNode is done with the functions StoreLocalItem() and StoreItemInContext().

==== StoreLocalItem() ====

The StoreLocalItem() function is called as follows:

<syntaxhighlight>
error = StoreLocalItem (iff, lci, position);
</syntaxhighlight>

The position argument determines where the LCI is stored. The possible values are IFFSLI_ROOT, IFFSLI_TOP, and IFFSLI_PROP.

; IFFSLI_ROOT
: causes StoreLocalItem() to store your LCI in the default ContextNode.

; IFFSLI_TOP
: gets your LCI stored in the top (current) ContextNode.

{{Note|title=The LCI Ends When the Current Context Ends|text=When the current context expires, your LCI will be deleted by the parser.}}

IFFSLI_PROP causes your LCI to be stored in the topmost context from which a property would apply. This is usually the topmost FORM or LIST chunk. For example, suppose you had a deeply nested ILBM FORM, and you wanted to store the BMHD property in its correct context such that, when the current FORM context expired, the BMHD property would be deleted. IFFSLI_PROP will cause StoreLocalItem() to locate the proper context for such scoping, and store the LCI there. See the section on "Finding the Prop Context" for additional information on the scope of properties.

==== StoreItemInContext() ====

StoreItemInContext() is used when you already have a pointer to the ContextNode to which you want to attach your LCI. It is called like so:

<syntaxhighlight>
IIFFParse->StoreItemInContext (iff, lci, contextnode);
</syntaxhighlight>

StoreItemInContext() links your LCI into the specified ContextNode. Then it searches the ContextNode to see if there is another LCI with the same type, ID, and identification values. If so, the old one is deleted.

==== FindLocalItem() ====

After you’ve stored your LCI in a ContextNode, you will no doubt want to be able to find it again later. You do this with the function FindLocalItem(), which is called as follows:

<syntaxhighlight>
lci = IIFFParse->FindLocalItem (iff, type, id, ident);
</syntaxhighlight>

FindLocalItem() attempts to locate an LCI having the specified type, ID, and identification values. The search proceeds as follows (refer to the previous figure to understand this better).

FindLocalItem() starts at the top (current) ContextNode and searches all LCIs in that context. If no matching LCIs are found, it proceeds down the context stack to the next ContextNode and searches all its LCIs. The process repeats until it finds the desired LCI (whereupon it returns a pointer to it), or reaches the end without finding anything (where it returns NULL).

{{Note|title=Context Stack Position|text=LCIs higher in the stack will "override" lower LCIs with the same type, ID, and identification field. This is how property scoping is handled. As ContextNodes are popped off the context stack, all its LCIs are deleted as well. See the section on “Freeing LCIs” below for additional information on deleting LCIs.}}

=== Some Interesting Internal Details ===

{{Note|title=Warning|text=This section details some internal implementation details of iffparse.library which may help you to understand it better. Use of the following information to do “clever” things in an application is forbidden and unsupportable. Don’t even think about it.}}

It turns out that StoredProperties, CollectionItems, and entry and exit handlers are all implemented using LCIs. For example, when you call FindProp(), you are actually calling a front-end to FindLocalItem(). The mysterious identification value (which has heretofore never been discussed) is a value which permits you to differentiate between LCIs having the same type and ID.

For instance, suppose you called PropChunk(), asking it to store an ILBM BMHD. PropChunk() will install an entry handler in the form of an LCI, having type equal to ‘ILBM’, ID equal to ‘BMHD’, and an identification value of IFFLCI_ENTRYHANDLER.

When an ILBM BMHD is encountered, the entry handler is called, and it creates and stores another LCI having type equal to ‘ILBM’, ID equal to ‘BMHD’ and an identification value of IFFLCI_PROP.

Thus, when you call FindProp(), it merely calls FindLocalItem() with your type and ID, and supplies IFFLCI_PROP for the identification value.

Therefore, handlers, StoredProperties, CollectionItems and your own custom LCIs can never be confused with each other, since they all have unique identification values. Since they are all handled (and searched for) in the same way, they all “override” each other in a consistent way. Just as StoredProperties higher in the context stack will be found and returned before identical ones in lower contexts, so will chunk handlers be found and invoked before ones lower on the context stack (recall FindLocalItem()’s search procedure).

This means you can temporarily override a chunk handler by installing an identical handler in a higher context. The handler will persist until the context in which it is stored expires, after which, the original one regains scope.

== Error Handling ==

If at any time during reading or writing you encounter an error, the IFFHandle is left in an undefined state. Upon detection of an error, you should perform an abort sequence and CloseIFF() the IFFHandle. Once CloseIFF() has been called, the IFFHandle is restored to normalcy and may be reused.

== Advanced Topics ==

This section discusses customizing of IFFParse data handling. For applications with special needs, IFFParse supports both custom stream handlers and custom chunk handlers.

=== Custom Stream Handlers ===

As discussed earlier, IFFParse contains built-in stream handlers for AmigaDOS file handles as returned by Open(), and for the clipboard.device. If you are using AmigaDOS filehandles or the clipboard.device, you need not supply a custom stream handler.

If you wish to use your compiler’s own file I/O functions (such as fread() ) or need to read or write to an unusual handler or Exec device, you must provide a custom stream handler for your IFFHandle. Your custom stream handler will be called to perform all reads, writes, and seeks on your custom stream. The allows you to use compiler file I/O functions, Exec device commands, or any other method to perform the requested stream operations.

If you are implementing your own custom stream handler, you will need to know the mechanics of hook call-backs, and how to interpret the parameters. An IFFParse custom stream handler is simply a function in your code that follows hook function conventions (Hook functions are also known as callback functions. See [[Utility_Library|Utility Library]] for more details).

==== Installing a Custom Stream Handler ====

To initialize your IFFHandle to point to your custom stream and stream handler, you must open your stream and place a pointer to the stream in your IFFHandle’s iff_Stream field. This pointer could be the return from fopen(), or an Exec device I/O request, or any other type of pointer which will provide your custom stream handler with a way to manage your stream. For example:

<syntaxhighlight>
iff->iff_Stream = (ULONG) fopen("foo");
</syntaxhighlight>

Next, you must install your custom handler for this stream, and also tell IFFParse the seek capabilities of your stream. To install your custom stream handler, you must first set up a Hook structure (<utility/hooks.h>) to point to your stream handling function. Then use InitIFF() to install your stream handler and also tell IFFParse the seek capabilities of your stream. There is “some assembly required”.

For an IFFParse custom stream hook the function prototype looks like this:

<syntaxhighlight>
int32 mystreamhandler(struct Hook *hook, struct IFFHandle *iff, struct IFFStreamCmd *actionpkt);
</syntaxhighlight>

A return of 0 indicates success. A non-zero return indicates an error.

For example,

<syntaxhighlight>
static int32 mystreamhandler
(
struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt
)
{
/*
* Code to handle the stream commands - see end this section
* for a complete example custom stream handler function.
*
*/
}

/* Initialization of Hook structure for registerized handler function */
struct Hook mystreamhook
{
{ NULL },
(HOOKFUNC) mystreamhandler, /* h_Entry, registerized function entry */
NULL,
NULL
};

/* Open custom stream and InitIFF to custom stream handler */
if ( iff->iff_Stream = (ULONG) myopen("foo") )
{
IIFFParse->InitIFF (iff, IFFF_FSEEK | IFFF_RSEEK, &mystreamhook);
}
</syntaxhighlight>

==== Inside a Custom Stream Handler ====

When the library calls your stream handler, you’ll be passed a pointer to the Hook structure (hook in the example used here), a pointer to the IFFHandle (iff), and a pointer to an IFFStreamCmd structure (actionpkt). Your stream pointer may be found in iff->iff_Stream where you previously stored it. The IFFStreamCmd (actionpkt) will describe the action that IFFParse needs you to perform on your stream:

<syntaxhighlight>
/* Custom stream handler is passed struct IFFStreamCmd *actionpkt */
struct IFFStreamCmd {
LONG sc_Command; /* Operation to be performed (IFFCMD_) */
APTR sc_Buf; /* Pointer to data buffer */
LONG sc_NBytes; /* Number of bytes to be affected */
};

/* Possible call-back command values. (Using 0 as the value for IFFCMD_INIT
* was, in retrospect, probably a bad idea.)
*/
#define IFFCMD_INIT 0 /* Prepare the stream for a session */
#define IFFCMD_CLEANUP 1 /* Terminate stream session */
#define IFFCMD_READ 2 /* Read bytes from stream */
#define IFFCMD_WRITE 3 /* Write bytes to stream */
#define IFFCMD_SEEK 4 /* Seek on stream */
#define IFFCMD_ENTRY 5 /* You just entered a new context */
#define IFFCMD_EXIT 6 /* You're about to leave a context */
#define IFFCMD_PURGELCI 7 /* Purge a LocalContextItem */
</syntaxhighlight>

Your custom stream handler should perform the requested action on your custom stream, and then return 0 for success or an IFFParse error if an error occurred. The following code demonstrates a sample stream handler for a stream which was opened with a compiler’s fopen() buffered file I/O function:

<syntaxhighlight>
static int32 mystreamhandler ( struct Hook *hook,
struct IFFHandle *iff,
struct IFFStreamCmd *actionpkt )
{
FILE *stream;
int32 nbytes, error;
uint8 *buf;

stream = (FILE *) iff->iff_Stream; /* get your stream pointer */
nbytes = actionpkt->sc_NBytes; /* length for command */
buf = (uint8 *) actionpkt->sc_Buf; /* buffer for the command */

/* Now perform the action specified by the actionpkt->sc_Command */

switch (actionpkt->sc_Command) {
case IFFCMD_READ:
/*
* IFFCMD_READ means read sc_NBytes from the stream and place
* it in the memory pointed to by sc_Buf. Be aware that
* sc_NBytes may be larger than can be contained in an int.
* This is important if you plan on recompiling this for
* 16-bit ints, since fread() takes int arguments.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_READ.
*/
error = (fread (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_WRITE:
/*
* IFFCMD_WRITE is analogous to IFFCMD_READ.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_WRITE.
*/
error = (fwrite (buf, 1, nbytes, stream) != nbytes);
break;

case IFFCMD_SEEK:
/*
* IFFCMD_SEEK asks that you performs a seek relative to the
* current position. sc_NBytes is a signed number,
* indicating seek direction (positive for forward, negative
* for backward). sc_Buf has no meaning here.
*
* Any error code returned will be remapped by IFFParse into
* IFFERR_SEEK.
*/
error = (fseek (stream, nbytes, 1) == -1);
break;

case IFFCMD_INIT:
/*
* IFFCMD_INIT means to prepare your stream for reading.
* This is used for certain streams that can't be read
* immediately upon opening, and need further preparation.
* This operation is allowed to fail; the error code placed
* in D0 will be returned directly to the client.
*
* An example of such a stream is the clipboard. The
* clipboard.device requires you to set the io_ClipID and
* io_Offset to zero before starting a read. You would
* perform such a sequence here. (Stdio files need no such
* preparation, so we simply return zero for success.)
*/
case IFFCMD_CLEANUP:
/*
* IFFCMD_CLEANUP means to terminate the transaction with
* the associated stream. This is used for streams that
* can't simply be closed. This operation is not allowed to
* fail; any error returned will be ignored.
*
* An example of such a stream is (surprise!) the clipboard.
* It requires you to explicitly end reads by CMD_READing
* past the end of a clip, and end writes by sending a
* CMD_UPDATE. You would perform such a sequence here.
* (Again, stdio needs no such sequence.)
*/
error = 0;
break;
}
return (error);
}
</syntaxhighlight>

=== Custom Chunk Handlers ===

Like custom stream handlers, custom chunk handlers are implemented using Hook structures. See the previous section for details on how a handler function may be interfaced using a Hook structure.

There are two types of chunk handlers: entry handlers and exit handlers. Entry handlers are invoked just after the parser enters the chunk; the stream will be positioned to read the first byte in the chunk. (If the chunk is a FORM, LIST, CAT, or PROP, the longword type will be read by the parser; the stream will be positioned to read the byte immediately following the type.) Exit handlers are invoked just before the parser leaves the chunk; the stream is not positioned predictably within the chunk.

==== Installing a Custom Chunk Handler ====

To install an entry handler, you call EntryHandler() in the following manner:

<syntaxhighlight>
error = IIFFParse->EntryHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

An exit handler is installed by saying:

<syntaxhighlight>
error = IIFFParse->ExitHandler (iff, type, id, position, hookptr, object);
</syntaxhighlight>

In both cases, a handler is installed for chunks having the specified type and id. The position argument specifies in what context to install the handler, and is identical to the position argument used by StoreLocalItem(). The hookptr argument given above is a pointer to your Hook structure.

==== Inside a Custom Chunk Handler ====

The mechanics of receiving parameters through the Hook are covered in the “Custom Stream Handlers” section, and are not duplicated here. Refer to the EntryHandler() and ExitHandler() Autodocs for the contents of the registers upon entry.

Once inside your handler, you can call nearly all functions in the iffparse.library, however, you should avoid calling ParseIFF() from within chunk handlers.

Your handler runs in the same environment as whoever called ParseIFF(). The propagation sequence is:

'''mainline''' --''calls''--> '''ParseIFF()''' --''calls''--> '''your_handler()'''

Thus, your handler runs on your mainline’s stack, and can call any OS functions the mainline code can. (Your handler will have to set the global base pointer if your code uses base-relative addressing.)

The return code will affect the parser in a number of ways:

* If you return zero (a normal, uneventful return), ParseIFF() will continue normally. If you return the value IFFERR_RETURN2CLIENT, ParseIFF() will stop and return the value zero to the mainline code.

* If you return any other value, ParseIFF() will stop and return that value to the mainline code. This is how you should return error conditions to the client code.

==== The Object Parameter ====

The object parameter supplied to EntryHandler() and ExitHandler() is a pointer which will be passed to your handler when invoked. This pointer can be anything; the parser doesn’t use it directly. As an example, you might pass the pointer to the IFFHandle. This way, when your handler is called, you’ll be able to easily perform operations on the IFFHandle within your handler. Such code might appear as follows:

<syntaxhighlight>
error = EntryHandler (iff, ID_ILBM, ID_BMHD, IFFSLI_ROOT, hook, iff);
</syntaxhighlight>

And your handler would be declared as follows:

<syntaxhighlight>
int32 MyHandler (struct Hook *hook,
int32 *cmd,
struct IFFHandle *iff)

</syntaxhighlight>

From within your handler, you could then call CurrentChunk(), ReadChunkBytes(), or nearly any other operation on the IFFHandle. Please refer to the EntryHandler() and ExitHandler() Autodocs for additional information on the use of chunk handlers.

=== Finding the Prop Context ===

Earlier it was mentioned that supplying a position value of IFFSLI_PROP to StoreLocalItem() would store it in the topmost property scope. FindPropContext() is the routine that finds that topmost context.

Property chunks (such as the BMHD, CMAP, and others) have dominion over the FORM that contains them; they are said to be “in scope” and their definition persists until the FORM’s context ends. Thus, a property chunk has a scoping level equal to the FORM that contains it; when the FORM ends, the property dies with it.

Consider a more complicated example. Suppose you have a LIST with a PROP in it. PROPs are the global variables of LISTs; thus a property chunk declared in a PROP will persist until the LIST’s context ends.

This is what FindPropContext() is looking for; a context level in which a property chunk may be installed.

FindPropContext() starts at the parent of the current context (second from the top of the context stack) and starts searching downward, looking for the first FORM or LIST context it finds. If it finds one, it returns a pointer to that ContextNode. If it can’t find a suitable context level, it returns NULL.

FindPropContext() is called as follows:

<syntaxhighlight>
struct ContextNode *cn = IFFParse->FindPropContext (iff);
</syntaxhighlight>

=== Freeing LCIs ===

Ordinarily, the parser will automatically delete LCIs you have allocated and installed. However, you may have a case where simply FreeVec()ing your LCI is not enough; you may need to free some ancillary memory, or decrement a counter, or send a signal, or something. This is where SetLocalItemPurge() comes in. It is called as follows:

<syntaxhighlight>
IFFParse->SetLocalItemPurge (lci, hookptr);
</syntaxhighlight>

When the parser is ready to delete your LCI, your purge handler code will be called through the Hook you supplied. You can then perform all your necessary operations. One of these operations should be to free the LCI itself. This is done with FreeLocalItem():

<syntaxhighlight>
IIFFParse->FreeLocalItem (lci);
</syntaxhighlight>

This deallocates the memory used to store the LCI and the client buffer allocated with it. FreeLocalItem() is only called as part of a custom purge handler.

As with custom chunk handlers, your purge handler executes in the same environment as the mainline code that called ParseIFF(). It is recommended that you keep purge handlers short and to the point; super clever stuff should be reserved for custom chunk handlers, or for the client’s mainline code. Custom purge handlers must ''always'' work; failures will be ignored.

== IFF FORM Specifications ==

The specifications for Amiga IFF formats are maintained by the AmigaOS Development Team. The latest specifications are published in the [[IFF_Standard|IFF Standard]]. Updates of the IFF Manual, selected new FORMs and changes to existing FORMs are documented on this wiki.

Some of the most commonly used IFF FORMs are the four that were originally specified in the EA IFF-85 standard:

{| class="wikitable"
| ILBM || Bitmap images and palettes
|-
| FTXT || Simple formatted text
|-
| SMUS || Simple musical scores
|-
| 8SVX || 8-bit sound samples
|}

Of these four, ILBM is the most commonly encountered FORM, and FTXT is becoming increasingly important since the ''conclip'' command passes clipped console text through the clipboard as FTXT. All data clipped to the clipboard must be in an IFF format.

This section will provide a brief summary of the ILBM and FTXT FORMs and their most used common chunks. Please consult the EA-IFF specifications for additional information.

=== FORM ILBM ===

The IFF file format for graphic images on the Amiga is called FORM ILBM (InterLeaved BitMap). It follows a standard parsable IFF format.

==== ILBM.BMHD BitMapHeader Chunk ====

The most important chunk in a FORM ILBM is the BMHD (BitMapHeader) chunk which describes the size and compression of the image:

<syntaxhighlight>
typedef UBYTE Masking; /* Choice of masking technique - Usually 0. */
#define mskNone 0
#define mskHasMask 1
#define mskHasTransparentColor 2
#define mskLasso 3

/* Compression algorithm applied to the rows of all source
* and mask planes. "cmpByteRun1" is byte run encoding.
* Do not compress across rows! Compression is usually 1.
*/
typedef UBYTE Compression;
#define cmpNone 0
#define cmpByteRun1 1

/* The BitMapHeader structure expressed as a C structure */
typedef struct {
UWORD w, h; /* raster width & height in pixels */
WORD x, y; /* pixel position for this image */
UBYTE nPlanes; /* # bitplanes (without mask, if any) */
Masking masking; /* One of the values above. Usually 0 */
Compression compression;/* One of the values above. Usually 1 */
UBYTE reserved1; /* reserved; ignore on read, write as 0 */
UWORD transparentColor; /* transparent color number. Usually 0 */
UBYTE xAspect, yAspect; /* pixel aspect, a ratio width : height */
WORD pageWidth, pageHeight; /* source "page" size in pixels */
} BitMapHeader;
</syntaxhighlight>

{{Note|title=Warning|text=This hex dump is shown only to help the reader understand how IFF chunks appear in a file. You cannot ever depend on any particular ILBM chunk being at any particular offset into the file. IFF files are composed, in their simplest form, of chunks within a FORM. Each chunk starts with a 4-letter chunkID, followed by a 32-bit length of the rest of the chunk. You must ''parse'' IFF files, skipping past unneeded or unknown chunks by seeking their length (+1 if odd length) to the next 4-letter chunk ID. In a real ILBM file, you are likely to encounter additional optional chunks. See the IFF Specification listed in [[IFF_Standard|IFF Standard]] for additional information on such chunks.}}

<pre>
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD
0010: 00000014 01400190 00000000 06000100 .....@..........
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..
0060: A0A0A0A0 90E0C0C0 C0D0A0E0 424F4459 ............BODY
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*... etc.

Interpretation:

'F O R M' length 'I L B M''B M H D'<-start of BitMapHeader chunk
0000: 464F524D 00016418 494C424D 424D4844 FORM..d.ILBMBMHD

length WideHigh XorgYorg PlMkCoRe <- Planes Mask Compression Reserved
0010: 00000014 01400190 00000000 06000100 .....@..........

TranAspt PagwPagh 'C A M G' length <- start of C-AMiGa View modes chunk
0020: 00000A0B 01400190 43414D47 00000004 .....@..CAMG....

dir include:
ViewMode 'C M A P' length R g b R <- ViewMode 800=HAM | 4=LACE
0030: 00000804 434D4150 00000030 001000E0 ....CMAP...0....

g b R g b R g b R g b R g b R g <- Rgb's are for reg0 thru regN
0040: E0E00000 20000050 30303050 50500030 .... ..P000PPP.0

b R g b R g b R g b R g b R g b
0050: 90805040 70707010 60E02060 E06080D0 ..P@ppp.`. `.`..

R g b R g b R g b R g b 'B O D Y'
0060: A0A0A0A0 90E0C0C0 C0D0A000 424F4459 ............BODY

length start of body data <- Compacted (Compression=1 above)
0070: 000163AC F8000F80 148A5544 2ABDEFFF ..c.......UD*...
0080: FFBFF800 0F7FF7FC FF04F85A 77AD5DFE ...........Zw.]. etc.

Simple CAMG ViewModes: HIRES=0x8000 LACE=0x4 HAM=0x800 HALFBRITE=0x80

( ILBMs may contain a LONGWORD ViewPort ModeID in CAMG )
</pre>

==== Interpreting ILBMs ====

ILBM is a fairly simple IFF FORM. All you really need to deal with to extract the image are the following chunks:

Information about the size, depth, compaction method (see interpreted hex dump above).

Optional Amiga ViewModes chunk. Most HAM and HALFBRITE ILBMs should have this chunk. If no CAMG chunk is present, and image is 6 planes deep, assume HAM and you’ll probably be right. Some Amiga ViewModes flags are HIRES=0x8000, LACE=0x4, HAM=0x800, HALFBRITE=0x80. 2.0 ILBM writers should write a full 32-bit mode ID in the CAMG. See the IFF Manual for more information on writing and interpreting 32-bit CAMG values.

RGB values for color registers 0 to N. Previously, 4-bit RGB components each left justified in a byte. These should now be stored as a full 8-bit RGB values by duplicating 4-bit values in the high and low nibble of the byte.

The pixel data, stored in an interleaved fashion as follows (each line individually compacted if BMHD Compression = 1):

<pre>
plane 0 scan line 0
plane 1 scan line 0
plane 2 scan line 0
...
plane n scan line 0
plane 0 scan line 1
plane 1 scan line 1
etc.
</pre>

Also watch for AUTH Author chunks and (c) copyright chunks and preserve any copyright information if you rewrite the ILBM.

==== ILBM BODY Compression ====

The BODY contains pixel data for the image. Width, Height, and depth (Planes) is specified in the BMHD.

If the BMHD Compression byte is 0, then the scan line data is not compressed. If Compression=1, then each scan line is individually compressed as follows:

<pre>while (not produced the desired number of bytes)

/* get a byte, call it N */

if (N >= 0 && N <= 127)
/* copy the next N+1 bytes literally */

if (N >= -127 && N <= -1)
/* repeat the next byte N+1 times */

if (N == -128)
/* skip it, presumably it's padding */</pre>
==== Interpreting the Scan Line Data ====

If the ILBM is not HAM or HALFBRITE, then after parsing and uncompacting if necessary, you will have N planes of pixel data. Color register used for each pixel is specified by looking at each pixel thru the planes. For instance, if you have 5 planes, and the bit for a particular pixel is set in planes 0 and 3:

<pre>
PLANE 4 3 2 1 0
PIXEL 0 1 0 0 1
</pre>

then that pixel uses color register binary 01001 = 9.

The RGB value for each color register is stored in the CMAP chunk of the ILBM, starting with register 0, with each register’s RGB value stored as one byte of R, one byte G, and one byte of B, with each component left justified in the byte. (i.e. Amiga R, G, and B components are each stored in the high nibble of a byte)

But, if the picture is HAM or HALFBRITE, it is interpreted differently. Hopefully, if the picture is HAM or HALFBRITE, the package that saved it properly saved a CAMG chunk (look at a hex dump of your file with ASCII interpretation - you will see the chunks - they all start with a 4-ASCII-char chunk ID). If the picture is 6 planes deep and has no CAMG chunk, it is probably HAM. If you see a CAMG chunk, the ‘CAMG’ is followed by the 32-bit chunk length, and then the 32-bit Amiga view mode flags.

HAM pictures will have the 0x800 bit set in CAMG chunk ViewModes. HALFBRITE pictures will have the 0x80 bit set. See the graphics library articles for more information on HAM and HALFBRITE modes.

==== Other ILBM Notes ====

Amiga ILBMs images must be stored as an even number of bytes in width. However, the ILBM BMHD field w (width) should describe the actual image width, not the rounded up width as stored.

ILBMs created with Electronic Arts IBM or Amiga ''Deluxe Paint II'' packages are compatible (though you may have to use a ‘.lbm’ filename extension on an IBM). The ILBM graphic files may be transferred between the machines (or between the Amiga and IBM sides your Amiga if you have a CBM Bridgeboard card installed) and loaded into either package.

=== FORM FTXT ===

The FTXT (Formatted TeXT) form is the standard format for sharing text on the Amiga. The console device clip and paste functions, in conjunction with the startup-sequence ''conclip'' command, pass clipped console text through the clipboard as FTXT.

By supporting reading and writing of clipboard device FTXT, your application will allow users to cut and paste text between your application, other applications, and Amiga Shell windows.

The FTXT form is very simple. Generally, for clip and paste operations, you will only be concerned with the CHRS (character string) chunks of an FTXT. There may be one or more CHRS chunks, each of which contains a non-NULL-terminated string of ASCII characters whose length is equal to the length (StoredProperty.sp_Size) of the chunk.

Be aware that if you CollectionChunk() the CHRS chunks of an FTXT, the list accumulated by IFFParse will be in reverse order from the chunk order in the file. See the ClipFTXT.c example at the end of this article for a simple example of reading (and optionally writing) FTXT to and from the clipboard. See also the [[Clipboard_Device|Clipboard Device]] and [[Console_Device|Console Device]] for more information on console clip and paste.

== IFFParse Examples ==

Two examples follow: “ClipFTXT.c” and “Sift.c”. These are simple examples that demonstrate the use of the IFFParse library. More complex examples for displaying and saving ILBMs may be found in the [[IFF_Standard|IFF Standard]] section.

=== Clipboard FTXT Example ===

ClipFTXT.c demonstrates reading (and optional writing) of clipboard device FTXT. This example may be used as the basis for supporting console pastes.

<syntaxhighlight>
/*
*
* clipftxt.c: Writes ASCII text to clipboard unit as FTXT
* (All clipboard data must be IFF)
*
* Usage: clipftxt unitnumber
*
* To convert to an example of reading only, comment out #define WRITEREAD
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

/* Causes example to write FTXT first, then read it back
* Comment out to create a reader only
*/
#define WRITEREAD

#define MINARGS 2

CONST_STRPTR usage = "Usage: clipftxt unitnumber (use zero for primary unit)";

/*
* Text error messages for possible IFFERR_#? returns from various
* IFF routines. To get the index into this array, take your IFFERR code,
* negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).",
"End of context (not an error).",
"No lexical scope.",
"Insufficient memory.",
"Stream read error.",
"Stream write error.",
"Stream seek error.",
"File is corrupt.",
"IFF syntax error.",
"Not an IFF file.",
"Required call-back hook missing.",
"Return to client. You should never see this."
};

#define RBUFSZ 512

#define ID_FTXT MAKE_ID('F','T','X','T')
#define ID_CHRS MAKE_ID('C','H','R','S')

struct IFFParseIFace *IIFFParse;

UBYTE mytext[]="This FTXT written to clipboard by clipftxt example.\n";

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
struct ContextNode *cn;
long error=0, unitnumber=0, rlen;
int textlen;
UBYTE readbuf[RBUFSZ];

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
return RETURN_WARN;
}

unitnumber = atoi(argv[1]);

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);

if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/*
* Allocate IFF_File structure.
*/
if (!(iff = IIFFParse->AllocIFF ()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) OpenClipboard (unitnumber)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
else IDOS->Printf("Opened clipboard unit %ld\n", unitnumber);

IIFFParse->InitIFFasClip (iff);

#ifdef WRITEREAD

/*
* Start the IFF transaction.
*/
if (error = IIFFParse->OpenIFF (iff, IFFF_WRITE))
{
IDOS->Printf("OpenIFF for write failed.\n");
goto bye;
}

/*
* Write our text to the clipboard as CHRS chunk in FORM FTXT
*
* First, write the FORM ID (FTXT)
*/
if(!(error = IIFFParse->PushChunk(iff, ID_FTXT, ID_FORM, IFFSIZE_UNKNOWN)))
{
/* Now the CHRS chunk ID followed by the chunk data
* We'll just write one CHRS chunk.
* You could write more chunks.
*/
if(!(error = IIFFParse->PushChunk(iff, 0, ID_CHRS, IFFSIZE_UNKNOWN)))
{
/* Now the actual data (the text) */
textlen = strlen(mytext);
if(IIFFParse->WriteChunkBytes(iff, mytext, textlen) != textlen)
{
IDOS->Printf("Error writing CHRS data.\n");
error = IFFERR_WRITE;
}
}
if(!error) error = IIFFParse->PopChunk(iff);
}
if(!error) error = IIFFParse->PopChunk(iff);

if(error)
{
IDOS->Printf("IFF write failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
goto bye;
}
else IDOS->Printf("Wrote text to clipboard as FTXT\n");

/*
* Now let's close it, then read it back
* First close the write handle, then close the clipboard
*/
IIFFParse->CloseIFF(iff);
if (iff->iff_Stream) CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);

if (!(iff->iff_Stream = (ULONG) OpenClipboard (unitnumber)))
{
IDOS->Printf("Reopen of Clipboard failed.\n");
goto bye;
}
else IDOS->Printf("Reopened clipboard unit %ld\n", unitnumber);

#endif /* WRITEREAD */

if (error = IIFFParse->OpenIFF (iff, IFFF_READ))
{
IDOS->Printf("OpenIFF for read failed.\n");
goto bye;
}

/* Tell iffparse we want to stop on FTXT CHRS chunks */
if (error = IFFParse->StopChunk(iff, ID_FTXT, ID_CHRS))
{
IDOS->Printf("StopChunk failed.\n");
goto bye;
}

/* Find all of the FTXT CHRS chunks */
while(1)
{
error = IIFFParse->ParseIFF(iff,IFFPARSE_SCAN);
if(error == IFFERR_EOC) continue; /* enter next context */
else if(error) break;

/* We only asked to stop at FTXT CHRS chunks
* If no error we've hit a stop chunk
* Read the CHRS chunk data
*/
cn = IIFFParse->CurrentChunk(iff);

if((cn)&&(cn->cn_Type == ID_FTXT)&&(cn->cn_ID == ID_CHRS))
{
IDOS->Printf("CHRS chunk contains:\n");
while((rlen = IIFFParse->ReadChunkBytes(iff,readbuf,RBUFSZ)) > 0)
{
IDOS->Write(Output(),readbuf,rlen);
}
if(rlen < 0) error = rlen;
}
}

if((error)&&(error != IFFERR_EOF))
{
IDOS->Printf ("IFF read failed, error %ld: %s\n",
error, errormsgs[-error - 1]);
}

bye:
if (iff) {
/*
* Terminate the IFF transaction with the stream. Free
* all associated structures.
*/
IIFFParse->CloseIFF (iff);

/*
* Close the clipboard stream
*/
if (iff->iff_Stream)
CloseClipboard ((struct ClipboardHandle *)
iff->iff_Stream);
/*
* Free the IFF_File structure itself.
*/
IIFFParse->FreeIFF (iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary (IFFParseBase);

return RETURN_OK;
}
</syntaxhighlight>

=== IFF Scanner Example ===

"Sift.c" lists the type and size of every chunk in an IFF file and, and checks the IFF file for correct syntax. You should use "Sift" to check IFF files created by your programs.

<syntaxhighlight>
/*
*
* sift.c: Takes any IFF file and tells you what's in it. Verifies syntax and all that cool stuff.
*
* Usage: sift -c ; For clipboard scanning
* or sift <file> ; For DOS file scanning
*
* Reads the specified stream and prints an IFFCheck-like listing of the contents of the IFF file, if any.
* Stream is a DOS file for <file> argument, or is the clipboard's primary clip for -c.
* This program must be run from a CLI.
*
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <libraries/dos.h>
#include <libraries/iffparse.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/iffparse.h>

#include <stdlib.h>
#include <string.h>

#define MINARGS 2

CONST_STRPTR usage = "Usage: sift IFFfilename (or -c for clipboard)";

void PrintTopChunk(struct IFFHandle *); /* prototype for our function */

/*
* Text error messages for possible IFFERR_#? returns from various IFF routines. To get the index into
* this array, take your IFFERR code, negate it, and subtract one.
* idx = -error - 1;
*/
char *errormsgs[] = {
"End of file (not an error).", "End of context (not an error).", "No lexical scope.",
"Insufficient memory.", "Stream read error.", "Stream write error.",
"Stream seek error.", "File is corrupt.", "IFF syntax error.",
"Not an IFF file.", "Required call-back hook missing.", "Return to client. You should never see this."
};

struct IFFParseIFace *IIFFParse = NULL;

int main(int argc, char **argv)
{
struct IFFHandle *iff = NULL;
int32 error;
int16 cbio;

/* if not enough args or '?', print usage */
if(((argc)&&(argc<MINARGS))||(argv[argc-1][0]=='?'))
{
IDOS->Printf("%s\n", usage);
goto bye;
}

/* Check to see if we are doing I/O to the Clipboard. */
cbio = (argv[1][0] == '-' && argv[1][1] == 'c');

struct Library *IFFParseBase = IExec->OpenLibrary("iffparse.library", 50);
IIFFParse = (struct IFFParseIFace*)IExec->GetInterface(IFFParseBase, "main", 1, NULL);
if (IIFFParse == NULL)
{
IDOS->Printf("Can't open iff parsing library.\n");
goto bye;
}

/* Allocate IFF_File structure. */
if (!(iff = IIFFParse->AllocIFF()))
{
IDOS->Printf("AllocIFF() failed.\n");
goto bye;
}

/*
* Internal support is provided for both AmigaDOS files, and the clipboard.device. This bizarre
* 'if' statement performs the appropriate machinations for each case.
*/
if (cbio)
{
/*
* Set up IFF_File for Clipboard I/O.
*/
if (!(iff->iff_Stream = (ULONG) IIFFParse->OpenClipboard(PRIMARY_CLIP)))
{
IDOS->Printf("Clipboard open failed.\n");
goto bye;
}
IIFFParse->InitIFFasClip(iff);
}
else
{
/* Set up IFF_File for AmigaDOS I/O. */
if (!(iff->iff_Stream = IDOS->Open(argv[1], MODE_OLDFILE)))
{
IDOS->Printf("File open failed.\n");
goto bye;
}
IIFFParse->InitIFFasDOS(iff);
}

/* Start the IFF transaction. */
if (error = IIFFParse->OpenIFF(iff, IFFF_READ))
{
IDOS->Printf("OpenIFF failed.\n");
goto bye;
}

while (1)
{
/*
* The interesting bit. IFFPARSE_RAWSTEP permits us to have precision monitoring of the
* parsing process, which is necessary if we wish to print the structure of an IFF file.
* ParseIFF() with _RAWSTEP will return the following things for the following reasons:
*
* Return code: Reason:
* 0 Entered new context.
* IFFERR_EOC About to leave a context.
* IFFERR_EOF Encountered end-of-file.
* <anything else> A parsing error.
*/
error = IIFFParse->ParseIFF(iff, IFFPARSE_RAWSTEP);

/*
* Since we're only interested in when we enter a context, we "discard" end-of-context
* (_EOC) events.
*/
if (error == IFFERR_EOC)
continue;
else if (error)
/*
* Leave the loop if there is any other error.
*/
break;

/* If we get here, error was zero. Print out the current state of affairs. */
PrintTopChunk(iff);
}

/*
* If error was IFFERR_EOF, then the parser encountered the end of
* the file without problems. Otherwise, we print a diagnostic.
*/
if (error == IFFERR_EOF)
IDOS->Printf("File scan complete.\n");
else
IDOS->Printf("File scan aborted, error %ld: %s\n",
error, errormsgs[-error - 1]);

bye:
if (iff) {
/* Terminate the IFF transaction with the stream. Free all associated structures. */
IIFFParse->CloseIFF(iff);

/*
* Close the stream itself.
*/
if (iff->iff_Stream)
if (cbio)
IIFFParse->CloseClipboard((struct ClipboardHandle *)iff->iff_Stream);
else
IDOS->Close(iff->iff_Stream);

/* Free the IFF_File structure itself. */
IIFFParse->FreeIFF(iff);
}
IExec->DropInterface((struct Interface*)IIFFParse);
IExec->CloseLibrary(IFFParseBase);

return RETURN_OK;
}

void PrintTopChunk(struct IFFHandle *iff)
{
struct ContextNode *top;
int32 i;
char idbuf[5];

/* Get a pointer to the context node describing the current context. */
if (!(top = IIFFParse->CurrentChunk(iff)))
return;

/*
* Print a series of dots equivalent to the current nesting depth of chunks processed so far.
* This will cause nested chunks to be printed out indented.
*/
for (i = iff->iff_Depth; i--; )
IDOS->Printf(". ");

/* Print out the current chunk's ID and size. */
IDOS->Printf("%s %ld ", IIFFParse->IDtoStr(top->cn_ID, idbuf), top->cn_Size);

/* Print the current chunk's type, with a newline. */
IDOS->Printf(IIFFParse->IDtoStr(top->cn_Type, idbuf));
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the IFFParse functions discussed in this article. Further information about these and other IFFParse functions can be found in the SDK.

{| class="wikitable"
! Function
! Description
|-
| AllocIFF()
| Creates an IFFHandle structure.
|-
| FreeIFF()
| Frees the IFFHandle structure created with AllocIFF().
|-
| OpenIFF()
| Initialize an IFFHandle structure to read or write an IFF stream.
|-
| CloseIFF()
| Closes an IFF context.
|-
| InitIFF()
| Initialize an IFFHandle as a user-defined stream.
|-
| InitIFFasDOS()
| Initialize an IFFHandle as an AmigaDOS stream.
|-
| InitIFFasClip()
| Initialize an IFFHandle as a clipboard stream.
|-
| OpenClipboard()
| Create a handle on a clipboard unit for InitIFFasClip().
|-
| ParseIFF()
| Parse an IFF file from an IFFHandle stream.
|-
| ReadChunkBytes()
| Read bytes from the current chunk into a buffer.
|-
| ReadChunkRecords()
| Read record elements from the current chunk into a buffer.
|-
| StopChunk()
| Declare a chunk that should cause ParseIFF() to return.
|-
| CurrentChunk()
| Get the context node for the current chunk.
|-
| PropChunk()
| Specify a property chunk to store.
|-
| FindProp()
| Search for a stored property in a given context.
|-
| CollectionChunk()
| Declare a chunk type for collection.
|-
| FindCollection()
| Get a pointer to the current list of collection items.
|-
| StopOnExit()
| Declare a stop condition for exiting a chunk.
|-
| EntryHandler()
| Add an entry handler to the IFFHandle context.
|-
| ExitHandler()
| Add an exit handler to the IFFHandle context.
|-
| PushChunk()
| Push a given context node onto the top of the context stack.
|-
| PopChunk()
| Pop the top context node off of the context stack.
|-
| CurrentChunk()
| Get the top context node for the current chunk.
|-
| ParentChunk()
| Get the nesting context node for a given chunk.
|-
| AllocLocalItem()
| Create a LocalContextItem (LCI) structure.
|-
| LocalItemData()
| Returns a pointer to the user data of a LocalContextItem (LCI).
|-
| StoreLocalItem()
| Insert a LocalContextItem (LCI).
|-
| StoreItemInContext()
| Store a LocalContextItem in a given context node.
|-
| FindPropContext()
| Find the property context for the current state.
|-
| FindLocalItem()
| Return a LocalContextItem from the context stack.
|-
| FreeLocalItem()
| Free a LocalContextItem (LCI) created with AllocLocalItem().
|-
| SetLocalItemPurge()
| Set purge vector for a local context item.
|}

Application Library

2017-05-31T14:37:30Z

Daniel Jedlicka: /* Minimum Application Library Support */

== Introduction ==

The Application Library is a multipurpose auxiliary library that provides various functions related to the development and use of applications. The very concept of ''application'' is a relatively recent addition to AmigaOS. Before, the system only distinguished between different types of program on a very low level, seeing them as either [[Exec_Tasks|tasks]] or [[AmigaDOS_Data_Structures#Process_Data_Structures|processes]]. This distinction might have been useful in the past when tasks (which require fewer resources in return for not being able to access DOS functions) could improve system performance. But it can hardly make a difference on today’s hardware so the trade-offs are no longer worth it. Nowadays it makes more sense to discriminate between programs that operate without the user even noticing (e.g. drivers, handlers, filesystems and other ''background services''), and genuine full-blown ''applications'' with [[UI_Style_Guide_Glossary#GUI|GUI]] and all.

AmigaOS alone cannot make such a distinction: it uses the Application Library as a mediator through which applications introduce themselves to the system. This process is called [[#Registering the Application|application registration]], during which the application receives a [[#Application Identifiers|unique identifier]] and is added to a public list among other applications. Once registered, the application can make use of the library’s many features:

* It can send/receive messages to/from other registered applications. The library supports a set of common [[#Control Messages|control messages]] (commands) such as those telling an application to quit, iconify or bring its window to front. But it also allows [[#Custom Messages|custom messages]] designed for an application’s particular needs; in this respect the Application Library provides an alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]] control.

* It can turn into a “watchdog” and get notified when other applications register.

* It can use [[PrefsObjects]], an XML-based, object-oriented system for handling program preferences. Before AmigaOS 4.x no real standard existed for storing preferences: some developers used icon tooltypes, some used proprietary formats, text or binary. The Application Library provides a format that is human-readable and easily editable in a simple text editor; that is comprehensive enough to cover even very complex settings structures; and that is fully controllable via the library, without the need to laboriously implement data parsing and verification.

* It can notify the user about, for example, completed tasks via automatic [[#Pop-up Notifications (Ringhio Messages)|pop-up messages]]. These represent a practical, less obtrusive alternative to traditional requesters.

* It can easily create and manage lists of recently-used documents.

* It can register as a ''unique application'', preventing other instances of itself from running.

* It can show its icon or display the current program state in taskbar-like applications, such as AmiDock.

* It can control the behaviour of screen-blankers. Applications that don’t want to be disturbed may prevent the blanker from kicking in, or tell other applications to “keep quiet”.

=== Frequently Asked Questions ===

{| class="wikitable"
|-
|''Q: Should my programs register with the Application Library?''
|A: Yes, that would make a lot of sense. Apart from access to the handy features mentioned above, the implementation of certain library features may improve the behaviour of your application within the AmigaOS ecosystem.
|-
|''Q: After registering with the library, will my application become controlled by the OS or by other applications?''
|A: No. The registration process alone does not turn on any features. There is a recommendation to allow a [[#Minimum Application Library Support|minimum degree of control]], but in the end it is the programmer who decides what functionality offered by the library will be provided and supported in his/her application. That also includes the scope of external control: if you don't want your application to be controlled beyond a certain limit, your code will simply not react to certain incoming [[#Control Messages|control messages]].
|-
|''Q: Doesn't the Application Library duplicate functionality already present in commodities?''
|A: No. The only similarity between the two is that programs register with some system library, which then acts as a control centre. [[Commodities_Exchange_Library|Commodities]] provide a way to install custom input handlers into the [[Input_Device|Input Device]]'s event stream. The Application Library's field and scope of operation is completely different (and much wider).
|-
|''Q: Why is this a library? Wouldn't it be wiser to implement it as a class, like MUI does it?''
|A: This would tie the functionality to the object-oriented (BOOPSI) API – applications designed using [[GUI_Programming#The_Two_Frameworks|other APIs or toolkits]] would not be able to use it.
|-
|''Q: Can a program be registered both as an application and as a commodity?''
|A: Yes, that's possible – although few programs would probably benefit from that. Exceptions include application managers and taskbars (e.g. AmiDock), which may need to control other applications and, at the same time, behave like a commodity.
|-
|''Q: Being XML-based, do the PrefsObjects introduce any overhead to the operating system?''
|A: Hardly any. The [[PrefsObjects]] .xml preference files are, typically, only read when the application starts and written at user request, so there is minimum overhead involved. Accessing the prefs file during program runtime doesn't put any strain on the OS either, as the Application Library caches the file in a pre-parsed format in memory.
|}

=== Minimum Application Library Support ===

In the foreseeable future, AmigaOS will feature an application manager to control running applications. (A third-party solution called [http://wiki.amiga.org/index.php?title=Exchanger Exchanger] is already available.) The idea is to provide a single, universal control point for both commodities and applications. In order to allow easy, consistent and predictable program control, developers are encouraged to [[#Registering the Application|register their applications]] and implement the following suggested minimum Application Library support:

* Provide a short [[#Description|description]] for a better identification of the application.
* Tell the OS whether your application supports iconification, that is, hiding/showing its GUI. If iconification is supported:
** set the REGAPP_HasIconifyFeature registration tag to TRUE;
** make the application respond to the [[#Control Messages|APPLIBMT_Hide and APPLIBMT_Unhide]] control messages;
** update the APPATTR_Hidden attribute accordingly each time your application iconifies or uniconifies.
* Allow the application to be shut down externally in a safe and graceful manner in reaction to the [[#Control Messages|APPLIBMT_Quit]] message.

A failure to implement this suggested minimum will mean that the application manager will be unable to control your application properly and consistently. This may cause confusion on the part of the users and degrade their AmigaOS experience.

== Library Opening Chores ==

{{Note|title=Note|text=Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2. This is due to changes in the Application Library API which had broken standard tag support until version 2 interfaces were introduced.}}

Just like other AmigaOS libraries, the Application Library must be opened before it is used. Further, at least one of its interfaces must be obtained, depending on the functionality you require. The Application Library has two interfaces, called “application” and “prefsobjects”. You always need to obtain the “application” interface because it provides access to most library functions including application registration. You’ll only need to open the “prefsobjects” interface if you intend to make use of the PrefsObjects preferences system.

<syntaxhighlight>
struct Library *ApplicationBase = NULL;
struct ApplicationIFace *IApplication = NULL;
struct PrefsObjectsIFace *IPrefsObjects = NULL;

if ( (ApplicationBase = IExec->OpenLibrary("application.library", 52)) )
{
IApplication = (struct ApplicationIFace *) IExec->GetInterface(ApplicationBase,
"application", 2, NULL);
IPrefsObjects = (struct PrefsObjectsIFace *) IExec->GetInterface(ApplicationBase,
"prefsobjects", 2, NULL);
}

if ( !ApplicationBase || !IApplication || !IPrefsObjects )
{
/* handle library opening error */
}
</syntaxhighlight>

Note that there is no interface called “main” like older, single-interface libraries have. The number in the GetInterface() call above refers to the version of the interface. Library interfaces are not backwards or forwards compatible so they must be specified precisely. '''Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2.''' This is due to certain changes in the Application Library API.

When your application has run its course, don’t forget to clean up and close both the library and its interface(s):

<syntaxhighlight>
IExec->DropInterface((struct Interface *)IPrefsObjects);
IExec->DropInterface((struct Interface *)IApplication);
IExec->CloseLibrary(ApplicationBase);
</syntaxhighlight>

== Registering the Application ==

Application registration is a simple process during which a program informs AmigaOS that it should be treated as an application, and provides some basic information about itself: the program name, an associated URL address, or a short description. Also, certain application-related properties can be set at registration time (although some of these may be provided or changed later). Registration typically takes place at program startup; unregistration is normally done at the end of program runtime.

*hint* Avoid using the _ underscore character in the registered name. These may cause "charsetconvert" errors when the system boots up later.

=== Application Identifiers ===

A successfully registered application receives a numeric identifier, which in this documentation will be referred to as ''appID''. The identifier is public: any registered application can obtain another application’s appID (see [[#Finding Applications|Finding Applications]] below) and use it to communicate with the respective application. AppIDs are unique integer numbers: the library generates them incrementally on a per-registration basis. They are never assigned again during the same AmigaOS session, which prevents programs from incidentally addressing the wrong application after the original appID holder unregisters.

Apart from the numeric appID an application can be referred to by its name (that is, a string-type identifier). As programs can get registered in an arbitrary order (and the same application will have a different appID each time), it is the name identifier that other applications must use to retrieve the correct appID. To construct a unique name, the Application Library uses a special naming scheme that combines:

* the application name;
* an instance count (if more than one instance of the same application is started);
* a URL identifier (for example, the domain name of the application’s homepage – optional).

The same naming scheme is used by the library’s PrefsObjects system to create the name of the preferences file.

=== Registration Functions ===

Now let’s say we have a program, a media player called Audio Monster created by the fictitious software company SuperCoders, Inc. The piece of C code to handle its registration (and unregistration) might look like this:

<syntaxhighlight>
uint32 appID;

appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
TAG_END);

if (!appID)
{
/* report registration error and quit */
}

/*
do whatever your program does
*/

IApplication->UnregisterApplication(appID, NULL);
</syntaxhighlight>

Note that we’ve had to alter the application name to “AudioMonster”; it is because the Application Library doesn’t allow spaces in application names. According to the naming scheme (outlined in the previous section) the application will now become registered under the name “AudioMonster.supercoders.com”. (Should a previous instance of Audio Monster be already running, the library will automatically append an instance counter to the application name: the second instance will therefore be called “AudioMonster_1.supercoders.com”, the third will register as “AudioMonster_2.supercoders.com”, and so on.)

Also note that the URL identifier is just the domain name, i.e. without the “www.” part. The identifier is only used to distinguish between applications, not to access their homepages. The domain name is, therefore, sufficient; the resulting name identifier needn’t be long and quirky.

After calling UnregisterApplication() the program will be removed from the public list, and Application Library features will no longer be available.

== Application Attributes ==

An application is described by a set of ''attributes''. There are attributes that describe the application's properties or feature set, indicate its current state, or determine its behaviour. Some attributes are only specified at registration time and cannot be altered once they are set, while others can be changed freely (as long as the application remains registered, of course). The general recommendation is to specify at registration time all properties that are not going to change during program lifetime: i.e. define all "static" application features in one place.

=== Description ===
The REGAPP_Description tag, used in the registration example code above, tells the system what the application is all about. Although the description is an optional attribute, it is recommended to always provide it, as it will allow application manager or taskbar programs to provide meaningful information to the user. Keep the description short, matter-of-fact and serious.

The application description cannot be changed after registration.

=== Uniqueness ===
A program can register as a ''unique application'', thus only allowing one instance of itself to run. While the multitasking nature and tradition of AmigaOS would suggest not imposing such limits, there sometimes can be good reasons to do so. For example, the developer of the Audio Monster player might decide to make his/her program a unique application because the user would most likely gain nothing from playing several media files at the same time. Multiple program instances would only compete for screen space and system resources, possibly jeopardizing OS performance on lower-specification computers.

The following function call will register Audio Monster as a unique application:

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_UniqueApplication, TRUE,
TAG_END);
</syntaxhighlight>

If the user now tries to launch a second instance of the program, it will fail on RegisterApplication() and the library will send a [[#Special Messages|special message]] to the first instance informing it about the attempt. It is the developer’s responsibility to react to this message in a sensible way. Do not show error messages here: the user doesn’t need to know (or care) that the application is unique, so an error message would scold them for doing nothing wrong. The recommended behaviour is to bring the first instance to view and activate its window.

Quite logically, uniqueness is an attribute that cannot be changed after registration.

=== Feature Set / Control Scope ===
Different applications can implement different control features, and can be designed for a different scope of external control. For example, a text editor may respond to a [[#Control Messages|control message]] (command) that tells it to create a new, blank, unnamed document, whereas in a media player such a command would be best ignored. Similarly, a simple tool with no configuration capability would want to stay clear of messages that control program settings. It is always good manners to inform the system about the scope of control your application supports, as other applications may query about (and rely on) this information when sending control messages. Always set the following boolean tags to TRUE in the RegisterApplication() call if your application implements support for the respective feature (the default value is FALSE):

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_HasIconifyFeature
|The application supports iconification and uniconification.
|Set to TRUE if your application responds to the APPLIBMT_Hide and APPLIBMT_Unhide messages.
|-
|REGAPP_HasPrefsWindow
|The application has a dedicated Preferences (Settings) window.
|Set to TRUE if your application responds to the APPLIBMT_OpenPrefs message.
|-
|REGAPP_CanCreateNewDocs
|The application can create new documents (projects).
|Set to TRUE if your application responds to the APPLIBMT_NewBlankDoc message.
|-
|REGAPP_CanPrintDocs
|The application can print documents.
|Set to TRUE if your application responds to the APPLIBMT_PrintDoc message.
|}

These four attributes can be changed after registration.

=== Receiving Notifications ===

The Application Library can send certain notification messages that may be of interest to special-purpose programs like application managers, taskbars or screen blankers. If you are developing such a program, you may want to register for the following notifications:

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_AppNotifications
|Receive notifications about application registration/unregistration, icon type changes, GUI state changes (hidden/unhidden), and changes in the last used applications/documents list.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to application managers and taskbar-like programs.
|-
|REGAPP_BlankerNotifications
|Receive notifications concerning blanker activity.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to screen blankers.
|}

Other types of application should not normally ask to receive these notifications: they would only increase traffic along their input stream.

These two attributes can be changed after registration.

=== Changing Application Attributes ===

Certain attributes describe "dynamic" application properties and, as such, can be set or changed after registration. Some of these are ''state attributes'' that need to be updated each time your program changes state (shows/hides its GUI, or enters the game mode; see below in the table). Some are not really attributes but, rather, commands that invoke an application-related action.

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|APPATTR_AllowsBlanker
|Same as REGAPP_AllowsBlanker above.
|You may want to be able to enable/disable blanking dynamically during application runtime – this what the APPATTR_AllowsBlanker tag is for. For example, a presentation program may allow blankers while the presentation is being worked on, and disable them when the presentation is started.
|-
|APPATTR_AppOpenedDocument
|Adds a new entry to the application's Last Used Documents list.
|Set this tag each time your application has successfully opened a named document or project. The parameter to this tag is a pointer to the name string (i.e. a STRPTR).
|-
|APPATTR_AppNotifications APPATTR_BlankerNotifications
|Same as the two corresponding [[#Receiving Notifications|registration tags]] above.
|
|-
|APPATTR_CanCreateNewDocs APPATTR_CanPrintDocs APPATTR_HasIconifyFeature APPATTR_HasPrefsWindow
|Same as the four corresponding [[#Feature Set / Control Scope|registration tags]] above.
|Prefer setting these properties at registration time.
|-
|APPATTR_ClearLastUsedDocs
|Clears the application's list of last used documents.
|Set this tag to TRUE to clear the list. (Note that this is not really an attribute but, rather, a command.)
|-
|APPATTR_FlushPrefs
|
|
|-
|APPATTR_Hidden
|A boolean program-state attribute indicating whether the application is currently iconified (hidden) or not.
|Update this attribute each time your application GUI changes state, as application managers may query about (and rely on) this information.
|-
|APPATTR_IconType
|Changes the application icon type.
|
|-
|APPATTR_MainPrefsDict
|Allows changing the application's Prefs dictionary.
|
|-
|APPATTR_NeedsGameMode
|A boolean program-state attribute informing the system (and other applications) that the program is about to enter, or has left, the game mode.
|By the "game mode" we understand a mode in which an application doesn't want to be "disturbed" by other applications. It normally assumes full screen operation, and possibly taking over the audio system. Games or presentation programs are examples of applications that may want to implement the game mode, in which other programs are simply asked to “keep quiet”: not try to play sounds, open windows, requesters, etc. This feature assumes discipline and cooperation on the part of other applications; please use it moderately and only enter the game mode when it is really needed. Also note that setting APPATTR_NeedsGameMode to TRUE does not guarantee that other applications will comply.
|-
|APPATTR_SavePrefs
|Same as REGAPP_SavePrefs above.
|
|}

The function to set or change application attributes is SetApplicationAttrs(). It is very similar to SetAttrs() used in Intuition programming, only the first parameter is not a pointer to a BOOPSI object but an application identifier. The appID is followed by a tag list, so several attributes can be set at a time. The following example call will inform the system that the application has iconified (or otherwise hidden its GUI) and that the screen blanker can now come to front freely (assuming that the blanker was forbidden before for some reason). The result value indicates whether the call was successful or not:

<syntaxhighlight>
BOOL result;

result = IApplication->SetApplicationAttrs(appID,
APPATTR_Hidden, TRUE,
APPATTR_AllowsBlanker, TRUE,
TAG_END);
</syntaxhighlight>

== Finding Applications ==

The Application Library maintains a public list of all registered applications. Certain special-purpose programs – ''application managers'' – will read this list (also keeping track of all subsequent registrations and unregistrations) and offer some degree of control: display information about applications and/or send commands telling them to do something. Quite naturally, most programs will not (nor are they supposed to!) act as managers but a need to talk to another application may arise. How do you find it, then?

Finding an application basically means obtaining its appID: it is an identifier as well as a “contact address” for the library's messaging system. To do this you need to know at least one of the following:

* the application name, ie. the one under which it was registered via RegisterApplication();
* the application name identifier, ie. the unique combination of the application’s name, instance number (should there be more instances running) and URL identifier – see [[#Application Identifiers|Application identifiers]] above;
* the pathname pointing to the program file on disk, e.g. “Work:Utils/AudioMonster”.

Based on this information, the respective piece of code that will find our application in the system might look like this:

<syntaxhighlight>
uint32 appID;

/* if you only know the application name */
appID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster",
TAG_END);

/* if you know the application name identifier */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster.supercoders.com",
TAG_END);

/* if you specifically want to talk to the second running instance */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster_1.supercoders.com",
TAG_END);

/* if you know the pathname to the program file */
appID = IApplication->FindApplication(FINDAPP_FileName, "Work:Utils/AudioMonster",
TAG_END);
</syntaxhighlight>

Once you have obtained the appID you can start communicating with the respective application.

== Messaging ==

Messages are used extensively in AmigaOS: the inner workings of Exec or Intuition actually involve a good deal of message passing. But it’s not just the operating system that needs to communicate. Modern software applications often want to talk to other running applications. Regardless of whether this communication will, in real use, entail a simple command-driven action or an intricate exchange of data, AmigaOS provides the necessary means: inter-program communication is supported on the low level (through Exec Library’s [[Exec Messages and Ports|messages and ports]]) as well as on the high level (using the ARexx-language scripting features). The Application Library has introduced yet another means of communication, which can be seen as lying somewhere in between the two levels.

Provided that you know its appID, you can send messages to any running application that is ready to accept them. You can even send a message to all applications at once! Basic application control can be achieved via a set of [[#Control Messages|predefined messages]] that correspond to common program commands and functions (such as New, Open, Print, Iconify or Quit). But the library also supports [[#Custom Messages|custom messages]], thus allowing for more sophisticated control or information exchange. The extent and complexity of messaging is fully up to the programmer: your application will only send/receive messages that you will implement (it has already been mentioned in the [[#Frequently Asked Questions|Frequently Asked Questions]] section above that registration alone does not magically turn on any features).

Furthermore, apart from this “invisible”, abstract communication taking place between application ports, you can use the library to provide real and visible information in the form of pop-up notification messages. However, as these are different and not really within the scope of the Application Library messaging framework, they are dealt with in a [[#Pop-up Notifications (Ringhio Messages)|separate section]] of this document.

{{Note|Before we get any further with Application Library messages, it must be made clear that they should not be confused with the similarly-named ''AppMessages''. The latter are a completely different breed, governed by the Workbench Library. They represent a specific way of communication between the Workbench desktop environment and running applications. It’s strictly one-way communication because Workbench can send AppMessages to applications but applications cannot send AppMessages to Workbench. (If you want to learn more about the use of AppMessages, consult the [[Workbench Library|Workbench Library]] section of the AmigaOS documentation wiki).
}}

=== Data Structures ===

Rather than introduce yet another system for communication, the Application Library builds upon the existing [[Exec_Messages_and_Ports|Exec messaging framework]]. Programmers will, therefore, find working with Application Library messages rather familiar. For instance, the library uses data structures that are in fact extensions of the standard Exec message structure. Also, the usual procedure of [[Exec_Messages_and_Ports#Getting_a_Message|GetMsg()]] and [[Exec_Messages_and_Ports#Replying|ReplyMsg()]] takes place when processing incoming Application Library messages (see section [[#Message Handling|Message Handling]] below) – although the library implements its own method for [[#Sending Messages|sending messages]].

The following three structures are defined for carrying Application Library message data:

<syntaxhighlight>
struct ApplicationMsg
{
struct Message msg;
uint32 senderAppID; // the appID of the sender application
uint32 type; // identifies the type of message
};

struct ApplicationOpenPrintDocMsg
{
struct ApplicationMsg almsg;
STRPTR fileName;
};

struct ApplicationCustomMsg
{
struct ApplicationMsg almsg;
STRPTR customMsg;
};
</syntaxhighlight>

As you can see, structure ''ApplicationMsg'' contains a standard ''[[Exec_Messages_and_Ports#Messages|struct Message]]'', the other fields are used for Application Library-specific data. The other two structures are mere extensions of the basic one: ''ApplicationOpenPrintDocMsg'' is used by certain [[#Control Messages|control messages]] that require a pointer to a filename; the ''ApplicationCustomMsg'' structure is used for [[#Custom Messages|custom messages]].

Upon message arrival you identify the message by reading the “type” field of the respective data structure. Similarly, if you want to [[#Sending Messages|send a message]] to an application you specify it in the “type” field.

=== Control Messages ===

The Application Library allows registered applications to send messages that control other applications. There is a set of predefined messages (or rather, commands) that can be sent to a running application, telling it – for example – that it should come to front, quit, open a document, create a new one, and so on. As these actions are common program functions, the library offers a practical and easy-to-implement way to control applications externally. The following control messages (commands) are currently provided:

{| class="wikitable"
!Message name
!Description
!Implementation notes
|-
|APPLIBMT_Quit
|The application is asked to shut down itself and quit.
|Basically, upon receiving this message you should react as if your main program window received the WMHI_CLOSEWINDOW event. When implementing support for APPLIBMT_Quit, the programmer is required to design the program exit sequence in such a way that no unexpected data loss can occur (for example, by displaying a confirmation requester that allows the user to save work or cancel the quit command).
|-
|APPLIBMT_ForceQuit
|Same as before but this time the application shall quit immediately, without asking for saving documents etc.
|Providing this command as part of the Application Library messaging framework was surely meant well but there is an inherent risk: a malevolent application could hamper the use of other applications by sending them this message and making them quit prematurely. So implement APPLIBMT_ForceQuit with care, or don't implement it at all. The official AmigaOS application manager will never try to send APPLIBMT_ForceQuit in order to shut down running applications.
|-
|APPLIBMT_Hide
|The application shall hide its interface and iconify on the Workbench screen.
|rowspan="2"|An application that supports APPLIBMT_Hide and APPLIBMT_Unhide is expected to register itself with REGAPP_HasIconifyFeature set to TRUE. Basically, upon receiving this message you should react as if your main program window received the WMHI_ICONIFY / WMHI_UNICONIFY event.
|-
|APPLIBMT_Unhide
|The application shall come back from the iconified (hidden) state.
|-
|APPLIBMT_ToFront
|The application window shall come to front.
|Programmatically that entails calling the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. See the end of the [[#Message Handling|Message Handling]] section for a note on APPLIBMT_ToFront.
|-
|APPLIBMT_OpenPrefs
|The application shall open its preferences window.
|Only implement if your application has a dedicated Preferences (Settings) window. An application that supports APPLIBMT_OpenPrefs is expected to register itself with the REGAPP_HasPrefsWindow set to TRUE.
|-
|APPLIBMT_ReloadPrefs
|The application shall reload its preferences.
|Whatever this command is useful for.
|-
|APPLIBMT_NewBlankDoc
|The application shall open a new, blank document or project.
|Applications such as web browsers can, too, make use of this command to open new program windows. An application that supports APPLIBMT_NewBlankDoc is expected to register itself with the REGAPP_CanCreateNewDocs set to TRUE.
|-
|APPLIBMT_OpenDoc
|The application shall try to open a specific document or project.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above).
|-
|APPLIBMT_PrintDoc
|The application shall try to print a specific document.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above). An application that supports APPLIBMT_PrintDoc is expected to register itself with the REGAPP_CanPrintDocs set to TRUE.
|}

An application will only react to messages that are implemented and supported. If you [[#Sending Messages|send a message]] to an application that is registered but does not perform any Application Library event handling, there will be no reaction at all. Further, many applications will only implement a subset of the available control commands: if a program does not have a Print function, an APPLIBMT_PrintDoc message will quite logically be ignored. There is no rule saying which or how many control messages should be implemented but you are encouraged to provide the [[#Minimum Application Library Support|minimum suggested support]] as outlined above. Implement the rest according to your application’s features and needs, and to the highest standards of security.

=== Custom Messages ===

In contrast to a [[#Control Messages|control message]] (see above), a custom message has no meaning or purpose predefined by the library. It is a simple text string the actual meaning of which is determined by the application. There is some undeniable beauty in this concept. For instance, the application can define a set of “publicly available” commands that call a corresponding function whenever a particular command (text string) arrives from another application. This kind of external control is very easy to implement and represents a practical alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]], while requiring less setup. Also, sender applications need not care about internals (such as knowing the ARexx port name) – all it takes is to [[#Finding Applications|find]] the receiver application and [[#Sending Messages|send a message]] to it.

The pointer to the message text string is contained in a special [[#Data Structures|data structure]], ''struct ApplicationCustomMsg''.

=== Special Messages ===

There are also some special messages that an application can receive from the library or another running application:

{| class="wikitable"
! Message name !! Description !! Implementation notes
|-
| APPLIBMT_Unique || If an application is registered as [[#Uniqueness|unique]] and the user attempts to start a second instance of the program, the attempt will fail and the library will send an APPLIBMT_Unique message to the first instance. || All unique applications should listen for this message and react to it: not doing so might leave the user puzzled as to why the program hasn’t started. The recommended reaction is to bring the first instance to view and focus. This may entail a couple of steps, like uniconifying (if the program is iconified at the moment), swapping screen (if the program runs on a dedicated screen), bringing the program window to front, and activating it. Basically, the APPLIBMT_Unique message should be treated in the same way as the APPLIBMT_ToFront message.
|-
| APPLIBMT_GameModeEntered || Sent to all currently running applications if another application enters the “game mode” – that is, a state in which it doesn’t want to be disturbed. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to TRUE.
|-
| APPLIBMT_GameModeLeft || Informs all running application that the sender has left the game mode. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to FALSE.
|}

=== Message Handling ===

You already know that messaging in AmigaOS takes place between [[Exec_Messages_and_Ports#Message_Ports|message ports]]. Being a superset of standard Exec messages, Application Library notifications (be they predefined [[#Control Messages|control messages]], [[#Custom Messages|custom messages]] or [[#Special Messages|special messages]]) are, too, sent to a message port. We’ll call this dedicated port – in order to distinguish it from other ports possibly used by the program – the ''notification port''. The port is automatically created by the library at registration time and freed as part of the UnregisterApplication() call. Messages arriving at the port are meant to be processed within the program’s main event loop, together with other events (such as Intuition’s [[Intuition_Input_and_Output_Methods#Receiving_Input_Events_from_Intuition|IDCMP messages]]). To process incoming messages you first need to obtain the notification port pointer from the library and then set the port’s signal bit. The signal bit is used to identify messages as Application Library notifications.

A simplified event loop code could look like the one below. Note that this example loop only waits for and processes Application Library messages. In real use you'll also want to handle other message types, such as input from the user interface (IDCMP events) or ARexx commands.

<syntaxhighlight>
void event_loop(uint32 appID)
{
struct MsgPort *notificationPort = NULL;
struct ApplicationMsg *appLibMsg = NULL;
struct ApplicationCustomMsg *customMsg = NULL;
uint32 appLibSignal = 0, sigGot = 0;
BOOL done = FALSE;

/* Obtain pointer to Application Library's notification port and set the signal bit. */
IApplication->GetApplicationAttrs(appID, APPATTR_Port, &notificationPort, TAG_END);
appLibSignal = (1L << notificationPort->mp_SigBit);

/* Go into the event loop. */
while (!done)
{
/* Wait for a signal to arrive. */
sigGot = IExec->Wait(appLibSignal);

/* Process all Application Library messages. */
if ( sigGot & appLibSignal )
{
/* Obtain pointer to the message. */
while ( (appLibMsg = (struct ApplicationMsg *) IExec->GetMsg(notificationPort)) )
{
/* Identify the type of message. */
switch (appLibMsg->type)
{
case APPLIBMT_Quit:
case APPLIBMT_ForceQuit:
done = TRUE;
break;

case APPLIBMT_ToFront:
/* Make the program window come to front. */
break;

case APPLIBMT_Hide:
/* Iconify the program. */
break;

case APPLIBMT_Unhide:
/* Uniconify the program. */
break;

/* Process the custom message as you like.
Here we just use printf() to output the message text. */
case APPLIBMT_CustomMsg:
customMsg = (struct ApplicationCustomMsg *) appLibMsg;
printf("The message text is: %s\n", customMsg-> customMsg);
break;

/*
Process any other Application Library messages.
*/

}
/* Return the processed message to the sender so that it can be freed. */
IExec->ReplyMsg( (struct Message *) appLibMsg);
}
}
}
</syntaxhighlight>

Like all [[Exec_Messages_and_Ports#Messages|Exec messages]] obtained via the GetMsg() function, Application Library messages must be [[Exec_Messages_and_Ports#Replying|replied to]], i.e. returned to the sender after they have been processed. This is what the last command does in the code above. Remember that all message resources are freed after ReplyMsg() so should you need to use the message data (for example, the custom message text string) beyond the event loop, you must copy it to a memory storage of your own.

Also remember that the notifications are addressed to an abstract ''application'' – this makes them rather different from IDCMP messages, which are always sent to a particular ''window'' (Intuition is unaware of the application concept). Whereas Intuition stops sending IDCMP messages as soon as the window becomes closed/iconified, the Application Library keeps passing messages as long as the application is registered, regardless of program window state. So be smart in your code when processing Application Library notifications: check for the availability of the program window and perform uniconification when necessary. For example, if an APPLIBMT_ToFront command is sent to your iconified application, there is no window to come to front; you need to uniconify it first and only then call the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. The mistake of referencing a non-existing window is as silly as it is easy to make!

=== Sending Messages ===

While incoming notifications are [[#Message Handling|processed]] pretty much like normal Exec messages, the Application Library implements its own method for message sending. It takes three simple steps to send a message to another application:

# Prepare the respective [[#Data Structures|data structure]]: specify the type of message and supply the sender's [[#Application Identifiers|identifier]] (appID).
# [[#Finding Applications|Find the receiver]] application.
# Send a message to it via the SendApplicationMsg() function.

For example, if you want to tell the Audio Monster application to quit, you send it an APPLIBMT_Quit message like this:

<syntaxhighlight>
struct ApplicationMsg appMsg; // message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Step 1: Prepare the message data structure. */
appMsg.senderAppID = appID; // identifier of the sender
appMsg.type = APPLIBMT_Quit; // type of message

/* Step 2: Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Step 3: Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
&appMsg,
APPLIBMT_Quit);
}
</syntaxhighlight>

Should you want to send your message to all currently registered applications at once, just use a receiver appID of 0.

Sending [[#Custom Messages|custom messages]] is done in a similar fashion, the only difference is that you must use a dedicated [[#Data Structures|data structure]] instead of the generic ''struct ApplicationMsg''. As our Audio Monster application is a media player, it may as well have defined a set of commands for external control, one of them being “Start playback”. Now if another application wants to tell Audio Monster to start playing, it will need to send the custom message like this:

<syntaxhighlight>
struct ApplicationCustomMsg customMsg; // custom message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Prepare the message data structure. */
customMsg.almsg.senderAppID = appID; // identifier of the sender
customMsg.almsg.type = APPLIBMT_CustomMsg; // type of message
customMsg.customMsg = "Start playback"; // message text

/* Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
(struct ApplicationMsg *) &customMsg,
APPLIBMT_CustomMsg);
}
</syntaxhighlight>

== Pop-up Notifications (Ringhio Messages) ==

As from the introduction of the Ringhio server in AmigaOS 4.1 Update 1, registered applications can inform the user via notifications displayed in a small pop-up box. These are sometimes called ''Ringhio messages'' because the server provides means through which the messages are communicated visually (in other words, Ringhio handles the actual display of messages sent by the Application Library). [[File:RinghioNotification.png|frame|Ringhio notification example]] The pop-ups function similarly to [[Intuition Requesters|requesters]] in that they show a text message; but unlike requesters, Ringhio messages do not require user interaction or acknowledgement. They just show up briefly and disappear – which makes them great for informing about less significant, matter-of-fact events such as that a certain task has been completed (this is especially helpful if the application is hidden or runs on a different screen, as the user is kept informed about something that is currently beyond his/her visual control).

Of all the types of Application Library messages, pop-up notifications are surely the easiest to program. They don’t require any setup or event handling; all it takes is a single function call:

<syntaxhighlight>
uint32 result;

result = IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
TAG_END);
</syntaxhighlight>

The first parameter is your application’s appID received from the [[#Registration Functions|registration function]]. The APPNOTIFY_Title tag specifies a short heading for the pop-up box while APPNOTIFY_Text contains the actual message text. Certain limits to text length apply to ensure that the pop-up remains easy to read: 64 characters for the heading (title) and 128 characters for the text (160 characters as of Ringhio 53.23). This particular message will display on the frontmost public screen (as specified in the APPNOTIFY_PubScreenName tag), which may as well be the right setting for most applications. You can of course provide any other public screen name – or you can call Notify() without this tag and let the library use the default, which is the [[Public_Screen_Type#The_Default_Public_Screen_and_Workbench|Workbench screen]].

The result value shows whether the call was successful; 0 means that an error has occurred and Ringhio failed to display the pop-up. Depending on the significance of the message, you may want to react upon the failure and inform the user through other means of communication, such as a requester.

The look and position of the pop-up box is configurable from the Notifications editor located in the Prefs drawer on your system partition. This is Ringhio’s preferences editor: as we have explained above, it is Ringhio that is responsible for the actual display of notification messages. The pop-up box can also show a small custom image (like the one in the picture above) to make the message more easily identifiable as related to a particular application. The maximum size of the image is 32x32 pixels. It can be any format, provided that there is a datatype for it installed in the system. Being application-specific, these images logically cannot be configured system-wide through the Notifications editor; instead, they are specified as part of the Notify() call. Note that a full path to the image file must be provided:

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "All right, ma!",
TAG_END);
</syntaxhighlight>

But what is this APPNOTIFY_BackMsg thing? It has been mentioned above that notification messages do not require user interaction: they display some text and go away. Nevertheless, Ringhio can send the application a [[#Custom Messages|custom message]] (called “back message” – hence the name of the tag) if the user has double-clicked on the message box. As the code snippet shows, this custom message takes the form of a text string (within the Application Library messaging context, [[#Custom Messages|custom messages]] are always text strings). It is sent to the same event stream, and is supposed to be processed within the same event loop, as other Application Library messages – see the [[#Message Handling|Message Handling]] section for how to go about it.

Whether receiving a “back message” would be useful for a particular application, and whether it would make sense to react upon it, is decided by the programmer. The reaction (if any – often none is needed) should be sensible and logical. Make sure not to misuse the feature! Note that Ringhio messages are not requesters, and double-clicking on the message box does not really equal pressing a requester button. Therefore, receiving the message could be interpreted as the user’s acknowledgement of what Ringhio has said, but never as a selection of an option. Do not use Ringhio to request input via the back-message feature: the text of the message should be a statement, not a question or an offer of choice. Considering this logic, the double click means “I understand”; it doesn't mean “Yes” or “No”.

If the text string provided in the APPNOTIFY_BackMsg tag is an URL, the feature works rather differently. Instead of sending the message to the event stream, this particular URL is opened in your default web browser. Because the process is done through the Launch Handler, your system should be recent enough to have it (the Launch Handler was introduced in AmigaOS 4.1 Update 1). The following piece of code will open Audio Monster’s homepage if the user double-clicks on the Ringhio box. The last in the tag list, APPNOTIFY_CloseOnDC, causes the message box to disappear right after the double click.

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "URL:http://www.supercoders.com",
APPNOTIFY_CloseOnDC, TRUE,
TAG_END);
</syntaxhighlight>

=== Pop-up Message Style Guide ===

* Keep the message text short. Give the user chance to read the entire message before it disappears.
* Do not use pop-up messages to report errors. An error is usually a serious situation, and as such it cannot be dismissed by simply displaying an automatic message (which can easily get missed or overlooked).
* Use the pop-up message facility with moderation. Displaying the messages too frequently might hamper the workflow, and would most probably annoy the user.

== Function Reference ==

The following are brief descriptions of the Application Library functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| FindApplication()
| Searches for a previously registered application.
|-
| FreeApplicationList()
| Frees the list of applications generated by GetApplicationList().
|-
| GetAppLibAttrs()
| Obtains global Application Library attributes.
|-
| GetApplicationAttrs()
| Obtains attributes of a registered application.
|-
| GetApplicationList()
| Obtains the list of all currently registered applications.
|-
| LockApplicationIcon()
| Attempts to lock an application icon.
|-
| Notify()
| Displays a pop-up message box.
|-
| RegisterApplication()
| Registers an application.
|-
| SendApplicationMsg()
| Sends a message to a registered application.
|-
| SetAppLibAttrs()
| Sets or changes global Application Library attributes.
|-
| SetApplicationAttrs()
| Sets or changes application attributes.
|-
| UnlockApplicationIcon()
| Unlocks an application icon.
|-
| UnregisterApplication()
| Unregisters an application.
|}

Intuition Screens

2017-04-14T07:08:53Z

Daniel Jedlicka: /* Function Reference */

== Intuition Screens ==

Intuition screens are the basis of any display Intuition can make. Screens determine the fundamental characteristics of the display such as the resolution and palette and they set up the environment for multiple, overlapping windows that makes it possible for each application to have its own separate visual context. This section shows how to use existing screens and how to create new screens.

=== Classic Intuition Screens ===

Intuition screens have evolved since they were closely tied to the Classic Amiga's hardware chip set. See [[Classic_Intuition_Screens|Classic Intuition Screens]] for more information on the now obsolete API that was used to work with screens.

== Types of Screens ==

Screens are important because they determine the basic resolution and maximum number of colors in the display. Once a screen is set up, these attributes cannot be changed so any graphics work done on a given screen is restricted to that screen's resolution and number of colors. Hence, the type of screen used is a basic design decision.

With Intuition screens, a video display can be created in any one of the many Amiga ''display modes''. The basic parameters of the video display such as resolution, total size, frame rate, genlock compatibility, support of screen movement and number of colors are defined by these modes.

Many display modes are available. All these display modes, including the specialized modes, are integrated through the graphics library ''display database''. See [[Graphics_Primitives|Graphics Primitives]] for a complete list of all Amiga display modes.

=== Multiple Screens ===

All Intuition display objects (such as windows and menus) take graphical characteristics from the screen. These objects are restricted to the same resolution and maximum number of colors as the screen they operate in. Other characteristics such as the palette, pens and fonts are inherited from the screen (but may be changed on a case by case basis).

This is not too much of a restriction because the Amiga can maintain multiple screens in memory at the same time. In other words, one application can use a high resolution screen (with 16 colors) while another application uses a low resolution screen (with 32 colors) at the same time. Screens typically take up the entire viewing area so only one is usually visible. But screens can be moved up and down or rearranged allowing the user (or application) to move between screens easily.

=== Public Screens and Custom Screens ===

An application may choose to use an existing screen or to create its own screen. For instance, the normal Amiga startup process opens the Workbench screen (Workbench is the Amiga's default user interface). Any application is free to use the Workbench screen instead of opening a new one. Screens that can be shared this way are called ''public'' screens.

[[Public_Screen_Type|Public screens]] allow applications to open windows on them. Any screen may be set up as a public screen so that other applications may use it.

The use of an existing public screen, like the Workbench screen, requires little effort by the application and does not use up any memory. However, using Workbench or another existing public screen means some flexibility is lost; the resolution, maximum number of colors and other attributes are already set. If the application cannot function under these limitations, it may open its own ''custom'' screen.

[[Custom_Screen_Type|Custom screens]] allow for complete control of the display space so an application can get exactly the kind of display it wants. However, since creating a new, custom screen uses up memory, they should only be used when there are no suitable public screens available.

Owners of a custom screen can keep their screen private, or they may allow other applications to share their screen by registering the screen with the operating system as a public screen. See the section on [[Public_Screen_Type|public screens]] for more about public screens and Workbench.

=== Screen Components ===

Screens have very little visual impact, they simply provide a resolution specific area to place other objects such as windows and menus. Screens have no borders. Only the title bar marks the screen limits (specifying the left and top edges, and the width of the screen), and the title bar may be hidden, or obscured by graphics or windows.

The title bar also serves as the menu bar when the user presses the menu button on the mouse. The menu bar area is shared by all applications operating within the screen.

Within the title bar, there are two gadgets: a screen drag gadget and a depth-arrangement gadget. The screen drag gadget allows the screen to be moved up and down. The depth-arrangement gadget allows the screen to be placed in front or behind all other screens.

[[File:LibFig3-1.png|frame|center|An Intuition Screen (Workbench)]]

Screens are always rectangular, and the areas at the sides and bottom of the display that are not within the screen's limits are filled with the background color. The area above all visible screens is filled with the background color of the highest screen. These areas surrounding the screen (normally unused) are known as the ''overscan'' area. The Amiga display system allows the overscan area to be used for graphics under special circumstances (see the section on [[Intuition_Screens#Overscan_and_the_Display_Clip|Overscan and the Display Clip]]).

== Screen Attributes ==

The sections above discuss only the basic functions and screen types that Intuition programmers need to understand to create a custom screen. Intuition supports an astonishing number of additional display features and options. In this section and the sections to follow, the finer points of screen attributes and the functions that control them are presented.

Screen attributes are specified using the tag item scheme described [[Utility_Library|Utility Library]]. Therefore, the screen attributes are listed here by tag values.

; SA_ErrorCode
: Extended error code. Data is a pointer to a long which will contain the error code on return if OpenScreenTagList() returns NULL. The error codes are described above.

; SA_Left, SA_Top
: Initial screen position (left edge and top edge). Data is a long, signed value. Offsets are relative to the text overscan rectangle.

: If SA_Left is not specified and a NewScreen structure is not passed in the OpenScreenTags/TagList() call and SA_Width is not specified or is specified as STDSCREENWIDTH, then the left edge of the screen will default to the left edge of the actual display clip of the screen. If the other conditions are met but some explicit SA_Width is specified, then the left edge defaults to zero (text overscan rectangle left edge). Likewise, the top edge may, independent of the left edge value, default to zero or to the top edge of the actual display clip. If SA_Top is not specified and a NewScreen structure is not passed in the OpenScreenTags/TagList() call and SA_Height is not specified or specified as STDSCREENHEIGHT, then the top edge of the screen will default to the top edge of the actual display clip of the screen. If the other conditions are met but some explicit SA_Height is specified, then the top edge defaults to zero (text overscan rectangle top edge).

: When opening a full sized overscan screen, SA_Left should be set to the MinX value of the display clip Rectangle used for the screen and SA_Top should be set to the MinY value of the display clip. This may be taken from the defaults, as explained above, or explicitly set by the application. See the section below on "Overscan and the Display Clip" and the OpenScreen() Autodoc for more details.

: If your screen is larger than your display clip, you may wish to set the SA_Left and SA_Top to values less than your display clip MinX and MinY in order to center a large screen on a smaller display. For an example of how to open a centered overscan screen, see "module/screen.c" in the [[IFF_Source_Code|IFF Source Code]].

; SA_Width, SA_Height
: Screen dimensions. Data is a long, unsigned value. These may be larger, smaller or the same as the dimensions of the display clip Rectangle. The use of STDSCREENWIDTH and STDSCREENHEIGHT will make the screen size equal to the display clip size.

: To calculate the width of the display clip Rectangle, subtract the MinX value from the MaxX value plus one. Similarly, the height of the display clip may be calculated by subtracting the MinY value from the MaxY value plus one.

; SA_Depth
: Screen bitmap depth. Data is a long, unsigned value. The depth of the screen determines the number of available colors. See the "Graphics Primitives" for more information on hardware limitations of the display. Do not set the depth to a value greater than that supported by the specific display mode. This information is available to the application through the graphics library display database. The default is one bitplane.

; SA_DisplayID
: Extended display mode key for the screen. Data is a long, unsigned value. By using DisplayIDs and the display database, applications can open a screen in any display mode available on a user's system, including PAL and NTSC modes. See the discussion of the display database in [[Display_Database|Display Database]] and the include file <graphics/displayinfo.h> for more information.

; SA_Pens
: Pen specification for the screen. Data is a pointer to a UWORD array terminated with ¬†0, as found in the DrawInfo structure. Specifying the SA_Pens tag informs the system that the application is prepared to handle a screen rendered with the new 3D look of Intuition. See the section below on "DrawInfo and the 3D Look". Omitting this tag produces a screen with a flat look, but whose color usage is more backwards compatible.

; SA_DetailPen
: Detail pen for the screen. Data is a long, unsigned value. Used for rendering details in the screen title bar and menus. Use SA_Pens beginning with V36 for more control of pen specification. If SA_Pens is not specified, the screen will not get the new 3D look of Intuition. Instead this value will be used as the detail pen.

; SA_BlockPen
: Block pen for the screen. Data is a long, unsigned value. Used for rendering block fills in the screen title bar and menus. Use SA_Pens for more control of pen specification. If SA_Pens is not specified, the screen will not get the new 3D look and this value will be used as the block pen.

; SA_Title
: Default screen title. Data is a pointer to a character string. This is the title displayed when the active window has no screen title or when no window is active on the screen.

; SA_Colors
: Specifies initial screen palette colors. Data is a pointer to an array of ColorSpec structures, terminated by a ColorSpec structure with ColorIndex = -1. Screen colors may be changed after the screen is opened with the graphics library functions SetRGB4() and LoadRGB4(). ColorSpec colors are right-justified, four bits per gun.

; SA_FullPalette
: Initialize color table to entire preferences palette (32 colors), rather than the subset from V34 and earlier, namely pens 0-3, 17-19, with remaining palette as returned by GetColorMap(). Data is a boolean value (use TRUE to set the flag). Defaults to FALSE.

; SA_Font
: Data is a pointer to a TextAttr structure (defined in <graphics/text.h>) which specifies the font, size and style to use for the screen. Equivalent to NewScreen.Font.

; SA_SysFont
: Alternative to SA_Font. Selects one of the preferences system fonts. Data is a long, unsigned value, with the following values defined:

:{| class="wikitable"
| 0 || Open screen with the user's preferred fixed width font (the default).
|-
| 1 || Open screen with the user's preferred font, which may be proportional.
|}

: The Workbench screen is opened with {SA_SysFont, 1}. The following table summarizes how the font selected at OpenScreen() time effects subsequent text operations in screens and windows.

: Intuition Font Selection Chart

:{| class="wikitable"
!
! What you tell OpenScreen()
! Screen font
! Window.RPort font
|-
| A
| NewScreen.Font = myfont
| myfont
| myfont
|-
| B
| NewScreen.Font = NULL
| GfxBase->DefaultFont
| GfxBase->DefaultFont
|-
| C
| {SA_Font, myfont}
| myfont
| myfont
|-
| D
| {SA_SysFont, 0}
| GfxBase->DefaultFont
| GfxBase->DefaultFont
|-
| E
| {SA_SysFont, 1}
| Font Prefs Screen text
| GfxBase->DefaultFont
|}

: Notes:

:* '''A''' and '''B''' are the options that existed in V34 and earlier OS versions.

:* '''C''' and '''D''' are tags equivalent to '''A''' and '''B''' respectively.

:* '''E''' is an option for V36 and higher. The Workbench screen uses this option.

:* For myfont, any font may be used including a proportional one. This is true under all releases of the OS.

:* GfxBase->DefaultFont is always monospace. (This is the "System Default Text" from Font Preferences.)

:* "Font Prefs Screen" text (the "Screen Text" choice from Font Preferences) can be monospace or proportional.

: The screen's font may not legally be changed after a screen is opened. The menu bar, window titles, menu items, and the contents of a string gadget all use the screen's font. The font used for menu items can be overridden in the menu item's IntuiText structure. Under V36 and higher, the font used in a string gadget can be overridden through the StringExtend structure. The font of the menu bar and window titles cannot be overridden.

: The Window.RPort font shown above is the initial font that Intuition sets in your window's RastPort. It is legal to change that subsequently with SetFont(). IntuiText rendered into a window (either through PrintIText() or as a gadget's GadgetText) defaults to the window's RastPort font, but can be overridden using its ITextFont field. Text rendered with the graphics library call Text() uses the window's RastPort font.

; SA_Type
: Equivalent to the SCREENTYPE bits of the NewScreen.Type field. Data is a long, unsigned value which may be set to either CUSTOMSCREEN or PUBLICSCREEN (WBENCHSCREEN is reserved for system use). See the tags SA_BitMap, SA_Behind, SA_Quiet, SA_ShowTitle and SA_AutoScroll for the other attributes of the NewScreen.Type field.

; SA_BitMap
: Use a custom bitmap for this screen. Data is a pointer to a BitMap structure. This tag is equivalent to NewScreen.CustomBitMap and implies the CUSTOMBITMAP flag of the NewScreen.Type field. The application is responsible for allocating and freeing the screen's bitmap.

; SA_Behind
: Open this screen behind all other screens in the system. Data is a boolean value (TRUE to set flag). This tag is equivalent to the SCREENBEHIND flag of the NewScreen.Type field.

; SA_Quiet
: Disable Intuition rendering into screen. Data is a boolean value (TRUE to set flag). This tag is equivalent to the SCREENQUIET flag of the NewScreen.Type field. The screen will have no visible title bar or gadgets, but dragging and depth arrangement still function. In order to completely prevent Intuition from rendering into the screen, menu operations must be disabled for each window in the screen using WFLG_RMBTRAP.

; SA_ShowTitle
: Setting this flag places the screen's title bar in front of any backdrop windows that are opened on the screen. Data is a boolean value (TRUE to set flag). This tag is equivalent to the SHOWTITLE flag of the NewScreen.Type field. The title bar of the screen is always displayed behind any non-backdrop windows on that screen. This attribute can be changed after the screen is open with the ShowTitle() function.

; SA_AutoScroll
: Setting this flag will enable autoscroll for this screen when it is the active screen. (Currently, the screen may only be made active by activating a window in that screen either under user or application control.) Data is a boolean value (TRUE to set flag). This tag is equivalent to the AUTOSCROLL flag of the NewScreen.Type field.

: Autoscroll means that screens larger than the visible display will automatically scroll when the user moves the mouse to the edge of the screen. Without this tag, the user moves the screen either by using the screen drag bar, or by pressing the mouse select button anywhere within the screen while holding down the left Amiga key and moving the mouse.

; SA_PubName
: Presence of this tag means that the screen is to be a public screen. Data is a pointer to a string. The string is the name of the public screen which is used by other applications to find the screen. This tag is order dependent, specify ''before'' SA_PubSig and SA_PubTask.

; SA_PubSig, SA_PubTask
: Task ID (returned by FindTask()) and signal for notification that the last window has closed on a public screen. Data for SA_PubSig is a long, unsigned value. Data for SA_PubTask is a pointer to a Task structure. These two tags are order dependent, and must be specified ''after'' the tag SA_PubName.

; SA_Overscan
: Set to one of the OSCAN_ specifiers to use a system standard overscan display clip and screen dimensions (unless otherwise specified). Data is a long, unsigned value. Do not specify this tag and SA_DClip. SA_Overscan is used to get one of the standard overscan dimensions, while SA_DClip is for custom dimensions. If a display clip is not specified with either SA_Overscan or SA_DClip, the display clip defaults to OSCAN_TEXT. See the section below on "Overscan and the Display Clip" for more information.

; SA_DClip
: Custom display clip specification. Data is a pointer to a Rectangle structure that defines the screen display clip region.

== DrawInfo and the 3D Look ==

Whenever a new screen is created, Intuition also creates an auxiliary data structure called a DrawInfo. The DrawInfo structure provides information Intuition uses to support the 3D look and specifies graphical information for applications that use the screen. The information includes such items as aspect ratio (resolution), font, number of colors and drawing pens.

<syntaxhighlight>
struct DrawInfo
{
UWORD dri_Version; /* will be DRI_VERSION */
UWORD dri_NumPens; /* guaranteed to be >= numDrIPens */
UWORD *dri_Pens; /* pointer to pen array */

struct TextFont *dri_Font; /* screen default font */
UWORD dri_Depth; /* (initial) depth of screen bitmap */

struct { /* from DisplayInfo database for initial display mode */
UWORD X;
UWORD Y;
} dri_Resolution;

ULONG dri_Flags; /* defined below */
ULONG dri_Reserved[7]; /* avoid recompilation ;^) */
};
</syntaxhighlight>

Before an application uses fields in the DrawInfo structure, it should check the version of the structure to ensure that all fields are available. If the field dri_Version is greater than or equal to the constant DRI_VERSION that the application was compiled with, it can be assured that all fields in DrawInfo that it knows about are being supported by Intuition.

=== The Pen Specification in DrawInfo ===

The drawing pen specification in DrawInfo.dri_Pens allows applications to use appropriate colors for graphic operations such as drawing text, shading 3D objects and filling items selected by the user.

Intuition has two default sets of pens, one for multi-bitplane screens and one for single bitplane screens. In addition, there is a special compatibility mode for screens that do not specify the SA_Pens tag.

; 3D Look
: The is the full 3D look as found by default on the Workbench screen. Objects are drawn so that light appears to come from the upper left of the screen with shadows cast to the lower right giving them a three-dimensional look.

; Monochrome Look
: It is impossible to produce the full 3D look in a single bitplane (two color) screen. Intuition provides a fallback pen specification that is used in monochrome screens with no loss of information.

; Compatible Look
: Custom screens that do not provide the SA_Pens tag are assumed to have no knowledge of the pen array. They are rendered in a special version of the monochrome new look, which uses the screen's DetailPen and BlockPen to get its colors. This is provided for compatibility with V34 and older versions of the operating system.

It is very easy for an application to use the default pen specification. Simply specify an empty pen specification (in C, {~0}), and Intuition will fill in all of the values with defaults appropriate for the screen. This technique is demonstrated in the first two examples listed earlier in this article.

For certain applications, a custom pen specification is required. A custom pen specification is set up when the screen is opened by using the SA_Pens tag and a pointer to a pen array. Currently, Intuition uses nine pens to support the 3D look. The application can specify all of these, or only a few pens and Intuition will fill in the rest. Intuition will only fill in pens that are past the end of those specified by the application, there is no facility for using default values for "leading" pens (those at the beginning of the array) without using the defaults for the rest of the pens.

Using the pen specification of an existing public screen is a bit more involved. First, the application must get a pointer to the screen structure of the public screen using the LockPubScreen() call. A copy of the screen's DrawInfo structure may then be obtained by calling GetScreenDrawInfo(). The DrawInfo structure contains a copy of the pen specification for the screen that can be used in the OpenScreenTagList() call with the SA_Pens tag. The pen array is copied to the data structures of the new screen (it is not kept as a pointer to the information passed), so the application may immediately call FreeScreenDrawInfo() and UnlockPubScreen() after the new screen is open.

<syntaxhighlight>
/* publicscreen.c
** open a screen with the pens from a public screen.
*/
#include <exec/types.h>
#include <intuition/intuition.h>
#include <intuition/screens.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/intuition.h>

VOID usePubScreenPens(void);

struct IntuitionIFace *IIntuition = NULL;

/* main(): open libraries, clean up when done.
*/
int main(int argc, char **argv)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if ( IIntuition != NULL )
{
usePubScreenPens();
}
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);
return 0;
}

/* Open a screen that uses the pens of an existing public screen
** (the Workbench screen in this case).
*/
VOID usePubScreenPens(void)
{
struct Screen *my_screen;
struct TagItem screen_tags[2];
UBYTE *pubScreenName = "Workbench";

struct Screen *pub_screen = NULL;
struct DrawInfo *screen_drawinfo = NULL;

/* Get a lock on the Workbench screen */
pub_screen = IIntuition->LockPubScreen(pubScreenName);
if ( pub_screen != NULL )
{
/* get the DrawInfo structure from the locked screen */
screen_drawinfo = IIntuition->GetScreenDrawInfo(pub_screen);
if ( screen_drawinfo != NULL)
{
/* the pens are copied in the OpenScreenTagList() call,
** so we can simply use a pointer to the pens in the tag list.
**
** This works better if the depth and colors of the new screen
** matches that of the public screen. Here we are forcing the
** workbench screen pens on a monochrome screen (which may not
** be a good idea). You could add the tag:
** (SA_Depth, screen_drawinfo->dri_Depth)
*/
screen_tags[0].ti_Tag = SA_Pens;
screen_tags[0].ti_Data = (ULONG)(screen_drawinfo->dri_Pens);
screen_tags[1].ti_Tag = TAG_END;
screen_tags[1].ti_Data = NULL;

my_screen = IIntuition->OpenScreenTagList(NULL, screen_tags);
if (my_screen != NULL)
{
/* We no longer need to hold the lock on the public screen
** or a copy of its DrawInfo structure as we now have our
** own screen. Release the screen.
*/
IIntuition->FreeScreenDrawInfo(pub_screen,screen_drawinfo);
screen_drawinfo = NULL;
IIntuition->UnlockPubScreen(pubScreenName,pub_screen);
pub_screen = NULL;

IDOS->Delay(90); /* should be rest_of_program */

IIntuition->CloseScreen(my_screen);
}
}
}

/* These are freed in the main loop if OpenScreenTagList() does
** not fail. If something goes wrong, free them here.
*/
if ( screen_drawinfo != NULL )
IIntuition->FreeScreenDrawInfo(pub_screen,screen_drawinfo);
if ( pub_screen!= NULL )
IIntuition->UnlockPubScreen(pubScreenName,pub_screen);
}
</syntaxhighlight>

The pen specification for the Workbench screen happens to match the Intuition default specification, however, this is not required and may change in the future. To create a screen that uses the pens defined in the Workbench screen, the application must get a copy of the pen array from the Workbench screen and use this copy with the SA_Pens tag as described above.

Here is a list of the pens that support the 3D look along with their uses. To read the value of a particular pen, use UWORD penvalue = myDrawInfo->dri_Pens[PENNAME], where myDrawInfo is a pointer to a DrawInfo structure and PENNAME is taken from the list below:

; DETAILPEN
: Pen compatible with V34. Used to render text in the screen's title bar.

; BLOCKPEN
: Pen compatible with V34. Used to fill the screen's title bar.

; TEXTPEN
: Pen for regular text on BACKGROUNDPEN.

; SHINEPEN
: Pen for the bright edge on 3D objects.

; SHADOWPEN
: Pen for the dark edge on 3D objects.

; FILLPEN
: Pen for filling the active window borders and selected gadgets.

; FILLTEXTPEN
: Pen for text rendered over FILLPEN.

; BACKGROUNDPEN
: Pen for the background color. Currently must be zero.

; HIGHLIGHTTEXTPEN
: Pen for "special color" or highlighted text on BACKGROUNDPEN.

=== The Font Specification in DrawInfo ===

Font information for a screen comes from a number of different places.

The application may specify the font to be used in a screen by providing the SA_Font tag with a TextAttr structure. In this case, the font will be used by the screen and will be the default font for the RastPort of any window opening in the screen.

If the application requests the user's preferred monospace font, it is taken from GfxBase->DefaultFont. Any window's RastPorts are also initialized to use this same font.

The screen font selected by the user from the Preferences font editor may be used for the screen by using the SA_SysFont tag. This font, the "preferred screen font", may be proportional. For compatibility reasons, if this font is specified for the screen, the window's RastPort will be initialized to GfxBase->DefaultFont (a non-proportional font).

To access information on an open screen's font, the application may reference Screen.Font or DrawInfo.dri_Font. These fonts are identical, the DrawInfo structure simply provides an alternate method of accessing the information. Note that Screen.Font is a pointer to a TextAttr structure and that DrawInfo.dri_Font is a pointer to a TextFont structure. The application may use whichever form is best suited to its requirements.

It is illegal to change the screen's font after the screen is opened. This means that the font specified in the Screen and DrawInfo structures is guaranteed to remain open as long is the screen is open.

The menu bar, window titles, menu items, and the contents of a string gadget all use the screen's font. The font used for menu items can be overridden in the menu item's IntuiText structure. The font used in a string gadget can be overridden through the StringExtend structure. The font of the menu bar and window titles cannot be overridden.

For more information on screen fonts, see the description of the SA_Font and SA_SysFont tags in the "Screen Attributes" section above.

== Overscan and the Display Clip ==

Screens may be larger or smaller than the defined display area (''overscan rectangle'' or ''display clip''). When a screen is smaller than the display area, the display clip acts as a "container" for the screen. The screen may be moved anywhere within the display clip. When a screen is larger than the display area, the display clip acts as a "window" into the screen. The screen may be moved so that different parts are visible. Each dimension of the screen is independent and may be larger than, the same as, or smaller than the dimensions of the display clip.

The system is very flexible in its specification of screen size. Unless an application fixes its screen size with hard coded values, it should be prepared to handle the possibility that the user has changed the default overscan presets or the default monitor.

Use the constants STDSCREENHEIGHT and STDSCREENWIDTH with the SA_Width and SA_Height tags to open a screen the same size as the display clip. These constants will work with any of the preset overscan values set with SA_Overscan, and with custom overscan values set with SA_DClip.

=== Preset Overscan Values ===

Four preset overscan dimensions are provided. Applications that support overscan should use these preset values where possible since they will be tailored to each individual system. Avoid using custom values that happen to look good on a specific system. However, be aware that the size and positioning of overscan screens can be different on every system depending on how the user has set Overscan Preferences. These preset values are also dependent on the underlying display mode so keep in mind that both offset and size parameters will change under different screen modes. Overscan presets can be used, among other things, with the SA_Overscan tag to set the size of the screen's display clip or passed as an argument to QueryOverscan() to find their current overscan settings.

; OSCAN_TEXT
: This overscan region is based on user preference settings and indicates a display that is completely within the visible bounds of the monitor. The View origin is set to the upper left corner of the text overscan rectangle which is the highest leftmost point known to be visible on the physical display. This position is set by the user through the Overscan Preferences editor. All screen positions and display clips are relative to this origin.

; OSCAN_STANDARD
: The edges of OSCAN_STANDARD display are also based on user preferences and are set to be just outside the visible bounds of the monitor. OSCAN_STANDARD provides the smallest possible display that will fill the entire screen with no border around it. Parts of the display created with OSCAN_STANDARD may not be visible to the user.

; OSCAN_MAX
: Create the largest display fully supported by Intuition and the graphics library. This is the largest size for which all enclosed sizes and positions are legal. Parts of the display created with OSCAN_MAX may not be visible to the user.

; OSCAN_VIDEO
: Create the largest display, restricted by the hardware. This is the only legal size and position that is possibly (but not necessarily) larger than OSCAN_MAX. You must use the exact size and position specified. OSCAN_VIDEO does not support variable left edge, top edge positioning. Parts of the display created with OSCAN_VIDEO may not be visible to the user.

If custom clipping is required, a display clip may be explicitly specified using the SA_DClip tag and a Rectangle structure specification. This custom rectangle must fit within the OSCAN_MAX rectangle, offset included. It is not permitted to specify custom rectangles whose values are in between OSCAN_MAX and OSCAN_VIDEO, nor is it permitted to specify rectangles larger than OSCAN_VIDEO. For an example of how to open a centered overscan screen based on user preferences, see the "module/screen.c" listing in the [[IFF_Source_Code|IFF Source Code]].

Use the Graphics library call VideoControl() to find the true display clip of a screen. See the Graphics Autodocs and [[Graphics_Primitives|Graphics Primitives]] for more information on VideoControl(). The ViewPortExtra structure contains the display clip information.

If any dimension of a screen is not equal to the equivalent display clip dimension, then the screen may be scrolled. If the screen's dimensions are smaller than the display clip, then the screen may be positioned within the display clip. If the screen is larger than the display clip, then it may be positioned such that any part of the screen is visible.

AutoScroll may be activated by setting the tag SA_AutoScroll. Screens will only scroll when they are the active screen. Activate a window in the screen to make the screen active.

{{Note|title=About the Default Display Clip|text=The default display clip for a screen is the entire screen, that is, the rectangle starting from the upper left corner of the screen and ending at the lower right corner of the screen. This display clip is only used if the application does not specify SA_Overscan or SA_DClip. When using this default display clip the screen will not scroll as the screen exactly fits into the clipping region.}}

When opening a window in an overscanned screen, it is often useful to open it relative to the visible part of the screen rather than relative to the entire screen. Use QueryOverscan() to find the overscan region and where the screen is positioned relative to it.

<syntaxhighlight>
LONG QueryOverscan(ULONG displayID, struct Rectangle *rect, WORD overscanType );
</syntaxhighlight>

This example was taken from [[Intuition_Windows|Intuition Windows]] in the section "Visible Display Sized Window Example". The complete example is reproduced there.

<syntaxhighlight>
/* this technique returns the text overscan rectangle of the screen that we
** are opening on. If you really need the actual value set into the display
** clip of the screen, use the VideoControl() command of the graphics library
** to return a copy of the ViewPortExtra structure. See the Graphics
** library articles and Autodocs for more details.
**
** GetVPModeID() is a graphics call...
*/

screen_modeID = IGraphics->GetVPModeID(&(pub_screen->ViewPort))))
if (screen_modeID != INVALID_ID)
{
if ( IGraphics->QueryOverscan(screen_modeID, &rect, OSCAN_TEXT) )
{
/* if this screen's origin is up or to the left of the */
/* view origin then move the window down and to the right */
left = max(0, -pub_screen->LeftEdge);
top = max(0, -pub_screen->TopEdge);

/* get width and height from size of display clip */
width = rect.MaxX - rect.MinX + 1;
height = rect.MaxY - rect.MinY + 1;

/* adjust height for pulled-down screen (only show visible part) */
if (pub_screen->TopEdge > 0)
height -= pub_screen->TopEdge;

/* ensure that window fits on screen */
height = min(height, pub_screen->Height);
width = min(width, pub_screen->Width);

/* make sure window is at least minimum size */
width = max(width, MIN_WINDOW_WIDTH);
height = max(height, MIN_WINDOW_HEIGHT);
}
}
</syntaxhighlight>

== Intuition Screens and the Graphics Library ==

As previously mentioned, an Intuition screen is related to a number of underlying graphics library structures.

{| class="wikitable"
|+ Graphics Data Structures Used with Screens
! Structure Name
! Description
! Include File
|-
| View || Root structure of the graphics display system || <graphics/view.h>
|-
| ViewPort || The graphics structure that corresponds to a screen || <graphics/view.h>
|-
| ColorMap || Contains size and pointer to the screen's color table || <graphics/view.h>
|-
| RastPort || Holds drawing, pen and font settings and the BitMap address || <graphics/rastport.h>
|}

These data structures are unified in Intuition's Screen structure (which also incorporates higher level Intuition constructs such as menus and windows). Here's a brief explanation of the graphics library structures used with Intuition.

; View
: The View is the graphics structure that corresponds to the whole display, including all visible screens. The system has just one View; it's what you see on the monitor. The address of the View may be obtained from any screen by using ViewAddress().

; ViewPort
: The ViewPort is the underlying graphics structure corresponding to a screen. Every screen has one ViewPort. To get the address of the ViewPort from the Screen structure, use (&my_screen->ViewPort). From the ViewPort an application may obtain pointers to all the screen's bitplanes and to its color table.

; ColorMap
: The ColorMap contains a pointer to the color table, an array of 32 WORDs for the hardware color registers. Use SetRGB4(), GetRGB4(), SetRGB4CM() and LoadRGB4() from the graphics library to access the color table. Do not read or write it directly.

; RastPort
: A RastPort controls the graphics rendering to ''any'' display area (not just screens). Screens have a RastPort to allow direct rendering into the screen. Applications may find the RastPort address of a screen with (&my_screen->RastPort). The screen's BitMap can also be found via the RastPort in the RastPort.BitMap field. This generally is not useful since applications normally render into windows.

=== Changing Screen Colors ===

Screen colors are set at the time the screen is opened with the SA_Colors tag. If the colors need to be changed after the screen is opened, the graphics library function, LoadRGB4() should be used. To change a single entry in the color table, use SetRGB4() and SetRGB4CM(). See [[Graphics_Primitives|Graphics Primitives]] for more information on these functions.

=== Direct Screen Access ===

Sometimes an application may want direct access to the custom screen's bitmap to use with low-level graphics library calls. This may be useful if the application needs to do custom manipulation of the display but also needs Intuition functionality. For instance, an application may want to use the graphics library primitives to perform double buffering then, when detecting user input, switch to Intuition control of the screen so that windows, gadgets and menus may be used to process the user input. If an application chooses to combine these techniques, it must take special care to avoid conflicts with Intuition rendered graphics. An example of how to do this is listed in the next section, "Advanced Screen Programming".

Application programs that open custom screens may use the screen's display memory in any way they choose. However, this memory is also used by Intuition for windows and other high level display components on the screen. Writing directly to the screen memory, whether through direct access or through graphics library calls that access the screen's RastPort, is not compatible with many Intuition constructs such as windows and menus.

Techniques such as this require great care and understanding of the Amiga. If possible, the application should avoid these techniques and only use standard Intuition display and input processing. Directly accessing the screen's bitmap, while possible, is not recommended. A better way to access the screen display is through windows. Windows provide access to the screen through layers which perform clipping and arbitration between multiple drawing areas.

Alternatives to writing directly to a screen, such as using a backdrop window, greatly limit the number of cases where an application must access screen memory. The ShowTitle() function allows the screen's title bar layer to be positioned in front of or behind any backdrop windows that are opened on the screen. Hence, a backdrop window may be created that uses the entire visible area of the monitor.

Application programs that use existing public screens do not have the same freedom to access the screen's display memory as they do with custom screens. In general, public screens must be shared through the use of windows and menus rather than directly accessing the screen's display memory.

{{Note|title=Use Direct Access Only On Screens You "Own"|text=An application may not steal the bitmap of a screen that it does not own. Stealing the Workbench screen's bitmap, or that of any other public screen, is strictly illegal. Accessing the underlying graphics structures of a screen may only be done on custom screens opened by the application itself.}}

{{Note|title=Do Not Perform Layers Operations Directly|text=While layers are not part of the graphics library, it is appropriate to mention them here. Certain types of layers operations are not allowed with Intuition. You may not, for example, call SizeLayer() on a window (use SizeWindow() instead). To access layers library features with screens, use Intuition windows!}}

A custom screen may be created to allow for modification of the screen's Copper list. The Copper is the display synchronized co-processor that handles the actual video display by directly affecting the hardware registers. See the ''Amiga Hardware Reference Manual'' or the graphics library articles for more information on programming the Copper.

=== Limitations of the Graphics Subsystem ===

If each of the visible screens does not have the same physical attributes, it may not be possible to display the data in its proper screen mode. ''Screen coercion'' is the technique that allows multiple screens with differing physical attributes to be displayed simultaneously. When a coerced screen is visible, its aspect ratio and colors may appear significantly changed. This is normal and the screen will be displayed correctly when it is the frontmost screen.

Hardware restrictions prevent certain types of displays. For instance, screens always use the full width of the display, regardless of the width of the overscan rectangle. This prevents any changes in display mode within a video line. Other modes, such as the VGA modes, require specific revisions of the custom chips and may not be available on all machines. See [[Graphics_Primitives|Graphics Primitives]] and the ''Amiga Hardware Reference Manual'' for more information on Amiga display organization and limitations.

== Advanced Screen Programming ==

This section discusses how to perform double-buffering of Intuition screens and other advanced topics. Dual-playfield Intuition screens are covered in the [[Classic_Intuition_Screens|Classic Intuition Screens]] section.

=== Screen Locking ===

Applications wishing to block all screen rendering so that they can do "exceptional" rendering (eg. dragging icons,
pop-up menus, etc.) need to LockScreen(). By using LockScreen() and UnlockScreen(), such applications avoid the risk of deadlocking with Intuition. Intuition will behave much like it does when menus are down; that is to say that layer-related events such as window size, depth, or position changes are deferred until the screen is unfrozen.

The application has the following obligations:
# When UnlockScreen() is finally called, the screen's bitmap must be bit-for-bit the same as when you called LockScreen(), with the exception of rendering into your own windows' RastPorts. That is to say, you are responsible for doing non-destructive rendering during the time you have the screen frozen.
# You may only make regular rendering calls (graphics calls, plus Intuition imagery functions such as PrintIText(), DrawImage(), DrawBorder()). Do not call any gadget refresh functions, OpenWindow(), Begin/EndRefresh(), etc. or any Intuition function that involves locking IntuitionBase (namely LockIBase()).
# Don't freeze the screen on the user. Freeze it only in response to the user. Typically, if you don't unfreeze the screen when the user lets the mouse button go, you're freezing for too long.
# Do not freeze a screen you don't own. It's OK to freeze a public screen (including the Workbench screen), or your own custom screen. If it's a public screen, be sure you hold a public-screen lock (see LockPubScreen()) or have a window open on it.

The active window will still receive mouse-, keyboard- and timer-messages. So if you want your window to get the IDCMP messages, the following must be done:
# make your window the active one, if it isn't (see ActivateWindow)
# wait for IDCMP_ACTIVEWINDOW
# then call LockScreen()
# do your input processing. When receiving IDCMP_INACTIVEWINDOW abort and call UnlockScreen() (your window could have gone inactive before you had the chance to call LockScreen())
# when done, call UnlockScreen()

{{Note|BOOPSI class implementers must use the LockScreenGI() and UnlockScreenGI() functions.}}

==== Locking the Screen List ====

Sometimes there is a need for applications to lock Intuition's entire screen list. For these situations use the LockScreenList() and UnlockScreenList functions. While the screen list is locked, Intuition is "frozen" from the user's point of view. It is best to copy any required information (e.g. screen titles) and then release the list.

=== Double Buffering ===

Intuition supports double (or multiple) buffering inside an Intuition screen, with full support for menus, and support for certain
kinds of gadget.

The AllocScreenBuffer() call allows you to create other BitMap buffers for your screen. The SB_SCREEN_BITMAP flag is used to get a buffer handle for the BitMap currently in use in the screen. Subsequent buffers are allocated with the SB_COPY_BITMAP flag instead, which instructs Intuition to copy the current imagery (e.g., the screen title-bar and any of your rendering) into the alternate BitMap. Normally you let Intuition allocate these alternate BitMaps, but if your screen is CUSTOMBITMAP, you should allocate the alternate BitMaps yourself.

To swap buffers, call the ChangeScreenBuffer() function, which attempts to install the new buffer. ChangeScreenBuffer() will fail if Intuition is temporarily unable to make the change (say while gadgets or menus are active). Intuition builds these functions on top of the graphics.library ChangeVPBitMap() function, so the signalling information that graphics provides is also available to the Intuition user.

To clean up, call FreeScreenBuffer() for each screen buffer. It is not necessary to restore the original buffer before freeing things. Consult the autodocs for full details.

When the user accesses the screen's menus, buffer-swapping will stop. The ChangeScreenBuffer() call will return failure during this time. When the user finishes his menu selection, buffer-swapping will be possible again. Only a small subset of gadgets are supportable in double-buffered screens. These gadgets are those whose imagery returns to the initial state when you release them (e.g., action buttons or the screen's depth gadget). To use other kinds of gadgets (such as sliders or string gadgets) you need to put them on a separate screen, which can be an attached screen.

Windows with borders are not supportable on double-buffered screens. Double-buffered screens are expected to consist nearly entirely of custom rendering.

An example program illustrating double-buffering under Intuition, with menu-lending and an attached screen to hold two slider gadgets is provided.

==== doublebuffer.c ====

<syntaxhighlight>
/*
* doublebuffer.c - shows double-buffering, attached screens, menu lending
*
* Example shows use of double-buffering functions to achieve
* 60 frame-per-second animation. Also shows use of menus in
* double-buffered screens, and the use of attached screens with
* menu-lending to achieve the appearance of slider gadgets in
* double-buffered screens.
*
*/

/*----------------------------------------------------------------------*/

#include <exec/types.h>
#include <graphics/displayinfo.h>
#include <graphics/videocontrol.h>
#include <graphics/gfxbase.h>
#include <intuition/intuitionbase.h>
#include <intuition/gadgetclass.h>
#include <libraries/gadtools.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/graphics.h>
#include <proto/intuition.h>
#include <proto/gadtools.h>

#include <stdlib.h>

/*----------------------------------------------------------------------*/

STRPTR init_all( void );
void error_exit( STRPTR errorstring );
struct Gadget *createAllGadgets( struct Gadget **glistptr, void *vi );
BOOL handleIntuiMessage( struct IntuiMessage *imsg );
void handleDBufMessage( struct Message *dbmsg );
ULONG handleBufferSwap( void );
struct BitMap *makeImageBM( void );
void CloseWindowSafely( struct Window *win );

/*----------------------------------------------------------------------*/

/* Some constants to handle the rendering of the animated face */
#define BM_WIDTH 120
#define BM_HEIGHT 60
#define BM_DEPTH 2

/* Odd numbers to give a non-repeating bounce */
#define CONTROLSC_TOP 191
#define SC_ID HIRES_KEY

/*----------------------------------------------------------------------*/

/* User interface constants and variables */

#define GAD_HORIZ 1
#define GAD_VERT 2

#define MENU_RUN 1
#define MENU_STEP 2
#define MENU_QUIT 3
#define MENU_HSLOW 4
#define MENU_HFAST 5
#define MENU_VSLOW 6
#define MENU_VFAST 7

struct TextAttr Topaz80 =
{
"topaz.font", /* Name */
8, /* YSize */
FS_NORMAL, /* Style */
FPF_ROMFONT|FPF_DESIGNED, /* Flags */
};

struct TagItem vctags[] =
{
VTAG_BORDERSPRITE_SET, TRUE,
TAG_END, 0,
};

UWORD pens[] =
{
0, /* DETAILPEN */
1, /* BLOCKPEN */
1, /* TEXTPEN */
2, /* SHINEPEN */
1, /* SHADOWPEN */
3, /* FILLPEN */
1, /* FILLTEXTPEN */
0, /* BACKGROUNDPEN */
2, /* HIGHLIGHTTEXTPEN */

1, /* BARDETAILPEN */
2, /* BARBLOCKPEN */
1, /* BARTRIMPEN */

(UWORD)~0,
};

struct NewMenu demomenu[] =
{
{ NM_TITLE, "Project", 0 , 0, 0, 0, },
{ NM_ITEM, "Run", "R", 0, 0, ( APTR ) MENU_RUN, },
{ NM_ITEM, "Step", "S", 0, 0, ( APTR ) MENU_STEP, },
{ NM_ITEM, NM_BARLABEL, 0 , 0, 0, 0, },
{ NM_ITEM, "Slower Horizontal", "1", 0, 0, ( APTR ) MENU_HSLOW, },
{ NM_ITEM, "Faster Horizontal", "2", 0, 0, ( APTR ) MENU_HFAST, },
{ NM_ITEM, "Slower Vertical", "3", 0, 0, ( APTR ) MENU_VSLOW, },
{ NM_ITEM, "Faster Vertical", "4", 0, 0, ( APTR ) MENU_VFAST, },

{ NM_ITEM, NM_BARLABEL, 0 , 0, 0, 0, },
{ NM_ITEM, "Quit", "Q", 0, 0, ( APTR ) MENU_QUIT, },

{ NM_END, 0, 0 , 0, 0, 0, },
};

struct Screen *canvassc = NULL;
struct Screen *controlsc = NULL;
struct Window *controlwin = NULL;
struct Window *canvaswin = NULL;
struct Gadget *glist = NULL;
struct Gadget *horizgad, *vertgad;
struct Menu *menu = NULL;
void *canvasvi = NULL;
void *controlvi = NULL;

/*----------------------------------------------------------------------*/

#define OK_REDRAW 1 /* Buffer fully detached, ready for redraw */
#define OK_SWAPIN 2 /* Buffer redrawn, ready for swap-in */

struct GraphicsIFace *IGraphics = NULL;
struct IntuitionIFace *IIntuition = NULL;
struct GadToolsIFace *IGadTools = NULL;

struct MsgPort *dbufport = NULL;
struct MsgPort *userport = NULL;

struct ScreenBuffer *scbuf[] =
{
NULL,
NULL,
};
struct RastPort rport[ 2 ];

ULONG status[ 2 ];

LONG prevx[ 2 ] =
{
50, 50,
};

LONG prevy[ 2 ] =
{
50, 50,
};

ULONG buf_current, buf_nextdraw, buf_nextswap;
ULONG count;
struct BitMap *face = NULL;
LONG x, y, xstep, xdir, ystep, ydir;

/*----------------------------------------------------------------------*/

int main()
{
STRPTR errorstring;
ULONG sigs;
BOOL terminated = FALSE;

/* Let's get everything initialized */
if ( errorstring = init_all() )
{
error_exit( errorstring );
}

count = 0;
buf_current = 0;
buf_nextdraw = 1;
buf_nextswap = 1;
sigs = 0;

while ( !terminated )
{
/* Check for and handle any IntuiMessages */
if ( sigs & ( 1 << userport->mp_SigBit ) )
{
struct IntuiMessage *imsg;

while ( imsg = IGadTools->GT_GetIMsg( userport ) )
{
terminated |= handleIntuiMessage( imsg );
IGadTools->GT_ReplyIMsg( imsg );
}
}

/* Check for and handle any double-buffering messages.
* Note that double-buffering messages are "replied" to
* us, so we don't want to reply them to anyone.
*/
if ( sigs & ( 1 << dbufport->mp_SigBit ) )
{
struct Message *dbmsg;
while ( dbmsg = IExec->GetMsg( dbufport ) )
{
handleDBufMessage( dbmsg );
}
}

if ( !terminated )
{
ULONG held_off = 0;
/* Only handle swapping buffers if count is non-zero */
if ( count )
{
held_off = handleBufferSwap();
}
if ( held_off )
{
/* If were held-off at ChangeScreenBuffer() time, then we
* need to try ChangeScreenBuffer() again, without awaiting
* a signal. We WaitTOF() to avoid busy-looping.
*/
IGraphics->WaitTOF();
}
else
{
/* If we were not held-off, then we're all done
* with what we have to do. We'll have no work to do
* until some kind of signal arrives. This will normally
* be the arrival of the dbi_SafeMessage from the ROM
* double-buffering routines, but it might also be an
* IntuiMessage.
*/
sigs = IExec->Wait( ( 1 << dbufport->mp_SigBit ) | ( 1 << userport->mp_SigBit ) );
}
}
}

error_exit( NULL );
}

/*----------------------------------------------------------------------*/

/* Handle the rendering and swapping of the buffers */

ULONG handleBufferSwap( void )
{
ULONG held_off = 0;
/* 'buf_nextdraw' is the next buffer to draw into.
* The buffer is ready for drawing when we've received the
* dbi_SafeMessage for that buffer. Our routine to handle
* messaging from the double-buffering functions sets the
* OK_REDRAW flag when this message has appeared.
*
* Here, we set the OK_SWAPIN flag after we've redrawn
* the imagery, since the buffer is ready to be swapped in.
* We clear the OK_REDRAW flag, since we're done with redrawing
*/
if ( status[ buf_nextdraw ] == OK_REDRAW )
{
x += xstep*xdir;
if ( x < 0 )
{
x = 0;
xdir = 1;
}
else if ( x > canvassc->Width - BM_WIDTH )
{
x = canvassc->Width - BM_WIDTH - 1;
xdir = -1;
}

y += ystep*ydir;
if ( y < canvassc->BarLayer->Height )
{
y = canvassc->BarLayer->Height;
ydir = 1;
}
else if ( y >= CONTROLSC_TOP - BM_HEIGHT )
{
y = CONTROLSC_TOP - BM_HEIGHT - 1;
ydir = -1;
}

IGraphics->SetAPen( &rport[ buf_nextdraw ], 0 );
IGraphics->RectFill( &rport[ buf_nextdraw ],
prevx[ buf_nextdraw ], prevy[ buf_nextdraw ],
prevx[ buf_nextdraw ] + BM_WIDTH - 1, prevy[ buf_nextdraw ] + BM_HEIGHT - 1 );
prevx[ buf_nextdraw ] = x;
prevy[ buf_nextdraw ] = y;

IGraphics->BltBitMapRastPort( face, 0, 0, &rport[ buf_nextdraw ], x, y,
BM_WIDTH, BM_HEIGHT, 0xc0 );

IGraphics->WaitBlit(); /* Gots to let the BBMRP finish */

status[ buf_nextdraw ] = OK_SWAPIN;

/* Toggle which the next buffer to draw is.
* If you're using multiple ( >2 ) buffering, you
* would use
*
* buf_nextdraw = ( buf_nextdraw+1 ) % NUMBUFFERS;
*
*/
buf_nextdraw ^= 1;
}

/* Let's make sure that the next frame is rendered before we swap...
*/
if ( status[ buf_nextswap ] == OK_SWAPIN )
{
scbuf[ buf_nextswap ]->sb_DBufInfo->dbi_SafeMessage.mn_ReplyPort = dbufport;

if ( IIntuition->ChangeScreenBuffer( canvassc, scbuf[ buf_nextswap ] ) )
{
status[ buf_nextswap ] = 0;

buf_current = buf_nextswap;
/* Toggle which the next buffer to swap in is.
* If you're using multiple ( >2 ) buffering, you
* would use
*
* buf_nextswap = ( buf_nextswap+1 ) % NUMBUFFERS;
*
*/
buf_nextswap ^= 1;

count--;
}
else
{
held_off = 1;
}
}
return( held_off );
}

/*----------------------------------------------------------------------*/

/* Handle Intuition messages */

BOOL handleIntuiMessage( struct IntuiMessage *imsg )
{
UWORD code = imsg->Code;
BOOL terminated = FALSE;

switch ( imsg->Class )
{
case IDCMP_GADGETDOWN:
case IDCMP_GADGETUP:
case IDCMP_MOUSEMOVE:
switch ( ( ( struct Gadget * )imsg->IAddress )->GadgetID )
{
case GAD_HORIZ:
xstep = code;
break;

case GAD_VERT:
ystep = code;
break;
}
break;

case IDCMP_VANILLAKEY:
switch ( code )
{
case 'S':
case 's':
count = 1;
break;

case 'R':
case 'r':
count = ~0;
break;

case 'Q':
case 'q':
count = 0;
terminated = TRUE;
break;
}
break;

case IDCMP_MENUPICK:
while ( code != MENUNULL )
{
struct MenuItem *item;

item = IIntuition->ItemAddress( menu, code );
switch ( ( ULONG ) GTMENUITEM_USERDATA( item ) )
{
case MENU_RUN:
count = ~0;
break;

case MENU_STEP:
count = 1;
break;

case MENU_QUIT:
count = 0;
terminated = TRUE;
break;

case MENU_HSLOW:
if ( xstep > 0 )
{
xstep--;
}
IGadTools->GT_SetGadgetAttrs( horizgad, controlwin, NULL,
GTSL_Level, xstep,
TAG_END );
break;

case MENU_HFAST:
if ( xstep < 9 )
{
xstep++;
}
IGadTools->GT_SetGadgetAttrs( horizgad, controlwin, NULL,
GTSL_Level, xstep,
TAG_END );
break;

case MENU_VSLOW:
if ( ystep > 0 )
{
ystep--;
}
IGadTools->GT_SetGadgetAttrs( vertgad, controlwin, NULL,
GTSL_Level, ystep,
TAG_END );
break;

case MENU_VFAST:
if ( ystep < 9 )
{
ystep++;
}
IGadTools->GT_SetGadgetAttrs( vertgad, controlwin, NULL,
GTSL_Level, ystep,
TAG_END );
break;
}
code = item->NextSelect;
}
break;
}
return( terminated );
}

/*----------------------------------------------------------------------*/

void handleDBufMessage( struct Message *dbmsg )
{
ULONG buffer;

/* dbi_SafeMessage is followed by an APTR dbi_UserData1, which
* contains the buffer number. This is an easy way to extract
* it.
* The dbi_SafeMessage tells us that it's OK to redraw the
* in the previous buffer.
*/
buffer = ( ULONG ) *( ( APTR ** ) ( dbmsg+1 ) );
/* Mark the previous buffer as OK to redraw into.
* If you're using multiple ( >2 ) buffering, you
* would use
*
* ( buffer + NUMBUFFERS - 1 ) % NUMBUFFERS
*
*/
status[ buffer^1 ] = OK_REDRAW;
}

/*----------------------------------------------------------------------*/

/* Get the resources and objects we need */

STRPTR init_all( void )
{
struct Library *GfxBase = IExec->OpenLibrary("graphics.library", 50);
IGraphics = (struct GraphicsIFace*)IExec->GetInterface(GfxBase, "main", 1, NULL);
if ( IGraphics == NULL )
{
return( "Couldn't open Gfx V50\n" );
}

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
if ( IIntuition == NULL )
{
return( "Couldn't open Intuition V50\n" );
}

struct Library *GadToolsBase = IExec->OpenLibrary("gadtools.library", 50);
IGadTools = (struct GadToolsIFace*)IExec->GetInterface(GadToolsBase, "main", 1, NULL);
if ( IGadtools == NULL )
{
return( "Couldn't open GadTools V50\n" );
}

if ( !( dbufport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END) ) )
{
return( "Failed to create port\n" );
}

if ( !( userport = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END) ) )
{
return( "Failed to create port\n" );
}

if ( !( canvassc = IIntuition->OpenScreenTags( NULL,
SA_DisplayID, SC_ID,
SA_Overscan, OSCAN_TEXT,
SA_Depth, 2,
SA_AutoScroll, 1,
SA_Pens, pens,
SA_ShowTitle, TRUE,
SA_Title, "Intuition double-buffering example",
SA_VideoControl, vctags,
SA_Font, &Topaz80,
TAG_END ) ) )
{
return( "Couldn't open screen\n" );
}

if ( !( canvasvi = IGadTools->GetVisualInfo( canvassc, TAG_END ) ) )
{
return( "Couldn't get VisualInfo\n" );
}

if ( !( canvaswin = IIntuition->OpenWindowTags( NULL,
WA_NoCareRefresh, TRUE,
WA_Activate, TRUE,
WA_Borderless, TRUE,
WA_Backdrop, TRUE,
WA_CustomScreen, canvassc,
WA_NewLookMenus, TRUE,
TAG_END ) ) )
{
return( "Couldn't open window\n" );
}
canvaswin->UserPort = userport;

IIntuition->ModifyIDCMP( canvaswin, IDCMP_MENUPICK | IDCMP_VANILLAKEY );

if ( !( controlsc = IIntuition->OpenScreenTags( NULL,
SA_DisplayID, SC_ID,
SA_Overscan, OSCAN_TEXT,
SA_Depth, 2,
SA_Pens, pens,
SA_Top, CONTROLSC_TOP,
SA_Height, 28,
SA_Parent, canvassc,
SA_ShowTitle, FALSE,
SA_Draggable, FALSE,
SA_VideoControl, vctags,
SA_Quiet, TRUE,
SA_Font, &Topaz80,
TAG_END ) ) )
{
return( "Couldn't open screen\n" );
}

if ( !( controlvi = IGadTools->GetVisualInfo( controlsc, TAG_END ) ) )
{
return( "Couldn't get VisualInfo\n" );
}

if ( !( menu = IGadTools->CreateMenus( demomenu, TAG_END ) ) )
{
return( "Couldn't create menus\n" );
}

if ( !IGadTools->LayoutMenus( menu, canvasvi,
GTMN_NewLookMenus, TRUE,
TAG_END ) )
{
return( "Couldn't layout menus\n" );
}

if ( !createAllGadgets( &glist, controlvi ) )
{
return( "Couldn't create gadgets\n" );
}

/* A borderless backdrop window so we can get input */
if ( !( controlwin = IIntuition->OpenWindowTags( NULL,
WA_NoCareRefresh, TRUE,
WA_Activate, TRUE,
WA_Borderless, TRUE,
WA_Backdrop, TRUE,
WA_CustomScreen, controlsc,
WA_NewLookMenus, TRUE,
WA_Gadgets, glist,
TAG_END ) ) )
{
return( "Couldn't open window\n" );
}

controlwin->UserPort = userport;
IIntuition->ModifyIDCMP( controlwin, SLIDERIDCMP | IDCMP_MENUPICK | IDCMP_VANILLAKEY );

IGadTools->GT_RefreshWindow( controlwin, NULL );
IIntuition->SetMenuStrip( canvaswin, menu );
IIntuition->LendMenus( controlwin, canvaswin );

if ( !( scbuf[ 0 ] = IIntuition->AllocScreenBuffer( canvassc, NULL, SB_SCREEN_BITMAP ) ) )
{
return( "Couldn't allocate ScreenBuffer 1\n" );
}

if ( !( scbuf[ 1 ] = IIntuition->AllocScreenBuffer( canvassc, NULL, SB_COPY_BITMAP ) ) )
{
return( "Couldn't allocate ScreenBuffer 2\n" );
}

/* Let's use the UserData to store the buffer number, for
* easy identification when the message comes back.
*/
scbuf[ 0 ]->sb_DBufInfo->dbi_UserData1 = ( APTR ) ( 0 );
scbuf[ 1 ]->sb_DBufInfo->dbi_UserData1 = ( APTR ) ( 1 );
status[ 0 ] = OK_REDRAW;
status[ 1 ] = OK_REDRAW;

if ( !( face = makeImageBM() ) )
{
return( "Couldn't allocate image bitmap\n" );
}
IGraphics->InitRastPort( &rport[ 0 ] );
IGraphics->InitRastPort( &rport[ 1 ] );
rport[ 0 ].BitMap = scbuf[ 0 ]->sb_BitMap;
rport[ 1 ].BitMap = scbuf[ 1 ]->sb_BitMap;

x = 50;
y = 70;
xstep = 1;
xdir = 1;
ystep = 1;
ydir = -1;

/* All is OK */
return( 0 );
}

/*----------------------------------------------------------------------*/

/* Draw a crude "face" for animation */

#define MAXVECTORS 10

struct BitMap *makeImageBM( void )
{
struct BitMap *bm;
struct RastPort rport;
struct AreaInfo area;
struct TmpRas tmpRas;
PLANEPTR planePtr;

BYTE areabuffer[ MAXVECTORS*5 ];

if ( bm = ( struct BitMap * )IGraphics->AllocBitMap( BM_WIDTH, BM_HEIGHT,
BM_DEPTH, BMF_CLEAR, NULL ) )
{
if ( planePtr = IGraphics->AllocRaster( BM_WIDTH, BM_HEIGHT ) )
{
IGraphics->InitRastPort( &rport );
rport.BitMap = bm;

IGraphics->InitArea( &area, areabuffer, MAXVECTORS );
rport.AreaInfo = &area;

IGraphics->InitTmpRas( &tmpRas, planePtr, RASSIZE( BM_WIDTH, BM_HEIGHT ) );
rport.TmpRas = &tmpRas;

IGraphics->SetABPenDrMd( &rport, 3, 0, JAM1 );
IGraphics->AreaEllipse( &rport, BM_WIDTH/2, BM_HEIGHT/2,
BM_WIDTH/2-4, BM_HEIGHT/2-4 );
IGraphics->AreaEnd( &rport );

IGraphics->SetAPen( &rport, 2 );
IGraphics->AreaEllipse( &rport, 5*BM_WIDTH/16, BM_HEIGHT/4,
BM_WIDTH/9, BM_HEIGHT/9 );
IGraphics->AreaEllipse( &rport, 11*BM_WIDTH/16, BM_HEIGHT/4,
BM_WIDTH/9, BM_HEIGHT/9 );
IGraphics->AreaEnd( &rport );

IGraphics->SetAPen( &rport, 1 );
IGraphics->AreaEllipse( &rport, BM_WIDTH/2, 3*BM_HEIGHT/4,
BM_WIDTH/3, BM_HEIGHT/9 );
IGraphics->AreaEnd( &rport );

IGraphics->FreeRaster( planePtr, BM_WIDTH, BM_HEIGHT );
}
else
{
IGraphics->FreeBitMap( bm );
bm = NULL;
}
return( bm );
}
}

/*----------------------------------------------------------------------*/

/* Make a pair of slider gadgets to control horizontal and vertical
* speed of motion.
*/
struct Gadget *createAllGadgets( struct Gadget **glistptr, void *vi )
{
struct NewGadget ng;
struct Gadget *gad;

gad = IGadTools->CreateContext( glistptr );

ng.ng_LeftEdge = 100;
ng.ng_TopEdge = 1;
ng.ng_Width = 100;
ng.ng_Height = 12;
ng.ng_GadgetText = "Horiz: ";
ng.ng_TextAttr = &Topaz80;
ng.ng_VisualInfo = vi;
ng.ng_GadgetID = GAD_HORIZ;
ng.ng_Flags = 0;

horizgad = gad = IGadTools->CreateGadget( SLIDER_KIND, gad, &ng,
GTSL_Min, 0,
GTSL_Max, 9,
GTSL_Level, 1,
GTSL_MaxLevelLen, 1,
GTSL_LevelFormat, "%ld",
TAG_END );

ng.ng_LeftEdge += 200;
ng.ng_GadgetID = GAD_VERT;
ng.ng_GadgetText = "Vert: ";
vertgad = gad = IGadTools->CreateGadget( SLIDER_KIND, gad, &ng,
GTSL_Min, 0,
GTSL_Max, 9,
GTSL_Level, 1,
GTSL_MaxLevelLen, 1,
GTSL_LevelFormat, "%ld",
TAG_END );

return( gad );
}

/*----------------------------------------------------------------------*/

/* Clean up everything and exit, printing the errorstring if any */
void error_exit( STRPTR errorstring )
{
if ( controlwin )
{
IIntuition->ClearMenuStrip( controlwin );
CloseWindowSafely( controlwin );
}

if ( canvaswin )
{
IIntuition->ClearMenuStrip( canvaswin );
CloseWindowSafely( canvaswin );
}

if ( controlsc )
{
IIntuition->CloseScreen( controlsc );
}

if ( canvassc )
{
IIntuition->FreeScreenBuffer( canvassc, scbuf[ 1 ] );
IIntuition->FreeScreenBuffer( canvassc, scbuf[ 0 ] );
IIntuition->CloseScreen( canvassc );
}

if ( dbufport )
{
IExec->FreeSysObject(ASOT_PORT, dbufport );
}

if ( userport )
{
IExec->FreeSysObject(ASOT_PORT, userport );
}

if ( IGadTools )
{
IGadTools->FreeGadgets( glist );
IGadTools->FreeMenus( menu );
IGadTools->FreeVisualInfo( canvasvi );
IGadTools->FreeVisualInfo( controlvi );
struct Library *libBase = IGadTools->Data.LibBase;
IExec->DropInterface((struct Interface*)IGadTools);
IExec->CloseLibrary( libBase );
}

if ( IIntuition )
{
struct Library *libBase = IIntuition->Data.LibBase;
IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary( libBase );
}

if ( face )
{
IGraphics->FreeBitMap( face );
}

if ( IGraphics )
{
struct Library *libBase = IGraphics->Data.LibBase;
IExec->DropInterface((struct Interface*)IGraphics);
IExec->CloseLibrary( libBase );
}

if ( errorstring )
{
IDOS->Printf( errorstring );
exit( 20 );
}

exit( 0 );
}

/*----------------------------------------------------------------------*/

/* these functions close an Intuition window
* that shares a port with other Intuition
* windows or IPC customers.
*
* We are careful to set the UserPort to
* null before closing, and to free
* any messages that it might have been
* sent.
*/
#include "exec/types.h"
#include "exec/nodes.h"
#include "exec/lists.h"
#include "exec/ports.h"
#include "intuition/intuition.h"

void
CloseWindowSafely( struct Window *win )
{
/* we forbid here to keep out of race conditions with Intuition */
IExec->Forbid();

/* send back any messages for this window
* that have not yet been processed
*/
IIntuition->StripIntuiMessages( win->UserPort, win );

/* clear UserPort so Intuition will not free it */
win->UserPort = NULL;

/* tell Intuition to stop sending more messages */
IIntuition->ModifyIDCMP( win, 0L );

/* turn multitasking back on */
IExec->Permit();

/* and really close the window */
IIntuition->CloseWindow( win );
}
</syntaxhighlight>

== Other Screen Functions ==

Other screen functions provided by Intuition control screen depth arrangement, screen movement, the screen title bar and provide a visual "error beep".

=== Screen Depth Arrangement ===

ScreenToFront() and ScreenToBack() make a screen either the frontmost or the backmost screen. If an application needs to render into a screen before the screen becomes visible to the user, the screen may be opened behind all other screens and later moved to the front when ready with ScreenToFront().

<syntaxhighlight>
VOID ScreenToFront( struct Screen * );
VOID ScreenToBack ( struct Screen * );
</syntaxhighlight>

Depth control of screens is also available through the depth arrangement gadget in the screen's title bar or through keyboard shortcuts. The N key with the Left-Amiga qualifier moves the Workbench screen to front. The M key with the Left-Amiga qualifier moves the frontmost screen to back. Repeated selection of Left-Amiga-M will cycle through available screens. These keys are processed through the keymap and will retain their value even if the key location changes.

=== Screen Movement and Scrolling ===

The MoveScreen() function moves the screen origin by the number of pixels specified in dx and dy.

<syntaxhighlight>
VOID MoveScreen( struct Screen *myscreen, WORD dx, WORD dy );
</syntaxhighlight>

Calls to MoveScreen() are asynchronous; the screen is not necessarily moved upon return of this function. If the calls happen too quickly, there may be unexpected results. One way to pace these calls is to call the function one time for each IDCMP_INTUITICKS event.

Screen movement is also available through the screen's drag gadget in the title bar and through a keyboard/mouse shortcut. Left-Amiga with the select button of the mouse anywhere within the screen will drag the screen (even if the title bar is totally concealed by a window). Dragging a screen down will reveal any screen(s) behind it. Screens are never revealed to the left, right or bottom of another screen.

Additionally, oversized screens may be moved with the autoscroll feature. With autoscroll, the screen is automatically scrolled as the pointer reaches one of the edges of the display. Autoscroll only works on the active screen.

Another screen movement feature is ''menu snap''. When a screen much larger than the viewing area is scrolled such that the upper left corner is not visible (scrolled down or to the right), menus may could be out of the visible portion of the screen. To prevent this, ''menu snap'' moves the screen to a position where the menus will be visible before rendering them. The screen appears to snap to the home position as the menus are selected, moving back when the operation is complete. If the Left-Amiga qualifier is held when the menus are selected then the screen will remain in the home position when the menu button is released.

The Intuition preferences editor, IControl, allows the user to change a number of Intuition features. Some of these features include the ability to globally disable menu snap, and to change the select qualifier for dragging the screen. See the User's Manual for more information on Preferences editors.

=== Miscellaneous Screen Functions ===

Three other functions used with screens are DisplayBeep(), ShowTitle() and GetScreenData(). DisplayBeep() flashes the screen colors to inform the user of an error or problem.

<syntaxhighlight>
VOID DisplayBeep( struct Screen *myscreen );
</syntaxhighlight>

Since not all users will have speakers attached to the system, DisplayBeep() can be used to provide a visible bell. DisplayBeep() can beep any single screen or, if myscreen is set to NULL, all screens.

ShowTitle() determines whether the screen's title bar will be displayed in front of or behind any backdrop windows on the screen.

<syntaxhighlight>
VOID ShowTitle( struct Screen *myscreen, BOOL infront );
</syntaxhighlight>

By default, the screen's title bar is set to display in front of backdrop windows. Call this function with infront set to FALSE to put the screen title bar behind backdrop windows. This can also be set when the screen is opened with the SA_ShowTitle tag.

== Function Reference ==

The following are brief descriptions of the Intuition functions that relate to the use of Intuition screens. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| OpenScreenTagList()
| Open a screen.
|-
| OpenScreenTags()
| Alternate calling sequence for OpenScreenTagList().
|-
| OpenScreen()
| Pre-V36 open screen function.
|-
| CloseScreen()
| Close an open screen.
|-
| MoveScreen()
| Change the position of an open screen.
|-
| ScreenToBack()
| Move a screen behind all other screens.
|-
| ScreenToFront()
| Move a screen in front of all other screens.
|-
| ShowTitle()
| Show the screen in front of through backdrop windows.
|-
| GetScreenDrawInfo()
| Get the DrawInfo information for an open screen.
|-
| FreeScreenDrawInfo()
| Free the DrawInfo information for a screen.
|-
| QueryOverscan()
| Find overscan information for a specific display type.
|-
| LockPubScreen()
| Obtain a lock on a public screen.
|-
| UnlockPubScreen()
| Release a lock on a public screen.
|-
| NextPubScreen()
| Return the name of the next public screen in the list.
|-
| PubScreenStatus()
| Make a public screen private or private screen public.
|-
| LockPubScreenList()
| Lock the public screen list (for a public screen utility).
|-
| UnlockPubScreenList()
| Unlock the public screen list.
|-
| SetDefaultPubScreen()
| Change the default public screen.
|-
| SetPubScreenModes()
| Establish global public screen behavior.
|-
| GetDefaultPubScreen()
| Copies the name of the default public screen to a buffer.
|-
| OpenWorkBench()
| Open the Workbench screen, if closed.
|-
| CloseWorkBench()
| Close the Workbench screen, if possible.
|-
| WBenchToBack()
| Move the Workbench screen behind all other screens.
|-
| WBenchToFront()
| Move the Workbench screen in front of all other screens.
|-
| GetScreenData()
| Pre-V36 way to return information on an open screen.
|-
| GetScreenAttr()
| Query a screen attribute.
|-
| GetScreenAttr() / GetScreenAttrsA()
| Query screen attributes.
|-
| ViewAddress()
| Return the address of a screen's View.
|-
| ViewPortAddress()
| Use &screen->ViewPort instead.
|-
| MakeScreen()
| Low level screen handling-rebuild Copper list.
|-
| RethinkDisplay()
| Low level screen handling-incorporate Copper list changes.
|-
| RemakeDisplay()
| MakeScreen() for all screens, then RethinkDisplay().
|}

DeveloperDoc:Main

2017-04-11T12:25:25Z

Daniel Jedlicka: /* Introduction */

== Introduction ==

Many programming languages can be used on AmigaOS, ranging from interpreted scripting languages to comprehensive compiled languages:

* [[AmigaOS Manual: ARexx|ARexx]]: the native AmigaOS scripting language, good for beginners,small projects and talking between applications.
* Python: a common cross platform scripting language ported to & included with AmigaOS.
* C: the primary compiled language for AmigaOS.
* [https://aglet.web.runbox.net/ Modula2]: the compiled language that evolved from Pascal.
* [http://cshandley.co.uk/portable/PortablE.html E]: an Amiga native compiled language.

ARexx is built into AmigaOS and its original documentation can be found in [[AmigaOS Manual: ARexx|this part]] of the Developer's Wiki.

A native compiler for the C language is part of the downloadable [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK].

Most of the remaining AmigaOS Developers Wiki provides the latest information on how to program systems running AmigaOS 4.x with the C language. It has been updated for Release 4.0 and higher of AmigaOS and covers all the computer systems which run the Amiga operating system from the Commodore A1200 all the way up to the AmigaOne X5000.

The Wiki assumes some previous experience with programming and familiarity with computers in general. Although it is not required, a knowledge of the C programming language will make it much easier to understand the material in this book. Most of the Amiga operating system is written in C, hence C is the language used for the programming examples.

Many of the AmigaOS concepts, methods described in the wiki for C will also be applicable to other compiled languages, with some variations. Please see the documentation of the respective languages.

This wiki is intended for the following audiences:

* Programmers who want to create application software for AmigaOS systems.
* Software developers who want to upgrade their software for Release 4.0 or higher of the operating system.
* Anyone who wants to know more about how AmigaOS works.

The system software is organized into related groups of functions called libraries. The same basic organization is used for this wiki.

== Software Development Kit (SDK) ==

You can find the [http://www.hyperion-entertainment.biz/index.php?option=com_registration&view=files&parent=30&Itemid=63 AmigaOS SDK at this location].

[[SDK Release Notes|Release Notes]]

[[SDK FAQ|Frequency Asked Questions]]

[[Autodocs:Main|Autodocs]]

[[Fundamental Types]]

== Reference ==

[[Kernel]]

[[Libraries]]

[[Devices]]

[[Resources]]

[[User Interface Style Guide]]

== General Information ==

[[AmigaOS Versions]]

[[Controlling Application Stack]]

[[GUI Programming]]

[[Programming in the Amiga Environment]]

[[Libraries and Devices]]

[[Migration Guide]]

[[Troubleshooting Your Software]]

[[Understanding the alert error numbers]]

[[Release 4 Compatibility]]

[[Writing apps for Xena]]

[[AmigaGuide 101]]

[[Installation Utility]]

[[Optimized Window Refreshing]]

[[Autodoc Style Guide]]

[[Debug Kernel]]

[[AmiDock and Dockies]]

[[Command Line Interface]]

[[DCFS and LNFS Low Level Data Structures]]

Exec Memory Pools

2016-04-09T19:36:35Z

Daniel Jedlicka: Fixed a typo: MEMF_CLEARED doesn't exist.

== Introduction ==

A memory pool is a block of memory that an application allocates for all its memory needs. The application draws from this pool rather than the system's free memory list whenever it requires memory.

Memory pools add to the efficiency of the system and applications in two ways. The first is a potential decrease in memory fragmentation. Memory fragmentation is a condition where system memory is made up of blocks of allocated memory interspersed with blocks of free memory. The second benefit of memory pools is faster memory allocations and deallocations.

By having an application take a pool of memory and allocate from it, fragmentation of system memory is decreased. An application may require six allocations ranging from 20 to 678 bytes in size which can be scattered throughout system memory. However, if those same six allocations are taken from a pool, the fragmentation occurs within the pool, but as far as the system is concerned, it's missing one large block instead of six small ones.

An application using a memory pool will have faster memory allocations because the memory list of a pool is smaller, and therefore easier to traverse than the memory list of the system memory. For deallocations, it's even faster because deleting the pool itself deletes all the individual allocations made from it instead of having to deallocate each piece that was allocated.

If you know that your memory pool allocations will always be of the same size, prefer using an [[Exec_Item_Pools|item pool]].

== Memory Pool Organization ==

A memory pool consists of units called puddles. Other than that, it has no formal organization. There is no pool structure defined anywhere. All you know about a pool is its address. Exec's pool manager handles the rest of the details.

When you create a pool, you specify the size of its puddles and a threshold value, not the size of the pool. This is because memory pools are dynamic, they have no fixed size. The pool manager takes the memory for your application from the puddles. As you require memory, the pool manager expands the pool by adding puddles, and as you free memory, the pool manager shrinks the pool by deleting puddles.

The size of the puddles is important because the pool manager will try to use as much of a puddle as possible before adding a new puddle. Each time you allocate memory from the pool, the pool manager takes the memory from a puddle unless an allocation exceeds the amount of memory remaining in a puddle. If the allocation request exceeds the memory remaining in a puddle, the pool manager adds a new puddle. If the allocation exceeds the pool's puddle size, the pool manager will create a special over-sized puddle to accommodate the allocation.

The key is to use all the drops in a puddle. If you create a pool with puddles of 200 bytes and allocate 150 bytes at a time, you'll waste 50 bytes in every puddle. Set the puddle size in accordance with your memory requirements.

The threshold value is the size of the largest allocation to use within a single puddle. An allocation request larger than the threshold value causes the pool manager to add a new puddle. Ideally, the threshold value should be the size of the largest allocation you will make.

The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size, so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.

== Creating a Memory Pool ==

You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEAR flag may also be specified to automatically clear memory allocated from the pool.

If successful, AllocSysObject() returns the address of the memory pool.

<syntaxhighlight>
APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_Puddle, 4096,
ASOPOOL_Threshold, 2048,
TAG_END);

if (mem_pool != NULL)
{
// ...
}
else
IDOS->Printf("Pool could not be created.\n");
</syntaxhighlight>

The example above attempts to create a pool of memory with a puddle size of 4096 bytes and a threshold size of 2048 bytes.

If your application requires memory of different types (for example, private memory and shared memory), it must create a pool for each type.

Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

== Allocating Memory from a Pool's Puddles ==

Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.

<syntaxhighlight>
struct Rectangle *rect = IExec->AllocPooled(mem_pool, sizeof(struct Rectangle);

if (rect != NULL)
{
// ...
}
else
IDOS->Printf("Memory could not be allocated.\n");
</syntaxhighlight>

== Freeing Memory from a Pool's Puddles ==

An application can free a block of memory it allocated from a pool by calling FreePooled():

<syntaxhighlight>
IExec->FreePooled(mem_pool, mem_drop, mem_size);
</syntaxhighlight>

This function requires a pointer to the memory pool (mem_pool), a pointer to the block of memory being freed (mem_drop), and the size of the memory being freed (mem_size).

== Deleting a Memory Pool ==

A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.

<syntaxhighlight>
IExec->FreeSysObject(ASOT_MEMPOOL, mem_pool);
</syntaxhighlight>

Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With FreeSysObject(), it would take only one call instead of many.

== Concurrent Access ==

Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.

<syntaxhighlight>
APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_MFlags, MEMF_SHARED,
ASOPOOL_Puddle, 4096,
ASOPOOL_Threshold, 2048,
ASOPOOL_Protected, TRUE,
TAG_END);
</syntaxhighlight>

In this case, the memory is being shared between two Tasks or Processes so it must be of type MEMF_SHARED. By specifying that the memory pool is protected we are guaranteed all operations performed on the memory pool are thread safe.

== Function Reference ==

The following table gives a brief description of the Exec functions that control memory pools. See the SDK/Autodocs for more details about each call.

{| class="wikitable"
! Function
! Description
|-
| AllocPooled()
| Allocate memory with the pool manager.
|-
| AllocSysObject(ASOT_MEMPOOL)
| Allocate and initialize a new memory pool.
|-
| AllocVecPooled()
| Allocate memory with the pool manager and track size.
|-
| FreePooled()
| Free pooled memory.
|-
| FreeSysObject(ASOT_MEMPOOL)
| Free a memory pool.
|-
| FreeVecPooled()
| Free pooled memory allocated with AllocVecPooled().
|}

=== Obsolete ===

These Exec functions are now practically obsolete and not recommended for use in new code:

{| class="wikitable"
! Function
! Description
|-
| CreatePool()
| Use AllocSysObject(ASOT_MEMPOOL) instead.
|-
| DeletePool()
| Use FreeSysObject(ASOT_MEMPOOL) instead.
|}

Programming in the Amiga Environment

2016-03-20T19:00:24Z

Daniel Jedlicka: Fixed a typo.

{{NeedUpdate}}
== Programming in the Amiga Environment ==

To program in the Amiga's dynamic environment you need to understand these special features of the Amiga's design:

* Multitasking (without memory protection)
* Shared libraries of functions
* Dynamic memory architecture (no memory map)
* Operating system versions
* Custom chips with DMA access (two kinds of memory)

=== Multitasking ===

The key feature of the Amiga's operating system design is ''multitasking''. Multitasking means many programs, or tasks, reside in memory at the same time sharing system resources with one another. Programs take turns running so it appears that many programs are running simultaneously.

Multitasking is based on the concept that a program spends most of its time waiting for things to happen. A program waits for events like key presses, mouse movement, or disk activity. While a program is waiting, the CPU is idle. The CPU could be used to run a different program during this idle period if there was a convenient method for rapidly switching from one program to another. This is what multitasking does.

=== What the System Does For You ===

The Amiga uses ''preemptive multitasking'' which means that the operating system keeps track of all the tasks in memory and decides which one should run. The system checks hundreds of times per second to see which task should be run based on whether or not it is waiting, and other factors. Since the system handles all the work of task switching, multitasking is transparent to the application. From the application's point of view, it appears to have the machine all to itself.

The Amiga OS also manages the sharing of resources between tasks. This is important because in order for a variety of tasks to run independently in the Amiga's multitasking environment, tasks must be prevented from interfering with one another. Imagine if five tasks were allowed to use the parallel port at the same time. The result would be I/O chaos. To prevent this, the operating system provides an arbitration method (usually a function call) for every system resource. For instance you must call a function, AllocMem(), to get exclusive access to a block of memory.

=== What the System Doesn't Do For You ===

The Amiga operating system handles most of the housekeeping needed for multitasking, but this does not mean that applications don't have to worry about multitasking at all. The current generation of Amiga systems do not have hardware memory protection, so there is nothing to stop a task from using memory it has not legally acquired. An errant task can easily corrupt some other task by accidentally overwriting its instructions or data. Amiga programmers need to be extra careful with memory; one bad memory pointer can cause the machine to crash (debugging utilities such as MungWall and Enforcer will prevent this).

In fact, Amiga programmers need to be careful with every system resource, not just memory. All system resources from audio channels to the floppy disk drives are shared among tasks. Before using a resource, you must ask the system for access to the resource. This may fail if the resource is already being used by another task. Once you have control of a resource, no other task can use it, so give it up as soon as you are finished. When your program exits, you must give everything back whether it's memory, access to a file, or an I/O port. You are responsible for this, the system will not do it for you automatically.

{{Note|title=What Every Amiga Programmer Should Know|text=The Amiga is a ''multitasking'' computer. Keep in mind that other tasks are running at the same time as your application. Always ask the system for control of any resource you need; some other task may already be using it. Give it back as soon as you are done; another task may want to use it. This applies to just about every computing activity your application can perform.}}

=== Libraries of functions ===

Most of the routines that make up the Amiga's operating system are organized into groups called libraries. Each library then contains one or more interfaces. In order to call a function on the Amiga you must first open the library that contains the function. Next, you get the interface which contains the function you want to call. For example, if you want to call the Read() function to read data from disk you must first open the [[AmigaDOS Introduction|DOS]] library and then get the "main" interface the Read() function is defined in.

The system's master library, called [[Exec]], is always open. [[Exec]] keeps track of all the other [[Exec Libraries|libraries]] and is in charge of opening and closing them. [[Exec]]'s "main" interface contains the OpenLibrary() function which is used to open all the other libraries.

Almost any program you write for the Amiga will have to call the OpenLibrary() and GetInterface() functions. Usage is as follows:

<syntaxhighlight>
// Global: declare this above main()
struct Library *LibBase;
struct Interface *LibIFace;

int main()
{
LibBase = IExec->OpenLibrary("library.name", libversion);
if(LibBase == NULL)
{
// Library did not open, so exit.
}
else
{
LibIFace = IExec->GetInterface(LibBase, "main", ifaceversion, NULL);
if(LibIFace == NULL)
{
IExec->CloseLibrary(LibBase);
// Could not get Interface, so exit.
}
else
{
// Interface obtained, so use its functions.
}
}
}
</syntaxhighlight>

; LibBase
: This is a pointer to the library structure in memory, often referred to as the ''library base''. The library may or may not be global depending on your needs. The name of this pointer may be changed although it is proper to use the established standard name. Refer to the list below for the appropriate name.

; LibIFace
: This is a pointer to the interface structure in memory. The interface may or may not be global depending on your needs. The name of this pointer may be changed although it is proper to use the established standard name. Refer to the list below for the appropriate name.

; library.name
: This is a C string that describes the name of the library you wish to open. The list of Amiga library names is given below.

; main
: This is a C string that describes the name of the interface you wish to use. The list of Amiga interface names depends on the library and is given below.

; libversion
: This should be set to the earliest acceptable library version. A value of 0 matches any version. A value of 53 means you require at least version 53 or a later version of the library. If the library version in the system is older than the one you specify, OpenLibrary() will fail (return 0).

; ifaceversion
: This should be set to the interface version you require. Each interface has a unique version number which defines all the functions in that interface. Most often an interface will have a single interface version of 1. If the interface version in the system does not match, GetInterface() will fail (return 0).

The table listed below shows all the function libraries that are currently part of the Amiga system software.

{| class="wikitable"
|+ Parameters to use with OpenLibrary()
!Library Name
!Library Base
!Oldest Library Version In Use
!Interface Name:Version
|-
| library.name* || LibBase || version || iface.name:version
|-
| asl.library || AslBase || 50 || main:1
|-
| commodities.library || CxBase || 50 || main:1
|-
| diskfont.library || DiskfontBase || 50 || main:1
|-
| dos.library || DOSBase || 50 || main:1
|-
| [[Introduction to Exec|exec.library]] || ExecBase || 50 || main:1
|-
| [[Expansion Library|expansion.library]] || ExpansionBase || 50 || main:1
|-
| gadtools.library || GadToolsBase || 50 || main:1
|-
| graphics.library || GfxBase || 50 || main:1
|-
| icon.library || IconBase || 50 || main:1
|-
| iffparse.library || IFFParseBase || 50 || main:1
|-
| intuition.library || IntuitionBase || 50 || main:1
|-
| keymap.library || KeymapBase || 50 || main:1
|-
| layers.library || LayersBase || 50 || main:1
|-
| mathffp.library || MathBase || 50 || main:1
|-
| mathtrans.library || MathTransBase || 50 || main:1
|-
| mathieeedoubbas.library || MathIeeeDoubBasBase || 50 || main:1
|-
| mathieeedoubtrans.library || MathIeeeDoubTransBase || 50 || main:1
|-
| mathieeesingbas.library || MathIeeeSingBasBase || 50 || main:1
|-
| mathieeesingtrans.library || MathIeeeSingTransBase || 50 || main:1
|-
| rexxsyslib.library || RexxSysBase || 50 || main:1
|-
| translator.library || TranslatorBase || 50 || main:1
|-
| [[Utility Library|utility.library]] || UtilityBase || 50 || main:1
|-
| workbench.library || WorkbenchBase || 50 || main:1
|}

* Other libraries may exist that are not supplied by the AmigaOS development team since it is a feature of the operating system to allow such libraries.

==== Opening a Library in C ====

Here's a brief example showing how OpenLibrary() and GetInterface() are used in C.

<syntaxhighlight>
/* easy.c: a complete example of how to open an Amiga function library in C.
* In this case the function library is Intuition. Once the Intuition
* function library is open and the interface obtains, any Intuition function
* can be called. This example uses the DisplayBeep() function of Intuition to
* flash the screen.
*/

#include <proto/exec.h>
#include <proto/intuition.h>

struct Library *IntuitionBase;
struct IntuitionIFace *IIntuition;

int main()
{
IntuitionBase = IExec->OpenLibrary("intuition.library", 50);

// Note it is safe to call GetInterface() with a NULL library pointer.
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if(IIntuition != NULL) /* Check to see if it actually opened. */
{ /* The Intuition library is now open so */
IIntuition->DisplayBeep(0); /* any of its functions may be used. */
}

// Always drop the interface and close the library if not in use.
// Note it is safe to call DropInterface() and CloseLibrary() with NULL pointers.
IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}
</syntaxhighlight>

==== Another Kind of Function Library ====

The Amiga has two kinds of libraries: run-time libraries and link libraries. All the libraries discussed so far are run-time libraries. Run-time libraries make up most of the Amiga's operating system and are the main topic of this book.

There is another type of library known as a link library. Even though a link library is a collection of functions just like a run-time library, there are some major differences in the two types.

A run-time, or shared library is a group of functions managed by [[Exec]] that resides either in ROM or on disk (in the "LIBS:" directory). A run-time library must be opened before it can be used (as explained above). The functions in a run-time library are accessed dynamically at run-time and can be used by many programs at once even though only one copy of the library is in memory. A disk based run-time library is loaded into memory only if requested by a program and can be automatically flushed from memory when no longer needed.

A link library is a group of functions on disk that are managed by the compiler at link time. Link libraries do not have to be opened before they are used, instead you must link your code with the library when you compile a program. The functions in a link library are actually copied into every program that uses them. For instance the exit() function used in the C program listed above is not part of any of the libraries that make up the Amiga OS. It comes from the link library supplied with the compiler. The code that performs the exit() function is copied into the program when it is compiled.

==== Libraries, Devices and Resources ====

Most of the Amiga's OS routines are organized into groups of shared run-time libraries. The Amiga also has specialized function groups called ''devices'' and ''resources'' that programmers use to perform basic I/O operations or access low-level hardware.

Devices and resources are similar in concept to a shared run-time library. They are managed by [[Exec]] and must be opened before they can be used. Their functions are separate from the programs that use them and are accessed dynamically at run time. Multiple programs can access the device or resource even though only one copy exists in memory (a few resources can only be used by one program at a time.)

[[File:LibFig1-1a.png|frame|center|'''Figure 1-1: Amiga System Software Hierarchy''']]

<center></center>

Devices and resources are managed by [[Exec]] just as libraries are. For more information on devices and resources, see the respective sections.

{{Note|title=What Every Amiga Programmer Should Know|text=The functions in the Amiga OS are accessed through shared run-time libraries. Libraries must be opened before their functions may be used. The system's master library, [[Exec]], is always open. The [[Exec]] function OpenLibrary() is used to open all other libraries.}}

=== Dynamic memory architecture ===

Unlike some microcomputer operating systems, the AmigaOS relies on absolute memory addresses as little as possible. Instead the Amiga OS uses a technique (sometimes referred to as soft machine architecture) which allows system routines and data structures to be positioned anywhere in memory.

Amiga run-time libraries may be positioned anywhere in memory because they are always accessed through a jump table. Each library whether in ROM or loaded from disk has an associated Library structure and jump table in RAM.

[[File:LibFig1-1b.png|frame|center|Amiga Library Structure and Jump Table]]

The system knows where the jump table starts in RAM because when a library is opened for the first time, [[Exec]] creates the library structure and keeps track of its location. The order of the entries in the library's jump table is always preserved between versions of the OS but the functions they point to can be anywhere in memory. Hence, system routines in ROM may be moved from one version of the OS to another. Given the location of the jump table and the appropriate offset into the table, any function can always be found.

Not only are system routines relocatable but system data structures are too. In the Amiga's multitasking environment, multiple applications run at the same time and each may have its own screen, memory, open files, and even its own subtasks. Since any number of application tasks are run and stopped at the user's option, system data structures have to be set up as needed. They cannot be set up ahead of time at a fixed memory location because there is no way to tell how many and what type will be needed.

The Amiga system software manages this confusion by using ''linked lists'' of information about items such as libraries, tasks, screens, files and available memory. A linked list is a chain of data items with each data item containing a pointer to the next item in the chain. Given a pointer to the first item in a linked list, pointers to all the other items in the chain can be found.

==== Exec: The System Executive ====

On the Amiga, the module that keeps track of linked lists is [[Exec]], the system executive. [[Exec]] is the heart of the Amiga operating system since it also is in charge of multitasking, granting access to system resources (like memory) and managing the Amiga library system.

As previously discussed, memory location 4 ($0000 0004), also known as SysBase, contains a pointer to the [[Exec]] library structure. This is the only absolutely defined location in the Amiga operating system. A program need only know where to find the [[Exec]] library to find, use and manipulate all other system code and data.

[[File:LibFig1-2.png|frame|center|[[Exec]] and the Organization of the Amiga OS]]

The diagram above shows how the entire Amiga operating system is built as a tree starting at SysBase. [[Exec]] keeps linked lists of all the system libraries, devices, memory, tasks and other data structures. Each of these in turn can have its own variables and linked lists of data structures built onto it. In this way, the flexibility of the OS is preserved so that upgrades can be made without jeopardizing compatibility.

{{Note|title=What Every Amiga Programmer Should Know|text=The Amiga has a dynamic memory map. There are no fixed locations for operating system variables and routines. Do not call ROM routines or access system data structures directly. Instead use the indirect access methods provided by the system.}}

=== Operating system versions ===

The Amiga operating system has undergone several major revisions. The latest revision is Release 4.1 (corresponds to library version 53).

See the table in the [[Introduction_to_Exec#Libraries_and_Devices|Libraries and Devices]] section for details on which version corresponds to which OS release.

The examples listed throughout this wiki assume you are using Release 4.0 or higher.

Many of the libraries and functions documented in this manual are available in all versions of the Amiga operating system. Others are completely new and cannot be used unless you have successfully opened the appropriate version of the library.

To find out which functions are new, refer to the SDK. The functions which are new are marked with ''(V50)'' or ''(V51)'' in the NAME line of the function Autodoc. These new functions require you to use the corresponding version number (50, 51, or higher) when opening the library.

Exit gracefully and informatively if the required library version is not available.

==== About Release 4 ====

Release 4 first appeared on the ''AmigaOne XE''. This initial version corresponds to Kickstart 4.0, system library version number V50.

{{Note|title=What Every Amiga Programmer Should Know|text=Some libraries or specific functions are not available in older versions of the Amiga operating system. Be sure to ask for the lowest library version that meets the requirements of your program.}}

==== Two Kinds of Memory ====

To keep the Classic Amiga running efficiently, the Classic Amiga has two memory buses and two kinds of memory. ''Chip memory'' is memory that both the CPU and custom chips can access. ''Fast memory'' is memory that only the CPU (and certain expansion cards) can access. Since Chip memory is shared, CPU access may be slowed down if the custom chips are doing heavy-duty processing. CPU access to Fast memory is never slowed down by contention with the custom chips.

The distinction between Chip memory and Fast memory is very important for Classic Amiga programmers to keep in mind because any data accessed directly by the custom chips such as video display data, audio data or sprite data ''must be in Chip memory''.

{| class="wikitable"
| ''What Every Amiga Programmer Should Know'': The Classic Amiga has ''two'' kinds of memory: ''Chip'' memory and ''Fast'' memory. Use the right kind.
|}

'''NOTE'''
There is no such thing as ''Chip'' memory in any of new PowerPC-based Amiga systems. The two types of memory only applies to the Classic Amiga hardware platforms such as the A1200 and A4000 models.

== About the Examples ==

For the most part, the examples in this book are written in C.

C examples have been compiled using the standard Software Development Kit (SDK) using GCC.

In general, the examples are also compatible with vbcc and other C compilers, however some changes will usually be necessary.

Specifically, all the C examples assume that the automatic Ctrl-C feature of the compiler has been disabled. For SAS C (and Lattice C revisions 4.0 and greater) this is handled with:

<pre>
/* Add this before main() to override the default Ctrl-C handling
* provided in SAS (Lattice) C. Ctrl-C event will be ignored */

int CXBRK ( void ) { return(0); }
int chkabort( void ) { return(0); }
</pre>

Other changes may be required depending on the example and the C compiler you are using. Most of the C examples do not require any special options and rely on the defaults provided by the SDK.

Except where noted, each example was linked with the standard newlib startup code which provides the following interfaces: IExec, IDOS and IUtility.

== General Amiga Development Guidelines ==

This sections presents specific guidelines that all Amiga programmers must follow. Some of these guidelines are for advanced programmers.

* Check for memory loss. Arrange your Workbench screen so that you have a Shell available and can start your program without rearranging any windows. In the Shell window type Avail flush several times (the flush option requires the Release 2 version of the Avail command). Note the total amount of free memory. Run your program (do not rearrange any windows other than those created by the program) and then exit. At the Shell, type Avail flush several times again. Compare the total amount of free memory with the earlier figure. They should be the same. Any difference indicates that your application is not freeing some memory it used or is not closing a disk-loaded library, device or font it opened. Note that under Release 2, a small amount of memory loss is normal if your application is the first to use the audio or narrator device.

* Use all of the program debugging and stress tools that are available when writing and testing your code. New debugging tools such as Enforcer, MungWall, and Scratch can help find uninitialized pointers, attempted use of freed memory and misuse of scratch registers or condition codes (even in programs that appear to work perfectly).

* Always make sure you actually get any system resource that you ask for. This applies to memory, windows, screens, file handles, libraries, devices, ports, etc. Where an error value or return is possible, ensure that there is a reasonable failure path. Many poorly written programs will appear to be reliable, until some error condition (such as memory full or a disk problem) causes the program to continue with an invalid or null pointer, or branch to untested error handling code.

* Always clean up after yourself. This applies for both normal program exit and program termination due to error conditions. Anything that was opened must be closed, anything allocated must be deallocated. It is generally correct to do closes and deallocations in reverse order of the opens and allocations. Be sure to check your development language manual and startup code; some items may be closed or deallocated automatically for you, especially in abort conditions. If you write in the C language, make sure your code handles Ctrl-C properly.

* Remember that memory, peripheral configurations, and ROMs differ between models and between individual systems. Do not make assumptions about memory address ranges, storage device names, or the locations of system structures or code. Never call ROM routines directly. Beware of any example code you find that calls routines at addresses in the $F00000 $FFFFFF range. These are ROM routines and they will move with every OS release. The only supported interface to system ROM code is through the library, device, and resource calls.

* Never assume library bases or structures will exist at any particular memory location. The only absolute address in the system is $00000004, which contains a pointer to the Exec library base. Do not modify or depend on the format of private system structures. This includes the poking of copper lists, memory lists, and library bases.

* Never assume that programs can access hardware resources directly. Most hardware is controlled by system software that will not respond well to interference from other programs. Shared hardware requires programs to use the proper sharing protocols. Use the defined interface; it is the best way to ensure that your software will continue to operate on future models of the Amiga.

* Never access shared data structures directly without the proper mutual exclusion (locking). Remember that other tasks may be accessing the same structures.

* The system does not monitor the size of a program's stack. (Your compiler may have an option to do this for you.) Take care that your program does not cause stack overflow and provide extra stack space for the possibility that some functions may use up additional stack space in future versions of the OS.

* Never use a polling loop to test signal bits. If your program waits for external events like menu selection or keystrokes, do not bog down the multitasking system by busy-waiting in a loop. Instead, let your task go to sleep by ''Wait()''ing on its signal bits. For example:
signals = (ULONG)Wait( (1<<windowPtr->UserPort->mp_SigBit) |
(1<<consoleMsgPortPtr->mp_SigBit) );

* This turns the signal bit number for each port into a mask, then combines them as the argument for the Exec library Wait() function. When your task wakes up, handle all of the messages at each port where the mp_SigBit is set. There may be more than one message per port, or no messages at the port. Make sure that you ReplyMsg() to all messages that are not replies themselves. If you have no signal bits to Wait() on, use Delay() or WaitTOF() to provide a measured delay.

* Tasks (and processes) execute in ''680x0'' user mode. Supervisor mode is reserved for interrupts, traps, and task dispatching. Take extreme care if your code executes in supervisor mode. Exceptions while in supervisor mode are deadly.

* Most system functions require a particular execution environment. All DOS functions and any functions that might call DOS (such as the opening of a disk-resident library, font, or device) can only be executed from a process. A task is not sufficient. Most other kernel functions may be executed from tasks. Only a few may be executed from interrupts.

* Never disable interrupts or multitasking for long periods. If you use Forbid() or Disable(), you should be aware that execution of any system function that performs the Wait() function will temporarily suspend the Forbid() or Disable() state, and allow multitasking and interrupts to occur. Such functions include almost all forms of DOS and device I/O, including common ''stdio'' functions like printf().

* Never tie up system resources unless it is absolutely necessary. For example, if your program does not require constant use of the printer, open the printer device only when you need it. This will allow other tasks to use the printer while your program is running. You must provide a reasonable error response if a resource is not available when you need it.

* All data for the custom chips must reside in Chip memory (type MEMF_CHIP). This includes bitplanes, sound samples, trackdisk buffers, and images for sprites, bobs, pointers, and gadgets. The AllocMem() call takes a flag for specifying the type of memory. A program that specifies the wrong type of memory may appear to run correctly because many Amigas have only Chip memory. (On all models of the Amiga, the first 512K of memory is Chip memory. In later models, Chip memory may occupy up to the first one or two megabytes).

* However, once expansion memory has been added to an Amiga (type MEMF_FAST), any memory allocations will be made in the expansion memory area by default. Hence, a program can run correctly on an unexpanded Amiga which has only Chip memory while crashing on an Amiga which has expanded memory. A developer with only Chip memory may fail to notice that memory was incorrectly specified.

* Most compilers have options to mark specific data structures or object modules so that they will load into Chip RAM. Some older compilers provide the Atom utility for marking object modules. If this method is unacceptable, use the AllocMem() call to dynamically allocate Chip memory, and copy your data there.

* When making allocations that do not require Chip memory, do not explicitly ask for Fast memory. Instead ask for memory type MEMF_PUBLIC or 0L as appropriate. If Fast memory is available, you will get it.

* Never use software delay loops! Under the multitasking operating system, the time spent in a loop can be better used by other tasks. Even ignoring the effect it has on multitasking, timing loops are inaccurate and will wait different amounts of time depending on the specific model of Amiga computer. The timer device provides precision timing for use under the multitasking system and it works the same on all models of the Amiga. The AmigaDOS Delay() function or the graphics library WaitTOF() function provide a simple interface for longer delays. The ''8520'' I/O chips provide timers for developers who are bypassing the operating system (see the ''Amiga Hardware Reference Manual'' for more information).

Always obey structure conventions!

* All non-byte fields must be word-aligned. Longwords should be longword-aligned for performance.

* All address pointers should be 32 bits (not 24 bits). Never use the upper byte for data.

* Fields that are not defined to contain particular initial values must be initialized to zero. This includes pointer fields.

* All reserved or unused fields must be initialized to zero for future compatibility.

* Data structures to be accessed by the custom chips, public data structures (such as a task control block), and structures which must be longword aligned must '''not''' be allocated on a program's stack.

* Dynamic allocation of structures with AllocMem() provides longword aligned memory of a specified type with optional initialization to zero, which is useful in the allocation of structures.

=== Hardware programming guidelines ===

If you find it necessary to program the hardware directly, then it is your responsibility to write code that will work correctly on the various models and configurations of the Amiga. Be sure to properly request and gain control of the hardware resources you are manipulating, and be especially careful in the following areas:

* Kickstart 2.0 uses the ''8520'' Complex Interface Adaptor (CIA) chips differently than 1.3 did. To ensure compatibility, you must always ask for CIA access using the cia.resource AddICRVector() and RemICRVector() functions. Do not make assumptions about what the system might be using the CIA chips for. If you write directly to the CIA chip registers, do not expect system services such as the trackdisk device to function. If you are leaving the system up, do not read or write to the CIA Interrupt Control Registers directly; use the cia.resource AbleICR(), and SetICR() functions. Even if you are taking over the machine, do not assume the initial contents of any of the CIA registers or the state of any enabled interrupts.

* All custom chip registers are Read-only or Write-only. Do not read Write-only registers, and do not write to Read-only registers.

* Never write data to, or interpret data from the unused bits or addresses in the custom chip space. To be software-compatible with future chip revisions, all undefined bits must be set to zeros on writes, and must be masked out on reads before interpreting the contents of the register.

* Never write past the current end of custom chip space. Custom chips may be extended or enhanced to provide additional registers, or to use bits that are currently undefined in existing registers.

* Never read, write, or use any currently undefined address ranges or registers. The current and future usage of such areas is reserved by the AmigaOS development team and is subject to change.

* Never assume that a hardware register will be initialized to any particular value. Different versions of the OS may leave registers set to different values. Check the ''Amiga Hardware Reference Manual'' to ensure that you are setting up all the registers that affect your code.

=== AmigaOS Interface Style Guide ===

In order to make all programs in AmigaOS look consistent, AmigaOS provides some default thumbnails that developers must use in their GUI. These pictures are located in the '''tbimages:''' assign. They are installed in any AmigaOS installation.
Note that something may still go wrong and these pictures may not be found. In this case, the program must provide a fallback method instead of just failing. The developer can choose to display text-only toolbars or include default pictures with their program.

While the look of windows and gadgets can be changed by the user, the default look is similar to this:

[[File:About.png]]

== Error Reports ==

All corrections and bug report should be made by posting a new topic at AmigaOS' support forum. The support forum is located at http://support.amigaos.net

Commodities Exchange Library

2015-12-06T21:09:12Z

Daniel Jedlicka: Fixed wrong qualifier strings for the "rawmouse" class string.

{{CodeReview}}
== Commodities Exchange Library ==

This article describes Commodities Exchange, the library of routines used to add a custom input handler to the Amiga. With Commodities Exchange, any program function can be associated with key combinations or other input events ''globally'' allowing the creation utility programs that run in the background for all tasks.

== Custom Input Handlers ==

The input.device has a hand in almost all user input on the Amiga. It gathers input events from the keyboard, the gameport (mouse), and several other sources, into one input "stream". Special programs called input event handlers intercept input events along this stream, examining and sometimes changing the input events. Both Intuition and the console device use input handlers to process user input.

[[File:LibFig31-1.png|frame|center|The Amiga Input Stream]]

Using the input.device, a program can introduce its own custom handler into the chain of input handlers at almost any point in the chain. "Hot key" programs, shell pop-up programs, and screen blankers all commonly use custom input handlers to monitor user input before it gets to the Intuition input handler.

[[File:LibFig31-2.png|frame|center|A Custom Input Handler]]

Custom input handlers do have their drawbacks, however. Not only are these handlers hard to program, but because there is no standard way to implement and control them, multiple handlers often do not work well together. Their antisocial behavior can result in load order dependencies and incompatibilities between different custom input handlers. Even for the expert user, having several custom input handlers coexist peacefully can be next to impossible.

[[File:LibFig31-3.png|frame|center|The Commodities Network]]

Commodities Exchange eliminates these problems by providing a simple, standardized way to program and control custom input handlers. It is divided into two parts: an Exec library and a controller program.

The Exec library is called commodities.library. When it is first opened, commodities.library establishes a single input handler just before Intuition in the input chain. When this input handler receives an input event, it creates a CxMessage (Commodities Exchange Message) corresponding to the input event, and diverts the CxMessage through the network of Commodities Exchange input handlers.

These handlers are made up of trees of different CxObjects (Commodities Exchange Objects), each of which performs a simple operation on the CxMessages. Any CxMessages that exit the network are returned to the input.device's input stream as input events.

Through function calls to the commodities.library, an application can install a custom input handler. A Commodities Exchange application, sometimes simply referred to as a commodity, uses the CxObject primitives to do things such as filter certain CxMessages, translate CxMessages, signal a task when a CxObject receives a CxMessage, send a message when a CxObject receives a CxMessage, or if necessary, call a custom function when a CxObject receives a CxMessage.

=== Commodities Control ===

The standard controller program is called Exchange. It is located in the Utilities/Commodities drawer on your system partition. With Exchange, the user can monitor and control all the currently running Commodities Exchange applications from this one program. The user can enable and disable a commodity, kill a commodity, or, if the commodity has a window, ask the commodity to show or hide its window. When the user requests any of these actions, the controller program sends the commodity a message, telling it which action to perform.

Starting with version 53.4 of the commodities.library, functions are available that allow developers to write their own commodity control programs (Exchange replacements). These functions were not public previously.

=== Important Notes ===

* Commodities are special-purpose programs. In fact, most programs or applications are '''not''' suitable for becoming commodities. The Commodities Exchange framework is ideal for programs that need to monitor all user input: hotkey utilities, screen blankers, mouse blankers, etc.
* In the past, some developers turned their programs into commodities only to provide them with a handy keyboard shortcut to bring up/close their GUI. Please note that such practice is actually a misuse of the commodities framework.
* Commodities Exchange should never be used as an alternate method of receiving user input for an application. Other applications depend on getting user input in some form or another from the input stream. A greedy program that diverts input to itself rather than letting the input go to where the user expects it can seriously confuse the user, not to mention compromise the advantages of multitasking.

== CxObjects ==

CxObjects are the basic building blocks used to construct a commodity. A commodity uses CxObjects to take care of all manipulations of CxMessages. When a CxMessage "arrives" at a CxObject, that CxObject carries out its primitive action and then, if it has not deleted the CxMessage, it passes the CxMessage on to the next CxObject. A commodity links together CxObjects into a tree, organizing these simple action objects to perform some higher function.

A CxObject is in one of two states, active or inactive. An active CxObject performs its primitive action every time it receives a CxMessage. If a CxObject is inactive, CxMessages bypass it, continuing to the CxObject that follows the inactive one. By default, all CxObjects except the type called brokers are created in the active state.

Currently, there are seven types of CxObjects:

{| class="wikitable"
|+ Commodities Exchange Object Types
! Object Type
! Purpose
|-
| Broker || Registers a new commodity with the commodity network
|-
| Filter || Accepts or rejects input events based on criteria set up by the application
|-
| Sender || Sends a message to a message port
|-
| Translate || Replaces the input event with a different one
|-
| Signal || Signals a task
|-
| Custom || Calls a custom function provided by the commodity
|-
| Debug || Sends debug information out the serial port
|}

== Installing A Broker Object ==

The Commodities Exchange input handler maintains a master list of CxObjects to which it diverts input events using CxMessages. The CxObjects in this master list are a special type of CxObject called ''brokers''. The only thing a broker CxObject does is divert CxMessages to its own personal list of CxObjects. A commodity creates a broker and attaches other CxObjects to it. These attached objects take care of the actual input handler related work of the commodity and make up the broker's personal list.

The first program listing, "Broker.c", is a very simple example of a working commodity. It serves only to illustrate the basics of a commodity, not to actually perform any useful function. It shows how to set up a broker and process commands from the controller program.

Besides opening commodities.library and creating an Exec message port, setting up a commodity requires creating a broker. The function CxBroker() creates a broker and adds it to the master list.

<syntaxhighlight>
CxObj *CxBroker(struct NewBroker *nb, LONG *error);
</syntaxhighlight>

CxBroker()'s first argument is a pointer to a NewBroker structure:

<syntaxhighlight>
struct NewBroker {
BYTE nb_Version; /* There is an implicit pad byte after this BYTE */
BYTE *nb_Name;
BYTE *nb_Title;
BYTE *nb_Descr;
SHORT nb_Unique;
SHORT nb_Flags;
BYTE nb_Pri; /* There is an implicit pad byte after this BYTE */
struct MsgPort *nb_Port;
WORD nb_ReservedChannel; /* Unused, make zero for future compatibility */
};
</syntaxhighlight>

Commodities Exchange gets all the information it needs about the broker from this structure. NewBroker's nb_Version field contains the version number of the NewBroker structure. This should be set to NB_VERSION which is defined in <libraries/commodities.h>. The nb_Name, nb_Title, and nb_Descr point to strings which hold the name, title, and description of the broker. The two bit fields, nb_Unique and nb_Flags, toggle certain features of Commodities Exchange based on their values. They are discussed in detail later in this article.

The nb_Pri field contains the broker's priority. Commodities Exchange inserts the broker into the master list based on this number. Higher priority brokers get CxMessages before lower priority brokers.

CxBroker()'s second argument is a pointer to a LONG. If this pointer is not NULL, CxBroker() fills in this field with one of the following error return codes from <libraries/commodities.h>:

<syntaxhighlight>
CBERR_OK 0 /* No error */
CBERR_SYSERR 1 /* System error , no memory, etc */
CBERR_DUP 2 /* uniqueness violation */
CBERR_VERSION 3 /* didn't understand nb_VERSION */
</syntaxhighlight>

Once the broker object is created with CxBroker(), it must be activated with ActivateCxObject().

<syntaxhighlight>
LONG oldactivationvalue = ActivateCxObj(CxObj *co, LONG newactivationvalue);
</syntaxhighlight>

After successfully completing the initial set up and activating the broker, a commodity can begin its input processing loop waiting for CxMessages to arrive.

== CxMessages ==

There are actually two types of CxMessages. The first, CXM_IEVENT, corresponds to an input event and travels through the Commodities Exchange network. The other type, CXM_COMMAND, carries a command to a commodity. A CXM_COMMAND normally comes from the controller program and is used to pass user commands on to a commodity. A commodity receives these commands through an Exec message port that the commodity sets up before it calls CxBroker(). The NewBroker's nb_Port field points to this message port. A commodity can tell the difference between the two types of CxMessages by calling the CxMsgType() function.

<syntaxhighlight>
ULONG CxMsgType( CxMsg *cxm );
UBYTE *CxMsgData( CxMsg *cxm );
LONG CxMsgID ( CxMsg *cxm );
</syntaxhighlight>

A CxMessage not only has a type, it can also have a data pointer as well as an ID associated with it. The data associated with a CXM_IEVENT CxMessage is an InputEvent structure. By using the CxMsgData() function, a commodity can obtain a pointer to the corresponding InputEvent of a CXM_IEVENT message. Commodities Exchange gives an ID of zero to any CXM_IEVENT CxMessage that it introduces to the Commodities network but certain CxObjects can assign an ID to them.

For a CXM_COMMAND CxMessages, the data pointer is generally not used but the ID specifies a command passed to the commodity from the user operating the controller program. The CxMsgID() macro extracts the ID from a CxMessage.

=== A Simple Commodity Example ===

The example below, "Broker.c", receives input from one source, the controller program. The controller program sends a CxMessage each time the user clicks its Enable, Disable, or Kill gadgets. Using the CxMsgID() function, the commodity finds out what the command is and executes it.

<syntaxhighlight>
// broker.c - Simple skeletal example of opening a broker

#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities = NULL;

CxObj *broker;
struct MsgPort *broker_mp;
ULONG cxsigflag;

struct NewBroker newbroker = {
NB_VERSION, /* nb_Version - Version of the NewBroker structure */
"Amiga broker", /* nb_Name - Name Commodities uses to identify this commodity */
"Broker", /* nb_Title - Title of commodity that appears in CXExchange */
"A simple example of a broker", /* nb_Descr - Description of the commodity */
0, /* nb_Unique - Tells CX not to launch another commodity with same name */
0, /* nb_Flags - Tells CX if this commodity has a window */
0, /* nb_Pri - This commodity's priority */
0, /* nb_Port - MsgPort CX talks to */
0 /* nb_ReservedChannel - reserved for later use */
};

int main()
{
CxMsg *msg;

struct Library *CxBase = = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);
if (ICommodities != NULL)
{
/* Commodities talks to a Commodities application through */
/* an Exec Message port, which the application provides */
if (broker_mp = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
{
newbroker.nb_Port = broker_mp;

/* The commodities.library function CxBroker() adds a borker to the
* master list. It takes two arguments, a pointer to a NewBroker
* structure and a pointer to a LONG. The NewBroker structure contains
* information to set up the broker. If the second argument is not
* NULL, CxBroker will fill it in with an error code.
*/
if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
cxsigflag = 1L << broker_mp->mp_SigBit;

/* After it's set up correctly, the broker has to be activated */
ICommodities->ActivateCxObj(broker, 1L);

/* the main processing loop */
ProcessMsg();

/* It's time to clean up. Start by removing the broker from the
* Commodities master list. The DeleteCxObjAll() function will
* take care of removing a CxObject and all those connected
* to it from the Commodities network
*/
ICommodities->DeleteCxObj(broker);

/* Empty the port of CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
}

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
CxMsg *msg;

uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while (returnvalue)
{
/* wait for something to happen */
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

/* process any messages */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
/* Extract necessary information from the CxMessage and return it */
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
/* Shouldn't get any of these in this example */
break;
case CXM_COMMAND:
/* Commodities has sent a command */
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
/* The user clicked Commodities Exchange disable
* gadget better disable
*/
ICommodities->ActivateCxObj(broker, 0);
break;
case CXCMD_ENABLE:
/* user clicked enable gadget */
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1);
break;
case CXCMD_KILL:
/* user clicked kill gadget, better quit */
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
/* Test to see if user tried to break */
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

Notice that "Broker.c" uses Ctrl-C as a break key. The break key for any commodity should be Ctrl-C.

=== Controller Commands ===

The commands that a commodity can receive from the controller program (as defined in <libraries/commodities.h>) are:

<syntaxhighlight>
CXCMD_DISABLE /* please disable yourself */
CXCMD_ENABLE /* please enable yourself */
CXCMD_KILL /* go away for good */
CXCMD_APPEAR /* open your window, if you can */
CXCMD_DISAPPEAR /* hide your window */
</syntaxhighlight>

The CXCMD_DISABLE, CXCMD_ENABLE, and CXCMD_KILL commands correspond to the similarly named controller program gadgets, Disable, Enable, and Kill; CXCMD_APPEAR and CXCMD_DISAPPEAR correspond to the controller program gadgets, Show and Hide. These gadgets are ghosted in Broker.c because it has no window (It doesn't make much sense to give the user a chance to click the Show and Hide gadgets). In order to do this, Broker.c has to tell Commodities Exchange to ghost these gadgets. When CxBroker() sets up a broker, it looks at the NewBroker.nb_Flags field to see if the COF_SHOW_HIDE bit (from <libraries/commodities.h>) is set. If it is, the "Show" and "Hide" gadgets for this broker will be selectable. Otherwise they are ghosted and disabled.

=== Shutting Down the Commodity ===

Shutting down a commodity is easy. After replying to all CxMessages waiting at the broker's message port, a commodity can delete its CxObjects. The DeleteCxObj() function removes a single CxObject from the Commodities network. DeleteCxObjectAll() removes multiple objects.

<syntaxhighlight>
VOID DeleteCxObj( CxObj *co );
VOID DeleteCxObjAll( CxObj *delete_co );
</syntaxhighlight>

If a commodity has a lot of CxObjects, deleting each individually can be a bit tedious. DeleteCxObjAll() will delete a CxObject and any other CxObjects that are attached to it. The HotKey.c example given later in this article uses this function to delete all its CxObjects. A commodity that uses DeleteCxObjAll() to delete all its CxObjects should make sure that they are all connected to the main one. (See the "Connecting CxObjects" section below.)

After deleting its CxObjects, a commodity must take care of any CxMessages that might have arrived at the message port just before the commodity deleted its objects.

<syntaxhighlight>
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
</syntaxhighlight>

== Commodity Tool Types ==

A goal of Commodities Exchange is to improve user control over input handlers. One way in which it accomplishes this goal is through the use of standard icon Tool Types. The user will expect commodities to recognize the set of standard Tool Types:

* CX_PRIORITY
* CX_POPUP
* CX_POPKEY

CX_PRIORITY lets the user set the priority of a commodity. The string "CX_PRIORITY=" is a number from -128 to 127. The higher the number, the higher the priority of the commodity, giving it access to input events before lower priority commodities. All commodities should recognize CX_PRIORITY.

CX_POPUP and CX_POPKEY are only relevant to commodities with a window. The string "CX_POPUP=" should be followed by a "yes" or "no", telling the commodity if it should or shouldn't show its window when it is first launched. CX_POPKEY is followed by a string describing the key to use as a hot key for making the commodity's window appear (pop up). The description string for CX_POPKEY describes an input event. The specific format of the string is discussed in the next section ("Filter Objects and the Input Description String").

=== Obsolete Parsing Functions ===

Prior to AmigaOS 4.0, the Commodities Library had the following support functions which were included in an external link library:

<syntaxhighlight>
UBYTE **ArgArrayInit(LONG argc, UBYTE **argv);
VOID ArgArrayDone(void);
STRPTR ArgString(UBYTE **tooltypearray, STRPTR tooltype, STRPTR defaultvalue);
LONG *ArgInt(UBYTE **tooltypearray, STRPTR tooltype, LONG defaultvalue);
</syntaxhighlight>

These functions are no longer available. Use IDOS->ReadArgs(), IIcon->FindToolType() and IIcon->MatchToolValue() instead, depending on whether the commodity was launched from Workbench or the Shell (CLI).

== Filter Objects and Input Description Strings ==

Because not all commodities are interested in every input event that makes it way down the input chain, Commodities Exchange has a method for filtering them. A filter CxObject compares the CxMessages it receives to a pattern. If a CxMessage matches the pattern, the filter diverts the CxMessage down its personal list of CxObjects.

<syntaxhighlight>
CxObj *CxFilter(STRPTR descriptionstring);
</syntaxhighlight>

The C macro CxFilter() (defined in <libraries/commodities.h>) returns a pointer to a filter CxObject. The macro has only one argument, a pointer to a string describing which input events to filter. The following regular expression outlines the format of the input event description string (CX_POPKEY uses the same description string format):

<pre>
[class] { [-] (qualifier | synonym) ) } [ [-] upstroke] [highmap | ANSICode]
</pre>

''Class'' can be any one of the class strings in the table below. Each class string corresponds to a class of input event as defined in <devices/inputevent.h>. Commodities Exchange will assume the class is rawkey if the class is not explicitly stated.

{| class="wikitable"
! Class String
! Input Event Class
|-
| "rawkey" || IECLASS_RAWKEY
|-
| "rawmouse" || IECLASS_RAWMOUSE
|-
| "event" || IECLASS_EVENT
|-
| "pointerpos" || IECLASS_POINTERPOS
|-
| "timer" || IECLASS_TIMER
|-
| "newprefs" || IECLASS_NEWPREFS
|-
| "diskremoved" || IECLASS_DISKREMOVED
|-
| "diskinserted" || IECLASS_DISKINSERTED
|}

''Qualifier'' is one of the qualifier strings from the table below. Each string corresponds to an input event qualifier as defined in <devices/inputevent.h>). A dash preceding the qualifier string tells the filter object not to care if that qualifier is present in the input event. Notice that there can be more than one qualifier (or none at all) in the input description string.

{| class="wikitable"
! Qualifier String
! Input Event Class
|-
| "lshift" || IEQUALIFIER_LSHIFT
|-
| "rshift" || IEQUALIFIER_RSHIFT
|-
| "capslock" || IEQUALIFIER_CAPSLOCK
|-
| "control" || IEQUALIFIER_CONTROL
|-
| "lalt" || IEQUALIFIER_LALT
|-
| "ralt" || IEQUALIFIER_RALT
|-
| "lcommand" || IEQUALIFIER_LCOMMAND
|-
| "rcommand" || IEQUALIFIER_RCOMMAND
|-
| "numericpad" || IEQUALIFIER_NUMERICPAD
|-
| "repeat" || IEQUALIFIER_REPEAT
|-
| "mouse_middlepress" || IEQUALIFIER_MIDBUTTON
|-
| "mouse_rightpress" || IEQUALIFIER_RBUTTON
|-
| "mouse_leftpress" || IEQUALIFIER_LEFTBUTTON
|-
| "relativemouse" || IEQUALIFIER_RELATIVEMOUSE
|}

''Synonym'' is one of the synonym strings from the table below. These strings act as synonyms for groups of qualifiers. Each string corresponds to a synonym identifier as defined in <libraries/commodities.h>. A dash preceding the synonym string tells the filter object not to care if that synonym is present in the input event. Notice that there can be more than one synonym (or none at all) in the input description string.

{| class="wikitable"
! Synonym String
! Synonym Identifier
! Description
|-
| "shift" || IXSYM_SHIFT || Look for either Shift key
|-
| "caps" || IXSYM_CAPS || Look for either Shift key or Caps Lock
|-
| "alt" || IXSYM_ALT || Look for either Alt key
|}

''Upstroke'' is the literal string "upstroke". If this string is absent, the filter considers only downstrokes. If it is present alone, the filter considers only upstrokes. If preceded by a dash, the filter considers both upstrokes and downstrokes.

''Highmap'' is one of the following strings:

"backspace", "del", "down", "enter", "esc", "f1", "f2",
"f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10",
"f11, "f12", "help", "left", "return", "right", "space", "tab", "up".

''ANSICode'' is a single character (for example "a" that Commodities Exchange looks up in the system default keymap.

Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the input description string would be:

<pre>
"rawkey lshift alt f2"
</pre>

To specify the key that produces an "a" (this may or may not be the A key depending on the keymap), with or without any Shift, Alt, or Control keys pressed use:

<pre>
"-shift -alt -control a"
</pre>

For a mouse move with the right mouse button down, use:

<pre>
"rawmouse mouse_rightpress"
</pre>

To specify a timer event use:

<pre>
"timer"
</pre>

== Connecting CxObjects ==

A CxObject has to be inserted into the Commodities network before it can process any CxMessages. AttachCxObj() adds a CxObject to the personal list of another CxObject. The HotKey.c example uses it to attach its filter to a broker.

<syntaxhighlight>
VOID AttachCxObj ( CxObj *headobj, CxObj *co);
VOID InsertCxObj ( CxObj *headobj, CxObj *co, CxObj *co_pred );
VOID EnqueueCxObj( CxObj *headobj, CxObj *co );
VOID SetCxObjPri ( CxObj *co, LONG pri );
VOID RemoveCxObj ( CxObj *co );
</syntaxhighlight>

AttachCxObj() adds the CxObject to the end of headobj's personal list. The ordering of a CxObject list determines which object gets CxMessages first. InsertCxObj() also inserts a CxObject, but it inserts it after another CxObject already in the personal list (co_pred in the prototype above).

Brokers aren't the only CxObjects with a priority. All CxObjects have a priority associated with them. To change the priority of any CxObject, use the SetCxObjPri() function. A commodity can use the priority to keep CxObjects in a personal list sorted by their priority. The commodities.library function EnqueueCxObj() inserts a CxObject into another CxObject's personal list based on priority.

Like its name implies, the RemoveCxObj() function removes a CxObject from a personal list. Note that it is not necessary to remove a CxObject from a list in order to delete it.

<syntaxhighlight>
/* HotKey.c - Simple hot key commodity
*/
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/commodities.h>
#include <proto/icon.h>

#define EVT_HOTKEY 1L

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities;
struct IconIFace *IIcon;

struct MsgPort *broker_mp;
CxObj *broker, *filter, *sender, *translate;

struct NewBroker newbroker = {
NB_VERSION,
"Amiga HotKey", /* string to identify this broker */
"A Simple HotKey",
"A simple hot key commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

uint32 cxsigflag;

int main(int argc, char **argv)
{
uint8 *hotkey, **ttypes;
CxMsg *msg;

struct Library *CxBase = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);

/* open the icon.library for the support library */
/* functions, ArgArrayInit() and ArgArrayDone() */
struct Library *IconBase = IExec->OpenLibrary("icon.library", 50);
struct IconIFace *IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);

if (ICommodities != NULL && IIcon != NULL)
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (from the 2.0 version
* of amiga.lib) that makes it easy to read arguments from either a
* CLI or from Workbench's ToolTypes. Because it uses icon.library,
* the library has to be open before calling this function.
* ArgArrayDone() cleans up after this function.
*/
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (also from amiga.lib) searches through the array set up
* by ArgArrayInit() for a specific ToolType. If it finds one, it
* returns the numeric value of the number that followed the
* ToolType (i.e., CX_PRIORITY=7). If it doesn't find the ToolType,
* it returns the default value (the third argument)
*/
newbroker.nb_Pri = (int8)ArgInt(ttypes, "CX_PRIORITY", 0);

/* ArgString() works just like ArgInt(), except it returns a pointer to a string
* rather than an integer. In the example below, if there is no ToolType
* "HOTKEY", the function returns a pointer to "rawkey control esc".
*/
hotkey = ArgString(ttypes, "HOTKEY", "rawkey control esc");

if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
/* CxFilter() is a macro that creates a filter CxObject. This filter
* passes input events that match the string pointed to by hotkey.
*/
if (filter = ICommodities->CxFilter(hotkey))
{
/* Add a CxObject to another's personal list */
ICommodities->AttachCxObj(broker, filter);

/* CxSender() creates a sender CxObject. Every time a sender gets
* a CxMessage, it sends a new CxMessage to the port pointed to in
* the first argument. CxSender()'s second argument will be the ID
* of any CxMessages the sender sends to the port. The data pointer
* associated with the CxMessage will point to a *COPY* of the
* InputEvent structure associated with the orginal CxMessage.
*/
if (sender = CxSender(broker_mp, EVT_HOTKEY))
{
ICommodities->AttachCxObj(filter, sender);

/* CxTranslate() creates a translate CxObject. When a translate
* CxObject gets a CxMessage, it deletes the original CxMessage
* and adds a new input event to the input.device's input stream
* after the Commodities input handler. CxTranslate's argument
* points to an InputEvent structure from which to create the new
* input event. In this example, the pointer is NULL, meaning no
* new event should be introduced, which causes any event that
* reaches this object to disappear from the input stream.
*/
if (translate = ICommodities->CxTranslate(NULL))
{
ICommodities->AttachCxObj(filter, translate);

/* CxObjError() is a commodities.library function that returns
* the internal accumulated error code of a CxObject.
*/
if (! CxObjError(filter))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
}
}
}
}
/* DeleteCxObjAll() is a commodities.library function that not only
* deletes the CxObject pointed to in its argument, but it deletes
* all of the CxObjects that are attached to it.
*/
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
/* this amiga.lib function cleans up after ArgArrayInit() */
ArgArrayDone();
}

IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while(returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
IDOS->Printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY: /* We got the message from the sender CxObject */
IDOS->Printf("You hit the HotKey.\n");
break;
default:
IDOS->Printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
IDOS->Printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a
* commodity with a name already in use but also can notify the
* already running commodity that it happened. It does this by
* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the
* user tries to run a windowless commodity that is already running,
* the user wants the commodity to shut down. */
IDOS->Printf("CXCMD_UNIQUE\n");
returnvalue = 0;
break;
default:
IDOS->Printf("Unknown msgid\n");
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Sender CxObjects ==

A filter CxObject by itself is not especially useful. It needs some other CxObjects attached to it. A commodity interested in knowing if a specific key was pressed uses a filter to detect and divert the corresponding CxMessage down the filter's personal list. The filter does this without letting the commodity know what happened. The sender CxObject can be attached to a filter to notify a commodity that it received a CxMessage. CxSender() is a macro that creates a sender CxObject.

<syntaxhighlight>
senderCxObj = CxObj *CxSender(struct MsgPort *senderport, LONG cxmID);
</syntaxhighlight>

CxSender() supplies the sender with an Exec message port and an ID. For every CxMessage a sender receives, it sends a new CxMessage to the Exec message port passed in CxSender(). Normally, the commodity creates this port. It is not unusual for a commodity's broker and sender(s) to share an Exec message port. The HotKey.c example does this to avoid creating unnecessary message ports. A sender uses the ID (cxmID) passed to CxSender() as the ID for all the CxMessages that the it transmits. A commodity uses the ID to monitor CxMessages from several senders at a single message port.

A sender does several things when it receives a CxMessage. First, it duplicates the CxMessage's corresponding input event and creates a new CxMessage. Then, it points the new CxMessage's data field to the copy of the input event and sets the new CxMessage's ID to the ID passed to CxSender(). Finally, it sends the new CxMessage to the port passed to CxSender(), asynchronously.

Because HotKey uses only one message port between its broker and sender object, it has to extract the CxMessage's type so it can tell if it is a CXM_IEVENT or a CXM_COMMAND. If HotKey gets a CXM_IEVENT, it compares the CxMessage's ID to the sender's ID, EVT_HOTKEY, to see which sender sent the CxMessage. Of course HotKey has only one sender, so it only checks for only one ID. If it had more senders, HotKey would check for the ID of each of the other senders as well.

Although HotKey doesn't use it, a CXM_IEVENT CxMessage contains a pointer to the copy of an input event. A commodity can extract this pointer (using CxMsgData()) if it needs to examine the input event copy. This pointer is only valid before the CxMessage reply. Note that it does not make any sense to modify the input event copy.

Senders are attached almost exclusively to CxObjects that filter out most input events (usually a filter CxObject). Because a sender sends a CxMessage for every single input event it gets, it should only get a select few input events. The AttachCxObj() function can add a CxObject to the end of a filter's (or some other filtering CxObject's) personal list. A commodity should not attach a CxObject to a sender as a sender ignores any CxObjects in its personal list.

== Translate CxObjects ==

Normally, after a commodity processes a hot key input event, it needs to eliminate that input event. Other commodities may need to replace an input event with a different one. The translate CxObject can be used for these purposes.

<syntaxhighlight>
translateCxObj = CxObj *CxTranslate(struct InputEvent *newinputevent);
</syntaxhighlight>

The macro CxTranslate() creates a new translate CxObject. CxTranslate()'s only argument is a pointer to a chain of one or more InputEvent structures.

When a translate CxObject receives a CxMessage, it eliminates the CxMessage and its corresponding input event from the system. The translator introduces a new input event, which Commodities Exchange copies from the InputEvent structure passed to CxTranslate() (newinputevent from the function prototype above), in place of the deleted input event.

A translator is normally attached to some kind of filtering CxObject. If it wasn't, it would translate all input events into the same exact input event. Like the sender CxObject, a translator does not divert CxMessages down its personal list, so it doesn't serve any purpose to add any to it.

<syntaxhighlight>
VOID SetTranslate( CxObj *translator, struct InputEvent *ie );
</syntaxhighlight>

It is possible to change the InputEvent structure that a translator looks at when it creates and introduces new input events into the input stream. The function SetTranslate() accepts a pointer to the new InputEvent structure, which the translator will duplicate and introduce when it receives a CxMessage.

HotKey utilizes a special kind of translator. Instead of supplying a new input event, HotKey passes a NULL to CxTranslate(). If a translator has a NULL new input event pointer, it does not introduce a new input event, but still eliminates any CxMessages and corresponding input events it receives.

== CxObject Errors ==

A Commodities Exchange function that acts on a CxObject records errors in the CxObject's accumulated error field. The function CxObjError() returns a CxObject's error field.

<syntaxhighlight>
int32 co_errorfield = CxObjError( CxObj *co );
</syntaxhighlight>

Each bit in the error field corresponds to a specific type of error. The following is a list of the currently defined CxObject errors and their corresponding bit mask constants.

{| class="wikitable"
! Error Constant
! Meaning
|-
| COERR_ISNULL
| CxObjError() was passed a NULL.
|-
| COERR_NULLATTACH
| Someone tried to attach a NULL CxObject to this CxObject.
|-
| COERR_BADFILTER
| This filter CxObject currently has an invalid filter description.
|-
| COERR_BADTYPE
| Someone tried to perform a type specific function on the wrong type of CxObject (for example calling SetFilter() on a sender CxObject).
|}

The remaining bits are reserved for future use. HotKey.c checks the error field of its filter CxObject to make sure the filter is valid. HotKey.c does not need to check the other objects with CxObjError() because it already makes sure that these other objects are not NULL, which is the only other kind of error the other objects can cause in this situation.

Commodities Exchange has a function that clears a CxObject's accumulated error field, ClearCxObjError().

<syntaxhighlight>
VOID ClearCxObjError( CxObj *co );
</syntaxhighlight>

A commodity should be careful about using this, especially on a filter. If a commodity clears a filter's error field and the COERR_BADFILTER bit is set, Commodities Exchange will think that the filter is OK and start sending messages through it.

== Uniqueness ==

When a commodity opens its broker, it can ask Commodities Exchange not to launch another broker with the same name (nb_Name). The purpose of the uniqueness feature is to prevent the user from starting duplicate commodities. If a commodity asks, Commodities Exchange will not only refuse to create a new, similarly named broker, but it will also notify the original commodity if someone tries to do so.

A commodity tells Commodities Exchange not to allow duplicates by setting certain bits in the nb_Unique field of the NewBroker structure it sends to CxBroker():

{| class="wikitable"
| NBU_UNIQUE
| bit 0
|-
| NBU_NOTIFY
| bit 1
|}

Setting the NBU_UNIQUE bit prevents duplicate commodities. Setting the NBU_NOTIFY bit tells Commodities Exchange to notify a commodity if an attempt was made to launch a duplicate. Such a commodity will receive a CXM_COMMAND CxMessage with an ID of CXCMD_UNIQUE when someone tries to duplicate it. Because the uniqueness feature uses the name a programmer gives a commodity to differentiate it from other commodities, it is possible for completely different commodities to share the same name, preventing the two from coexisting. For this reason, a commodity should not use a name that is likely to be in use by other commodities (like "filter" or "hotkey"). Instead, use a name that matches the commodity name.

When "HotKey.c" gets a CXCMD_UNIQUE CxMessage, it shuts itself down. "HotKey.c" and all the windowless commodities that come with Workbench shut themselves down when they get a CXCMD_UNIQUE CxMessage. Because the user will expect all windowless commodities to work this way, all windowless commodities should follow this standard.

When the user tries to launch a duplicate of a system commodity that has a window, the system commodity moves its window to the front of the display, as if the user had clicked the "Show" gadget in the controller program's window. A windowed commodity should mimic conventions set by existing windowed system commodities, and move its window to the front of the display.

== Signal CxObjects ==

A commodity can use a sender CxObject to find out if a CxMessage has "visited" a CxObject, but this method unnecessarily uses system resources. A commodity that is only interested in knowing if such a visitation took place does not need to see a corresponding input event or a CxMessage ID. Instead, Commodities Exchange has a CxObject that uses an Exec signal.

<syntaxhighlight>
CxObj *signalCxObj = CxSignal(struct Task *, LONG cx_signal);
</syntaxhighlight>

CxSignal() sets up a signal CxObject. When a signal CxObject receives a CxMessage, it signals a task. The commodity is responsible for determining the proper task ID and allocating the signal. Normally, a commodity wants to be signaled so it uses FindTask(NULL) to find it's own task address. Note that cx_signal from the above prototype is the signal number as returned by AllocSignal(), not the signal mask made from that number. For more information on signals, see [[Exec_Signals|Exec Signals]].

The example "Divert.c" (shown a little later) uses a signal CxObject.

== Custom CxObjects ==

Although the CxObjects mentioned so far take care of most of the input event handling a commodity needs to do, they cannot do it all. This is why Commodities Exchange has a custom CxObject. When a custom CxObject receives a CxMessage, it calls a function provided by the commodity.

<syntaxhighlight>
CxObject *customCxObj = CxCustom(int32 *customfunction(), int32 cxmID);
</syntaxhighlight>

A custom CxObject is the only means by which a commodity can directly modify input events as they pass through the Commodities network as CxMessages. For this reason, it is probably the most dangerous of the CxObjects to use.

{{Note|title=A Warning About Custom CxObjects|text=Unlike the rest of the code a commodities programmer writes, the code passed to a custom CxObject runs as part of the input.device task, putting severe restrictions on the function. No DOS or Intuition functions can be called. No assumptions can be made about the values of registers upon entry. Any function passed to CxCustom() should be very quick and very simple, with a minimum of stack usage.}}

Commodities Exchange calls a custom CxObject's function as follows:

<syntaxhighlight>
VOID customfunction(CxMsg *cxm, CxObj *customcxobj);
</syntaxhighlight>

where cxm is a pointer to a CxMessage corresponding to a real input event, and customcxobj is a pointer to the custom CxObject. The custom function can extract the pointer to the input event by calling CxMsgData(). Before passing the CxMessage to the custom function, Commodities Exchange sets the CxMessage's ID to the ID passed to CxCustom().

The following is an example of a custom CxObject function that swaps the function of the left and right mouse buttons.

<syntaxhighlight>
custom = CxCustom(CxFunction, 0)

/* The custom function for the custom CxObject. Any code for a custom CxObj must be */
/* short and sweet. This code runs as part of the input.device task */
#define CODEMASK (0x00FF & IECODE_LBUTTON & IECODE_RBUTTON)

void CxFunction(register CxMsg *cxm, CxObj *co)
{
uint16 mousequals = 0x0000;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent
* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it.
*/
struct InputEvent *ie = (struct InputEvent *)CxMsgData(cxm);

/* Check to see if this input event is a left or right mouse button */
/* by itself (a mouse button can also be a qualifier). If it is, flip the */
/* low order bit to switch leftbutton <--> rightbutton. */
if (ie->ie_Class == IECLASS_RAWMOUSE)
if ((ie->ie_Code & CODEMASK) == CODEMASK) ie->ie_Code ^= 0x0001;

/* Check the qualifiers. If a mouse button was down when this */
/* input event occurred, set the other mouse button bit. */
if (ie->ie_Qualifier & IEQUALIFIER_RBUTTON) mousequals |= IEQUALIFIER_LEFTBUTTON;
if (ie->ie_Qualifier & IEQUALIFIER_LEFTBUTTON) mousequals |= IEQUALIFIER_RBUTTON;

/* clear the RBUTTON and LEFTBUTTON qualifier bits */
ie->ie_Qualifier &= ~(IEQUALIFIER_LEFTBUTTON | IEQUALIFIER_RBUTTON);

/* set the mouse button qualifier bits to their new values */
ie->ie_Qualifier |= mousequals;
}
</syntaxhighlight>

== Debug CxObjects ==

The final CxObject is the debug CxObject. When a debug CxObject receives a CxMessage, it sends debugging information to the serial port using DebugPrintF().

<syntaxhighlight>
CxObj *debugCxObj = CxDebug(int32 ID);
</syntaxhighlight>

The debug CxObject will DebugPrintF() the following information about itself, the CxMsg, and the corresponding InputEvent structure:

<pre>
DEBUG NODE: 7CB5AB0, ID: 2
CxMsg: 7CA6EF2, type: 0, data 2007CA destination 6F1E07CB
dump IE: 7CA6F1E
Class 1
Code 40
Qualifier 8000
EventAddress 40001802
</pre>

There has to be a terminal connected to the Amiga's serial port to receive this information.

== The IX Structure ==

Commodities Exchange does not use the input event description strings discussed earlier to match input events. Instead, Commodities Exchange converts these strings to its own internal format. These input expressions are available for commodities to use instead of the input description strings. The following is the IX structure as defined in <libraries/commodities.h>:

<syntaxhighlight>
#define IX_VERSION 2

struct InputXpression {
UBYTE ix_Version; /* must be set to IX_VERSION */
UBYTE ix_Class; /* class must match exactly */
UWORD ix_Code;
UWORD ix_CodeMask; /* normally used for UPCODE */
UWORD ix_Qualifier;
UWORD ix_QualMask;
UWORD ix_QualSame; /* synonyms in qualifier */
};

typedef struct InputXpression IX;
</syntaxhighlight>

The ix_Version field contains the current version number of the InputXpression structure. The current version is defined as IX_VERSION. The ix_Class field contains the IECLASS_ constant (defined in <devices/inputevent.h>) of the class of input event sought. Commodities Exchange uses the ix_Code and ix_CodeMask fields to match the ie_Code field of a struct InputEvent. The bits of ix_CodeMask indicate which bits are relevant in the ix_Code field when trying to match against a ie_Code. If any bits in ix_CodeMask are off, Commodities Exchange does not consider the corresponding bit in ie_Code when trying to match input events. This is used primarily to mask out the IECODE_UP_PREFIX bit of rawkey events, making it easier to match both up and down presses of a particular key.

IX's qualifier fields, ix_Qualifier, ix_QualMask, and ix_QualSame, are used to match the ie_Qualifier field of an InputEvent structure. The ix_Qualifier and ix_QualMask fields work just like ix_Code and ix_CodeMask. The bits of ix_QualMask indicate which bits are relevant when comparing ix_Qualifier to ie_Qualifier. The ix_QualSame field tells Commodities Exchange that certain qualifiers are equivalent:

<syntaxhighlight>
#define IXSYM_SHIFT 1 /* left- and right- shift are equivalent */
#define IXSYM_CAPS 2 /* either shift or caps lock are equivalent */
#define IXSYM_ALT 4 /* left- and right- alt are equivalent */
</syntaxhighlight>

For example, the input description string

<pre>
"rawkey -caps -lalt -relativemouse -upstroke ralt tab"
</pre>

matches a tab upstroke or downstroke with the right Alt key pressed whether or not the left Alt, either Shift, or the Caps Lock keys are down. The following IX structure corresponds to that input description string:

<syntaxhighlight>
IX ix = {
IX_VERSION, /* The version */
IECLASS_RAWKEY, /* We're looking for a RAWKEY event */
0x42, /* The key the usa0 keymap maps to a tab*/
0x00FF & (~IECODE_UP_PREFIX), /* We want up and down key presses */
IEQUALIFIER_RALT, /* The right alt key must be down */
0xFFFF & ~(IEQUALIFIER_LALT | IEQUALIFIER_LSHIFT |
IEQUALIFIER_RSHIFT | IEQUALIFIER_CAPSLOCK | IEQUALIFIER_RELATIVEMOUSE),
/* don't care about left alt, shift, capslock, or relativemouse qualifiers */
IXSYM_CAPS /* The shift keys and the capslock key qualifiers are all equivalent */
};
</syntaxhighlight>

The CxFilter() macro only accepts a description string to describe an input event. A commodity can change this filter, however, with the SetFilter() and SetFilterIX() function calls.

<syntaxhighlight>
VOID SetFilter( CxObj *filter, STRPTR descrstring );
VOID SetFilterIX( CxObj *filter, IX *ix );
</syntaxhighlight>

SetFilter() and SetFilterIX() change which input events a filter CxObject diverts. SetFilter() accepts a pointer to an input description string. SetFilterIX() accepts a pointer to an IX input expression. A commodity that uses either of these functions should check the filter's error code with CxObjError() to make sure the change worked.

The function ParseIX() parses an input description string and translates it into an IX input expression.

<syntaxhighlight>
LONG errorcode = ParseIX( STRPTR descrstring, IX *ix );
</syntaxhighlight>

Commodities Exchange uses ParseIX() to convert the description string in CxFilter() to an IX input expression. As was mentioned previously, ParseIX() does not work with certain kinds of input strings.

== Controlling CxMessages ==

A Custom CxObject has the power to directly manipulate the CxMessages that travel around the Commodities network. One way is to directly change values in the corresponding input event. Another way is to redirect (or dispose of) the CxMessages.

<syntaxhighlight>
VOID DivertCxMsg ( CxMsg *cxm, CxObj *headobj, CxObj *retobj );
VOID RouteCxMsg ( CxMsg *cxm, CxObj *co );
VOID DisposeCxMsg( CxMsg *cxm );
</syntaxhighlight>

DivertCxMsg() and RouteCxMsg() dictate where the CxMessage will go next. Conceptually, DivertCxMsg() is analogous to a subroutine in a program; the CxMessage will travel down the personal list of a CxObject (headobj in the prototype) until it gets to the end of that list. It then returns and visits the CxObject that follows the return CxObject (the return CxObject in the prototype above is retobj). RouteCxMsg() is analogous to a goto in a program; it has no CxObject to return to.

DisposeCxMsg() removes a CxMessage from the network and releases its resources. The translate CxObject uses this function to remove a CxMessage.

The example "Divert.c" shows how to use DivertCxMsg() as well as a signal CxObject.

<pre>
;/* divert.c - commodity to monitor user inactivity - compiled with SASC 5.10
LC -b0 -cfist -v -j73 divert.c
Blink FROM LIB:c.o,divert.o TO divert LIBRARY LIB:LC.lib,LIB:Amiga.lib NODEBUG SC SD
quit; */
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>
#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/alib_stdio_protos.h>
#include <clib/commodities_protos.h>
#include <devices/inputevent.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); }
#endif

#define TIMER_CLICKS 100

void main(int, char **);
void ProcessMsg(void);
void CxFunction(CxMsg *, CxObj *);

struct Library *CxBase, *IconBase;
struct MsgPort *broker_mp;
CxObj *broker, *cocustom, *cosignal;

struct NewBroker newbroker =
{
NB_VERSION,
"Divert", /* string to identify this broker */
"Divert",
"show divert",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

struct Task *task;
ULONG cxsigflag, signal, cxobjsignal;

void main(int argc, char **argv)
{
UBYTE **ttypes;
CxMsg *msg;

if (CxBase = OpenLibrary("commodities.library", 37L))
{
/* open the icon.library for support library functions, ArgArrayInit() and ArgArrayDone() */
if (IconBase = OpenLibrary("icon.library", 36L))
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (in the 2.0 version of amiga.lib) */
/* that makes it easy to read arguments from either a CLI or from Workbench's */
/* ToolTypes. Because it uses icon.library, the library has to be open before */
/* before calling this function. ArgArrayDone() cleans up after this function. */
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (in amiga.lib) searches through the array set up by ArgArrayInit() */
/* for a specific ToolType. If it finds one, it returns the numeric value of the */
/* number that followed the ToolType (i.e., CX_PRIORITY=7). If it doesn't find */
/* the ToolType, it returns the default value (the third argument) */
newbroker.nb_Pri = (BYTE)ArgInt(ttypes, "CX_PRIORITY", 0);

if (broker = CxBroker(&newbroker, NULL))
{
/* CxCustom() takes two arguments, a pointer to the custom function */
/* and an ID. Commodities Exchange will assign that ID to any CxMsg */
/* passed to the custom function. */
if (cocustom = CxCustom(CxFunction, 0L))
{
AttachCxObj(broker, cocustom);

/* Allocate a signal bit for the signal CxObj */
if ( (signal = (ULONG)AllocSignal(-1L)) != -1)
{
/* set up the signal mask */
cxobjsignal = 1L << signal;
cxsigflag |= cxobjsignal;

/* CxSignal takes two arguments, a pointer to the task to signal */
/* (normally the commodity) and the number of the signal bit the */
/* commodity acquired to signal with. */
task = FindTask(NULL);
if (cosignal = CxSignal(task, signal))
{
AttachCxObj(cocustom, cosignal);
ActivateCxObj(broker, 1L);
ProcessMsg();
}
FreeSignal(signal);
}
}
/* DeleteCxObjAll() is a commodities.library function that not only deletes */
/* the CxObject pointed to in its argument, but it deletes all of the */
/* CxObjects that are attached to it. */
DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)GetMsg(broker_mp))
ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
ArgArrayDone(); /* this amiga.lib function cleans up after ArgArrayInit() */
CloseLibrary(IconBase);
}
CloseLibrary(CxBase);
}
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
ULONG sigrcvd, msgid;
LONG returnvalue = 1L;

while (returnvalue)
{
sigrcvd = Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)GetMsg(broker_mp))
{
msgid = CxMsgID(msg);
ReplyMsg((struct Message *)msg);

switch(msgid)
{
case CXCMD_DISABLE:
ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
returnvalue = 0L;
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C) returnvalue = 0L;

/* Check to see if the signal CxObj signalled us. */
if (sigrcvd & cxobjsignal) printf("Got Signal\n");
}
}

/* The custom function for the custom CxObject. Any code for a custom CxObj must be short */
/* and sweet because it runs as part of the input.device task. */
void CxFunction(register CxMsg *cxm, CxObj *co)
{
struct InputEvent *ie;
static ULONG time = 0L;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent */
/* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it. */
ie = (struct InputEvent *)CxMsgData(cxm);

/* This custom function counts the number of timer events that go by while no other input */
/* events occur. If it counts more than a certain amount of timer events, it clears the */
/* count and diverts the timer event CxMsg to the custom object's personal */
/* list. If an event besides a timer event passes by, the timer event count is reset. */
if (ie->ie_Class == IECLASS_TIMER)
{
time++;
if (time >= TIMER_CLICKS)
{
time = 0L;
DivertCxMsg(cxm, co, co);
}
}
else
time = 0L;
}
</pre>

== New Input Events ==

The Commodities Library also has functions used to introduce new input events to the input stream.

<syntaxhighlight>
struct InputEvent *InvertString( UBYTE *string, ULONG *keymap );
VOID FreeIEvents( struct InputEvent *ie );
VOID AddIEvents( struct InputEvent *ie );
</syntaxhighlight>

InvertString() is a function that accepts an ASCII string and creates a linked list of input events that translate into the string using the supplied keymap (or the system default if the key map is NULL). The NULL terminated string may contain ANSI character codes, an input description enclosed in angle (<>) brackets, or one of the following backslash escape characters:

{| class="wikitable"
| \r
| Return
|-
| \t
| Tab
|-
| \\
| Backslash
|}

For example:

<pre>
abc<alt f1>\rhi there.
</pre>

FreeIEvents() frees a list of input events allocated by InvertString(). AddIEvents() is a commodities.library function that adds a linked list of input events at the the top of the Commodities network. Each input event in the list is made into an individual CxMessage. Note that if passed a linked list of input events created by InvertString(), the order the events appear in the string will be reversed.

=== Example ===
<syntaxhighlight>
/* PopShell.c - Simple hot key commodity example.
Adapted by xenic from the original source code.

Compile commands: gcc PopShell.c -o popshell -lamiga -Wall

To run the compiled program - Open 2 shell windows. Execute
PopShell in the first shell window with a line like:
PopShell HOTKEY "ctrl alt f"
Activate the second shell window and enter the keyboard shortcut.
A new shell window should open on the Workbench screen.
*/

#include <stdio.h>
#include <signal.h>

#include <libraries/commodities.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>
#include <clib/alib_protos.h>

static CONST_STRPTR version USED = "$VER: PopShell 1.1 (05.11.2015)";
static CONST_STRPTR stackcookie USED = "$STACK: 32768";

#define EVT_HOTKEY 1L

struct Library *CxBase = NULL;
struct CommoditiesIFace *ICommodities = NULL;

struct MsgPort *broker_mp = NULL;
CxObj *broker, *filter;

struct NewBroker newbroker =
{
NB_VERSION,
"Amiga PopShell", /* string to identify this broker */
"A Simple PopShell",
"A simple PopShell commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

CONST_STRPTR newshell = "\rllehswen"; /* "newshell" spelled backwards */
struct InputEvent *ie = NULL;
uint32 cxsigflag;

#define TEMPLATE "HOTKEY/K,CX_PRIORITY/N"
enum
{
ARG_HOTKEY, ARG_PRIORITY, ARG_MAX
};

void ProcessMsg(void);

int main(int argc, char **argv)
{
STRPTR hotkey = NULL;
CxMsg *msg = NULL;
struct RDArgs *argsdata = NULL;
int32 rargs[ARG_MAX] = {0};
int8 priority = 0;

signal(SIGINT, SIG_IGN);

if ((CxBase = IExec->OpenLibrary("commodities.library", 37L)))
{
if ((ICommodities = (struct CommoditiesIFace *)IExec->GetInterface(CxBase, "main", 1, NULL)))
{
if ((argsdata = IDOS->ReadArgs(TEMPLATE, rargs, NULL)))
{
if (rargs[ARG_PRIORITY])
priority = (int8)*(uint32 *)rargs[ARG_PRIORITY];
if ((broker_mp = IExec->AllocSysObject(ASOT_PORT, NULL)))
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;
newbroker.nb_Pri = priority;
hotkey = (STRPTR)rargs[ARG_HOTKEY];

if ((broker = ICommodities->CxBroker(&newbroker, NULL)))
{
/* CxFilter(), CxSender() & CxTranslate() are */
/* macros defined in libraries/commodities.h. */
/* CxFilter() creates a filter CxObject. */
/* CxSender() creates a sender CxObject. */
/* CxTranslate() creates a translation CxObject. */
if ((filter = CxFilter(hotkey)))
{
/* Add a filter CxObject to another's personal list. */
ICommodities->AttachCxObj(broker, filter);

/* Add a sender CxObject to the filter CxObject. */
ICommodities->AttachCxObj(filter, CxSender(broker_mp, EVT_HOTKEY));

/* Add a translation CxObject to the filter CxObject */
ICommodities->AttachCxObj(filter, CxTranslate(NULL));

if (!(ICommodities->CxObjError(filter)))
{
/* InvertString() is an amiga.lib function that creates a linked */
/* list of input events which would translate into the string */
/* passed to it. Note that it puts the input events in the */
/* opposite order in which the corresponding letters appear in */
/* the string. A translate CxObject expects them backwards. */
if ((ie = InvertString(newshell, NULL)))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
/* we have to release the memory allocated by InvertString. */
FreeIEvents(ie);
}
}
}
/* DeleteCxObjAll() is a commodities.library function that */
/* deletes the CxObject pointed to in its argument and */
/* deletes all of the CxObjects attached to it. */
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
IDOS->FreeArgs(argsdata); /* cleans up after ReadArgs() */
}
IExec->DropInterface((struct Interface *)ICommodities);
}
IExec->CloseLibrary(CxBase);
}
return RETURN_OK;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern uint32 cxsigflag;
CxMsg *msg = NULL;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1L;

while (returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY:
/* We got the message from the sender CxObject */
printf("You hit the HotKey.\n");
/* Add the string "newshell" to input * stream. */
/* If a shell gets it, it'll open a new shell. */
ICommodities->AddIEvents(ie);
break;
default:
printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
printf("CXCMD_KILL\n");
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a */
/* commodity with a name already in use but also can notify the */
/* already running commodity that it happened. It does this by */
/* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the */
/* user tries to run a windowless commodity that is already running, */
/* the user wants the commodity to shut down. */
printf("CXCMD_UNIQUE\n");
returnvalue = 0L;
break;
default:
printf("Unknown msgid\n");
break;
}
break;
default:
printf("Unknown msgtype\n");
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0L;
printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Commodities Exchange functions covered in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CxBroker()
| Creates a CxObject of type Broker.
|-
| CxFilter()
| Creates a CxObject of type Filter.
|-
| CxSender()
| Creates a CxObject of type Sender.
|-
| CxTranslate()
| Creates a CxObject of type Translate.
|-
| CxSignal()
| Creates a CxObject of type Signal.
|-
| CxCustom()
| Creates a CxObject of type Custom.
|-
| CxDebug()
| Creates a CxObject of type Debug.
|-
| DeleteCxObj()
| Frees a single CxObject
|-
| DeleteCxObjAll()
| Frees a group of connected CxObjects
|-
| ActivateCxObj()
| Activates a newly created CxObject in the commodities network.
|-
| CxTranslate()
| Sets up substitution of one input event for another by translate CxObjects.
|-
| CxMsgType()
| Finds the type of a CxMessage.
|-
| CxMsgData()
| Returns the CxMessage data.
|-
| CxMsgID()
| Returns the CxMessage ID.
|-
| CxObjError()
| Returns the CxObject's accumulated error field.
|-
| ClearCxObjError()
| Clear the CxObject's accumulated error field.
|-
| AttachCxObj()
| Attaches a CxObject to the end of a given CxObject's list.
|-
| InsertCxObj()
| Inserts a CxObject in a given position in a CxObject's list.
|-
| EnqueueCxObj()
| Inserts a CxObject in a CxObject's list by priority.
|-
| SetCxObjPri()
| Sets a CxObject's priority for EnqueueCxObj().
|-
| RemoveCxObj()
| Removes a CxObject from a list.
|-
| SetFilter()
| Set a filter for a CxObject from an input description string.
|-
| SetFilterIX()
| Set a filter for a CxObject from an IX data structure.
|-
| ParseIX()
| Convert an input description string to an IX data structure.
|-
| DivertCxMsg()
| Divert a CxMessage to one CxObject and return it to another.
|-
| RouteCxMsg()
| Redirect a CxMessage to a new CxObject.
|-
| DisposeCxMsg()
| Cancel a CxMessage removing it from the Commodities network.
|-
| InvertString()
| Creates a linked list of input events that correspond to a given string.
|-
| FreeIEvents()
| Frees the linked list of input events created with InvertString().
|-
| AddIEvents()
| Converts a list of input events to CxMessages and puts them into the network.
|-
| CopyBrokerList()
| Creates a local copy of the current broker list (V53.4).
|-
| FreeBrokerList()
| Frees the local broker list (V53.4).
|-
| BrokerCommand()
| Sends a command to a commodity broker (V53.4).
|}

=== Obsolete Functions ===

The following functions are obsolete and no longer used:

{| class="wikitable"
! Function
! Description
|-
| ArgArrayInit()
| Create a Tool Types array from argc and argv (Workbench or Shell).
|-
| ArgArrayDone()
| Free the resources used by ArgArrayInit().
|-
| ArgString()
| Return the string associated with a given Tool Type in the array.
|-
| ArgInt()
| Return the integer associated with a given Tool Type in the array.
|}

Commodities Exchange Library

2015-12-06T09:06:16Z

Daniel Jedlicka: Replaced BYTE, ULONG and LONG with int8, uint32 and int32, respectively.

{{CodeReview}}
== Commodities Exchange Library ==

This article describes Commodities Exchange, the library of routines used to add a custom input handler to the Amiga. With Commodities Exchange, any program function can be associated with key combinations or other input events ''globally'' allowing the creation utility programs that run in the background for all tasks.

== Custom Input Handlers ==

The input.device has a hand in almost all user input on the Amiga. It gathers input events from the keyboard, the gameport (mouse), and several other sources, into one input "stream". Special programs called input event handlers intercept input events along this stream, examining and sometimes changing the input events. Both Intuition and the console device use input handlers to process user input.

[[File:LibFig31-1.png|frame|center|The Amiga Input Stream]]

Using the input.device, a program can introduce its own custom handler into the chain of input handlers at almost any point in the chain. "Hot key" programs, shell pop-up programs, and screen blankers all commonly use custom input handlers to monitor user input before it gets to the Intuition input handler.

[[File:LibFig31-2.png|frame|center|A Custom Input Handler]]

Custom input handlers do have their drawbacks, however. Not only are these handlers hard to program, but because there is no standard way to implement and control them, multiple handlers often do not work well together. Their antisocial behavior can result in load order dependencies and incompatibilities between different custom input handlers. Even for the expert user, having several custom input handlers coexist peacefully can be next to impossible.

[[File:LibFig31-3.png|frame|center|The Commodities Network]]

Commodities Exchange eliminates these problems by providing a simple, standardized way to program and control custom input handlers. It is divided into two parts: an Exec library and a controller program.

The Exec library is called commodities.library. When it is first opened, commodities.library establishes a single input handler just before Intuition in the input chain. When this input handler receives an input event, it creates a CxMessage (Commodities Exchange Message) corresponding to the input event, and diverts the CxMessage through the network of Commodities Exchange input handlers.

These handlers are made up of trees of different CxObjects (Commodities Exchange Objects), each of which performs a simple operation on the CxMessages. Any CxMessages that exit the network are returned to the input.device's input stream as input events.

Through function calls to the commodities.library, an application can install a custom input handler. A Commodities Exchange application, sometimes simply referred to as a commodity, uses the CxObject primitives to do things such as filter certain CxMessages, translate CxMessages, signal a task when a CxObject receives a CxMessage, send a message when a CxObject receives a CxMessage, or if necessary, call a custom function when a CxObject receives a CxMessage.

=== Commodities Control ===

The standard controller program is called Exchange. It is located in the Utilities/Commodities drawer on your system partition. With Exchange, the user can monitor and control all the currently running Commodities Exchange applications from this one program. The user can enable and disable a commodity, kill a commodity, or, if the commodity has a window, ask the commodity to show or hide its window. When the user requests any of these actions, the controller program sends the commodity a message, telling it which action to perform.

Starting with version 53.4 of the commodities.library, functions are available that allow developers to write their own commodity control programs (Exchange replacements). These functions were not public previously.

=== Important Notes ===

* Commodities are special-purpose programs. In fact, most programs or applications are '''not''' suitable for becoming commodities. The Commodities Exchange framework is ideal for programs that need to monitor all user input: hotkey utilities, screen blankers, mouse blankers, etc.
* In the past, some developers turned their programs into commodities only to provide them with a handy keyboard shortcut to bring up/close their GUI. Please note that such practice is actually a misuse of the commodities framework.
* Commodities Exchange should never be used as an alternate method of receiving user input for an application. Other applications depend on getting user input in some form or another from the input stream. A greedy program that diverts input to itself rather than letting the input go to where the user expects it can seriously confuse the user, not to mention compromise the advantages of multitasking.

== CxObjects ==

CxObjects are the basic building blocks used to construct a commodity. A commodity uses CxObjects to take care of all manipulations of CxMessages. When a CxMessage "arrives" at a CxObject, that CxObject carries out its primitive action and then, if it has not deleted the CxMessage, it passes the CxMessage on to the next CxObject. A commodity links together CxObjects into a tree, organizing these simple action objects to perform some higher function.

A CxObject is in one of two states, active or inactive. An active CxObject performs its primitive action every time it receives a CxMessage. If a CxObject is inactive, CxMessages bypass it, continuing to the CxObject that follows the inactive one. By default, all CxObjects except the type called brokers are created in the active state.

Currently, there are seven types of CxObjects:

{| class="wikitable"
|+ Commodities Exchange Object Types
! Object Type
! Purpose
|-
| Broker || Registers a new commodity with the commodity network
|-
| Filter || Accepts or rejects input events based on criteria set up by the application
|-
| Sender || Sends a message to a message port
|-
| Translate || Replaces the input event with a different one
|-
| Signal || Signals a task
|-
| Custom || Calls a custom function provided by the commodity
|-
| Debug || Sends debug information out the serial port
|}

== Installing A Broker Object ==

The Commodities Exchange input handler maintains a master list of CxObjects to which it diverts input events using CxMessages. The CxObjects in this master list are a special type of CxObject called ''brokers''. The only thing a broker CxObject does is divert CxMessages to its own personal list of CxObjects. A commodity creates a broker and attaches other CxObjects to it. These attached objects take care of the actual input handler related work of the commodity and make up the broker's personal list.

The first program listing, "Broker.c", is a very simple example of a working commodity. It serves only to illustrate the basics of a commodity, not to actually perform any useful function. It shows how to set up a broker and process commands from the controller program.

Besides opening commodities.library and creating an Exec message port, setting up a commodity requires creating a broker. The function CxBroker() creates a broker and adds it to the master list.

<syntaxhighlight>
CxObj *CxBroker(struct NewBroker *nb, LONG *error);
</syntaxhighlight>

CxBroker()'s first argument is a pointer to a NewBroker structure:

<syntaxhighlight>
struct NewBroker {
BYTE nb_Version; /* There is an implicit pad byte after this BYTE */
BYTE *nb_Name;
BYTE *nb_Title;
BYTE *nb_Descr;
SHORT nb_Unique;
SHORT nb_Flags;
BYTE nb_Pri; /* There is an implicit pad byte after this BYTE */
struct MsgPort *nb_Port;
WORD nb_ReservedChannel; /* Unused, make zero for future compatibility */
};
</syntaxhighlight>

Commodities Exchange gets all the information it needs about the broker from this structure. NewBroker's nb_Version field contains the version number of the NewBroker structure. This should be set to NB_VERSION which is defined in <libraries/commodities.h>. The nb_Name, nb_Title, and nb_Descr point to strings which hold the name, title, and description of the broker. The two bit fields, nb_Unique and nb_Flags, toggle certain features of Commodities Exchange based on their values. They are discussed in detail later in this article.

The nb_Pri field contains the broker's priority. Commodities Exchange inserts the broker into the master list based on this number. Higher priority brokers get CxMessages before lower priority brokers.

CxBroker()'s second argument is a pointer to a LONG. If this pointer is not NULL, CxBroker() fills in this field with one of the following error return codes from <libraries/commodities.h>:

<syntaxhighlight>
CBERR_OK 0 /* No error */
CBERR_SYSERR 1 /* System error , no memory, etc */
CBERR_DUP 2 /* uniqueness violation */
CBERR_VERSION 3 /* didn't understand nb_VERSION */
</syntaxhighlight>

Once the broker object is created with CxBroker(), it must be activated with ActivateCxObject().

<syntaxhighlight>
LONG oldactivationvalue = ActivateCxObj(CxObj *co, LONG newactivationvalue);
</syntaxhighlight>

After successfully completing the initial set up and activating the broker, a commodity can begin its input processing loop waiting for CxMessages to arrive.

== CxMessages ==

There are actually two types of CxMessages. The first, CXM_IEVENT, corresponds to an input event and travels through the Commodities Exchange network. The other type, CXM_COMMAND, carries a command to a commodity. A CXM_COMMAND normally comes from the controller program and is used to pass user commands on to a commodity. A commodity receives these commands through an Exec message port that the commodity sets up before it calls CxBroker(). The NewBroker's nb_Port field points to this message port. A commodity can tell the difference between the two types of CxMessages by calling the CxMsgType() function.

<syntaxhighlight>
ULONG CxMsgType( CxMsg *cxm );
UBYTE *CxMsgData( CxMsg *cxm );
LONG CxMsgID ( CxMsg *cxm );
</syntaxhighlight>

A CxMessage not only has a type, it can also have a data pointer as well as an ID associated with it. The data associated with a CXM_IEVENT CxMessage is an InputEvent structure. By using the CxMsgData() function, a commodity can obtain a pointer to the corresponding InputEvent of a CXM_IEVENT message. Commodities Exchange gives an ID of zero to any CXM_IEVENT CxMessage that it introduces to the Commodities network but certain CxObjects can assign an ID to them.

For a CXM_COMMAND CxMessages, the data pointer is generally not used but the ID specifies a command passed to the commodity from the user operating the controller program. The CxMsgID() macro extracts the ID from a CxMessage.

=== A Simple Commodity Example ===

The example below, "Broker.c", receives input from one source, the controller program. The controller program sends a CxMessage each time the user clicks its Enable, Disable, or Kill gadgets. Using the CxMsgID() function, the commodity finds out what the command is and executes it.

<syntaxhighlight>
// broker.c - Simple skeletal example of opening a broker

#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities = NULL;

CxObj *broker;
struct MsgPort *broker_mp;
ULONG cxsigflag;

struct NewBroker newbroker = {
NB_VERSION, /* nb_Version - Version of the NewBroker structure */
"Amiga broker", /* nb_Name - Name Commodities uses to identify this commodity */
"Broker", /* nb_Title - Title of commodity that appears in CXExchange */
"A simple example of a broker", /* nb_Descr - Description of the commodity */
0, /* nb_Unique - Tells CX not to launch another commodity with same name */
0, /* nb_Flags - Tells CX if this commodity has a window */
0, /* nb_Pri - This commodity's priority */
0, /* nb_Port - MsgPort CX talks to */
0 /* nb_ReservedChannel - reserved for later use */
};

int main()
{
CxMsg *msg;

struct Library *CxBase = = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);
if (ICommodities != NULL)
{
/* Commodities talks to a Commodities application through */
/* an Exec Message port, which the application provides */
if (broker_mp = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
{
newbroker.nb_Port = broker_mp;

/* The commodities.library function CxBroker() adds a borker to the
* master list. It takes two arguments, a pointer to a NewBroker
* structure and a pointer to a LONG. The NewBroker structure contains
* information to set up the broker. If the second argument is not
* NULL, CxBroker will fill it in with an error code.
*/
if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
cxsigflag = 1L << broker_mp->mp_SigBit;

/* After it's set up correctly, the broker has to be activated */
ICommodities->ActivateCxObj(broker, 1L);

/* the main processing loop */
ProcessMsg();

/* It's time to clean up. Start by removing the broker from the
* Commodities master list. The DeleteCxObjAll() function will
* take care of removing a CxObject and all those connected
* to it from the Commodities network
*/
ICommodities->DeleteCxObj(broker);

/* Empty the port of CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
}

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
CxMsg *msg;

uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while (returnvalue)
{
/* wait for something to happen */
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

/* process any messages */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
/* Extract necessary information from the CxMessage and return it */
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
/* Shouldn't get any of these in this example */
break;
case CXM_COMMAND:
/* Commodities has sent a command */
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
/* The user clicked Commodities Exchange disable
* gadget better disable
*/
ICommodities->ActivateCxObj(broker, 0);
break;
case CXCMD_ENABLE:
/* user clicked enable gadget */
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1);
break;
case CXCMD_KILL:
/* user clicked kill gadget, better quit */
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
/* Test to see if user tried to break */
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

Notice that "Broker.c" uses Ctrl-C as a break key. The break key for any commodity should be Ctrl-C.

=== Controller Commands ===

The commands that a commodity can receive from the controller program (as defined in <libraries/commodities.h>) are:

<syntaxhighlight>
CXCMD_DISABLE /* please disable yourself */
CXCMD_ENABLE /* please enable yourself */
CXCMD_KILL /* go away for good */
CXCMD_APPEAR /* open your window, if you can */
CXCMD_DISAPPEAR /* hide your window */
</syntaxhighlight>

The CXCMD_DISABLE, CXCMD_ENABLE, and CXCMD_KILL commands correspond to the similarly named controller program gadgets, Disable, Enable, and Kill; CXCMD_APPEAR and CXCMD_DISAPPEAR correspond to the controller program gadgets, Show and Hide. These gadgets are ghosted in Broker.c because it has no window (It doesn't make much sense to give the user a chance to click the Show and Hide gadgets). In order to do this, Broker.c has to tell Commodities Exchange to ghost these gadgets. When CxBroker() sets up a broker, it looks at the NewBroker.nb_Flags field to see if the COF_SHOW_HIDE bit (from <libraries/commodities.h>) is set. If it is, the "Show" and "Hide" gadgets for this broker will be selectable. Otherwise they are ghosted and disabled.

=== Shutting Down the Commodity ===

Shutting down a commodity is easy. After replying to all CxMessages waiting at the broker's message port, a commodity can delete its CxObjects. The DeleteCxObj() function removes a single CxObject from the Commodities network. DeleteCxObjectAll() removes multiple objects.

<syntaxhighlight>
VOID DeleteCxObj( CxObj *co );
VOID DeleteCxObjAll( CxObj *delete_co );
</syntaxhighlight>

If a commodity has a lot of CxObjects, deleting each individually can be a bit tedious. DeleteCxObjAll() will delete a CxObject and any other CxObjects that are attached to it. The HotKey.c example given later in this article uses this function to delete all its CxObjects. A commodity that uses DeleteCxObjAll() to delete all its CxObjects should make sure that they are all connected to the main one. (See the "Connecting CxObjects" section below.)

After deleting its CxObjects, a commodity must take care of any CxMessages that might have arrived at the message port just before the commodity deleted its objects.

<syntaxhighlight>
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
</syntaxhighlight>

== Commodity Tool Types ==

A goal of Commodities Exchange is to improve user control over input handlers. One way in which it accomplishes this goal is through the use of standard icon Tool Types. The user will expect commodities to recognize the set of standard Tool Types:

* CX_PRIORITY
* CX_POPUP
* CX_POPKEY

CX_PRIORITY lets the user set the priority of a commodity. The string "CX_PRIORITY=" is a number from -128 to 127. The higher the number, the higher the priority of the commodity, giving it access to input events before lower priority commodities. All commodities should recognize CX_PRIORITY.

CX_POPUP and CX_POPKEY are only relevant to commodities with a window. The string "CX_POPUP=" should be followed by a "yes" or "no", telling the commodity if it should or shouldn't show its window when it is first launched. CX_POPKEY is followed by a string describing the key to use as a hot key for making the commodity's window appear (pop up). The description string for CX_POPKEY describes an input event. The specific format of the string is discussed in the next section ("Filter Objects and the Input Description String").

=== Obsolete Parsing Functions ===

Prior to AmigaOS 4.0, the Commodities Library had the following support functions which were included in an external link library:

<syntaxhighlight>
UBYTE **ArgArrayInit(LONG argc, UBYTE **argv);
VOID ArgArrayDone(void);
STRPTR ArgString(UBYTE **tooltypearray, STRPTR tooltype, STRPTR defaultvalue);
LONG *ArgInt(UBYTE **tooltypearray, STRPTR tooltype, LONG defaultvalue);
</syntaxhighlight>

These functions are no longer available. Use IDOS->ReadArgs(), IIcon->FindToolType() and IIcon->MatchToolValue() instead, depending on whether the commodity was launched from Workbench or the Shell (CLI).

== Filter Objects and Input Description Strings ==

Because not all commodities are interested in every input event that makes it way down the input chain, Commodities Exchange has a method for filtering them. A filter CxObject compares the CxMessages it receives to a pattern. If a CxMessage matches the pattern, the filter diverts the CxMessage down its personal list of CxObjects.

<syntaxhighlight>
CxObj *CxFilter(STRPTR descriptionstring);
</syntaxhighlight>

The C macro CxFilter() (defined in <libraries/commodities.h>) returns a pointer to a filter CxObject. The macro has only one argument, a pointer to a string describing which input events to filter. The following regular expression outlines the format of the input event description string (CX_POPKEY uses the same description string format):

<pre>
[class] { [-] (qualifier | synonym) ) } [ [-] upstroke] [highmap | ANSICode]
</pre>

''Class'' can be any one of the class strings in the table below. Each class string corresponds to a class of input event as defined in <devices/inputevent.h>. Commodities Exchange will assume the class is rawkey if the class is not explicitly stated.

{| class="wikitable"
! Class String
! Input Event Class
|-
| "rawkey" || IECLASS_RAWKEY
|-
| "rawmouse" || IECLASS_RAWMOUSE
|-
| "event" || IECLASS_EVENT
|-
| "pointerpos" || IECLASS_POINTERPOS
|-
| "timer" || IECLASS_TIMER
|-
| "newprefs" || IECLASS_NEWPREFS
|-
| "diskremoved" || IECLASS_DISKREMOVED
|-
| "diskinserted" || IECLASS_DISKINSERTED
|}

''Qualifier'' is one of the qualifier strings from the table below. Each string corresponds to an input event qualifier as defined in <devices/inputevent.h>). A dash preceding the qualifier string tells the filter object not to care if that qualifier is present in the input event. Notice that there can be more than one qualifier (or none at all) in the input description string.

{| class="wikitable"
! Qualifier String
! Input Event Class
|-
| "lshift" || IEQUALIFIER_LSHIFT
|-
| "rshift" || IEQUALIFIER_RSHIFT
|-
| "capslock" || IEQUALIFIER_CAPSLOCK
|-
| "control" || IEQUALIFIER_CONTROL
|-
| "lalt" || IEQUALIFIER_LALT
|-
| "ralt" || IEQUALIFIER_RALT
|-
| "lcommand" || IEQUALIFIER_LCOMMAND
|-
| "rcommand" || IEQUALIFIER_RCOMMAND
|-
| "numericpad" || IEQUALIFIER_NUMERICPAD
|-
| "repeat" || IEQUALIFIER_REPEAT
|-
| "midbutton" || IEQUALIFIER_MIDBUTTON
|-
| "rbutton" || IEQUALIFIER_RBUTTON
|-
| "leftbutton" || IEQUALIFIER_LEFTBUTTON
|-
| "relativemouse" || IEQUALIFIER_RELATIVEMOUSE
|}

''Synonym'' is one of the synonym strings from the table below. These strings act as synonyms for groups of qualifiers. Each string corresponds to a synonym identifier as defined in <libraries/commodities.h>. A dash preceding the synonym string tells the filter object not to care if that synonym is present in the input event. Notice that there can be more than one synonym (or none at all) in the input description string.

{| class="wikitable"
! Synonym String
! Synonym Identifier
! Description
|-
| "shift" || IXSYM_SHIFT || Look for either Shift key
|-
| "caps" || IXSYM_CAPS || Look for either Shift key or Caps Lock
|-
| "alt" || IXSYM_ALT || Look for either Alt key
|}

''Upstroke'' is the literal string "upstroke". If this string is absent, the filter considers only downstrokes. If it is present alone, the filter considers only upstrokes. If preceded by a dash, the filter considers both upstrokes and downstrokes.

''Highmap'' is one of the following strings:

"backspace", "del", "down", "enter", "esc", "f1", "f2",
"f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10",
"f11, "f12", "help", "left", "return", "right", "space", "tab", "up".

''ANSICode'' is a single character (for example "a" that Commodities Exchange looks up in the system default keymap.

Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the input description string would be:

<pre>
"rawkey lshift alt f2"
</pre>

To specify the key that produces an "a" (this may or may not be the A key depending on the keymap), with or without any Shift, Alt, or Control keys pressed use:

<pre>
"-shift -alt -control a"
</pre>

For a mouse move with the right mouse button down, use:

<pre>
"rawmouse rbutton"
</pre>

To specify a timer event use:

<pre>
"timer"
</pre>

== Connecting CxObjects ==

A CxObject has to be inserted into the Commodities network before it can process any CxMessages. AttachCxObj() adds a CxObject to the personal list of another CxObject. The HotKey.c example uses it to attach its filter to a broker.

<syntaxhighlight>
VOID AttachCxObj ( CxObj *headobj, CxObj *co);
VOID InsertCxObj ( CxObj *headobj, CxObj *co, CxObj *co_pred );
VOID EnqueueCxObj( CxObj *headobj, CxObj *co );
VOID SetCxObjPri ( CxObj *co, LONG pri );
VOID RemoveCxObj ( CxObj *co );
</syntaxhighlight>

AttachCxObj() adds the CxObject to the end of headobj's personal list. The ordering of a CxObject list determines which object gets CxMessages first. InsertCxObj() also inserts a CxObject, but it inserts it after another CxObject already in the personal list (co_pred in the prototype above).

Brokers aren't the only CxObjects with a priority. All CxObjects have a priority associated with them. To change the priority of any CxObject, use the SetCxObjPri() function. A commodity can use the priority to keep CxObjects in a personal list sorted by their priority. The commodities.library function EnqueueCxObj() inserts a CxObject into another CxObject's personal list based on priority.

Like its name implies, the RemoveCxObj() function removes a CxObject from a personal list. Note that it is not necessary to remove a CxObject from a list in order to delete it.

<syntaxhighlight>
/* HotKey.c - Simple hot key commodity
*/
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/commodities.h>
#include <proto/icon.h>

#define EVT_HOTKEY 1L

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities;
struct IconIFace *IIcon;

struct MsgPort *broker_mp;
CxObj *broker, *filter, *sender, *translate;

struct NewBroker newbroker = {
NB_VERSION,
"Amiga HotKey", /* string to identify this broker */
"A Simple HotKey",
"A simple hot key commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

uint32 cxsigflag;

int main(int argc, char **argv)
{
uint8 *hotkey, **ttypes;
CxMsg *msg;

struct Library *CxBase = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);

/* open the icon.library for the support library */
/* functions, ArgArrayInit() and ArgArrayDone() */
struct Library *IconBase = IExec->OpenLibrary("icon.library", 50);
struct IconIFace *IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);

if (ICommodities != NULL && IIcon != NULL)
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (from the 2.0 version
* of amiga.lib) that makes it easy to read arguments from either a
* CLI or from Workbench's ToolTypes. Because it uses icon.library,
* the library has to be open before calling this function.
* ArgArrayDone() cleans up after this function.
*/
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (also from amiga.lib) searches through the array set up
* by ArgArrayInit() for a specific ToolType. If it finds one, it
* returns the numeric value of the number that followed the
* ToolType (i.e., CX_PRIORITY=7). If it doesn't find the ToolType,
* it returns the default value (the third argument)
*/
newbroker.nb_Pri = (int8)ArgInt(ttypes, "CX_PRIORITY", 0);

/* ArgString() works just like ArgInt(), except it returns a pointer to a string
* rather than an integer. In the example below, if there is no ToolType
* "HOTKEY", the function returns a pointer to "rawkey control esc".
*/
hotkey = ArgString(ttypes, "HOTKEY", "rawkey control esc");

if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
/* CxFilter() is a macro that creates a filter CxObject. This filter
* passes input events that match the string pointed to by hotkey.
*/
if (filter = ICommodities->CxFilter(hotkey))
{
/* Add a CxObject to another's personal list */
ICommodities->AttachCxObj(broker, filter);

/* CxSender() creates a sender CxObject. Every time a sender gets
* a CxMessage, it sends a new CxMessage to the port pointed to in
* the first argument. CxSender()'s second argument will be the ID
* of any CxMessages the sender sends to the port. The data pointer
* associated with the CxMessage will point to a *COPY* of the
* InputEvent structure associated with the orginal CxMessage.
*/
if (sender = CxSender(broker_mp, EVT_HOTKEY))
{
ICommodities->AttachCxObj(filter, sender);

/* CxTranslate() creates a translate CxObject. When a translate
* CxObject gets a CxMessage, it deletes the original CxMessage
* and adds a new input event to the input.device's input stream
* after the Commodities input handler. CxTranslate's argument
* points to an InputEvent structure from which to create the new
* input event. In this example, the pointer is NULL, meaning no
* new event should be introduced, which causes any event that
* reaches this object to disappear from the input stream.
*/
if (translate = ICommodities->CxTranslate(NULL))
{
ICommodities->AttachCxObj(filter, translate);

/* CxObjError() is a commodities.library function that returns
* the internal accumulated error code of a CxObject.
*/
if (! CxObjError(filter))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
}
}
}
}
/* DeleteCxObjAll() is a commodities.library function that not only
* deletes the CxObject pointed to in its argument, but it deletes
* all of the CxObjects that are attached to it.
*/
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
/* this amiga.lib function cleans up after ArgArrayInit() */
ArgArrayDone();
}

IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while(returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
IDOS->Printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY: /* We got the message from the sender CxObject */
IDOS->Printf("You hit the HotKey.\n");
break;
default:
IDOS->Printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
IDOS->Printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a
* commodity with a name already in use but also can notify the
* already running commodity that it happened. It does this by
* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the
* user tries to run a windowless commodity that is already running,
* the user wants the commodity to shut down. */
IDOS->Printf("CXCMD_UNIQUE\n");
returnvalue = 0;
break;
default:
IDOS->Printf("Unknown msgid\n");
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Sender CxObjects ==

A filter CxObject by itself is not especially useful. It needs some other CxObjects attached to it. A commodity interested in knowing if a specific key was pressed uses a filter to detect and divert the corresponding CxMessage down the filter's personal list. The filter does this without letting the commodity know what happened. The sender CxObject can be attached to a filter to notify a commodity that it received a CxMessage. CxSender() is a macro that creates a sender CxObject.

<syntaxhighlight>
senderCxObj = CxObj *CxSender(struct MsgPort *senderport, LONG cxmID);
</syntaxhighlight>

CxSender() supplies the sender with an Exec message port and an ID. For every CxMessage a sender receives, it sends a new CxMessage to the Exec message port passed in CxSender(). Normally, the commodity creates this port. It is not unusual for a commodity's broker and sender(s) to share an Exec message port. The HotKey.c example does this to avoid creating unnecessary message ports. A sender uses the ID (cxmID) passed to CxSender() as the ID for all the CxMessages that the it transmits. A commodity uses the ID to monitor CxMessages from several senders at a single message port.

A sender does several things when it receives a CxMessage. First, it duplicates the CxMessage's corresponding input event and creates a new CxMessage. Then, it points the new CxMessage's data field to the copy of the input event and sets the new CxMessage's ID to the ID passed to CxSender(). Finally, it sends the new CxMessage to the port passed to CxSender(), asynchronously.

Because HotKey uses only one message port between its broker and sender object, it has to extract the CxMessage's type so it can tell if it is a CXM_IEVENT or a CXM_COMMAND. If HotKey gets a CXM_IEVENT, it compares the CxMessage's ID to the sender's ID, EVT_HOTKEY, to see which sender sent the CxMessage. Of course HotKey has only one sender, so it only checks for only one ID. If it had more senders, HotKey would check for the ID of each of the other senders as well.

Although HotKey doesn't use it, a CXM_IEVENT CxMessage contains a pointer to the copy of an input event. A commodity can extract this pointer (using CxMsgData()) if it needs to examine the input event copy. This pointer is only valid before the CxMessage reply. Note that it does not make any sense to modify the input event copy.

Senders are attached almost exclusively to CxObjects that filter out most input events (usually a filter CxObject). Because a sender sends a CxMessage for every single input event it gets, it should only get a select few input events. The AttachCxObj() function can add a CxObject to the end of a filter's (or some other filtering CxObject's) personal list. A commodity should not attach a CxObject to a sender as a sender ignores any CxObjects in its personal list.

== Translate CxObjects ==

Normally, after a commodity processes a hot key input event, it needs to eliminate that input event. Other commodities may need to replace an input event with a different one. The translate CxObject can be used for these purposes.

<syntaxhighlight>
translateCxObj = CxObj *CxTranslate(struct InputEvent *newinputevent);
</syntaxhighlight>

The macro CxTranslate() creates a new translate CxObject. CxTranslate()'s only argument is a pointer to a chain of one or more InputEvent structures.

When a translate CxObject receives a CxMessage, it eliminates the CxMessage and its corresponding input event from the system. The translator introduces a new input event, which Commodities Exchange copies from the InputEvent structure passed to CxTranslate() (newinputevent from the function prototype above), in place of the deleted input event.

A translator is normally attached to some kind of filtering CxObject. If it wasn't, it would translate all input events into the same exact input event. Like the sender CxObject, a translator does not divert CxMessages down its personal list, so it doesn't serve any purpose to add any to it.

<syntaxhighlight>
VOID SetTranslate( CxObj *translator, struct InputEvent *ie );
</syntaxhighlight>

It is possible to change the InputEvent structure that a translator looks at when it creates and introduces new input events into the input stream. The function SetTranslate() accepts a pointer to the new InputEvent structure, which the translator will duplicate and introduce when it receives a CxMessage.

HotKey utilizes a special kind of translator. Instead of supplying a new input event, HotKey passes a NULL to CxTranslate(). If a translator has a NULL new input event pointer, it does not introduce a new input event, but still eliminates any CxMessages and corresponding input events it receives.

== CxObject Errors ==

A Commodities Exchange function that acts on a CxObject records errors in the CxObject's accumulated error field. The function CxObjError() returns a CxObject's error field.

<syntaxhighlight>
int32 co_errorfield = CxObjError( CxObj *co );
</syntaxhighlight>

Each bit in the error field corresponds to a specific type of error. The following is a list of the currently defined CxObject errors and their corresponding bit mask constants.

{| class="wikitable"
! Error Constant
! Meaning
|-
| COERR_ISNULL
| CxObjError() was passed a NULL.
|-
| COERR_NULLATTACH
| Someone tried to attach a NULL CxObject to this CxObject.
|-
| COERR_BADFILTER
| This filter CxObject currently has an invalid filter description.
|-
| COERR_BADTYPE
| Someone tried to perform a type specific function on the wrong type of CxObject (for example calling SetFilter() on a sender CxObject).
|}

The remaining bits are reserved for future use. HotKey.c checks the error field of its filter CxObject to make sure the filter is valid. HotKey.c does not need to check the other objects with CxObjError() because it already makes sure that these other objects are not NULL, which is the only other kind of error the other objects can cause in this situation.

Commodities Exchange has a function that clears a CxObject's accumulated error field, ClearCxObjError().

<syntaxhighlight>
VOID ClearCxObjError( CxObj *co );
</syntaxhighlight>

A commodity should be careful about using this, especially on a filter. If a commodity clears a filter's error field and the COERR_BADFILTER bit is set, Commodities Exchange will think that the filter is OK and start sending messages through it.

== Uniqueness ==

When a commodity opens its broker, it can ask Commodities Exchange not to launch another broker with the same name (nb_Name). The purpose of the uniqueness feature is to prevent the user from starting duplicate commodities. If a commodity asks, Commodities Exchange will not only refuse to create a new, similarly named broker, but it will also notify the original commodity if someone tries to do so.

A commodity tells Commodities Exchange not to allow duplicates by setting certain bits in the nb_Unique field of the NewBroker structure it sends to CxBroker():

{| class="wikitable"
| NBU_UNIQUE
| bit 0
|-
| NBU_NOTIFY
| bit 1
|}

Setting the NBU_UNIQUE bit prevents duplicate commodities. Setting the NBU_NOTIFY bit tells Commodities Exchange to notify a commodity if an attempt was made to launch a duplicate. Such a commodity will receive a CXM_COMMAND CxMessage with an ID of CXCMD_UNIQUE when someone tries to duplicate it. Because the uniqueness feature uses the name a programmer gives a commodity to differentiate it from other commodities, it is possible for completely different commodities to share the same name, preventing the two from coexisting. For this reason, a commodity should not use a name that is likely to be in use by other commodities (like "filter" or "hotkey"). Instead, use a name that matches the commodity name.

When "HotKey.c" gets a CXCMD_UNIQUE CxMessage, it shuts itself down. "HotKey.c" and all the windowless commodities that come with Workbench shut themselves down when they get a CXCMD_UNIQUE CxMessage. Because the user will expect all windowless commodities to work this way, all windowless commodities should follow this standard.

When the user tries to launch a duplicate of a system commodity that has a window, the system commodity moves its window to the front of the display, as if the user had clicked the "Show" gadget in the controller program's window. A windowed commodity should mimic conventions set by existing windowed system commodities, and move its window to the front of the display.

== Signal CxObjects ==

A commodity can use a sender CxObject to find out if a CxMessage has "visited" a CxObject, but this method unnecessarily uses system resources. A commodity that is only interested in knowing if such a visitation took place does not need to see a corresponding input event or a CxMessage ID. Instead, Commodities Exchange has a CxObject that uses an Exec signal.

<syntaxhighlight>
CxObj *signalCxObj = CxSignal(struct Task *, LONG cx_signal);
</syntaxhighlight>

CxSignal() sets up a signal CxObject. When a signal CxObject receives a CxMessage, it signals a task. The commodity is responsible for determining the proper task ID and allocating the signal. Normally, a commodity wants to be signaled so it uses FindTask(NULL) to find it's own task address. Note that cx_signal from the above prototype is the signal number as returned by AllocSignal(), not the signal mask made from that number. For more information on signals, see [[Exec_Signals|Exec Signals]].

The example "Divert.c" (shown a little later) uses a signal CxObject.

== Custom CxObjects ==

Although the CxObjects mentioned so far take care of most of the input event handling a commodity needs to do, they cannot do it all. This is why Commodities Exchange has a custom CxObject. When a custom CxObject receives a CxMessage, it calls a function provided by the commodity.

<syntaxhighlight>
CxObject *customCxObj = CxCustom(int32 *customfunction(), int32 cxmID);
</syntaxhighlight>

A custom CxObject is the only means by which a commodity can directly modify input events as they pass through the Commodities network as CxMessages. For this reason, it is probably the most dangerous of the CxObjects to use.

{{Note|title=A Warning About Custom CxObjects|text=Unlike the rest of the code a commodities programmer writes, the code passed to a custom CxObject runs as part of the input.device task, putting severe restrictions on the function. No DOS or Intuition functions can be called. No assumptions can be made about the values of registers upon entry. Any function passed to CxCustom() should be very quick and very simple, with a minimum of stack usage.}}

Commodities Exchange calls a custom CxObject's function as follows:

<syntaxhighlight>
VOID customfunction(CxMsg *cxm, CxObj *customcxobj);
</syntaxhighlight>

where cxm is a pointer to a CxMessage corresponding to a real input event, and customcxobj is a pointer to the custom CxObject. The custom function can extract the pointer to the input event by calling CxMsgData(). Before passing the CxMessage to the custom function, Commodities Exchange sets the CxMessage's ID to the ID passed to CxCustom().

The following is an example of a custom CxObject function that swaps the function of the left and right mouse buttons.

<syntaxhighlight>
custom = CxCustom(CxFunction, 0)

/* The custom function for the custom CxObject. Any code for a custom CxObj must be */
/* short and sweet. This code runs as part of the input.device task */
#define CODEMASK (0x00FF & IECODE_LBUTTON & IECODE_RBUTTON)

void CxFunction(register CxMsg *cxm, CxObj *co)
{
uint16 mousequals = 0x0000;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent
* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it.
*/
struct InputEvent *ie = (struct InputEvent *)CxMsgData(cxm);

/* Check to see if this input event is a left or right mouse button */
/* by itself (a mouse button can also be a qualifier). If it is, flip the */
/* low order bit to switch leftbutton <--> rightbutton. */
if (ie->ie_Class == IECLASS_RAWMOUSE)
if ((ie->ie_Code & CODEMASK) == CODEMASK) ie->ie_Code ^= 0x0001;

/* Check the qualifiers. If a mouse button was down when this */
/* input event occurred, set the other mouse button bit. */
if (ie->ie_Qualifier & IEQUALIFIER_RBUTTON) mousequals |= IEQUALIFIER_LEFTBUTTON;
if (ie->ie_Qualifier & IEQUALIFIER_LEFTBUTTON) mousequals |= IEQUALIFIER_RBUTTON;

/* clear the RBUTTON and LEFTBUTTON qualifier bits */
ie->ie_Qualifier &= ~(IEQUALIFIER_LEFTBUTTON | IEQUALIFIER_RBUTTON);

/* set the mouse button qualifier bits to their new values */
ie->ie_Qualifier |= mousequals;
}
</syntaxhighlight>

== Debug CxObjects ==

The final CxObject is the debug CxObject. When a debug CxObject receives a CxMessage, it sends debugging information to the serial port using DebugPrintF().

<syntaxhighlight>
CxObj *debugCxObj = CxDebug(int32 ID);
</syntaxhighlight>

The debug CxObject will DebugPrintF() the following information about itself, the CxMsg, and the corresponding InputEvent structure:

<pre>
DEBUG NODE: 7CB5AB0, ID: 2
CxMsg: 7CA6EF2, type: 0, data 2007CA destination 6F1E07CB
dump IE: 7CA6F1E
Class 1
Code 40
Qualifier 8000
EventAddress 40001802
</pre>

There has to be a terminal connected to the Amiga's serial port to receive this information.

== The IX Structure ==

Commodities Exchange does not use the input event description strings discussed earlier to match input events. Instead, Commodities Exchange converts these strings to its own internal format. These input expressions are available for commodities to use instead of the input description strings. The following is the IX structure as defined in <libraries/commodities.h>:

<syntaxhighlight>
#define IX_VERSION 2

struct InputXpression {
UBYTE ix_Version; /* must be set to IX_VERSION */
UBYTE ix_Class; /* class must match exactly */
UWORD ix_Code;
UWORD ix_CodeMask; /* normally used for UPCODE */
UWORD ix_Qualifier;
UWORD ix_QualMask;
UWORD ix_QualSame; /* synonyms in qualifier */
};

typedef struct InputXpression IX;
</syntaxhighlight>

The ix_Version field contains the current version number of the InputXpression structure. The current version is defined as IX_VERSION. The ix_Class field contains the IECLASS_ constant (defined in <devices/inputevent.h>) of the class of input event sought. Commodities Exchange uses the ix_Code and ix_CodeMask fields to match the ie_Code field of a struct InputEvent. The bits of ix_CodeMask indicate which bits are relevant in the ix_Code field when trying to match against a ie_Code. If any bits in ix_CodeMask are off, Commodities Exchange does not consider the corresponding bit in ie_Code when trying to match input events. This is used primarily to mask out the IECODE_UP_PREFIX bit of rawkey events, making it easier to match both up and down presses of a particular key.

IX's qualifier fields, ix_Qualifier, ix_QualMask, and ix_QualSame, are used to match the ie_Qualifier field of an InputEvent structure. The ix_Qualifier and ix_QualMask fields work just like ix_Code and ix_CodeMask. The bits of ix_QualMask indicate which bits are relevant when comparing ix_Qualifier to ie_Qualifier. The ix_QualSame field tells Commodities Exchange that certain qualifiers are equivalent:

<syntaxhighlight>
#define IXSYM_SHIFT 1 /* left- and right- shift are equivalent */
#define IXSYM_CAPS 2 /* either shift or caps lock are equivalent */
#define IXSYM_ALT 4 /* left- and right- alt are equivalent */
</syntaxhighlight>

For example, the input description string

<pre>
"rawkey -caps -lalt -relativemouse -upstroke ralt tab"
</pre>

matches a tab upstroke or downstroke with the right Alt key pressed whether or not the left Alt, either Shift, or the Caps Lock keys are down. The following IX structure corresponds to that input description string:

<syntaxhighlight>
IX ix = {
IX_VERSION, /* The version */
IECLASS_RAWKEY, /* We're looking for a RAWKEY event */
0x42, /* The key the usa0 keymap maps to a tab*/
0x00FF & (~IECODE_UP_PREFIX), /* We want up and down key presses */
IEQUALIFIER_RALT, /* The right alt key must be down */
0xFFFF & ~(IEQUALIFIER_LALT | IEQUALIFIER_LSHIFT |
IEQUALIFIER_RSHIFT | IEQUALIFIER_CAPSLOCK | IEQUALIFIER_RELATIVEMOUSE),
/* don't care about left alt, shift, capslock, or relativemouse qualifiers */
IXSYM_CAPS /* The shift keys and the capslock key qualifiers are all equivalent */
};
</syntaxhighlight>

The CxFilter() macro only accepts a description string to describe an input event. A commodity can change this filter, however, with the SetFilter() and SetFilterIX() function calls.

<syntaxhighlight>
VOID SetFilter( CxObj *filter, STRPTR descrstring );
VOID SetFilterIX( CxObj *filter, IX *ix );
</syntaxhighlight>

SetFilter() and SetFilterIX() change which input events a filter CxObject diverts. SetFilter() accepts a pointer to an input description string. SetFilterIX() accepts a pointer to an IX input expression. A commodity that uses either of these functions should check the filter's error code with CxObjError() to make sure the change worked.

The function ParseIX() parses an input description string and translates it into an IX input expression.

<syntaxhighlight>
LONG errorcode = ParseIX( STRPTR descrstring, IX *ix );
</syntaxhighlight>

Commodities Exchange uses ParseIX() to convert the description string in CxFilter() to an IX input expression. As was mentioned previously, ParseIX() does not work with certain kinds of input strings.

== Controlling CxMessages ==

A Custom CxObject has the power to directly manipulate the CxMessages that travel around the Commodities network. One way is to directly change values in the corresponding input event. Another way is to redirect (or dispose of) the CxMessages.

<syntaxhighlight>
VOID DivertCxMsg ( CxMsg *cxm, CxObj *headobj, CxObj *retobj );
VOID RouteCxMsg ( CxMsg *cxm, CxObj *co );
VOID DisposeCxMsg( CxMsg *cxm );
</syntaxhighlight>

DivertCxMsg() and RouteCxMsg() dictate where the CxMessage will go next. Conceptually, DivertCxMsg() is analogous to a subroutine in a program; the CxMessage will travel down the personal list of a CxObject (headobj in the prototype) until it gets to the end of that list. It then returns and visits the CxObject that follows the return CxObject (the return CxObject in the prototype above is retobj). RouteCxMsg() is analogous to a goto in a program; it has no CxObject to return to.

DisposeCxMsg() removes a CxMessage from the network and releases its resources. The translate CxObject uses this function to remove a CxMessage.

The example "Divert.c" shows how to use DivertCxMsg() as well as a signal CxObject.

<pre>
;/* divert.c - commodity to monitor user inactivity - compiled with SASC 5.10
LC -b0 -cfist -v -j73 divert.c
Blink FROM LIB:c.o,divert.o TO divert LIBRARY LIB:LC.lib,LIB:Amiga.lib NODEBUG SC SD
quit; */
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>
#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/alib_stdio_protos.h>
#include <clib/commodities_protos.h>
#include <devices/inputevent.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); }
#endif

#define TIMER_CLICKS 100

void main(int, char **);
void ProcessMsg(void);
void CxFunction(CxMsg *, CxObj *);

struct Library *CxBase, *IconBase;
struct MsgPort *broker_mp;
CxObj *broker, *cocustom, *cosignal;

struct NewBroker newbroker =
{
NB_VERSION,
"Divert", /* string to identify this broker */
"Divert",
"show divert",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

struct Task *task;
ULONG cxsigflag, signal, cxobjsignal;

void main(int argc, char **argv)
{
UBYTE **ttypes;
CxMsg *msg;

if (CxBase = OpenLibrary("commodities.library", 37L))
{
/* open the icon.library for support library functions, ArgArrayInit() and ArgArrayDone() */
if (IconBase = OpenLibrary("icon.library", 36L))
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (in the 2.0 version of amiga.lib) */
/* that makes it easy to read arguments from either a CLI or from Workbench's */
/* ToolTypes. Because it uses icon.library, the library has to be open before */
/* before calling this function. ArgArrayDone() cleans up after this function. */
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (in amiga.lib) searches through the array set up by ArgArrayInit() */
/* for a specific ToolType. If it finds one, it returns the numeric value of the */
/* number that followed the ToolType (i.e., CX_PRIORITY=7). If it doesn't find */
/* the ToolType, it returns the default value (the third argument) */
newbroker.nb_Pri = (BYTE)ArgInt(ttypes, "CX_PRIORITY", 0);

if (broker = CxBroker(&newbroker, NULL))
{
/* CxCustom() takes two arguments, a pointer to the custom function */
/* and an ID. Commodities Exchange will assign that ID to any CxMsg */
/* passed to the custom function. */
if (cocustom = CxCustom(CxFunction, 0L))
{
AttachCxObj(broker, cocustom);

/* Allocate a signal bit for the signal CxObj */
if ( (signal = (ULONG)AllocSignal(-1L)) != -1)
{
/* set up the signal mask */
cxobjsignal = 1L << signal;
cxsigflag |= cxobjsignal;

/* CxSignal takes two arguments, a pointer to the task to signal */
/* (normally the commodity) and the number of the signal bit the */
/* commodity acquired to signal with. */
task = FindTask(NULL);
if (cosignal = CxSignal(task, signal))
{
AttachCxObj(cocustom, cosignal);
ActivateCxObj(broker, 1L);
ProcessMsg();
}
FreeSignal(signal);
}
}
/* DeleteCxObjAll() is a commodities.library function that not only deletes */
/* the CxObject pointed to in its argument, but it deletes all of the */
/* CxObjects that are attached to it. */
DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)GetMsg(broker_mp))
ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
ArgArrayDone(); /* this amiga.lib function cleans up after ArgArrayInit() */
CloseLibrary(IconBase);
}
CloseLibrary(CxBase);
}
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
ULONG sigrcvd, msgid;
LONG returnvalue = 1L;

while (returnvalue)
{
sigrcvd = Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)GetMsg(broker_mp))
{
msgid = CxMsgID(msg);
ReplyMsg((struct Message *)msg);

switch(msgid)
{
case CXCMD_DISABLE:
ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
returnvalue = 0L;
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C) returnvalue = 0L;

/* Check to see if the signal CxObj signalled us. */
if (sigrcvd & cxobjsignal) printf("Got Signal\n");
}
}

/* The custom function for the custom CxObject. Any code for a custom CxObj must be short */
/* and sweet because it runs as part of the input.device task. */
void CxFunction(register CxMsg *cxm, CxObj *co)
{
struct InputEvent *ie;
static ULONG time = 0L;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent */
/* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it. */
ie = (struct InputEvent *)CxMsgData(cxm);

/* This custom function counts the number of timer events that go by while no other input */
/* events occur. If it counts more than a certain amount of timer events, it clears the */
/* count and diverts the timer event CxMsg to the custom object's personal */
/* list. If an event besides a timer event passes by, the timer event count is reset. */
if (ie->ie_Class == IECLASS_TIMER)
{
time++;
if (time >= TIMER_CLICKS)
{
time = 0L;
DivertCxMsg(cxm, co, co);
}
}
else
time = 0L;
}
</pre>

== New Input Events ==

The Commodities Library also has functions used to introduce new input events to the input stream.

<syntaxhighlight>
struct InputEvent *InvertString( UBYTE *string, ULONG *keymap );
VOID FreeIEvents( struct InputEvent *ie );
VOID AddIEvents( struct InputEvent *ie );
</syntaxhighlight>

InvertString() is a function that accepts an ASCII string and creates a linked list of input events that translate into the string using the supplied keymap (or the system default if the key map is NULL). The NULL terminated string may contain ANSI character codes, an input description enclosed in angle (<>) brackets, or one of the following backslash escape characters:

{| class="wikitable"
| \r
| Return
|-
| \t
| Tab
|-
| \\
| Backslash
|}

For example:

<pre>
abc<alt f1>\rhi there.
</pre>

FreeIEvents() frees a list of input events allocated by InvertString(). AddIEvents() is a commodities.library function that adds a linked list of input events at the the top of the Commodities network. Each input event in the list is made into an individual CxMessage. Note that if passed a linked list of input events created by InvertString(), the order the events appear in the string will be reversed.

=== Example ===
<syntaxhighlight>
/* PopShell.c - Simple hot key commodity example.
Adapted by xenic from the original source code.

Compile commands: gcc PopShell.c -o popshell -lamiga -Wall

To run the compiled program - Open 2 shell windows. Execute
PopShell in the first shell window with a line like:
PopShell HOTKEY "ctrl alt f"
Activate the second shell window and enter the keyboard shortcut.
A new shell window should open on the Workbench screen.
*/

#include <stdio.h>
#include <signal.h>

#include <libraries/commodities.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>
#include <clib/alib_protos.h>

static CONST_STRPTR version USED = "$VER: PopShell 1.1 (05.11.2015)";
static CONST_STRPTR stackcookie USED = "$STACK: 32768";

#define EVT_HOTKEY 1L

struct Library *CxBase = NULL;
struct CommoditiesIFace *ICommodities = NULL;

struct MsgPort *broker_mp = NULL;
CxObj *broker, *filter;

struct NewBroker newbroker =
{
NB_VERSION,
"Amiga PopShell", /* string to identify this broker */
"A Simple PopShell",
"A simple PopShell commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

CONST_STRPTR newshell = "\rllehswen"; /* "newshell" spelled backwards */
struct InputEvent *ie = NULL;
uint32 cxsigflag;

#define TEMPLATE "HOTKEY/K,CX_PRIORITY/N"
enum
{
ARG_HOTKEY, ARG_PRIORITY, ARG_MAX
};

void ProcessMsg(void);

int main(int argc, char **argv)
{
STRPTR hotkey = NULL;
CxMsg *msg = NULL;
struct RDArgs *argsdata = NULL;
int32 rargs[ARG_MAX] = {0};
int8 priority = 0;

signal(SIGINT, SIG_IGN);

if ((CxBase = IExec->OpenLibrary("commodities.library", 37L)))
{
if ((ICommodities = (struct CommoditiesIFace *)IExec->GetInterface(CxBase, "main", 1, NULL)))
{
if ((argsdata = IDOS->ReadArgs(TEMPLATE, rargs, NULL)))
{
if (rargs[ARG_PRIORITY])
priority = (int8)*(uint32 *)rargs[ARG_PRIORITY];
if ((broker_mp = IExec->AllocSysObject(ASOT_PORT, NULL)))
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;
newbroker.nb_Pri = priority;
hotkey = (STRPTR)rargs[ARG_HOTKEY];

if ((broker = ICommodities->CxBroker(&newbroker, NULL)))
{
/* CxFilter(), CxSender() & CxTranslate() are */
/* macros defined in libraries/commodities.h. */
/* CxFilter() creates a filter CxObject. */
/* CxSender() creates a sender CxObject. */
/* CxTranslate() creates a translation CxObject. */
if ((filter = CxFilter(hotkey)))
{
/* Add a filter CxObject to another's personal list. */
ICommodities->AttachCxObj(broker, filter);

/* Add a sender CxObject to the filter CxObject. */
ICommodities->AttachCxObj(filter, CxSender(broker_mp, EVT_HOTKEY));

/* Add a translation CxObject to the filter CxObject */
ICommodities->AttachCxObj(filter, CxTranslate(NULL));

if (!(ICommodities->CxObjError(filter)))
{
/* InvertString() is an amiga.lib function that creates a linked */
/* list of input events which would translate into the string */
/* passed to it. Note that it puts the input events in the */
/* opposite order in which the corresponding letters appear in */
/* the string. A translate CxObject expects them backwards. */
if ((ie = InvertString(newshell, NULL)))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
/* we have to release the memory allocated by InvertString. */
FreeIEvents(ie);
}
}
}
/* DeleteCxObjAll() is a commodities.library function that */
/* deletes the CxObject pointed to in its argument and */
/* deletes all of the CxObjects attached to it. */
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
IDOS->FreeArgs(argsdata); /* cleans up after ReadArgs() */
}
IExec->DropInterface((struct Interface *)ICommodities);
}
IExec->CloseLibrary(CxBase);
}
return RETURN_OK;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern uint32 cxsigflag;
CxMsg *msg = NULL;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1L;

while (returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY:
/* We got the message from the sender CxObject */
printf("You hit the HotKey.\n");
/* Add the string "newshell" to input * stream. */
/* If a shell gets it, it'll open a new shell. */
ICommodities->AddIEvents(ie);
break;
default:
printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
printf("CXCMD_KILL\n");
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a */
/* commodity with a name already in use but also can notify the */
/* already running commodity that it happened. It does this by */
/* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the */
/* user tries to run a windowless commodity that is already running, */
/* the user wants the commodity to shut down. */
printf("CXCMD_UNIQUE\n");
returnvalue = 0L;
break;
default:
printf("Unknown msgid\n");
break;
}
break;
default:
printf("Unknown msgtype\n");
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0L;
printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Commodities Exchange functions covered in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CxBroker()
| Creates a CxObject of type Broker.
|-
| CxFilter()
| Creates a CxObject of type Filter.
|-
| CxSender()
| Creates a CxObject of type Sender.
|-
| CxTranslate()
| Creates a CxObject of type Translate.
|-
| CxSignal()
| Creates a CxObject of type Signal.
|-
| CxCustom()
| Creates a CxObject of type Custom.
|-
| CxDebug()
| Creates a CxObject of type Debug.
|-
| DeleteCxObj()
| Frees a single CxObject
|-
| DeleteCxObjAll()
| Frees a group of connected CxObjects
|-
| ActivateCxObj()
| Activates a newly created CxObject in the commodities network.
|-
| CxTranslate()
| Sets up substitution of one input event for another by translate CxObjects.
|-
| CxMsgType()
| Finds the type of a CxMessage.
|-
| CxMsgData()
| Returns the CxMessage data.
|-
| CxMsgID()
| Returns the CxMessage ID.
|-
| CxObjError()
| Returns the CxObject's accumulated error field.
|-
| ClearCxObjError()
| Clear the CxObject's accumulated error field.
|-
| AttachCxObj()
| Attaches a CxObject to the end of a given CxObject's list.
|-
| InsertCxObj()
| Inserts a CxObject in a given position in a CxObject's list.
|-
| EnqueueCxObj()
| Inserts a CxObject in a CxObject's list by priority.
|-
| SetCxObjPri()
| Sets a CxObject's priority for EnqueueCxObj().
|-
| RemoveCxObj()
| Removes a CxObject from a list.
|-
| SetFilter()
| Set a filter for a CxObject from an input description string.
|-
| SetFilterIX()
| Set a filter for a CxObject from an IX data structure.
|-
| ParseIX()
| Convert an input description string to an IX data structure.
|-
| DivertCxMsg()
| Divert a CxMessage to one CxObject and return it to another.
|-
| RouteCxMsg()
| Redirect a CxMessage to a new CxObject.
|-
| DisposeCxMsg()
| Cancel a CxMessage removing it from the Commodities network.
|-
| InvertString()
| Creates a linked list of input events that correspond to a given string.
|-
| FreeIEvents()
| Frees the linked list of input events created with InvertString().
|-
| AddIEvents()
| Converts a list of input events to CxMessages and puts them into the network.
|-
| CopyBrokerList()
| Creates a local copy of the current broker list (V53.4).
|-
| FreeBrokerList()
| Frees the local broker list (V53.4).
|-
| BrokerCommand()
| Sends a command to a commodity broker (V53.4).
|}

=== Obsolete Functions ===

The following functions are obsolete and no longer used:

{| class="wikitable"
! Function
! Description
|-
| ArgArrayInit()
| Create a Tool Types array from argc and argv (Workbench or Shell).
|-
| ArgArrayDone()
| Free the resources used by ArgArrayInit().
|-
| ArgString()
| Return the string associated with a given Tool Type in the array.
|-
| ArgInt()
| Return the integer associated with a given Tool Type in the array.
|}

Commodities Exchange Library

2015-12-06T08:50:06Z

Daniel Jedlicka: Replaced the popshell.c example source code by a version adapted for OS4 by xenic.

{{CodeReview}}
== Commodities Exchange Library ==

This article describes Commodities Exchange, the library of routines used to add a custom input handler to the Amiga. With Commodities Exchange, any program function can be associated with key combinations or other input events ''globally'' allowing the creation utility programs that run in the background for all tasks.

== Custom Input Handlers ==

The input.device has a hand in almost all user input on the Amiga. It gathers input events from the keyboard, the gameport (mouse), and several other sources, into one input "stream". Special programs called input event handlers intercept input events along this stream, examining and sometimes changing the input events. Both Intuition and the console device use input handlers to process user input.

[[File:LibFig31-1.png|frame|center|The Amiga Input Stream]]

Using the input.device, a program can introduce its own custom handler into the chain of input handlers at almost any point in the chain. "Hot key" programs, shell pop-up programs, and screen blankers all commonly use custom input handlers to monitor user input before it gets to the Intuition input handler.

[[File:LibFig31-2.png|frame|center|A Custom Input Handler]]

Custom input handlers do have their drawbacks, however. Not only are these handlers hard to program, but because there is no standard way to implement and control them, multiple handlers often do not work well together. Their antisocial behavior can result in load order dependencies and incompatibilities between different custom input handlers. Even for the expert user, having several custom input handlers coexist peacefully can be next to impossible.

[[File:LibFig31-3.png|frame|center|The Commodities Network]]

Commodities Exchange eliminates these problems by providing a simple, standardized way to program and control custom input handlers. It is divided into two parts: an Exec library and a controller program.

The Exec library is called commodities.library. When it is first opened, commodities.library establishes a single input handler just before Intuition in the input chain. When this input handler receives an input event, it creates a CxMessage (Commodities Exchange Message) corresponding to the input event, and diverts the CxMessage through the network of Commodities Exchange input handlers.

These handlers are made up of trees of different CxObjects (Commodities Exchange Objects), each of which performs a simple operation on the CxMessages. Any CxMessages that exit the network are returned to the input.device's input stream as input events.

Through function calls to the commodities.library, an application can install a custom input handler. A Commodities Exchange application, sometimes simply referred to as a commodity, uses the CxObject primitives to do things such as filter certain CxMessages, translate CxMessages, signal a task when a CxObject receives a CxMessage, send a message when a CxObject receives a CxMessage, or if necessary, call a custom function when a CxObject receives a CxMessage.

=== Commodities Control ===

The standard controller program is called Exchange. It is located in the Utilities/Commodities drawer on your system partition. With Exchange, the user can monitor and control all the currently running Commodities Exchange applications from this one program. The user can enable and disable a commodity, kill a commodity, or, if the commodity has a window, ask the commodity to show or hide its window. When the user requests any of these actions, the controller program sends the commodity a message, telling it which action to perform.

Starting with version 53.4 of the commodities.library, functions are available that allow developers to write their own commodity control programs (Exchange replacements). These functions were not public previously.

=== Important Notes ===

* Commodities are special-purpose programs. In fact, most programs or applications are '''not''' suitable for becoming commodities. The Commodities Exchange framework is ideal for programs that need to monitor all user input: hotkey utilities, screen blankers, mouse blankers, etc.
* In the past, some developers turned their programs into commodities only to provide them with a handy keyboard shortcut to bring up/close their GUI. Please note that such practice is actually a misuse of the commodities framework.
* Commodities Exchange should never be used as an alternate method of receiving user input for an application. Other applications depend on getting user input in some form or another from the input stream. A greedy program that diverts input to itself rather than letting the input go to where the user expects it can seriously confuse the user, not to mention compromise the advantages of multitasking.

== CxObjects ==

CxObjects are the basic building blocks used to construct a commodity. A commodity uses CxObjects to take care of all manipulations of CxMessages. When a CxMessage "arrives" at a CxObject, that CxObject carries out its primitive action and then, if it has not deleted the CxMessage, it passes the CxMessage on to the next CxObject. A commodity links together CxObjects into a tree, organizing these simple action objects to perform some higher function.

A CxObject is in one of two states, active or inactive. An active CxObject performs its primitive action every time it receives a CxMessage. If a CxObject is inactive, CxMessages bypass it, continuing to the CxObject that follows the inactive one. By default, all CxObjects except the type called brokers are created in the active state.

Currently, there are seven types of CxObjects:

{| class="wikitable"
|+ Commodities Exchange Object Types
! Object Type
! Purpose
|-
| Broker || Registers a new commodity with the commodity network
|-
| Filter || Accepts or rejects input events based on criteria set up by the application
|-
| Sender || Sends a message to a message port
|-
| Translate || Replaces the input event with a different one
|-
| Signal || Signals a task
|-
| Custom || Calls a custom function provided by the commodity
|-
| Debug || Sends debug information out the serial port
|}

== Installing A Broker Object ==

The Commodities Exchange input handler maintains a master list of CxObjects to which it diverts input events using CxMessages. The CxObjects in this master list are a special type of CxObject called ''brokers''. The only thing a broker CxObject does is divert CxMessages to its own personal list of CxObjects. A commodity creates a broker and attaches other CxObjects to it. These attached objects take care of the actual input handler related work of the commodity and make up the broker's personal list.

The first program listing, "Broker.c", is a very simple example of a working commodity. It serves only to illustrate the basics of a commodity, not to actually perform any useful function. It shows how to set up a broker and process commands from the controller program.

Besides opening commodities.library and creating an Exec message port, setting up a commodity requires creating a broker. The function CxBroker() creates a broker and adds it to the master list.

<syntaxhighlight>
CxObj *CxBroker(struct NewBroker *nb, LONG *error);
</syntaxhighlight>

CxBroker()'s first argument is a pointer to a NewBroker structure:

<syntaxhighlight>
struct NewBroker {
BYTE nb_Version; /* There is an implicit pad byte after this BYTE */
BYTE *nb_Name;
BYTE *nb_Title;
BYTE *nb_Descr;
SHORT nb_Unique;
SHORT nb_Flags;
BYTE nb_Pri; /* There is an implicit pad byte after this BYTE */
struct MsgPort *nb_Port;
WORD nb_ReservedChannel; /* Unused, make zero for future compatibility */
};
</syntaxhighlight>

Commodities Exchange gets all the information it needs about the broker from this structure. NewBroker's nb_Version field contains the version number of the NewBroker structure. This should be set to NB_VERSION which is defined in <libraries/commodities.h>. The nb_Name, nb_Title, and nb_Descr point to strings which hold the name, title, and description of the broker. The two bit fields, nb_Unique and nb_Flags, toggle certain features of Commodities Exchange based on their values. They are discussed in detail later in this article.

The nb_Pri field contains the broker's priority. Commodities Exchange inserts the broker into the master list based on this number. Higher priority brokers get CxMessages before lower priority brokers.

CxBroker()'s second argument is a pointer to a LONG. If this pointer is not NULL, CxBroker() fills in this field with one of the following error return codes from <libraries/commodities.h>:

<syntaxhighlight>
CBERR_OK 0 /* No error */
CBERR_SYSERR 1 /* System error , no memory, etc */
CBERR_DUP 2 /* uniqueness violation */
CBERR_VERSION 3 /* didn't understand nb_VERSION */
</syntaxhighlight>

Once the broker object is created with CxBroker(), it must be activated with ActivateCxObject().

<syntaxhighlight>
LONG oldactivationvalue = ActivateCxObj(CxObj *co, LONG newactivationvalue);
</syntaxhighlight>

After successfully completing the initial set up and activating the broker, a commodity can begin its input processing loop waiting for CxMessages to arrive.

== CxMessages ==

There are actually two types of CxMessages. The first, CXM_IEVENT, corresponds to an input event and travels through the Commodities Exchange network. The other type, CXM_COMMAND, carries a command to a commodity. A CXM_COMMAND normally comes from the controller program and is used to pass user commands on to a commodity. A commodity receives these commands through an Exec message port that the commodity sets up before it calls CxBroker(). The NewBroker's nb_Port field points to this message port. A commodity can tell the difference between the two types of CxMessages by calling the CxMsgType() function.

<syntaxhighlight>
ULONG CxMsgType( CxMsg *cxm );
UBYTE *CxMsgData( CxMsg *cxm );
LONG CxMsgID ( CxMsg *cxm );
</syntaxhighlight>

A CxMessage not only has a type, it can also have a data pointer as well as an ID associated with it. The data associated with a CXM_IEVENT CxMessage is an InputEvent structure. By using the CxMsgData() function, a commodity can obtain a pointer to the corresponding InputEvent of a CXM_IEVENT message. Commodities Exchange gives an ID of zero to any CXM_IEVENT CxMessage that it introduces to the Commodities network but certain CxObjects can assign an ID to them.

For a CXM_COMMAND CxMessages, the data pointer is generally not used but the ID specifies a command passed to the commodity from the user operating the controller program. The CxMsgID() macro extracts the ID from a CxMessage.

=== A Simple Commodity Example ===

The example below, "Broker.c", receives input from one source, the controller program. The controller program sends a CxMessage each time the user clicks its Enable, Disable, or Kill gadgets. Using the CxMsgID() function, the commodity finds out what the command is and executes it.

<syntaxhighlight>
// broker.c - Simple skeletal example of opening a broker

#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities = NULL;

CxObj *broker;
struct MsgPort *broker_mp;
ULONG cxsigflag;

struct NewBroker newbroker = {
NB_VERSION, /* nb_Version - Version of the NewBroker structure */
"Amiga broker", /* nb_Name - Name Commodities uses to identify this commodity */
"Broker", /* nb_Title - Title of commodity that appears in CXExchange */
"A simple example of a broker", /* nb_Descr - Description of the commodity */
0, /* nb_Unique - Tells CX not to launch another commodity with same name */
0, /* nb_Flags - Tells CX if this commodity has a window */
0, /* nb_Pri - This commodity's priority */
0, /* nb_Port - MsgPort CX talks to */
0 /* nb_ReservedChannel - reserved for later use */
};

int main()
{
CxMsg *msg;

struct Library *CxBase = = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);
if (ICommodities != NULL)
{
/* Commodities talks to a Commodities application through */
/* an Exec Message port, which the application provides */
if (broker_mp = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END))
{
newbroker.nb_Port = broker_mp;

/* The commodities.library function CxBroker() adds a borker to the
* master list. It takes two arguments, a pointer to a NewBroker
* structure and a pointer to a LONG. The NewBroker structure contains
* information to set up the broker. If the second argument is not
* NULL, CxBroker will fill it in with an error code.
*/
if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
cxsigflag = 1L << broker_mp->mp_SigBit;

/* After it's set up correctly, the broker has to be activated */
ICommodities->ActivateCxObj(broker, 1L);

/* the main processing loop */
ProcessMsg();

/* It's time to clean up. Start by removing the broker from the
* Commodities master list. The DeleteCxObjAll() function will
* take care of removing a CxObject and all those connected
* to it from the Commodities network
*/
ICommodities->DeleteCxObj(broker);

/* Empty the port of CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
}

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
CxMsg *msg;

uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while (returnvalue)
{
/* wait for something to happen */
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

/* process any messages */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
/* Extract necessary information from the CxMessage and return it */
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
/* Shouldn't get any of these in this example */
break;
case CXM_COMMAND:
/* Commodities has sent a command */
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
/* The user clicked Commodities Exchange disable
* gadget better disable
*/
ICommodities->ActivateCxObj(broker, 0);
break;
case CXCMD_ENABLE:
/* user clicked enable gadget */
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1);
break;
case CXCMD_KILL:
/* user clicked kill gadget, better quit */
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
/* Test to see if user tried to break */
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

Notice that "Broker.c" uses Ctrl-C as a break key. The break key for any commodity should be Ctrl-C.

=== Controller Commands ===

The commands that a commodity can receive from the controller program (as defined in <libraries/commodities.h>) are:

<syntaxhighlight>
CXCMD_DISABLE /* please disable yourself */
CXCMD_ENABLE /* please enable yourself */
CXCMD_KILL /* go away for good */
CXCMD_APPEAR /* open your window, if you can */
CXCMD_DISAPPEAR /* hide your window */
</syntaxhighlight>

The CXCMD_DISABLE, CXCMD_ENABLE, and CXCMD_KILL commands correspond to the similarly named controller program gadgets, Disable, Enable, and Kill; CXCMD_APPEAR and CXCMD_DISAPPEAR correspond to the controller program gadgets, Show and Hide. These gadgets are ghosted in Broker.c because it has no window (It doesn't make much sense to give the user a chance to click the Show and Hide gadgets). In order to do this, Broker.c has to tell Commodities Exchange to ghost these gadgets. When CxBroker() sets up a broker, it looks at the NewBroker.nb_Flags field to see if the COF_SHOW_HIDE bit (from <libraries/commodities.h>) is set. If it is, the "Show" and "Hide" gadgets for this broker will be selectable. Otherwise they are ghosted and disabled.

=== Shutting Down the Commodity ===

Shutting down a commodity is easy. After replying to all CxMessages waiting at the broker's message port, a commodity can delete its CxObjects. The DeleteCxObj() function removes a single CxObject from the Commodities network. DeleteCxObjectAll() removes multiple objects.

<syntaxhighlight>
VOID DeleteCxObj( CxObj *co );
VOID DeleteCxObjAll( CxObj *delete_co );
</syntaxhighlight>

If a commodity has a lot of CxObjects, deleting each individually can be a bit tedious. DeleteCxObjAll() will delete a CxObject and any other CxObjects that are attached to it. The HotKey.c example given later in this article uses this function to delete all its CxObjects. A commodity that uses DeleteCxObjAll() to delete all its CxObjects should make sure that they are all connected to the main one. (See the "Connecting CxObjects" section below.)

After deleting its CxObjects, a commodity must take care of any CxMessages that might have arrived at the message port just before the commodity deleted its objects.

<syntaxhighlight>
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
</syntaxhighlight>

== Commodity Tool Types ==

A goal of Commodities Exchange is to improve user control over input handlers. One way in which it accomplishes this goal is through the use of standard icon Tool Types. The user will expect commodities to recognize the set of standard Tool Types:

* CX_PRIORITY
* CX_POPUP
* CX_POPKEY

CX_PRIORITY lets the user set the priority of a commodity. The string "CX_PRIORITY=" is a number from -128 to 127. The higher the number, the higher the priority of the commodity, giving it access to input events before lower priority commodities. All commodities should recognize CX_PRIORITY.

CX_POPUP and CX_POPKEY are only relevant to commodities with a window. The string "CX_POPUP=" should be followed by a "yes" or "no", telling the commodity if it should or shouldn't show its window when it is first launched. CX_POPKEY is followed by a string describing the key to use as a hot key for making the commodity's window appear (pop up). The description string for CX_POPKEY describes an input event. The specific format of the string is discussed in the next section ("Filter Objects and the Input Description String").

=== Obsolete Parsing Functions ===

Prior to AmigaOS 4.0, the Commodities Library had the following support functions which were included in an external link library:

<syntaxhighlight>
UBYTE **ArgArrayInit(LONG argc, UBYTE **argv);
VOID ArgArrayDone(void);
STRPTR ArgString(UBYTE **tooltypearray, STRPTR tooltype, STRPTR defaultvalue);
LONG *ArgInt(UBYTE **tooltypearray, STRPTR tooltype, LONG defaultvalue);
</syntaxhighlight>

These functions are no longer available. Use IDOS->ReadArgs(), IIcon->FindToolType() and IIcon->MatchToolValue() instead, depending on whether the commodity was launched from Workbench or the Shell (CLI).

== Filter Objects and Input Description Strings ==

Because not all commodities are interested in every input event that makes it way down the input chain, Commodities Exchange has a method for filtering them. A filter CxObject compares the CxMessages it receives to a pattern. If a CxMessage matches the pattern, the filter diverts the CxMessage down its personal list of CxObjects.

<syntaxhighlight>
CxObj *CxFilter(STRPTR descriptionstring);
</syntaxhighlight>

The C macro CxFilter() (defined in <libraries/commodities.h>) returns a pointer to a filter CxObject. The macro has only one argument, a pointer to a string describing which input events to filter. The following regular expression outlines the format of the input event description string (CX_POPKEY uses the same description string format):

<pre>
[class] { [-] (qualifier | synonym) ) } [ [-] upstroke] [highmap | ANSICode]
</pre>

''Class'' can be any one of the class strings in the table below. Each class string corresponds to a class of input event as defined in <devices/inputevent.h>. Commodities Exchange will assume the class is rawkey if the class is not explicitly stated.

{| class="wikitable"
! Class String
! Input Event Class
|-
| "rawkey" || IECLASS_RAWKEY
|-
| "rawmouse" || IECLASS_RAWMOUSE
|-
| "event" || IECLASS_EVENT
|-
| "pointerpos" || IECLASS_POINTERPOS
|-
| "timer" || IECLASS_TIMER
|-
| "newprefs" || IECLASS_NEWPREFS
|-
| "diskremoved" || IECLASS_DISKREMOVED
|-
| "diskinserted" || IECLASS_DISKINSERTED
|}

''Qualifier'' is one of the qualifier strings from the table below. Each string corresponds to an input event qualifier as defined in <devices/inputevent.h>). A dash preceding the qualifier string tells the filter object not to care if that qualifier is present in the input event. Notice that there can be more than one qualifier (or none at all) in the input description string.

{| class="wikitable"
! Qualifier String
! Input Event Class
|-
| "lshift" || IEQUALIFIER_LSHIFT
|-
| "rshift" || IEQUALIFIER_RSHIFT
|-
| "capslock" || IEQUALIFIER_CAPSLOCK
|-
| "control" || IEQUALIFIER_CONTROL
|-
| "lalt" || IEQUALIFIER_LALT
|-
| "ralt" || IEQUALIFIER_RALT
|-
| "lcommand" || IEQUALIFIER_LCOMMAND
|-
| "rcommand" || IEQUALIFIER_RCOMMAND
|-
| "numericpad" || IEQUALIFIER_NUMERICPAD
|-
| "repeat" || IEQUALIFIER_REPEAT
|-
| "midbutton" || IEQUALIFIER_MIDBUTTON
|-
| "rbutton" || IEQUALIFIER_RBUTTON
|-
| "leftbutton" || IEQUALIFIER_LEFTBUTTON
|-
| "relativemouse" || IEQUALIFIER_RELATIVEMOUSE
|}

''Synonym'' is one of the synonym strings from the table below. These strings act as synonyms for groups of qualifiers. Each string corresponds to a synonym identifier as defined in <libraries/commodities.h>. A dash preceding the synonym string tells the filter object not to care if that synonym is present in the input event. Notice that there can be more than one synonym (or none at all) in the input description string.

{| class="wikitable"
! Synonym String
! Synonym Identifier
! Description
|-
| "shift" || IXSYM_SHIFT || Look for either Shift key
|-
| "caps" || IXSYM_CAPS || Look for either Shift key or Caps Lock
|-
| "alt" || IXSYM_ALT || Look for either Alt key
|}

''Upstroke'' is the literal string "upstroke". If this string is absent, the filter considers only downstrokes. If it is present alone, the filter considers only upstrokes. If preceded by a dash, the filter considers both upstrokes and downstrokes.

''Highmap'' is one of the following strings:

"backspace", "del", "down", "enter", "esc", "f1", "f2",
"f3", "f4", "f5", "f6", "f7", "f8", "f9", "f10",
"f11, "f12", "help", "left", "return", "right", "space", "tab", "up".

''ANSICode'' is a single character (for example "a" that Commodities Exchange looks up in the system default keymap.

Here are some example description strings. For function key F2 with the left Shift and either Alt key pressed, the input description string would be:

<pre>
"rawkey lshift alt f2"
</pre>

To specify the key that produces an "a" (this may or may not be the A key depending on the keymap), with or without any Shift, Alt, or Control keys pressed use:

<pre>
"-shift -alt -control a"
</pre>

For a mouse move with the right mouse button down, use:

<pre>
"rawmouse rbutton"
</pre>

To specify a timer event use:

<pre>
"timer"
</pre>

== Connecting CxObjects ==

A CxObject has to be inserted into the Commodities network before it can process any CxMessages. AttachCxObj() adds a CxObject to the personal list of another CxObject. The HotKey.c example uses it to attach its filter to a broker.

<syntaxhighlight>
VOID AttachCxObj ( CxObj *headobj, CxObj *co);
VOID InsertCxObj ( CxObj *headobj, CxObj *co, CxObj *co_pred );
VOID EnqueueCxObj( CxObj *headobj, CxObj *co );
VOID SetCxObjPri ( CxObj *co, LONG pri );
VOID RemoveCxObj ( CxObj *co );
</syntaxhighlight>

AttachCxObj() adds the CxObject to the end of headobj's personal list. The ordering of a CxObject list determines which object gets CxMessages first. InsertCxObj() also inserts a CxObject, but it inserts it after another CxObject already in the personal list (co_pred in the prototype above).

Brokers aren't the only CxObjects with a priority. All CxObjects have a priority associated with them. To change the priority of any CxObject, use the SetCxObjPri() function. A commodity can use the priority to keep CxObjects in a personal list sorted by their priority. The commodities.library function EnqueueCxObj() inserts a CxObject into another CxObject's personal list based on priority.

Like its name implies, the RemoveCxObj() function removes a CxObject from a personal list. Note that it is not necessary to remove a CxObject from a list in order to delete it.

<syntaxhighlight>
/* HotKey.c - Simple hot key commodity
*/
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>

#include <proto/exec.h>
#include <proto/commodities.h>
#include <proto/icon.h>

#define EVT_HOTKEY 1L

void ProcessMsg(void);

struct CommoditiesIFace *ICommodities;
struct IconIFace *IIcon;

struct MsgPort *broker_mp;
CxObj *broker, *filter, *sender, *translate;

struct NewBroker newbroker = {
NB_VERSION,
"Amiga HotKey", /* string to identify this broker */
"A Simple HotKey",
"A simple hot key commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

uint32 cxsigflag;

int main(int argc, char **argv)
{
uint8 *hotkey, **ttypes;
CxMsg *msg;

struct Library *CxBase = IExec->OpenLibrary("commodities.library", 50);
ICommodities = (struct CommoditiesIFace*)IExec->GetInterface(CxBase, "main", 1, NULL);

/* open the icon.library for the support library */
/* functions, ArgArrayInit() and ArgArrayDone() */
struct Library *IconBase = IExec->OpenLibrary("icon.library", 50);
struct IconIFace *IIcon = (struct IconIFace*)IExec->GetInterface(IconBase, "main", 1, NULL);

if (ICommodities != NULL && IIcon != NULL)
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (from the 2.0 version
* of amiga.lib) that makes it easy to read arguments from either a
* CLI or from Workbench's ToolTypes. Because it uses icon.library,
* the library has to be open before calling this function.
* ArgArrayDone() cleans up after this function.
*/
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (also from amiga.lib) searches through the array set up
* by ArgArrayInit() for a specific ToolType. If it finds one, it
* returns the numeric value of the number that followed the
* ToolType (i.e., CX_PRIORITY=7). If it doesn't find the ToolType,
* it returns the default value (the third argument)
*/
newbroker.nb_Pri = (int8)ArgInt(ttypes, "CX_PRIORITY", 0);

/* ArgString() works just like ArgInt(), except it returns a pointer to a string
* rather than an integer. In the example below, if there is no ToolType
* "HOTKEY", the function returns a pointer to "rawkey control esc".
*/
hotkey = ArgString(ttypes, "HOTKEY", "rawkey control esc");

if (broker = ICommodities->CxBroker(&newbroker, NULL))
{
/* CxFilter() is a macro that creates a filter CxObject. This filter
* passes input events that match the string pointed to by hotkey.
*/
if (filter = ICommodities->CxFilter(hotkey))
{
/* Add a CxObject to another's personal list */
ICommodities->AttachCxObj(broker, filter);

/* CxSender() creates a sender CxObject. Every time a sender gets
* a CxMessage, it sends a new CxMessage to the port pointed to in
* the first argument. CxSender()'s second argument will be the ID
* of any CxMessages the sender sends to the port. The data pointer
* associated with the CxMessage will point to a *COPY* of the
* InputEvent structure associated with the orginal CxMessage.
*/
if (sender = CxSender(broker_mp, EVT_HOTKEY))
{
ICommodities->AttachCxObj(filter, sender);

/* CxTranslate() creates a translate CxObject. When a translate
* CxObject gets a CxMessage, it deletes the original CxMessage
* and adds a new input event to the input.device's input stream
* after the Commodities input handler. CxTranslate's argument
* points to an InputEvent structure from which to create the new
* input event. In this example, the pointer is NULL, meaning no
* new event should be introduced, which causes any event that
* reaches this object to disappear from the input stream.
*/
if (translate = ICommodities->CxTranslate(NULL))
{
ICommodities->AttachCxObj(filter, translate);

/* CxObjError() is a commodities.library function that returns
* the internal accumulated error code of a CxObject.
*/
if (! CxObjError(filter))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
}
}
}
}
/* DeleteCxObjAll() is a commodities.library function that not only
* deletes the CxObject pointed to in its argument, but it deletes
* all of the CxObjects that are attached to it.
*/
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
IExec->ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
/* this amiga.lib function cleans up after ArgArrayInit() */
ArgArrayDone();
}

IExec->DropInterface((struct Interface*)IIcon);
IExec->CloseLibrary(IconBase);

IExec->DropInterface((struct Interface*)ICommodities);
IExec->CloseLibrary(CxBase);

return 0;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
uint32 sigrcvd, msgid, msgtype;
int32 returnvalue = 1;

while(returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)IExec->GetMsg(broker_mp))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
IDOS->Printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY: /* We got the message from the sender CxObject */
IDOS->Printf("You hit the HotKey.\n");
break;
default:
IDOS->Printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
IDOS->Printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
IDOS->Printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
IDOS->Printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
IDOS->Printf("CXCMD_KILL\n");
returnvalue = 0;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a
* commodity with a name already in use but also can notify the
* already running commodity that it happened. It does this by
* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the
* user tries to run a windowless commodity that is already running,
* the user wants the commodity to shut down. */
IDOS->Printf("CXCMD_UNIQUE\n");
returnvalue = 0;
break;
default:
IDOS->Printf("Unknown msgid\n");
break;
}
break;
default:
IDOS->Printf("Unknown msgtype\n");
break;
}
}
if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0;
IDOS->Printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Sender CxObjects ==

A filter CxObject by itself is not especially useful. It needs some other CxObjects attached to it. A commodity interested in knowing if a specific key was pressed uses a filter to detect and divert the corresponding CxMessage down the filter's personal list. The filter does this without letting the commodity know what happened. The sender CxObject can be attached to a filter to notify a commodity that it received a CxMessage. CxSender() is a macro that creates a sender CxObject.

<syntaxhighlight>
senderCxObj = CxObj *CxSender(struct MsgPort *senderport, LONG cxmID);
</syntaxhighlight>

CxSender() supplies the sender with an Exec message port and an ID. For every CxMessage a sender receives, it sends a new CxMessage to the Exec message port passed in CxSender(). Normally, the commodity creates this port. It is not unusual for a commodity's broker and sender(s) to share an Exec message port. The HotKey.c example does this to avoid creating unnecessary message ports. A sender uses the ID (cxmID) passed to CxSender() as the ID for all the CxMessages that the it transmits. A commodity uses the ID to monitor CxMessages from several senders at a single message port.

A sender does several things when it receives a CxMessage. First, it duplicates the CxMessage's corresponding input event and creates a new CxMessage. Then, it points the new CxMessage's data field to the copy of the input event and sets the new CxMessage's ID to the ID passed to CxSender(). Finally, it sends the new CxMessage to the port passed to CxSender(), asynchronously.

Because HotKey uses only one message port between its broker and sender object, it has to extract the CxMessage's type so it can tell if it is a CXM_IEVENT or a CXM_COMMAND. If HotKey gets a CXM_IEVENT, it compares the CxMessage's ID to the sender's ID, EVT_HOTKEY, to see which sender sent the CxMessage. Of course HotKey has only one sender, so it only checks for only one ID. If it had more senders, HotKey would check for the ID of each of the other senders as well.

Although HotKey doesn't use it, a CXM_IEVENT CxMessage contains a pointer to the copy of an input event. A commodity can extract this pointer (using CxMsgData()) if it needs to examine the input event copy. This pointer is only valid before the CxMessage reply. Note that it does not make any sense to modify the input event copy.

Senders are attached almost exclusively to CxObjects that filter out most input events (usually a filter CxObject). Because a sender sends a CxMessage for every single input event it gets, it should only get a select few input events. The AttachCxObj() function can add a CxObject to the end of a filter's (or some other filtering CxObject's) personal list. A commodity should not attach a CxObject to a sender as a sender ignores any CxObjects in its personal list.

== Translate CxObjects ==

Normally, after a commodity processes a hot key input event, it needs to eliminate that input event. Other commodities may need to replace an input event with a different one. The translate CxObject can be used for these purposes.

<syntaxhighlight>
translateCxObj = CxObj *CxTranslate(struct InputEvent *newinputevent);
</syntaxhighlight>

The macro CxTranslate() creates a new translate CxObject. CxTranslate()'s only argument is a pointer to a chain of one or more InputEvent structures.

When a translate CxObject receives a CxMessage, it eliminates the CxMessage and its corresponding input event from the system. The translator introduces a new input event, which Commodities Exchange copies from the InputEvent structure passed to CxTranslate() (newinputevent from the function prototype above), in place of the deleted input event.

A translator is normally attached to some kind of filtering CxObject. If it wasn't, it would translate all input events into the same exact input event. Like the sender CxObject, a translator does not divert CxMessages down its personal list, so it doesn't serve any purpose to add any to it.

<syntaxhighlight>
VOID SetTranslate( CxObj *translator, struct InputEvent *ie );
</syntaxhighlight>

It is possible to change the InputEvent structure that a translator looks at when it creates and introduces new input events into the input stream. The function SetTranslate() accepts a pointer to the new InputEvent structure, which the translator will duplicate and introduce when it receives a CxMessage.

HotKey utilizes a special kind of translator. Instead of supplying a new input event, HotKey passes a NULL to CxTranslate(). If a translator has a NULL new input event pointer, it does not introduce a new input event, but still eliminates any CxMessages and corresponding input events it receives.

== CxObject Errors ==

A Commodities Exchange function that acts on a CxObject records errors in the CxObject's accumulated error field. The function CxObjError() returns a CxObject's error field.

<syntaxhighlight>
int32 co_errorfield = CxObjError( CxObj *co );
</syntaxhighlight>

Each bit in the error field corresponds to a specific type of error. The following is a list of the currently defined CxObject errors and their corresponding bit mask constants.

{| class="wikitable"
! Error Constant
! Meaning
|-
| COERR_ISNULL
| CxObjError() was passed a NULL.
|-
| COERR_NULLATTACH
| Someone tried to attach a NULL CxObject to this CxObject.
|-
| COERR_BADFILTER
| This filter CxObject currently has an invalid filter description.
|-
| COERR_BADTYPE
| Someone tried to perform a type specific function on the wrong type of CxObject (for example calling SetFilter() on a sender CxObject).
|}

The remaining bits are reserved for future use. HotKey.c checks the error field of its filter CxObject to make sure the filter is valid. HotKey.c does not need to check the other objects with CxObjError() because it already makes sure that these other objects are not NULL, which is the only other kind of error the other objects can cause in this situation.

Commodities Exchange has a function that clears a CxObject's accumulated error field, ClearCxObjError().

<syntaxhighlight>
VOID ClearCxObjError( CxObj *co );
</syntaxhighlight>

A commodity should be careful about using this, especially on a filter. If a commodity clears a filter's error field and the COERR_BADFILTER bit is set, Commodities Exchange will think that the filter is OK and start sending messages through it.

== Uniqueness ==

When a commodity opens its broker, it can ask Commodities Exchange not to launch another broker with the same name (nb_Name). The purpose of the uniqueness feature is to prevent the user from starting duplicate commodities. If a commodity asks, Commodities Exchange will not only refuse to create a new, similarly named broker, but it will also notify the original commodity if someone tries to do so.

A commodity tells Commodities Exchange not to allow duplicates by setting certain bits in the nb_Unique field of the NewBroker structure it sends to CxBroker():

{| class="wikitable"
| NBU_UNIQUE
| bit 0
|-
| NBU_NOTIFY
| bit 1
|}

Setting the NBU_UNIQUE bit prevents duplicate commodities. Setting the NBU_NOTIFY bit tells Commodities Exchange to notify a commodity if an attempt was made to launch a duplicate. Such a commodity will receive a CXM_COMMAND CxMessage with an ID of CXCMD_UNIQUE when someone tries to duplicate it. Because the uniqueness feature uses the name a programmer gives a commodity to differentiate it from other commodities, it is possible for completely different commodities to share the same name, preventing the two from coexisting. For this reason, a commodity should not use a name that is likely to be in use by other commodities (like "filter" or "hotkey"). Instead, use a name that matches the commodity name.

When "HotKey.c" gets a CXCMD_UNIQUE CxMessage, it shuts itself down. "HotKey.c" and all the windowless commodities that come with Workbench shut themselves down when they get a CXCMD_UNIQUE CxMessage. Because the user will expect all windowless commodities to work this way, all windowless commodities should follow this standard.

When the user tries to launch a duplicate of a system commodity that has a window, the system commodity moves its window to the front of the display, as if the user had clicked the "Show" gadget in the controller program's window. A windowed commodity should mimic conventions set by existing windowed system commodities, and move its window to the front of the display.

== Signal CxObjects ==

A commodity can use a sender CxObject to find out if a CxMessage has "visited" a CxObject, but this method unnecessarily uses system resources. A commodity that is only interested in knowing if such a visitation took place does not need to see a corresponding input event or a CxMessage ID. Instead, Commodities Exchange has a CxObject that uses an Exec signal.

<syntaxhighlight>
CxObj *signalCxObj = CxSignal(struct Task *, LONG cx_signal);
</syntaxhighlight>

CxSignal() sets up a signal CxObject. When a signal CxObject receives a CxMessage, it signals a task. The commodity is responsible for determining the proper task ID and allocating the signal. Normally, a commodity wants to be signaled so it uses FindTask(NULL) to find it's own task address. Note that cx_signal from the above prototype is the signal number as returned by AllocSignal(), not the signal mask made from that number. For more information on signals, see [[Exec_Signals|Exec Signals]].

The example "Divert.c" (shown a little later) uses a signal CxObject.

== Custom CxObjects ==

Although the CxObjects mentioned so far take care of most of the input event handling a commodity needs to do, they cannot do it all. This is why Commodities Exchange has a custom CxObject. When a custom CxObject receives a CxMessage, it calls a function provided by the commodity.

<syntaxhighlight>
CxObject *customCxObj = CxCustom(int32 *customfunction(), int32 cxmID);
</syntaxhighlight>

A custom CxObject is the only means by which a commodity can directly modify input events as they pass through the Commodities network as CxMessages. For this reason, it is probably the most dangerous of the CxObjects to use.

{{Note|title=A Warning About Custom CxObjects|text=Unlike the rest of the code a commodities programmer writes, the code passed to a custom CxObject runs as part of the input.device task, putting severe restrictions on the function. No DOS or Intuition functions can be called. No assumptions can be made about the values of registers upon entry. Any function passed to CxCustom() should be very quick and very simple, with a minimum of stack usage.}}

Commodities Exchange calls a custom CxObject's function as follows:

<syntaxhighlight>
VOID customfunction(CxMsg *cxm, CxObj *customcxobj);
</syntaxhighlight>

where cxm is a pointer to a CxMessage corresponding to a real input event, and customcxobj is a pointer to the custom CxObject. The custom function can extract the pointer to the input event by calling CxMsgData(). Before passing the CxMessage to the custom function, Commodities Exchange sets the CxMessage's ID to the ID passed to CxCustom().

The following is an example of a custom CxObject function that swaps the function of the left and right mouse buttons.

<syntaxhighlight>
custom = CxCustom(CxFunction, 0)

/* The custom function for the custom CxObject. Any code for a custom CxObj must be */
/* short and sweet. This code runs as part of the input.device task */
#define CODEMASK (0x00FF & IECODE_LBUTTON & IECODE_RBUTTON)

void CxFunction(register CxMsg *cxm, CxObj *co)
{
uint16 mousequals = 0x0000;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent
* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it.
*/
struct InputEvent *ie = (struct InputEvent *)CxMsgData(cxm);

/* Check to see if this input event is a left or right mouse button */
/* by itself (a mouse button can also be a qualifier). If it is, flip the */
/* low order bit to switch leftbutton <--> rightbutton. */
if (ie->ie_Class == IECLASS_RAWMOUSE)
if ((ie->ie_Code & CODEMASK) == CODEMASK) ie->ie_Code ^= 0x0001;

/* Check the qualifiers. If a mouse button was down when this */
/* input event occurred, set the other mouse button bit. */
if (ie->ie_Qualifier & IEQUALIFIER_RBUTTON) mousequals |= IEQUALIFIER_LEFTBUTTON;
if (ie->ie_Qualifier & IEQUALIFIER_LEFTBUTTON) mousequals |= IEQUALIFIER_RBUTTON;

/* clear the RBUTTON and LEFTBUTTON qualifier bits */
ie->ie_Qualifier &= ~(IEQUALIFIER_LEFTBUTTON | IEQUALIFIER_RBUTTON);

/* set the mouse button qualifier bits to their new values */
ie->ie_Qualifier |= mousequals;
}
</syntaxhighlight>

== Debug CxObjects ==

The final CxObject is the debug CxObject. When a debug CxObject receives a CxMessage, it sends debugging information to the serial port using DebugPrintF().

<syntaxhighlight>
CxObj *debugCxObj = CxDebug(int32 ID);
</syntaxhighlight>

The debug CxObject will DebugPrintF() the following information about itself, the CxMsg, and the corresponding InputEvent structure:

<pre>
DEBUG NODE: 7CB5AB0, ID: 2
CxMsg: 7CA6EF2, type: 0, data 2007CA destination 6F1E07CB
dump IE: 7CA6F1E
Class 1
Code 40
Qualifier 8000
EventAddress 40001802
</pre>

There has to be a terminal connected to the Amiga's serial port to receive this information.

== The IX Structure ==

Commodities Exchange does not use the input event description strings discussed earlier to match input events. Instead, Commodities Exchange converts these strings to its own internal format. These input expressions are available for commodities to use instead of the input description strings. The following is the IX structure as defined in <libraries/commodities.h>:

<syntaxhighlight>
#define IX_VERSION 2

struct InputXpression {
UBYTE ix_Version; /* must be set to IX_VERSION */
UBYTE ix_Class; /* class must match exactly */
UWORD ix_Code;
UWORD ix_CodeMask; /* normally used for UPCODE */
UWORD ix_Qualifier;
UWORD ix_QualMask;
UWORD ix_QualSame; /* synonyms in qualifier */
};

typedef struct InputXpression IX;
</syntaxhighlight>

The ix_Version field contains the current version number of the InputXpression structure. The current version is defined as IX_VERSION. The ix_Class field contains the IECLASS_ constant (defined in <devices/inputevent.h>) of the class of input event sought. Commodities Exchange uses the ix_Code and ix_CodeMask fields to match the ie_Code field of a struct InputEvent. The bits of ix_CodeMask indicate which bits are relevant in the ix_Code field when trying to match against a ie_Code. If any bits in ix_CodeMask are off, Commodities Exchange does not consider the corresponding bit in ie_Code when trying to match input events. This is used primarily to mask out the IECODE_UP_PREFIX bit of rawkey events, making it easier to match both up and down presses of a particular key.

IX's qualifier fields, ix_Qualifier, ix_QualMask, and ix_QualSame, are used to match the ie_Qualifier field of an InputEvent structure. The ix_Qualifier and ix_QualMask fields work just like ix_Code and ix_CodeMask. The bits of ix_QualMask indicate which bits are relevant when comparing ix_Qualifier to ie_Qualifier. The ix_QualSame field tells Commodities Exchange that certain qualifiers are equivalent:

<syntaxhighlight>
#define IXSYM_SHIFT 1 /* left- and right- shift are equivalent */
#define IXSYM_CAPS 2 /* either shift or caps lock are equivalent */
#define IXSYM_ALT 4 /* left- and right- alt are equivalent */
</syntaxhighlight>

For example, the input description string

<pre>
"rawkey -caps -lalt -relativemouse -upstroke ralt tab"
</pre>

matches a tab upstroke or downstroke with the right Alt key pressed whether or not the left Alt, either Shift, or the Caps Lock keys are down. The following IX structure corresponds to that input description string:

<syntaxhighlight>
IX ix = {
IX_VERSION, /* The version */
IECLASS_RAWKEY, /* We're looking for a RAWKEY event */
0x42, /* The key the usa0 keymap maps to a tab*/
0x00FF & (~IECODE_UP_PREFIX), /* We want up and down key presses */
IEQUALIFIER_RALT, /* The right alt key must be down */
0xFFFF & ~(IEQUALIFIER_LALT | IEQUALIFIER_LSHIFT |
IEQUALIFIER_RSHIFT | IEQUALIFIER_CAPSLOCK | IEQUALIFIER_RELATIVEMOUSE),
/* don't care about left alt, shift, capslock, or relativemouse qualifiers */
IXSYM_CAPS /* The shift keys and the capslock key qualifiers are all equivalent */
};
</syntaxhighlight>

The CxFilter() macro only accepts a description string to describe an input event. A commodity can change this filter, however, with the SetFilter() and SetFilterIX() function calls.

<syntaxhighlight>
VOID SetFilter( CxObj *filter, STRPTR descrstring );
VOID SetFilterIX( CxObj *filter, IX *ix );
</syntaxhighlight>

SetFilter() and SetFilterIX() change which input events a filter CxObject diverts. SetFilter() accepts a pointer to an input description string. SetFilterIX() accepts a pointer to an IX input expression. A commodity that uses either of these functions should check the filter's error code with CxObjError() to make sure the change worked.

The function ParseIX() parses an input description string and translates it into an IX input expression.

<syntaxhighlight>
LONG errorcode = ParseIX( STRPTR descrstring, IX *ix );
</syntaxhighlight>

Commodities Exchange uses ParseIX() to convert the description string in CxFilter() to an IX input expression. As was mentioned previously, ParseIX() does not work with certain kinds of input strings.

== Controlling CxMessages ==

A Custom CxObject has the power to directly manipulate the CxMessages that travel around the Commodities network. One way is to directly change values in the corresponding input event. Another way is to redirect (or dispose of) the CxMessages.

<syntaxhighlight>
VOID DivertCxMsg ( CxMsg *cxm, CxObj *headobj, CxObj *retobj );
VOID RouteCxMsg ( CxMsg *cxm, CxObj *co );
VOID DisposeCxMsg( CxMsg *cxm );
</syntaxhighlight>

DivertCxMsg() and RouteCxMsg() dictate where the CxMessage will go next. Conceptually, DivertCxMsg() is analogous to a subroutine in a program; the CxMessage will travel down the personal list of a CxObject (headobj in the prototype) until it gets to the end of that list. It then returns and visits the CxObject that follows the return CxObject (the return CxObject in the prototype above is retobj). RouteCxMsg() is analogous to a goto in a program; it has no CxObject to return to.

DisposeCxMsg() removes a CxMessage from the network and releases its resources. The translate CxObject uses this function to remove a CxMessage.

The example "Divert.c" shows how to use DivertCxMsg() as well as a signal CxObject.

<pre>
;/* divert.c - commodity to monitor user inactivity - compiled with SASC 5.10
LC -b0 -cfist -v -j73 divert.c
Blink FROM LIB:c.o,divert.o TO divert LIBRARY LIB:LC.lib,LIB:Amiga.lib NODEBUG SC SD
quit; */
#include <exec/libraries.h>
#include <libraries/commodities.h>
#include <dos/dos.h>
#include <clib/exec_protos.h>
#include <clib/alib_protos.h>
#include <clib/alib_stdio_protos.h>
#include <clib/commodities_protos.h>
#include <devices/inputevent.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable Lattice CTRL/C handling */
int chkabort(void) { return(0); }
#endif

#define TIMER_CLICKS 100

void main(int, char **);
void ProcessMsg(void);
void CxFunction(CxMsg *, CxObj *);

struct Library *CxBase, *IconBase;
struct MsgPort *broker_mp;
CxObj *broker, *cocustom, *cosignal;

struct NewBroker newbroker =
{
NB_VERSION,
"Divert", /* string to identify this broker */
"Divert",
"show divert",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

struct Task *task;
ULONG cxsigflag, signal, cxobjsignal;

void main(int argc, char **argv)
{
UBYTE **ttypes;
CxMsg *msg;

if (CxBase = OpenLibrary("commodities.library", 37L))
{
/* open the icon.library for support library functions, ArgArrayInit() and ArgArrayDone() */
if (IconBase = OpenLibrary("icon.library", 36L))
{
if (broker_mp = CreateMsgPort())
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;

/* ArgArrayInit() is a support library function (in the 2.0 version of amiga.lib) */
/* that makes it easy to read arguments from either a CLI or from Workbench's */
/* ToolTypes. Because it uses icon.library, the library has to be open before */
/* before calling this function. ArgArrayDone() cleans up after this function. */
ttypes = ArgArrayInit(argc, argv);

/* ArgInt() (in amiga.lib) searches through the array set up by ArgArrayInit() */
/* for a specific ToolType. If it finds one, it returns the numeric value of the */
/* number that followed the ToolType (i.e., CX_PRIORITY=7). If it doesn't find */
/* the ToolType, it returns the default value (the third argument) */
newbroker.nb_Pri = (BYTE)ArgInt(ttypes, "CX_PRIORITY", 0);

if (broker = CxBroker(&newbroker, NULL))
{
/* CxCustom() takes two arguments, a pointer to the custom function */
/* and an ID. Commodities Exchange will assign that ID to any CxMsg */
/* passed to the custom function. */
if (cocustom = CxCustom(CxFunction, 0L))
{
AttachCxObj(broker, cocustom);

/* Allocate a signal bit for the signal CxObj */
if ( (signal = (ULONG)AllocSignal(-1L)) != -1)
{
/* set up the signal mask */
cxobjsignal = 1L << signal;
cxsigflag |= cxobjsignal;

/* CxSignal takes two arguments, a pointer to the task to signal */
/* (normally the commodity) and the number of the signal bit the */
/* commodity acquired to signal with. */
task = FindTask(NULL);
if (cosignal = CxSignal(task, signal))
{
AttachCxObj(cocustom, cosignal);
ActivateCxObj(broker, 1L);
ProcessMsg();
}
FreeSignal(signal);
}
}
/* DeleteCxObjAll() is a commodities.library function that not only deletes */
/* the CxObject pointed to in its argument, but it deletes all of the */
/* CxObjects that are attached to it. */
DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while(msg = (CxMsg *)GetMsg(broker_mp))
ReplyMsg((struct Message *)msg);
}
DeletePort(broker_mp);
}
ArgArrayDone(); /* this amiga.lib function cleans up after ArgArrayInit() */
CloseLibrary(IconBase);
}
CloseLibrary(CxBase);
}
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg;
ULONG sigrcvd, msgid;
LONG returnvalue = 1L;

while (returnvalue)
{
sigrcvd = Wait(SIGBREAKF_CTRL_C | cxsigflag);

while(msg = (CxMsg *)GetMsg(broker_mp))
{
msgid = CxMsgID(msg);
ReplyMsg((struct Message *)msg);

switch(msgid)
{
case CXCMD_DISABLE:
ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
returnvalue = 0L;
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C) returnvalue = 0L;

/* Check to see if the signal CxObj signalled us. */
if (sigrcvd & cxobjsignal) printf("Got Signal\n");
}
}

/* The custom function for the custom CxObject. Any code for a custom CxObj must be short */
/* and sweet because it runs as part of the input.device task. */
void CxFunction(register CxMsg *cxm, CxObj *co)
{
struct InputEvent *ie;
static ULONG time = 0L;

/* Get the struct InputEvent associated with this CxMsg. Unlike the InputEvent */
/* extracted from a CxSender's CxMsg, this is a *REAL* input event, be careful with it. */
ie = (struct InputEvent *)CxMsgData(cxm);

/* This custom function counts the number of timer events that go by while no other input */
/* events occur. If it counts more than a certain amount of timer events, it clears the */
/* count and diverts the timer event CxMsg to the custom object's personal */
/* list. If an event besides a timer event passes by, the timer event count is reset. */
if (ie->ie_Class == IECLASS_TIMER)
{
time++;
if (time >= TIMER_CLICKS)
{
time = 0L;
DivertCxMsg(cxm, co, co);
}
}
else
time = 0L;
}
</pre>

== New Input Events ==

The Commodities Library also has functions used to introduce new input events to the input stream.

<syntaxhighlight>
struct InputEvent *InvertString( UBYTE *string, ULONG *keymap );
VOID FreeIEvents( struct InputEvent *ie );
VOID AddIEvents( struct InputEvent *ie );
</syntaxhighlight>

InvertString() is a function that accepts an ASCII string and creates a linked list of input events that translate into the string using the supplied keymap (or the system default if the key map is NULL). The NULL terminated string may contain ANSI character codes, an input description enclosed in angle (<>) brackets, or one of the following backslash escape characters:

{| class="wikitable"
| \r
| Return
|-
| \t
| Tab
|-
| \\
| Backslash
|}

For example:

<pre>
abc<alt f1>\rhi there.
</pre>

FreeIEvents() frees a list of input events allocated by InvertString(). AddIEvents() is a commodities.library function that adds a linked list of input events at the the top of the Commodities network. Each input event in the list is made into an individual CxMessage. Note that if passed a linked list of input events created by InvertString(), the order the events appear in the string will be reversed.

=== Example ===
<syntaxhighlight>
/* PopShell.c - Simple hot key commodity example.
Adapted by xenic from the original source code.

Compile commands: gcc PopShell.c -o popshell -lamiga -Wall

To run the compiled program - Open 2 shell windows. Execute
PopShell in the first shell window with a line like:
PopShell HOTKEY "ctrl alt f"
Activate the second shell window and enter the keyboard shortcut.
A new shell window should open on the Workbench screen.
*/

#include <stdio.h>
#include <signal.h>

#include <libraries/commodities.h>

#include <proto/exec.h>
#include <proto/dos.h>
#include <proto/commodities.h>
#include <clib/alib_protos.h>

static CONST_STRPTR version USED = "$VER: PopShell 1.1 (05.11.2015)";
static CONST_STRPTR stackcookie USED = "$STACK: 32768";

#define EVT_HOTKEY 1L

struct Library *CxBase = NULL;
struct CommoditiesIFace *ICommodities = NULL;

struct MsgPort *broker_mp = NULL;
CxObj *broker, *filter;

struct NewBroker newbroker =
{
NB_VERSION,
"Amiga PopShell", /* string to identify this broker */
"A Simple PopShell",
"A simple PopShell commodity",
NBU_UNIQUE | NBU_NOTIFY, /* Don't want any new commodities starting with this name. */
0, 0, 0, 0 /* If someone tries it, let me know */
};

CONST_STRPTR newshell = "\rllehswen"; /* "newshell" spelled backwards */
struct InputEvent *ie = NULL;
ULONG cxsigflag;

#define TEMPLATE "HOTKEY/K,CX_PRIORITY/N"
enum
{
ARG_HOTKEY, ARG_PRIORITY, ARG_MAX
};

void ProcessMsg(void);

int main(int argc, char **argv)
{
STRPTR hotkey = NULL;
CxMsg *msg = NULL;
struct RDArgs *argsdata = NULL;
int32 rargs[ARG_MAX] = {0};
BYTE priority = 0;

signal(SIGINT, SIG_IGN);

if ((CxBase = IExec->OpenLibrary("commodities.library", 37L)))
{
if ((ICommodities = (struct CommoditiesIFace *)IExec->GetInterface(CxBase, "main", 1, NULL)))
{
if ((argsdata = IDOS->ReadArgs(TEMPLATE, rargs, NULL)))
{
if (rargs[ARG_PRIORITY])
priority = (BYTE)*(uint32 *)rargs[ARG_PRIORITY];
if ((broker_mp = IExec->AllocSysObject(ASOT_PORT, NULL)))
{
newbroker.nb_Port = broker_mp;
cxsigflag = 1L << broker_mp->mp_SigBit;
newbroker.nb_Pri = priority;
hotkey = (STRPTR)rargs[ARG_HOTKEY];

if ((broker = ICommodities->CxBroker(&newbroker, NULL)))
{
/* CxFilter(), CxSender() & CxTranslate() are */
/* macros defined in libraries/commodities.h. */
/* CxFilter() creates a filter CxObject. */
/* CxSender() creates a sender CxObject. */
/* CxTranslate() creates a translation CxObject. */
if ((filter = CxFilter(hotkey)))
{
/* Add a filter CxObject to another's personal list. */
ICommodities->AttachCxObj(broker, filter);

/* Add a sender CxObject to the filter CxObject. */
ICommodities->AttachCxObj(filter, CxSender(broker_mp, EVT_HOTKEY));

/* Add a translation CxObject to the filter CxObject */
ICommodities->AttachCxObj(filter, CxTranslate(NULL));

if (!(ICommodities->CxObjError(filter)))
{
/* InvertString() is an amiga.lib function that creates a linked */
/* list of input events which would translate into the string */
/* passed to it. Note that it puts the input events in the */
/* opposite order in which the corresponding letters appear in */
/* the string. A translate CxObject expects them backwards. */
if ((ie = InvertString(newshell, NULL)))
{
ICommodities->ActivateCxObj(broker, 1L);
ProcessMsg();
/* we have to release the memory allocated by InvertString. */
FreeIEvents(ie);
}
}
}
/* DeleteCxObjAll() is a commodities.library function that */
/* deletes the CxObject pointed to in its argument and */
/* deletes all of the CxObjects attached to it. */
ICommodities->DeleteCxObjAll(broker);

/* Empty the port of all CxMsgs */
while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
IExec->ReplyMsg((struct Message *)msg);
}
IExec->FreeSysObject(ASOT_PORT, broker_mp);
}
IDOS->FreeArgs(argsdata); /* cleans up after ReadArgs() */
}
IExec->DropInterface((struct Interface *)ICommodities);
}
IExec->CloseLibrary(CxBase);
}
return RETURN_OK;
}

void ProcessMsg(void)
{
extern struct MsgPort *broker_mp;
extern CxObj *broker;
extern ULONG cxsigflag;
CxMsg *msg = NULL;
ULONG sigrcvd, msgid, msgtype;
LONG returnvalue = 1L;

while (returnvalue)
{
sigrcvd = IExec->Wait(SIGBREAKF_CTRL_C | cxsigflag);

while((msg = (CxMsg *)IExec->GetMsg(broker_mp)))
{
msgid = ICommodities->CxMsgID(msg);
msgtype = ICommodities->CxMsgType(msg);
IExec->ReplyMsg((struct Message *)msg);

switch(msgtype)
{
case CXM_IEVENT:
printf("A CXM_EVENT, ");
switch(msgid)
{
case EVT_HOTKEY:
/* We got the message from the sender CxObject */
printf("You hit the HotKey.\n");
/* Add the string "newshell" to input * stream. */
/* If a shell gets it, it'll open a new shell. */
ICommodities->AddIEvents(ie);
break;
default:
printf("unknown.\n");
break;
}
break;
case CXM_COMMAND:
printf("A command: ");
switch(msgid)
{
case CXCMD_DISABLE:
printf("CXCMD_DISABLE\n");
ICommodities->ActivateCxObj(broker, 0L);
break;
case CXCMD_ENABLE:
printf("CXCMD_ENABLE\n");
ICommodities->ActivateCxObj(broker, 1L);
break;
case CXCMD_KILL:
printf("CXCMD_KILL\n");
returnvalue = 0L;
break;
case CXCMD_UNIQUE:
/* Commodities Exchange can be told not only to refuse to launch a */
/* commodity with a name already in use but also can notify the */
/* already running commodity that it happened. It does this by */
/* sending a CXM_COMMAND with the ID set to CXMCMD_UNIQUE. If the */
/* user tries to run a windowless commodity that is already running, */
/* the user wants the commodity to shut down. */
printf("CXCMD_UNIQUE\n");
returnvalue = 0L;
break;
default:
printf("Unknown msgid\n");
break;
}
break;
default:
printf("Unknown msgtype\n");
break;
}
}

if (sigrcvd & SIGBREAKF_CTRL_C)
{
returnvalue = 0L;
printf("CTRL C signal break\n");
}
}
}
</syntaxhighlight>

== Function Reference ==

The following are brief descriptions of the Commodities Exchange functions covered in this article. See the SDK for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| CxBroker()
| Creates a CxObject of type Broker.
|-
| CxFilter()
| Creates a CxObject of type Filter.
|-
| CxSender()
| Creates a CxObject of type Sender.
|-
| CxTranslate()
| Creates a CxObject of type Translate.
|-
| CxSignal()
| Creates a CxObject of type Signal.
|-
| CxCustom()
| Creates a CxObject of type Custom.
|-
| CxDebug()
| Creates a CxObject of type Debug.
|-
| DeleteCxObj()
| Frees a single CxObject
|-
| DeleteCxObjAll()
| Frees a group of connected CxObjects
|-
| ActivateCxObj()
| Activates a newly created CxObject in the commodities network.
|-
| CxTranslate()
| Sets up substitution of one input event for another by translate CxObjects.
|-
| CxMsgType()
| Finds the type of a CxMessage.
|-
| CxMsgData()
| Returns the CxMessage data.
|-
| CxMsgID()
| Returns the CxMessage ID.
|-
| CxObjError()
| Returns the CxObject's accumulated error field.
|-
| ClearCxObjError()
| Clear the CxObject's accumulated error field.
|-
| AttachCxObj()
| Attaches a CxObject to the end of a given CxObject's list.
|-
| InsertCxObj()
| Inserts a CxObject in a given position in a CxObject's list.
|-
| EnqueueCxObj()
| Inserts a CxObject in a CxObject's list by priority.
|-
| SetCxObjPri()
| Sets a CxObject's priority for EnqueueCxObj().
|-
| RemoveCxObj()
| Removes a CxObject from a list.
|-
| SetFilter()
| Set a filter for a CxObject from an input description string.
|-
| SetFilterIX()
| Set a filter for a CxObject from an IX data structure.
|-
| ParseIX()
| Convert an input description string to an IX data structure.
|-
| DivertCxMsg()
| Divert a CxMessage to one CxObject and return it to another.
|-
| RouteCxMsg()
| Redirect a CxMessage to a new CxObject.
|-
| DisposeCxMsg()
| Cancel a CxMessage removing it from the Commodities network.
|-
| InvertString()
| Creates a linked list of input events that correspond to a given string.
|-
| FreeIEvents()
| Frees the linked list of input events created with InvertString().
|-
| AddIEvents()
| Converts a list of input events to CxMessages and puts them into the network.
|-
| CopyBrokerList()
| Creates a local copy of the current broker list (V53.4).
|-
| FreeBrokerList()
| Frees the local broker list (V53.4).
|-
| BrokerCommand()
| Sends a command to a commodity broker (V53.4).
|}

=== Obsolete Functions ===

The following functions are obsolete and no longer used:

{| class="wikitable"
! Function
! Description
|-
| ArgArrayInit()
| Create a Tool Types array from argc and argv (Workbench or Shell).
|-
| ArgArrayDone()
| Free the resources used by ArgArrayInit().
|-
| ArgString()
| Return the string associated with a given Tool Type in the array.
|-
| ArgInt()
| Return the integer associated with a given Tool Type in the array.
|}

Graphics Library

2015-09-27T20:35:37Z

Daniel Jedlicka: /* RTG Support */

Graphics Library (graphics.library) provides many services related to graphics on the Amiga including:
* [[Graphics_Primitives|Graphics Primitives]]
* [[Graphics_Sprites,_Bobs_and_Animation|Sprites, Bobs and Animation]]
* [[Graphics_Library_and_Text|Text Rendering]]
* [[Graphics_Regions|Region Clipping]]
* [[Graphics_Composited_Video|Composited Video]]
* [[Graphics_Video_Overlay|Video Overlay]]

== RTG Support ==

Starting with graphics.library V54, full Re-Targetable Graphics (RTG) support has been added to the graphics subsystem. In AmigaOS 4.0, programmers must juggle both the Picasso96 and graphics.library APIs simultaneously. The situation is worse in AmigaOS 3.x and earlier where different RTG implementations compete for market share.

Graphics Library

2015-09-27T20:34:02Z

Daniel Jedlicka:

Graphics Library (graphics.library) provides many services related to graphics on the Amiga including:
* [[Graphics_Primitives|Graphics Primitives]]
* [[Graphics_Sprites,_Bobs_and_Animation|Sprites, Bobs and Animation]]
* [[Graphics_Library_and_Text|Text Rendering]]
* [[Graphics_Regions|Region Clipping]]
* [[Graphics_Composited_Video|Composited Video]]
* [[Graphics_Video_Overlay|Video Overlay]]

== RTG Support ==

Starting with graphics.library V54, full Re-Targetable Graphics (RTG) support has been added to the graphics subsystem. In AmigaOS 4.0, programmers must juggle both the Picasso 96 and graphics.library APIs simultaneously. The situation is worse in AmigaOS 3.x and earlier where different RTG implementations compete for market share.

UI Style Guide Keyboard

2015-09-25T18:07:57Z

Daniel Jedlicka: /* Application Keyboard Shortcuts */

[[Category:User Interface Style Guide]]
== The Keyboard ==

Your application should make gadget and menu items selectable with the keyboard as well as with the mouse. Often these keyboard equivalents ("hotkeys") will provide shortcuts and a smoother workflow that is appreciated by the user. Also, allowing the choice conforms to the Amiga credo: "Power to the User".

The set of conventions you should follow to implement this style rule are presented in this section.

== Keyboard Conventions ==

The arrangement of the Amiga's keyboard varies from model to model, but in general there are always three sets of keys:
* the standard keyboard
* special keys
* modifier keys

=== The Standard Keyboard ===

The standard keys consist of the familiar alphanumeric keys found on any standard typewriter. (In English, this is referred to as the QWERTY keyboard, but in German, since the standard keys are arranged differently, it's known as the QWERTZ keyboard. It's called other names in other languages.)

The actual arrangement of the standard keys can vary. To handle this, AmigaOS uses a special facility known as a keymap that allows the user to change the way the keyboard input is mapped so it will correspond to his country's keyboard layout and characters. For example, to access all the standard German ASCII characters the user can type "Setmap d" in the Shell. Then German characters such as ü and ß will have the same key designations as they do on a standard German keyboard.

Use the keymap facility to handle key assignments on the standard keyboard.

=== Special Keys ===

The special keys include the function keys on the top row of your computer's keyboard, the Help key, the cursor (arrow) keys, the Del key, the backspace key and the Esc key.

=== Modifier Keys ===

The modifier keys are the Ctrl, Shift, Alt and Amiga keys found on either side of the space bar. Modifier keys don't do anything by themselves; they alter the meaning of a key that is pressed at the same time. They are also used to modify the meaning of a mouse selection. For example, holding down the Shift key while clicking with the mouse is used for multiple object selection.

==== Dead Keys ====

A "dead" key is a key, or combination, that does nothing immediately but modifies the output of the next key. For example, on an American keyboard, Alt-H will superimpose a caret (^) symbol over the next appropriate character.

Although relatively unimportant on the American keyboard, dead keys are important in many languages. Keep in mind that you need to work these in manually if you're doing your own raw key mapping.

== System Keyboard Shortcuts ==

To provide mouse functions from the keyboard, only three features a needed: a way to press the left mouse button, a way to press the right mouse button, and a way to move the mouse pointer. These are provided by the system. They are listed here so you are aware of them and can avoid using these key combinations for any other purpose.

{| class="wikitable"
! Keyboard Shortcut
! Equivalent Mouse Activity
|-
| Either Amiga + Left-Alt
| Same as clicking left mouse button
|-
| Either Amiga + Right-Alt
| Same as clicking right mouse button
|-
| Either Amiga + Cursor Key
| Moves mouse pointer
|-
| Either Amiga + Shift + Cursor Key
| Moves mouse pointer in larger steps
|}

Five additional Amiga system functions have keyboard shortcuts:

{| class="wikitable"
! Default Keyboard Shortcut
! Equivalent System Function
|-
| Left-Amiga + N
| Workbench screen to front
|-
| Left-Amiga + M
| Front screen to back
|-
| Left-Amiga + B
| Requester OK (leftmost gadget)
|-
| Left-Amiga + V
| Requester Cancel (rightmost gadget)
|-
| Left-Amiga + selection button
| Drags screen whether the pointer is on the title bar or not
|}

The first four functions listed above always use Left-Amiga in combination with another key. The second key in the combination can be changed by the user with the IControl preferences editor in your AmigaOS Prefs drawer. For the screen dragging shortcut, the user can change the modifier or combination of modifiers (Ctrl, Amiga, Shift, Alt) that need to be combined with the selection button.

=== The Left-Amiga Key ===

Keep in mind that the Left-Amiga key is reserved at all times for system operations and should never be used as a qualifier for an application keyboard shortcut!

== Application Keyboard Shortcuts ==

Your application should provide a way for the user to bind an application function or ARexx macro to a key or combination of keys. Keyboard access to program features and common functions can speed up workflow significantly.

On the other hand, it’s not necessary to provide hotkeys for every single function in your program: the user wouldn’t be able to remember them anyway. Plus, keyboard shortcuts work best if they are mnemonic and logical: S for Save, P for Print, etc. Therefore, save handy mnemonics for common and really important functions, don't waste them on secondary features.

Prefer common character keys for shortcuts: if possible, avoid punctuation characters like brackets, quotation marks, the exclamation mark, the slash, the apostrophe, the tilde etc. While easily accessible with the English keymap, in certain languages the keymap will bind these characters with a qualifier key, making them more difficult to access. This is especially true of the [[#Menus|menu shortcuts]] where the Right Amiga key is also required: the user would then have to press two qualifiers plus the respective character key. If your application implements many functions and you need to resort to using punctuation-based shortcuts, make sure you assign them to less commonly used functions.

If you provide a hotkey for an operation that can be dangerous (such as format disk or delete-type operations), make sure the user will get the opportunity to confirm or cancel the action should he/she make an inadvertent key press. The general rule of application design is: never put the user's data at stake!

=== Gadgets ===

Place an underscore under the letter in the gadget label that activates the gadget. (Note: although the letter is capitalized on the label, the
default action should react to the lower-case letter. Some Intuition gadgets have a different action for the shifted version of the letter. See the list in the table below.)

The following three rules should apply:

* All action should occur on the down press of the key.
* The same visual feedback should be given for keyboard activation as is given for mouse activation.
* Avoid assigning the Enter key to a gadget.

'''Feedback from Keystroke-Activated Gadgets'''

{| class="wikitable"
| Action button
| On the down press of the key, the gadget should appear to be pressed in. On release of the key, the gadget should come back out. (Note: at the time this manual was published, GadTools did not support this function.)
|-
| Check box
| Toggle the state of the check mark.
|-
| Scrolling list
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Radio button
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Cycle gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Selection gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Scroll gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Slider
| Unshifted would increase the level by one unit. Shifted would decrease the level by one unit.
|-
| Text box
| Activate the gadget for entry.
|-
| Numeric entry
| Activate the gadget for entry.
|}

=== Menus ===

Use a Right-Amiga combination as the default keyboard shortcut for a menu item. Here is a list of recommended hotkeys for common functions found in an application's menus:

Project Menu
Right-Amiga + N New
Right-Amiga + O Open...
Right-Amiga + S Save
Right-Amiga + A Save As...
Right-Amiga + P Print
Right-Amiga + ? About...
Right-Amiga + Q Quit Program

Edit Menu
Right-Amiga + X Cut
Right-Amiga + C Copy
Right-Amiga + V Paste
Right-Amiga + Z Undo

Some of these (namely: N for New, O for Open, S for Save, P for Print, and the four Edit Menu shortcuts) are de facto cross-platform standards, and should therefore be respected as such. On the other hand, the choice of suitable keys is limited so a particular “standard” shortcut may certainly be reused if the application does not implement the respective function. For example, an application that does not print or cannot create new projects (such as a music player) can use the Right-Amiga+N and Right-Amiga+P combination for something else.

The original User Interface Style Guide suggested in this section that menu shortcuts should be [[Locale_Library|localized]] to reflect the user's preferred language as set in the system. This recommendation has turned out to be rather short-sighted and impractical: certain hotkeys like the ones listed above are so common, universal and "dyed in the wool" that changing them based on the currently selected locale would only be confusing. Also remember that unlike in gadgets, where the user can see the actual shortcut (it is underscored in the gadget label), you get no direct visual cue when using menu hotkeys because they are hidden in the menu. Thus, a menu hotkey could potentially be dangerous if the user pressed a known key combination that has suddenly changed meaning due to locale change.

=== Requesters ===

Hotkeys for requester buttons should also be provided. Requesters require user interaction: they "get in the way" and can slow down workflow. The user would therefore appreciate requester buttons having keyboard shortcuts (unless there’s a good reason not to provide them, such as safety of operation).

== Use of the Special Keys ==

As stated previously, the special keys are the function keys, the Del key, the Help key, the cursor (arrow) keys and the Esc key.

=== Cursor Keys ===

Cursor keys are a convenient way to control the movement of the cursor inside an application. Here are some standard ways to use them:

==== Unmodified Cursor ====

Move a small amount in the specified direction. Often this is one unit such as a character in a word processor or a pixel in a paint package, but it could be several pixels in an application where navigation is more important than fine control.

==== Shift + Cursor ====

Move to the appropriate extreme of the window, or shift the view by one window full if you're already at that extreme.

In applications such as a word processor where the two directions are not symmetrical, shifted cursor keys could take on different meanings. Shifted up and down cursors would page through windowfuls while the shifted left and right cursors would show more on the left and right if there is more to show. Of course it is often the case that the width of the document fits in the window, so the shifted left and right cursors could act as beginning-and end-of-line commands (or edge of window if the cursor isn't constrained to the form of the text).

==== Alt-Cursor ====

This is used for application-specific functions. It's usually semantic units such as words in a text processor or fields in a spreadsheet.

==== Ctrl-Cursor ====

Move to the appropriate extreme of the project (beginning, end, extreme left, extreme right).

In the word processor example, the up and down cursor keys would take the cursor to the beginning and end of the file, respectively. But again, if the file fits within the width of the window, the left and right cursor keys combined with Alt would act like their shifted cousins.

==== Function Keys ====

Function keys should generally be reserved for the user to define. If your application does make use of them, then it should at least allow the user to redefine or modify them.

==== Help Key ====

If your application has built-in help, use the Help key to trigger it from the keyboard. Avoid giving the user that helpless feeling he gets when he presses the Help key and nothing happens.

Note that PC keyboards connected to an AmigaOS-compatible computer will not feature the Help key. On such keyboards the Help key will be mapped to the ScrollLock key.

UI Style Guide Keyboard

2015-09-20T08:59:18Z

Daniel Jedlicka: Added a note on (re)using the "standard" menu shortcuts.

[[Category:User Interface Style Guide]]
== The Keyboard ==

Your application should make gadget and menu items selectable with the keyboard as well as with the mouse. Often these keyboard equivalents ("hotkeys") will provide shortcuts and a smoother workflow that is appreciated by the user. Also, allowing the choice conforms to the Amiga credo: "Power to the User".

The set of conventions you should follow to implement this style rule are presented in this section.

== Keyboard Conventions ==

The arrangement of the Amiga's keyboard varies from model to model, but in general there are always three sets of keys:
* the standard keyboard
* special keys
* modifier keys

=== The Standard Keyboard ===

The standard keys consist of the familiar alphanumeric keys found on any standard typewriter. (In English, this is referred to as the QWERTY keyboard, but in German, since the standard keys are arranged differently, it's known as the QWERTZ keyboard. It's called other names in other languages.)

The actual arrangement of the standard keys can vary. To handle this, AmigaOS uses a special facility known as a keymap that allows the user to change the way the keyboard input is mapped so it will correspond to his country's keyboard layout and characters. For example, to access all the standard German ASCII characters the user can type "Setmap d" in the Shell. Then German characters such as ü and ß will have the same key designations as they do on a standard German keyboard.

Use the keymap facility to handle key assignments on the standard keyboard.

=== Special Keys ===

The special keys include the function keys on the top row of your computer's keyboard, the Help key, the cursor (arrow) keys, the Del key, the backspace key and the Esc key.

=== Modifier Keys ===

The modifier keys are the Ctrl, Shift, Alt and Amiga keys found on either side of the space bar. Modifier keys don't do anything by themselves; they alter the meaning of a key that is pressed at the same time. They are also used to modify the meaning of a mouse selection. For example, holding down the Shift key while clicking with the mouse is used for multiple object selection.

==== Dead Keys ====

A "dead" key is a key, or combination, that does nothing immediately but modifies the output of the next key. For example, on an American keyboard, Alt-H will superimpose a caret (^) symbol over the next appropriate character.

Although relatively unimportant on the American keyboard, dead keys are important in many languages. Keep in mind that you need to work these in manually if you're doing your own raw key mapping.

== System Keyboard Shortcuts ==

To provide mouse functions from the keyboard, only three features a needed: a way to press the left mouse button, a way to press the right mouse button, and a way to move the mouse pointer. These are provided by the system. They are listed here so you are aware of them and can avoid using these key combinations for any other purpose.

{| class="wikitable"
! Keyboard Shortcut
! Equivalent Mouse Activity
|-
| Either Amiga + Left-Alt
| Same as clicking left mouse button
|-
| Either Amiga + Right-Alt
| Same as clicking right mouse button
|-
| Either Amiga + Cursor Key
| Moves mouse pointer
|-
| Either Amiga + Shift + Cursor Key
| Moves mouse pointer in larger steps
|}

Five additional Amiga system functions have keyboard shortcuts:

{| class="wikitable"
! Default Keyboard Shortcut
! Equivalent System Function
|-
| Left-Amiga + N
| Workbench screen to front
|-
| Left-Amiga + M
| Front screen to back
|-
| Left-Amiga + B
| Requester OK (leftmost gadget)
|-
| Left-Amiga + V
| Requester Cancel (rightmost gadget)
|-
| Left-Amiga + selection button
| Drags screen whether the pointer is on the title bar or not
|}

The first four functions listed above always use Left-Amiga in combination with another key. The second key in the combination can be changed by the user with the IControl preferences editor in your AmigaOS Prefs drawer. For the screen dragging shortcut, the user can change the modifier or combination of modifiers (Ctrl, Amiga, Shift, Alt) that need to be combined with the selection button.

=== The Left-Amiga Key ===

Keep in mind that the Left-Amiga key is reserved at all times for system operations and should never be used as a qualifier for an application keyboard shortcut!

== Application Keyboard Shortcuts ==

Your application should provide a way for the user to bind an application function or ARexx macro to a key or combination of keys. Keyboard access to program features and common functions can speed up workflow significantly.

On the other hand, it’s not necessary to provide hotkeys for every single function in your program: the user wouldn’t be able to remember them anyway. Plus, keyboard shortcuts work best if they are mnemonic and logical: S for Save, P for Print, etc. Therefore, save handy mnemonics for common and really important functions, don't waste them on secondary features.

If you provide a hotkey for an operation that can be dangerous (such as format disk or delete-type operations), make sure the user will get the opportunity to confirm or cancel the action should he/she make an inadvertent key press. The general rule of application design is: never put the user's data at stake!

=== Gadgets ===

Place an underscore under the letter in the gadget label that activates the gadget. (Note: although the letter is capitalized on the label, the
default action should react to the lower-case letter. Some Intuition gadgets have a different action for the shifted version of the letter. See the list in the table below.)

The following three rules should apply:

* All action should occur on the down press of the key.
* The same visual feedback should be given for keyboard activation as is given for mouse activation.
* Avoid assigning the Enter key to a gadget.

'''Feedback from Keystroke-Activated Gadgets'''

{| class="wikitable"
| Action button
| On the down press of the key, the gadget should appear to be pressed in. On release of the key, the gadget should come back out. (Note: at the time this manual was published, GadTools did not support this function.)
|-
| Check box
| Toggle the state of the check mark.
|-
| Scrolling list
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Radio button
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Cycle gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Selection gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Scroll gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Slider
| Unshifted would increase the level by one unit. Shifted would decrease the level by one unit.
|-
| Text box
| Activate the gadget for entry.
|-
| Numeric entry
| Activate the gadget for entry.
|}

=== Menus ===

Use a Right-Amiga combination as the default keyboard shortcut for a menu item. Here is a list of recommended hotkeys for common functions found in an application's menus:

Project Menu
Right-Amiga + N New
Right-Amiga + O Open...
Right-Amiga + S Save
Right-Amiga + A Save As...
Right-Amiga + P Print
Right-Amiga + ? About...
Right-Amiga + Q Quit Program

Edit Menu
Right-Amiga + X Cut
Right-Amiga + C Copy
Right-Amiga + V Paste
Right-Amiga + Z Undo

Some of these (namely: N for New, O for Open, S for Save, P for Print, and the four Edit Menu shortcuts) are de facto cross-platform standards, and should therefore be respected as such. On the other hand, the choice of suitable keys is limited so a particular “standard” shortcut may certainly be reused if the application does not implement the respective function. For example, an application that does not print or cannot create new projects (such as a music player) can use the Right-Amiga+N and Right-Amiga+P combination for something else.

The original User Interface Style Guide suggested in this section that menu shortcuts should be [[Locale_Library|localized]] to reflect the user's preferred language as set in the system. This recommendation has turned out to be rather short-sighted and impractical: certain hotkeys like the ones listed above are so common, universal and "dyed in the wool" that changing them based on the currently selected locale would only be confusing. Also remember that unlike in gadgets, where the user can see the actual shortcut (it is underscored in the gadget label), you get no direct visual cue when using menu hotkeys because they are hidden in the menu. Thus, a menu hotkey could potentially be dangerous if the user pressed a known key combination that has suddenly changed meaning due to locale change.

=== Requesters ===

Hotkeys for requester buttons should also be provided. Requesters require user interaction: they "get in the way" and can slow down workflow. The user would therefore appreciate requester buttons having keyboard shortcuts (unless there’s a good reason not to provide them, such as safety of operation).

== Use of the Special Keys ==

As stated previously, the special keys are the function keys, the Del key, the Help key, the cursor (arrow) keys and the Esc key.

=== Cursor Keys ===

Cursor keys are a convenient way to control the movement of the cursor inside an application. Here are some standard ways to use them:

==== Unmodified Cursor ====

Move a small amount in the specified direction. Often this is one unit such as a character in a word processor or a pixel in a paint package, but it could be several pixels in an application where navigation is more important than fine control.

==== Shift + Cursor ====

Move to the appropriate extreme of the window, or shift the view by one window full if you're already at that extreme.

In applications such as a word processor where the two directions are not symmetrical, shifted cursor keys could take on different meanings. Shifted up and down cursors would page through windowfuls while the shifted left and right cursors would show more on the left and right if there is more to show. Of course it is often the case that the width of the document fits in the window, so the shifted left and right cursors could act as beginning-and end-of-line commands (or edge of window if the cursor isn't constrained to the form of the text).

==== Alt-Cursor ====

This is used for application-specific functions. It's usually semantic units such as words in a text processor or fields in a spreadsheet.

==== Ctrl-Cursor ====

Move to the appropriate extreme of the project (beginning, end, extreme left, extreme right).

In the word processor example, the up and down cursor keys would take the cursor to the beginning and end of the file, respectively. But again, if the file fits within the width of the window, the left and right cursor keys combined with Alt would act like their shifted cousins.

==== Function Keys ====

Function keys should generally be reserved for the user to define. If your application does make use of them, then it should at least allow the user to redefine or modify them.

==== Help Key ====

If your application has built-in help, use the Help key to trigger it from the keyboard. Avoid giving the user that helpless feeling he gets when he presses the Help key and nothing happens.

Note that PC keyboards connected to an AmigaOS-compatible computer will not feature the Help key. On such keyboards the Help key will be mapped to the ScrollLock key.

PrefsObjects

2015-09-18T13:04:15Z

Daniel Jedlicka: /* The Interface and its Functions */

== Introduction ==

Many applications are user-configurable so they need a way to store their settings; we traditionally use the term ''preferences'' or simply ''prefs'' in the AmigaOS context. It may come as a surprise that before version 4.x, AmigaOS had no real standard for storing preference data. Developers used various, often proprietary solutions: [[Icon_Library#The_Tool_Types_Array|icon tooltypes]], IFF-based formats, text files mimicking the Windows ''.ini'' format, or binary formats. Some of them are still very popular (tooltypes) or even used by the OS itself (some [[UI_Style_Guide_Preferences#Preferences|system preferences]] are stored as IFF-PREF files). While this is not a place to go into detail and discuss their particular advantages and disadvantages, let’s mention two common drawbacks that ultimately led to the development of the Application Library PrefsObjects system:

# All of the solutions above require you to implement your own preferences handling code (that is, routines for parsing, verification, and saving).
# None of the various formats used have ever provided a smart enough way to administer complex, structured settings.

Since its introduction in AmigaOS, PrefsObjects has largely been promoted as being ''XML-based'' and therefore human-readable and easy to edit. Yet using an industry standard format that is platform-independent and supports Unicode is not the biggest “selling point” of PrefsObjects. What makes it different from (and superior to) previous solutions is not the fact that it is XML-based but, rather, that it is ''object-oriented''. Among other things, this property also helps address the two drawbacks mentioned above.

Imagine, for example, a program that uses a plug-in system. Both the main program and its plug-in modules are configurable. Instead of having ten or more individual preference files, you’ll likely want a single file containing settings for the program as well as for the plug-ins. This naturally introduces a certain hierarchy. Plus, as some plug-ins may be delivered by third parties, the particular structure of the prefs file is somewhat beyond the control of the main program: the amount, contents and sequencing of data in the file depends on which plug-ins are installed and on how (and when, if ever) they store their settings. You would have to take all of this into account when implementing your own prefs-handling routines, which means a good deal of work.

== The Interface and its Functions ==

The Application Library contains two interfaces, named “application” and “prefsobjects”. If you want to implement your program preferences using the PrefsObjects system, you must obtain the “prefsobjects” interface: all the necessary functions and methods are contained therein. Naturally, your application must be registered before you can make use of PrefsObjects.

Starting with AmigaOS SDK 53.24, both interfaces (“application” and “prefsobjects”) must be at version 2. See the [[Application_Library#Library Opening Chores|Library Opening Chores]] section of the Application Library documentation for more information.

All operations related to settings – retrieving, adding and changing –, as well as all operations related to the prefs file itself – creation, loading and saving – are performed solely through the library functions. Some operations can even be automated, sparing the programmer from unnecessary hassle.

== Object Types ==

PrefsObjects tackles the task by seeing data as ''objects'', and by providing functions and methods for object manipulation. Loading, adding, updating or removing preference objects (be they single items or entire clusters of settings) then becomes a matter of calling the respective function – “invoking the method on the object”, as we say in object-oriented programming. If you are acquainted with this philosophy (as used, for example, in Intuition’s [[BOOPSI]] framework), you will find working with PrefsObjects very easy and straightforward.

PrefsObjects distinguishes between six object types:

{| class="wikitable"
! Object Type
! Description
|-
| Dictionary || A container to encapsulate (embed) other objects. The prefs file usually has a Dictionary object at the top level.
|-
| Array || A container to encapsulate other objects. The difference between a Dictionary and an Array is in object referencing: in Arrays encapsulated objects are referenced by an index, while in a Dictionary they are referenced by a name (key string).
|-
| Number || An object to carry a long integer, double, or a boolean value.
|-
| String || An object to carry a text string.
|-
| Date || An object to carry date and time information.
|-
| Binary || An object to carry arbitrary binary data. However, binary data should be avoided as much as possible because it's restrictive in its form and is not future-proof, as it does not enable addition or removal of data without compromising compatibility.
|}

== The Preferences File ==

The files generated by the Application Library's PrefsObjects system are standard XML documents. They are encoded in UTF-8 (which AmigaOS doesn't support directly) but that doesn't necessarily pose a problem. First, you rarely need to edit prefs files manually – nor are you encouraged to do so, unless the file has become corrupted or contains a setting that prevents the application from starting up or running properly. Second, characters beyond the ASCII range are rarely used in preferences, so the prefs files will likely be readable and editable even in a text editor that has no notion of UTF-8. And third, you can always use the dedicated [[PrefsObjectsEditor]], located in the Utilities drawer on your system disk, which allows easy and safe editing of PrefsObjects files (the usage of this tool is, however, out of the scope of this page).

As already mentioned above, all data access is handled by the Application Library. On the part of the programmer (or the application user), no actual knowledge of XML is required.

=== File Structure ===

The preferences file normally starts with a Dictionary object at the top level. The advantage of using a Dictionary is that objects stored in it are identified by a name (called a “key”). Using named objects is very practical. Unlike in Arrays, where objects are indexed, the order of data is quite irrelevant as long as you deal with objects on the same level. Your application can retrieve, add, modify, re-sequence or remove individual objects in an arbitrary order without having to worry about breaking anything: a named object will always be addressed properly if it exists.

Object names (keys) must be unique at each particular level. In other words, you cannot have two settings items (objects) with the same key in the same dictionary. However, identical object names can be used in different dictionaries. The following example shows a prefs file structure that embeds two separate dictionaries named “Screen settings” and “Window settings”. As you can see, identical keys (“Name”, “Width” and “Height”) are then used without collision:

<center>
<classdiagram type="orderly" scale="80" dir="prf">
[“Root”\n(Dictionary)]->[“Screen settings”\n(Dictionary)]
[“Window settings”\n(Dictionary)]->[“Height”\n(Number) ]
[“Window settings”\n(Dictionary)]->[“Width”\n(Number) ]
[“Window settings”\n(Dictionary)]->[“Name”\n(String) ]
[“Root”\n(Dictionary)]->[“Window settings”\n(Dictionary)]
[“Screen settings”\n(Dictionary)]->[“Height”\n(Number)]
[“Screen settings”\n(Dictionary)]->[“Width”\n(Number)]
[“Screen settings”\n(Dictionary)]->[“Name”\n(String)]
</classdiagram>
</center>

The diagram also illustrates the hierarchical nature of the PrefsObjects system: the fact that objects can be embedded inside other objects.

== Reading Preferences ==

In most cases, there will be just one preferences file associated with your application. If all you need is simply read settings from the file (and save them upon user request), it is recommended that you let the Application Library handle the file access. Registering your application like this

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_LoadPrefs, TRUE,
TAG_END);
</syntaxhighlight>

will tell the library to access the prefs file automatically, under its default name and from the default location. The default naming scheme for prefs files uses the application name combined with the [[Application_Library#Application Identifiers|URL identifier]]. Also, the ''.xml'' extension is appended at the end of the name to identify the document format. So with this particular registration call, the default file name will be “AudioMonster.supercoders.com.xml” and the library will try to access it from the ENV: directory. (Don't worry, both the file name and location can be changed.)

If the file is found, the library will internally allocate a Dictionary object and read the settings into it. If the file is not found, the library will allocate an empty Dictionary for you. In either case the said Dictionary object will become the application's ''Main Prefs Dictionary'' and will be associated with the application as one of its attributes. (The application may use multiple prefs Dictionaries but at any given point in time, only one of them is main.)

After start-up and registration, the application will typically want to access the settings in order to configure itself. Having used ''REGAPP_LoadPrefs, TRUE'' in the registration call above, we should now have the application's Main Prefs Dictionary somewhere in memory, to which we need to obtain a pointer. This is done through the function GetApplicationAttrs() because as explained above, the Main Prefs Dictionary is an application attribute. After that we can use dedicated functions to access the individual objects (i.e. settings items) in the Dictionary.

The code fragment below assumes that our prefs file – already loaded by the registration routine and transformed into an object – contains three settings items:

* a boolean value stored in the file under the key of “Switch”;
* a numeric value of type uint32 stored under the key of “Number”;
* a text string stored under the key of “String”.

We first obtain the pointer to the prefs Dictionary object, retrieve the three values, and store them in a dedicated data structure:

<syntaxhighlight>
/* Default settings */
#define DEF_SWITCH TRUE
#define DEF_NUMBER 100
#define DEF_STRING "Play it again, Sam!"

struct Settings
{
BOOL switch;
uint32 number;
STRPTR string;
};

PrefsObject *myPrefsDict = NULL; /* Main Prefs Dictionary */
struct Settings mySettings; /* Structure to hold the settings */

/* Obtain the Dictionary object pointer */
IApplication->GetApplicationAttrs(appID, APPATTR_MainPrefsDict, &myPrefsDict, TAG_END);

if ( myPrefsDict )
{

/* Retrieve the settings values.

Note: here we need to cast the type of the number and of the string value
to avoid compiler warnings. This is because DictGetIntegerForKey()
and DictGetStringForKey() return int32 and CONST_STRPTR, respectively,
whereas our program declares them as uint32 and STRPTR.
*/
mySettings.switch = IPrefsObjects->DictGetBoolForKey(myPrefsDict, "Switch", DEF_SWITCH);
mySettings.number = (uint32) IPrefsObjects->DictGetIntegerForKey(myPrefsDict, "Number", DEF_NUMBER);
mySettings.string = (STRPTR) IPrefsObjects->DictGetStringForKey(myPrefsDict, "String", DEF_STRING);

/* Test out the string value. */
IDOS->Printf("All I want to say is: %s\n", mySettings.string);
}
</syntaxhighlight>

Should any of the settings items be missing, the respective default value is used. This will be the case, for example, when a physical XML prefs file is not present and the PrefsObjects system supplies an empty Dictionary.

(to be continued)

== Function Reference ==

The following are brief descriptions of the PrefsObjects-related functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| BeginDeserialization()
| Begins the deserialization of a prefs object.
|-
| DictGetBoolForKey()
| Obtains a boolean value for a dictionary key.
|-
| DictGetIntegerForKey()
| Obtains an integer value for a dictionary key.
|-
| DictGetObjectForKey()
| Obtains an object for a dictionary key.
|-
| DictGetOptionForKey()
| Obtains a string from an option table.
|-
| DictGetStringForKey()
| Obtains a string value for a dictionary key.
|-
| DictSetObjectForKey()
| Sets an object for a dictionary key.
|-
| PrefsArray()
| PrefsObjects array object access function.
|-
| PrefsBaseObject()
| PrefsObjects base object access function.
|-
| PrefsBinary()
| PrefsObjects binary object access function.
|-
| PrefsDate()
| PrefsObjects date object access function.
|-
| PrefsDictionary()
| PrefsObjects dictionary object access function.
|-
| PrefsNumber()
| PrefsObjects number object access function.
|-
| PrefsString()
| PrefsObjects string object access function.
|-
| ReadPrefs()
| Reads a prefs dictionary from a file.
|-
| WritePrefs()
| Writes a prefs dictionary to a file.
|}

Application Library

2015-09-18T12:37:26Z

Daniel Jedlicka: Moved the PrefsObjects section into a new page.

== Introduction ==

The Application Library is a multipurpose auxiliary library that provides various functions related to the development and use of applications. The very concept of ''application'' is a relatively recent addition to AmigaOS. Before, the system only distinguished between different types of program on a very low level, seeing them as either [[Exec_Tasks|tasks]] or [[AmigaDOS_Data_Structures#Process_Data_Structures|processes]]. This distinction might have been useful in the past when tasks (which require fewer resources in return for not being able to access DOS functions) could improve system performance. But it can hardly make a difference on today’s hardware so the trade-offs are no longer worth it. Nowadays it makes more sense to discriminate between programs that operate without the user even noticing (e.g. drivers, handlers, filesystems and other ''background services''), and genuine full-blown ''applications'' with [[UI_Style_Guide_Glossary#GUI|GUI]] and all.

AmigaOS alone cannot make such a distinction: it uses the Application Library as a mediator through which applications introduce themselves to the system. This process is called [[#Registering the Application|application registration]], during which the application receives a [[#Application Identifiers|unique identifier]] and is added to a public list among other applications. Once registered, the application can make use of the library’s many features:

* It can send/receive messages to/from other registered applications. The library supports a set of common [[#Control Messages|control messages]] (commands) such as those telling an application to quit, iconify or bring its window to front. But it also allows [[#Custom Messages|custom messages]] designed for an application’s particular needs; in this respect the Application Library provides an alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]] control.

* It can turn into a “watchdog” and get notified when other applications register.

* It can use [[PrefsObjects]], an XML-based, object-oriented system for handling program preferences. Before AmigaOS 4.x no real standard existed for storing preferences: some developers used icon tooltypes, some used proprietary formats, text or binary. The Application Library provides a format that is human-readable and easily editable in a simple text editor; that is comprehensive enough to cover even very complex settings structures; and that is fully controllable via the library, without the need to laboriously implement data parsing and verification.

* It can notify the user about, for example, completed tasks via automatic [[#Pop-up Notifications (Ringhio Messages)|pop-up messages]]. These represent a practical, less obtrusive alternative to traditional requesters.

* It can easily create and manage lists of recently-used documents.

* It can register as a ''unique application'', preventing other instances of itself from running.

* It can show its icon or display the current program state in taskbar-like applications, such as AmiDock.

* It can control the behaviour of screen-blankers. Applications that don’t want to be disturbed may prevent the blanker from kicking in, or tell other applications to “keep quiet”.

=== Frequently Asked Questions ===

{| class="wikitable"
|-
|''Q: Should my programs register with the Application Library?''
|A: Yes, that would make a lot of sense. Apart from access to the handy features mentioned above, the implementation of certain library features may improve the behaviour of your application within the AmigaOS ecosystem.
|-
|''Q: After registering with the library, will my application become controlled by the OS or by other applications?''
|A: No. The registration process alone does not turn on any features. There is a recommendation to allow a [[#Minimum Application Library Support|minimum degree of control]], but in the end it is the programmer who decides what functionality offered by the library will be provided and supported in his/her application. That also includes the scope of external control: if you don't want your application to be controlled beyond a certain limit, your code will simply not react to certain incoming [[#Control Messages|control messages]].
|-
|''Q: Doesn't the Application Library duplicate functionality already present in commodities?''
|A: No. The only similarity between the two is that programs register with some system library, which then acts as a control centre. [[Commodities_Exchange_Library|Commodities]] provide a way to install custom input handlers into the [[Input_Device|Input Device]]'s event stream. The Application Library's field and scope of operation is completely different (and much wider).
|-
|''Q: Why is this a library? Wouldn't it be wiser to implement it as a class, like MUI does it?''
|A: This would tie the functionality to the object-oriented (BOOPSI) API – applications designed using [[GUI_Programming#The_Two_Frameworks|other APIs or toolkits]] would not be able to use it.
|-
|''Q: Can a program be registered both as an application and as a commodity?''
|A: Yes, that's possible – although few programs would probably benefit from that. Exceptions include application managers and taskbars (e.g. AmiDock), which may need to control other applications and, at the same time, behave like a commodity.
|-
|''Q: Being XML-based, do the PrefsObjects introduce any overhead to the operating system?''
|A: Hardly any. The [[PrefsObjects]] .xml preference files are, typically, only read when the application starts and written at user request, so there is minimum overhead involved. Accessing the prefs file during program runtime doesn't put any strain on the OS either, as the Application Library caches the file in a pre-parsed format in memory.
|}

=== Minimum Application Library Support ===

In the foreseeable future, AmigaOS will feature an application manager to control running applications. The idea is to extend or possibly even replace Exchange to offer a single, universal control point for both commodities and applications. In order to allow easy, consistent and predictable program control, developers are encouraged to [[#Registering the Application|register their applications]] and implement the following suggested minimum Application Library support:

* Provide a short [[#Description|description]] for a better identification of the application.
* Tell the OS whether the application supports iconification, that is, hiding/showing its GUI (for more information, see [[#Feature Set / Control Scope|this section]]). If iconification is supported:
** make the application respond to the [[#Control Messages|APPLIBMT_Hide and APPLIBMT_Unhide]] control messages;
** update the APPATTR_Hidden attribute accordingly each time your application iconifies or uniconifies.
* Allow the application to be shut down externally in a safe and graceful manner in reaction to the [[#Control Messages|APPLIBMT_Quit]] message.

A failure to implement this suggested minimum will mean that the OS application manager will be unable to control your application properly and consistently. This may cause confusion on the part of the users and degrade their AmigaOS experience.

== Library Opening Chores ==

{{Note|title=Note|text=Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2. This is due to changes in the Application Library API which had broken standard tag support until version 2 interfaces were introduced.}}

Just like other AmigaOS libraries, the Application Library must be opened before it is used. Further, at least one of its interfaces must be obtained, depending on the functionality you require. The Application Library has two interfaces, called “application” and “prefsobjects”. You always need to obtain the “application” interface because it provides access to most library functions including application registration. You’ll only need to open the “prefsobjects” interface if you intend to make use of the PrefsObjects preferences system.

<syntaxhighlight>
struct Library *ApplicationBase = NULL;
struct ApplicationIFace *IApplication = NULL;
struct PrefsObjectsIFace *IPrefsObjects = NULL;

if ( (ApplicationBase = IExec->OpenLibrary("application.library", 52)) )
{
IApplication = (struct ApplicationIFace *) IExec->GetInterface(ApplicationBase,
"application", 2, NULL);
IPrefsObjects = (struct PrefsObjectsIFace *) IExec->GetInterface(ApplicationBase,
"prefsobjects", 2, NULL);
}

if ( !ApplicationBase || !IApplication || !IPrefsObjects )
{
/* handle library opening error */
}
</syntaxhighlight>

Note that there is no interface called “main” like older, single-interface libraries have. The number in the GetInterface() call above refers to the version of the interface. Library interfaces are not backwards or forwards compatible so they must be specified precisely. '''Starting with AmigaOS SDK 53.24, both Application Library interfaces (application and prefsobjects) must be at version 2.''' This is due to certain changes in the Application Library API.

When your application has run its course, don’t forget to clean up and close both the library and its interface(s):

<syntaxhighlight>
IExec->DropInterface((struct Interface *)IPrefsObjects);
IExec->DropInterface((struct Interface *)IApplication);
IExec->CloseLibrary(ApplicationBase);
</syntaxhighlight>

== Registering the Application ==

Application registration is a simple process during which a program informs AmigaOS that it should be treated as an application, and provides some basic information about itself: the program name, an associated URL address, or a short description. Also, certain application-related properties can be set at registration time (although some of these may be provided or changed later). Registration typically takes place at program startup; unregistration is normally done at the end of program runtime.

*hint* Avoid using the _ underscore character in the registered name. These may cause "charsetconvert" errors when the system boots up later.

=== Application Identifiers ===

A successfully registered application receives a numeric identifier, which in this documentation will be referred to as ''appID''. The identifier is public: any registered application can obtain another application’s appID (see [[#Finding Applications|Finding Applications]] below) and use it to communicate with the respective application. AppIDs are unique integer numbers: the library generates them incrementally on a per-registration basis. They are never assigned again during the same AmigaOS session, which prevents programs from incidentally addressing the wrong application after the original appID holder unregisters.

Apart from the numeric appID an application can be referred to by its name (that is, a string-type identifier). As programs can get registered in an arbitrary order (and the same application will have a different appID each time), it is the name identifier that other applications must use to retrieve the correct appID. To construct a unique name, the Application Library uses a special naming scheme that combines:

* the application name;
* an instance count (if more than one instance of the same application is started);
* a URL identifier (for example, the domain name of the application’s homepage – optional).

The same naming scheme is used by the library’s PrefsObjects system to create the name of the preferences file.

=== Registration Functions ===

Now let’s say we have a program, a media player called Audio Monster created by the fictitious software company SuperCoders, Inc. The piece of C code to handle its registration (and unregistration) might look like this:

<syntaxhighlight>
uint32 appID;

appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
TAG_END);

if (!appID)
{
/* report registration error and quit */
}

/*
do whatever your program does
*/

IApplication->UnregisterApplication(appID, NULL);
</syntaxhighlight>

Note that we’ve had to alter the application name to “AudioMonster”; it is because the Application Library doesn’t allow spaces in application names. According to the naming scheme (outlined in the previous section) the application will now become registered under the name “AudioMonster.supercoders.com”. (Should a previous instance of Audio Monster be already running, the library will automatically append an instance counter to the application name: the second instance will therefore be called “AudioMonster_1.supercoders.com”, the third will register as “AudioMonster_2.supercoders.com”, and so on.)

Also note that the URL identifier is just the domain name, i.e. without the “www.” part. The identifier is only used to distinguish between applications, not to access their homepages. The domain name is, therefore, sufficient; the resulting name identifier needn’t be long and quirky.

After calling UnregisterApplication() the program will be removed from the public list, and Application Library features will no longer be available.

== Application Attributes ==

An application is described by a set of ''attributes''. There are attributes that describe the application's properties or feature set, indicate its current state, or determine its behaviour. Some attributes are only specified at registration time and cannot be altered once they are set, while others can be changed freely (as long as the application remains registered, of course). The general recommendation is to specify at registration time all properties that are not going to change during program lifetime: i.e. define all "static" application features in one place.

=== Description ===
The REGAPP_Description tag, used in the registration example code above, tells the system what the application is all about. Although the description is an optional attribute, it is recommended to always provide it, as it will allow application manager or taskbar programs to provide meaningful information to the user. Keep the description short, matter-of-fact and serious.

The application description cannot be changed after registration.

=== Uniqueness ===
A program can register as a ''unique application'', thus only allowing one instance of itself to run. While the multitasking nature and tradition of AmigaOS would suggest not imposing such limits, there sometimes can be good reasons to do so. For example, the developer of the Audio Monster player might decide to make his/her program a unique application because the user would most likely gain nothing from playing several media files at the same time. Multiple program instances would only compete for screen space and system resources, possibly jeopardizing OS performance on lower-specification computers.

The following function call will register Audio Monster as a unique application:

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_UniqueApplication, TRUE,
TAG_END);
</syntaxhighlight>

If the user now tries to launch a second instance of the program, it will fail on RegisterApplication() and the library will send a [[#Special Messages|special message]] to the first instance informing it about the attempt. It is the developer’s responsibility to react to this message in a sensible way. Do not show error messages here: the user doesn’t need to know (or care) that the application is unique, so an error message would scold them for doing nothing wrong. The recommended behaviour is to bring the first instance to view and activate its window.

Quite logically, uniqueness is an attribute that cannot be changed after registration.

=== Feature Set / Control Scope ===
Different applications can implement different control features, and can be designed for a different scope of external control. For example, a text editor may respond to a [[#Control Messages|control message]] (command) that tells it to create a new, blank, unnamed document, whereas in a media player such a command would be best ignored. Similarly, a simple tool with no configuration capability would want to stay clear of messages that control program settings. It is always good manners to inform the system about the scope of control your application supports, as other applications may query about (and rely on) this information when sending control messages. Always set the following boolean tags to TRUE in the RegisterApplication() call if your application implements support for the respective feature (the default value is FALSE):

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_HasIconifyFeature
|The application supports iconification and uniconification.
|Set to TRUE if your application responds to the APPLIBMT_Hide and APPLIBMT_Unhide messages.
|-
|REGAPP_HasPrefsWindow
|The application has a dedicated Preferences (Settings) window.
|Set to TRUE if your application responds to the APPLIBMT_OpenPrefs message.
|-
|REGAPP_CanCreateNewDocs
|The application can create new documents (projects).
|Set to TRUE if your application responds to the APPLIBMT_NewBlankDoc message.
|-
|REGAPP_CanPrintDocs
|The application can print documents.
|Set to TRUE if your application responds to the APPLIBMT_PrintDoc message.
|}

These four attributes can be changed after registration.

=== Receiving Notifications ===

The Application Library can send certain notification messages that may be of interest to special-purpose programs like application managers, taskbars or screen blankers. If you are developing such a program, you may want to register for the following notifications:

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|REGAPP_AppNotifications
|Receive notifications about application registration/unregistration, icon type changes, GUI state changes (hidden/unhidden), and changes in the last used applications/documents list.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to application managers and taskbar-like programs.
|-
|REGAPP_BlankerNotifications
|Receive notifications concerning blanker activity.
|Set to TRUE if you want to receive such notifications. These messages will only be useful to screen blankers.
|}

Other types of application should not normally ask to receive these notifications: they would only increase traffic along their input stream.

These two attributes can be changed after registration.

=== Changing Application Attributes ===

Certain attributes describe "dynamic" application properties and, as such, can be set or changed after registration. Some of these are ''state attributes'' that need to be updated each time your program changes state (shows/hides its GUI, or enters the game mode; see below in the table). Some are not really attributes but, rather, commands that invoke an application-related action.

{| class="wikitable"
!Tag
!Description
!Implementation notes
|-
|APPATTR_AllowsBlanker
|Same as REGAPP_AllowsBlanker above.
|You may want to be able to enable/disable blanking dynamically during application runtime – this what the APPATTR_AllowsBlanker tag is for. For example, a presentation program may allow blankers while the presentation is being worked on, and disable them when the presentation is started.
|-
|APPATTR_AppOpenedDocument
|Adds a new entry to the application's Last Used Documents list.
|Set this tag each time your application has successfully opened a named document or project. The parameter to this tag is a pointer to the name string (i.e. a STRPTR).
|-
|APPATTR_AppNotifications APPATTR_BlankerNotifications
|Same as the two corresponding [[#Receiving Notifications|registration tags]] above.
|
|-
|APPATTR_CanCreateNewDocs APPATTR_CanPrintDocs APPATTR_HasIconifyFeature APPATTR_HasPrefsWindow
|Same as the four corresponding [[#Feature Set / Control Scope|registration tags]] above.
|Prefer setting these properties at registration time.
|-
|APPATTR_ClearLastUsedDocs
|Clears the application's list of last used documents.
|Set this tag to TRUE to clear the list. (Note that this is not really an attribute but, rather, a command.)
|-
|APPATTR_FlushPrefs
|
|
|-
|APPATTR_Hidden
|A boolean program-state attribute indicating whether the application is currently iconified (hidden) or not.
|Update this attribute each time your application GUI changes state, as application managers may query about (and rely on) this information.
|-
|APPATTR_IconType
|Changes the application icon type.
|
|-
|APPATTR_MainPrefsDict
|Allows changing the application's Prefs dictionary.
|
|-
|APPATTR_NeedsGameMode
|A boolean program-state attribute informing the system (and other applications) that the program is about to enter, or has left, the game mode.
|By the "game mode" we understand a mode in which an application doesn't want to be "disturbed" by other applications. It normally assumes full screen operation, and possibly taking over the audio system. Games or presentation programs are examples of applications that may want to implement the game mode, in which other programs are simply asked to “keep quiet”: not try to play sounds, open windows, requesters, etc. This feature assumes discipline and cooperation on the part of other applications; please use it moderately and only enter the game mode when it is really needed. Also note that setting APPATTR_NeedsGameMode to TRUE does not guarantee that other applications will comply.
|-
|APPATTR_SavePrefs
|Same as REGAPP_SavePrefs above.
|
|}

The function to set or change application attributes is SetApplicationAttrs(). It is very similar to SetAttrs() used in Intuition programming, only the first parameter is not a pointer to a BOOPSI object but an application identifier. The appID is followed by a tag list, so several attributes can be set at a time. The following example call will inform the system that the application has iconified (or otherwise hidden its GUI) and that the screen blanker can now come to front freely (assuming that the blanker was forbidden before for some reason). The result value indicates whether the call was successful or not:

<syntaxhighlight>
BOOL result;

result = IApplication->SetApplicationAttrs(appID,
APPATTR_Hidden, TRUE,
APPATTR_AllowsBlanker, TRUE,
TAG_END);
</syntaxhighlight>

== Finding Applications ==

The Application Library maintains a public list of all registered applications. Certain special-purpose programs – ''application managers'' – will read this list (also keeping track of all subsequent registrations and unregistrations) and offer some degree of control: display information about applications and/or send commands telling them to do something. Quite naturally, most programs will not (nor are they supposed to!) act as managers but a need to talk to another application may arise. How do you find it, then?

Finding an application basically means obtaining its appID: it is an identifier as well as a “contact address” for the library's messaging system. To do this you need to know at least one of the following:

* the application name, ie. the one under which it was registered via RegisterApplication();
* the application name identifier, ie. the unique combination of the application’s name, instance number (should there be more instances running) and URL identifier – see [[#Application Identifiers|Application identifiers]] above;
* the pathname pointing to the program file on disk, e.g. “Work:Utils/AudioMonster”.

Based on this information, the respective piece of code that will find our application in the system might look like this:

<syntaxhighlight>
uint32 appID;

/* if you only know the application name */
appID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster",
TAG_END);

/* if you know the application name identifier */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster.supercoders.com",
TAG_END);

/* if you specifically want to talk to the second running instance */
appID = IApplication->FindApplication(FINDAPP_AppIdentifier, "AudioMonster_1.supercoders.com",
TAG_END);

/* if you know the pathname to the program file */
appID = IApplication->FindApplication(FINDAPP_FileName, "Work:Utils/AudioMonster",
TAG_END);
</syntaxhighlight>

Once you have obtained the appID you can start communicating with the respective application.

== Messaging ==

Messages are used extensively in AmigaOS: the inner workings of Exec or Intuition actually involve a good deal of message passing. But it’s not just the operating system that needs to communicate. Modern software applications often want to talk to other running applications. Regardless of whether this communication will, in real use, entail a simple command-driven action or an intricate exchange of data, AmigaOS provides the necessary means: inter-program communication is supported on the low level (through Exec Library’s [[Exec Messages and Ports|messages and ports]]) as well as on the high level (using the ARexx-language scripting features). The Application Library has introduced yet another means of communication, which can be seen as lying somewhere in between the two levels.

Provided that you know its appID, you can send messages to any running application that is ready to accept them. You can even send a message to all applications at once! Basic application control can be achieved via a set of [[#Control Messages|predefined messages]] that correspond to common program commands and functions (such as New, Open, Print, Iconify or Quit). But the library also supports [[#Custom Messages|custom messages]], thus allowing for more sophisticated control or information exchange. The extent and complexity of messaging is fully up to the programmer: your application will only send/receive messages that you will implement (it has already been mentioned in the [[#Frequently Asked Questions|Frequently Asked Questions]] section above that registration alone does not magically turn on any features).

Furthermore, apart from this “invisible”, abstract communication taking place between application ports, you can use the library to provide real and visible information in the form of pop-up notification messages. However, as these are different and not really within the scope of the Application Library messaging framework, they are dealt with in a [[#Pop-up Notifications (Ringhio Messages)|separate section]] of this document.

{{Note|Before we get any further with Application Library messages, it must be made clear that they should not be confused with the similarly-named ''AppMessages''. The latter are a completely different breed, governed by the Workbench Library. They represent a specific way of communication between the Workbench desktop environment and running applications. It’s strictly one-way communication because Workbench can send AppMessages to applications but applications cannot send AppMessages to Workbench. (If you want to learn more about the use of AppMessages, consult the [[Workbench Library|Workbench Library]] section of the AmigaOS documentation wiki).
}}

=== Data Structures ===

Rather than introduce yet another system for communication, the Application Library builds upon the existing [[Exec_Messages_and_Ports|Exec messaging framework]]. Programmers will, therefore, find working with Application Library messages rather familiar. For instance, the library uses data structures that are in fact extensions of the standard Exec message structure. Also, the usual procedure of [[Exec_Messages_and_Ports#Getting_a_Message|GetMsg()]] and [[Exec_Messages_and_Ports#Replying|ReplyMsg()]] takes place when processing incoming Application Library messages (see section [[#Message Handling|Message Handling]] below) – although the library implements its own method for [[#Sending Messages|sending messages]].

The following three structures are defined for carrying Application Library message data:

<syntaxhighlight>
struct ApplicationMsg
{
struct Message msg;
uint32 senderAppID; // the appID of the sender application
uint32 type; // identifies the type of message
};

struct ApplicationOpenPrintDocMsg
{
struct ApplicationMsg almsg;
STRPTR fileName;
};

struct ApplicationCustomMsg
{
struct ApplicationMsg almsg;
STRPTR customMsg;
};
</syntaxhighlight>

As you can see, structure ''ApplicationMsg'' contains a standard ''[[Exec_Messages_and_Ports#Messages|struct Message]]'', the other fields are used for Application Library-specific data. The other two structures are mere extensions of the basic one: ''ApplicationOpenPrintDocMsg'' is used by certain [[#Control Messages|control messages]] that require a pointer to a filename; the ''ApplicationCustomMsg'' structure is used for [[#Custom Messages|custom messages]].

Upon message arrival you identify the message by reading the “type” field of the respective data structure. Similarly, if you want to [[#Sending Messages|send a message]] to an application you specify it in the “type” field.

=== Control Messages ===

The Application Library allows registered applications to send messages that control other applications. There is a set of predefined messages (or rather, commands) that can be sent to a running application, telling it – for example – that it should come to front, quit, open a document, create a new one, and so on. As these actions are common program functions, the library offers a practical and easy-to-implement way to control applications externally. The following control messages (commands) are currently provided:

{| class="wikitable"
!Message name
!Description
!Implementation notes
|-
|APPLIBMT_Quit
|The application is asked to shut down itself and quit.
|Basically, upon receiving this message you should react as if your main program window received the WMHI_CLOSEWINDOW event. When implementing support for APPLIBMT_Quit, the programmer is required to design the program exit sequence in such a way that no unexpected data loss can occur (for example, by displaying a confirmation requester that allows the user to save work or cancel the quit command).
|-
|APPLIBMT_ForceQuit
|Same as before but this time the application shall quit immediately, without asking for saving documents etc.
|Providing this command as part of the Application Library messaging framework was surely meant well but there is an inherent risk: a malevolent application could hamper the use of other applications by sending them this message and making them quit prematurely. So implement APPLIBMT_ForceQuit with care, or don't implement it at all. The official AmigaOS application manager will never try to send APPLIBMT_ForceQuit in order to shut down running applications.
|-
|APPLIBMT_Hide
|The application shall hide its interface and iconify on the Workbench screen.
|rowspan="2"|An application that supports APPLIBMT_Hide and APPLIBMT_Unhide is expected to register itself with REGAPP_HasIconifyFeature set to TRUE. Basically, upon receiving this message you should react as if your main program window received the WMHI_ICONIFY / WMHI_UNICONIFY event.
|-
|APPLIBMT_Unhide
|The application shall come back from the iconified (hidden) state.
|-
|APPLIBMT_ToFront
|The application window shall come to front.
|Programmatically that entails calling the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. See the end of the [[#Message Handling|Message Handling]] section for a note on APPLIBMT_ToFront.
|-
|APPLIBMT_OpenPrefs
|The application shall open its preferences window.
|Only implement if your application has a dedicated Preferences (Settings) window. An application that supports APPLIBMT_OpenPrefs is expected to register itself with the REGAPP_HasPrefsWindow set to TRUE.
|-
|APPLIBMT_ReloadPrefs
|The application shall reload its preferences.
|Whatever this command is useful for.
|-
|APPLIBMT_NewBlankDoc
|The application shall open a new, blank document or project.
|Applications such as web browsers can, too, make use of this command to open new program windows. An application that supports APPLIBMT_NewBlankDoc is expected to register itself with the REGAPP_CanCreateNewDocs set to TRUE.
|-
|APPLIBMT_OpenDoc
|The application shall try to open a specific document or project.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above).
|-
|APPLIBMT_PrintDoc
|The application shall try to print a specific document.
|The name of the document is passed as part of the message data structure (''struct ApplicationOpenPrintDocMsg'': see [[#Data Structures|Data Structures]] above). An application that supports APPLIBMT_PrintDoc is expected to register itself with the REGAPP_CanPrintDocs set to TRUE.
|}

An application will only react to messages that are implemented and supported. If you [[#Sending Messages|send a message]] to an application that is registered but does not perform any Application Library event handling, there will be no reaction at all. Further, many applications will only implement a subset of the available control commands: if a program does not have a Print function, an APPLIBMT_PrintDoc message will quite logically be ignored. There is no rule saying which or how many control messages should be implemented but you are encouraged to provide the [[#Minimum Application Library Support|minimum suggested support]] as outlined above. Implement the rest according to your application’s features and needs, and to the highest standards of security.

=== Custom Messages ===

In contrast to a [[#Control Messages|control message]] (see above), a custom message has no meaning or purpose predefined by the library. It is a simple text string the actual meaning of which is determined by the application. There is some undeniable beauty in this concept. For instance, the application can define a set of “publicly available” commands that call a corresponding function whenever a particular command (text string) arrives from another application. This kind of external control is very easy to implement and represents a practical alternative to [[UI_Style_Guide_Glossary#ARexx|ARexx]], while requiring less setup. Also, sender applications need not care about internals (such as knowing the ARexx port name) – all it takes is to [[#Finding Applications|find]] the receiver application and [[#Sending Messages|send a message]] to it.

The pointer to the message text string is contained in a special [[#Data Structures|data structure]], ''struct ApplicationCustomMsg''.

=== Special Messages ===

There are also some special messages that an application can receive from the library or another running application:

{| class="wikitable"
! Message name !! Description !! Implementation notes
|-
| APPLIBMT_Unique || If an application is registered as [[#Uniqueness|unique]] and the user attempts to start a second instance of the program, the attempt will fail and the library will send an APPLIBMT_Unique message to the first instance. || All unique applications should listen for this message and react to it: not doing so might leave the user puzzled as to why the program hasn’t started. The recommended reaction is to bring the first instance to view and focus. This may entail a couple of steps, like uniconifying (if the program is iconified at the moment), swapping screen (if the program runs on a dedicated screen), bringing the program window to front, and activating it. Basically, the APPLIBMT_Unique message should be treated in the same way as the APPLIBMT_ToFront message.
|-
| APPLIBMT_GameModeEntered || Sent to all currently running applications if another application enters the “game mode” – that is, a state in which it doesn’t want to be disturbed. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to TRUE.
|-
| APPLIBMT_GameModeLeft || Informs all running application that the sender has left the game mode. || The message is sent around whenever an application sets its APPATTR_NeedsGameMode attribute to FALSE.
|}

=== Message Handling ===

You already know that messaging in AmigaOS takes place between [[Exec_Messages_and_Ports#Message_Ports|message ports]]. Being a superset of standard Exec messages, Application Library notifications (be they predefined [[#Control Messages|control messages]], [[#Custom Messages|custom messages]] or [[#Special Messages|special messages]]) are, too, sent to a message port. We’ll call this dedicated port – in order to distinguish it from other ports possibly used by the program – the ''notification port''. The port is automatically created by the library at registration time and freed as part of the UnregisterApplication() call. Messages arriving at the port are meant to be processed within the program’s main event loop, together with other events (such as Intuition’s [[Intuition_Input_and_Output_Methods#Receiving_Input_Events_from_Intuition|IDCMP messages]]). To process incoming messages you first need to obtain the notification port pointer from the library and then set the port’s signal bit. The signal bit is used to identify messages as Application Library notifications.

A simplified event loop code could look like the one below. Note that this example loop only waits for and processes Application Library messages. In real use you'll also want to handle other message types, such as input from the user interface (IDCMP events) or ARexx commands.

<syntaxhighlight>
void event_loop(uint32 appID)
{
struct MsgPort *notificationPort = NULL;
struct ApplicationMsg *appLibMsg = NULL;
struct ApplicationCustomMsg *customMsg = NULL;
uint32 appLibSignal = 0, sigGot = 0;
BOOL done = FALSE;

/* Obtain pointer to Application Library's notification port and set the signal bit. */
IApplication->GetApplicationAttrs(appID, APPATTR_Port, &notificationPort, TAG_END);
appLibSignal = (1L << notificationPort->mp_SigBit);

/* Go into the event loop. */
while (!done)
{
/* Wait for a signal to arrive. */
sigGot = IExec->Wait(appLibSignal);

/* Process all Application Library messages. */
if ( sigGot & appLibSignal )
{
/* Obtain pointer to the message. */
while ( (appLibMsg = (struct ApplicationMsg *) IExec->GetMsg(notificationPort)) )
{
/* Identify the type of message. */
switch (appLibMsg->type)
{
case APPLIBMT_Quit:
case APPLIBMT_ForceQuit:
done = TRUE;
break;

case APPLIBMT_ToFront:
/* Make the program window come to front. */
break;

case APPLIBMT_Hide:
/* Iconify the program. */
break;

case APPLIBMT_Unhide:
/* Uniconify the program. */
break;

/* Process the custom message as you like.
Here we just use printf() to output the message text. */
case APPLIBMT_CustomMsg:
customMsg = (struct ApplicationCustomMsg *) appLibMsg;
printf("The message text is: %s\n", customMsg-> customMsg);
break;

/*
Process any other Application Library messages.
*/

}
/* Return the processed message to the sender so that it can be freed. */
IExec->ReplyMsg( (struct Message *) appLibMsg);
}
}
}
</syntaxhighlight>

Like all [[Exec_Messages_and_Ports#Messages|Exec messages]] obtained via the GetMsg() function, Application Library messages must be [[Exec_Messages_and_Ports#Replying|replied to]], i.e. returned to the sender after they have been processed. This is what the last command does in the code above. Remember that all message resources are freed after ReplyMsg() so should you need to use the message data (for example, the custom message text string) beyond the event loop, you must copy it to a memory storage of your own.

Also remember that the notifications are addressed to an abstract ''application'' – this makes them rather different from IDCMP messages, which are always sent to a particular ''window'' (Intuition is unaware of the application concept). Whereas Intuition stops sending IDCMP messages as soon as the window becomes closed/iconified, the Application Library keeps passing messages as long as the application is registered, regardless of program window state. So be smart in your code when processing Application Library notifications: check for the availability of the program window and perform uniconification when necessary. For example, if an APPLIBMT_ToFront command is sent to your iconified application, there is no window to come to front; you need to uniconify it first and only then call the ScreenToFront(), WindowToFront() and ActivateWindow() sequence. The mistake of referencing a non-existing window is as silly as it is easy to make!

=== Sending Messages ===

While incoming notifications are [[#Message Handling|processed]] pretty much like normal Exec messages, the Application Library implements its own method for message sending. It takes three simple steps to send a message to another application:

# Prepare the respective [[#Data Structures|data structure]]: specify the type of message and supply the sender's [[#Application Identifiers|identifier]] (appID).
# [[#Finding Applications|Find the receiver]] application.
# Send a message to it via the SendApplicationMsg() function.

For example, if you want to tell the Audio Monster application to quit, you send it an APPLIBMT_Quit message like this:

<syntaxhighlight>
struct ApplicationMsg appMsg; // message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Step 1: Prepare the message data structure. */
appMsg.senderAppID = appID; // identifier of the sender
appMsg.type = APPLIBMT_Quit; // type of message

/* Step 2: Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Step 3: Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
&appMsg,
APPLIBMT_Quit);
}
</syntaxhighlight>

Should you want to send your message to all currently registered applications at once, just use a receiver appID of 0.

Sending [[#Custom Messages|custom messages]] is done in a similar fashion, the only difference is that you must use a dedicated [[#Data Structures|data structure]] instead of the generic ''struct ApplicationMsg''. As our Audio Monster application is a media player, it may as well have defined a set of commands for external control, one of them being “Start playback”. Now if another application wants to tell Audio Monster to start playing, it will need to send the custom message like this:

<syntaxhighlight>
struct ApplicationCustomMsg customMsg; // custom message data structure
uint32 audioMonsterID; // identifier of the receiver

/* Prepare the message data structure. */
customMsg.almsg.senderAppID = appID; // identifier of the sender
customMsg.almsg.type = APPLIBMT_CustomMsg; // type of message
customMsg.customMsg = "Start playback"; // message text

/* Find the receiver application. */
if ( (audioMonsterID = IApplication->FindApplication(FINDAPP_Name, "AudioMonster", TAG_END)) )
{
/* Send the message. */
IApplication->SendApplicationMsg(appID,
audioMonsterID,
(struct ApplicationMsg *) &customMsg,
APPLIBMT_CustomMsg);
}
</syntaxhighlight>

== Pop-up Notifications (Ringhio Messages) ==

As from the introduction of the Ringhio server in AmigaOS 4.1 Update 1, registered applications can inform the user via notifications displayed in a small pop-up box. These are sometimes called ''Ringhio messages'' because the server provides means through which the messages are communicated visually (in other words, Ringhio handles the actual display of messages sent by the Application Library). [[File:RinghioNotification.png|frame|Ringhio notification example]] The pop-ups function similarly to [[Intuition Requesters|requesters]] in that they show a text message; but unlike requesters, Ringhio messages do not require user interaction or acknowledgement. They just show up briefly and disappear – which makes them great for informing about less significant, matter-of-fact events such as that a certain task has been completed (this is especially helpful if the application is hidden or runs on a different screen, as the user is kept informed about something that is currently beyond his/her visual control).

Of all the types of Application Library messages, pop-up notifications are surely the easiest to program. They don’t require any setup or event handling; all it takes is a single function call:

<syntaxhighlight>
uint32 result;

result = IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
TAG_END);
</syntaxhighlight>

The first parameter is your application’s appID received from the [[#Registration Functions|registration function]]. The APPNOTIFY_Title tag specifies a short heading for the pop-up box while APPNOTIFY_Text contains the actual message text. Certain limits to text length apply to ensure that the pop-up remains easy to read: 64 characters for the heading (title) and 128 characters for the text (160 characters as of Ringhio 53.23). This particular message will display on the frontmost public screen (as specified in the APPNOTIFY_PubScreenName tag), which may as well be the right setting for most applications. You can of course provide any other public screen name – or you can call Notify() without this tag and let the library use the default, which is the [[Public_Screen_Type#The_Default_Public_Screen_and_Workbench|Workbench screen]].

The result value shows whether the call was successful; 0 means that an error has occurred and Ringhio failed to display the pop-up. Depending on the significance of the message, you may want to react upon the failure and inform the user through other means of communication, such as a requester.

The look and position of the pop-up box is configurable from the Notifications editor located in the Prefs drawer on your system partition. This is Ringhio’s preferences editor: as we have explained above, it is Ringhio that is responsible for the actual display of notification messages. The pop-up box can also show a small custom image (like the one in the picture above) to make the message more easily identifiable as related to a particular application. The maximum size of the image is 32x32 pixels. It can be any format, provided that there is a datatype for it installed in the system. Being application-specific, these images logically cannot be configured system-wide through the Notifications editor; instead, they are specified as part of the Notify() call. Note that a full path to the image file must be provided:

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "All right, ma!",
TAG_END);
</syntaxhighlight>

But what is this APPNOTIFY_BackMsg thing? It has been mentioned above that notification messages do not require user interaction: they display some text and go away. Nevertheless, Ringhio can send the application a [[#Custom Messages|custom message]] (called “back message” – hence the name of the tag) if the user has double-clicked on the message box. As the code snippet shows, this custom message takes the form of a text string (within the Application Library messaging context, [[#Custom Messages|custom messages]] are always text strings). It is sent to the same event stream, and is supposed to be processed within the same event loop, as other Application Library messages – see the [[#Message Handling|Message Handling]] section for how to go about it.

Whether receiving a “back message” would be useful for a particular application, and whether it would make sense to react upon it, is decided by the programmer. The reaction (if any – often none is needed) should be sensible and logical. Make sure not to misuse the feature! Note that Ringhio messages are not requesters, and double-clicking on the message box does not really equal pressing a requester button. Therefore, receiving the message could be interpreted as the user’s acknowledgement of what Ringhio has said, but never as a selection of an option. Do not use Ringhio to request input via the back-message feature: the text of the message should be a statement, not a question or an offer of choice. Considering this logic, the double click means “I understand”; it doesn't mean “Yes” or “No”.

If the text string provided in the APPNOTIFY_BackMsg tag is an URL, the feature works rather differently. Instead of sending the message to the event stream, this particular URL is opened in your default web browser. Because the process is done through the Launch Handler, your system should be recent enough to have it (the Launch Handler was introduced in AmigaOS 4.1 Update 1). The following piece of code will open Audio Monster’s homepage if the user double-clicks on the Ringhio box. The last in the tag list, APPNOTIFY_CloseOnDC, causes the message box to disappear right after the double click.

<syntaxhighlight>
IApplication->Notify(appID,
APPNOTIFY_Title, "Important Message",
APPNOTIFY_Text, "Your socks need changing!",
APPNOTIFY_PubScreenName, "FRONT",
APPNOTIFY_ImageFile, "PROGDIR:Images/AudioMonster.jpg",
APPNOTIFY_BackMsg, "URL:http://www.supercoders.com",
APPNOTIFY_CloseOnDC, TRUE,
TAG_END);
</syntaxhighlight>

=== Pop-up Message Style Guide ===

* Keep the message text short. Give the user chance to read the entire message before it disappears.
* Do not use pop-up messages to report errors. An error is usually a serious situation, and as such it cannot be dismissed by simply displaying an automatic message (which can easily get missed or overlooked).
* Use the pop-up message facility with moderation. Displaying the messages too frequently might hamper the workflow, and would most probably annoy the user.

== Function Reference ==

The following are brief descriptions of the Application Library functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| FindApplication()
| Searches for a previously registered application.
|-
| FreeApplicationList()
| Frees the list of applications generated by GetApplicationList().
|-
| GetAppLibAttrs()
| Obtains global Application Library attributes.
|-
| GetApplicationAttrs()
| Obtains attributes of a registered application.
|-
| GetApplicationList()
| Obtains the list of all currently registered applications.
|-
| LockApplicationIcon()
| Attempts to lock an application icon.
|-
| Notify()
| Displays a pop-up message box.
|-
| RegisterApplication()
| Registers an application.
|-
| SendApplicationMsg()
| Sends a message to a registered application.
|-
| SetAppLibAttrs()
| Sets or changes global Application Library attributes.
|-
| SetApplicationAttrs()
| Sets or changes application attributes.
|-
| UnlockApplicationIcon()
| Unlocks an application icon.
|-
| UnregisterApplication()
| Unregisters an application.
|}

PrefsObjects

2015-09-18T12:27:32Z

Daniel Jedlicka: Made this a separate wiki page.

== Introduction ==

Many applications are user-configurable so they need a way to store their settings; we traditionally use the term ''preferences'' or simply ''prefs'' in the AmigaOS context. It may come as a surprise that before version 4.x, AmigaOS had no real standard for storing preference data. Developers used various, often proprietary solutions: [[Icon_Library#The_Tool_Types_Array|icon tooltypes]], IFF-based formats, text files mimicking the Windows ''.ini'' format, or binary formats. Some of them are still very popular (tooltypes) or even used by the OS itself (some [[UI_Style_Guide_Preferences#Preferences|system preferences]] are stored as IFF-PREF files). While this is not a place to go into detail and discuss their particular advantages and disadvantages, let’s mention two common drawbacks that ultimately led to the development of the Application Library PrefsObjects system:

# All of the solutions above require you to implement your own preferences handling code (that is, routines for parsing, verification, and saving).
# None of the various formats used have ever provided a smart enough way to administer complex, structured settings.

Since its introduction in AmigaOS, PrefsObjects has largely been promoted as being ''XML-based'' and therefore human-readable and easy to edit. Yet using an industry standard format that is platform-independent and supports Unicode is not the biggest “selling point” of PrefsObjects. What makes it different from (and superior to) previous solutions is not the fact that it is XML-based but, rather, that it is ''object-oriented''. Among other things, this property also helps address the two drawbacks mentioned above.

Imagine, for example, a program that uses a plug-in system. Both the main program and its plug-in modules are configurable. Instead of having ten or more individual preference files, you’ll likely want a single file containing settings for the program as well as for the plug-ins. This naturally introduces a certain hierarchy. Plus, as some plug-ins may be delivered by third parties, the particular structure of the prefs file is somewhat beyond the control of the main program: the amount, contents and sequencing of data in the file depends on which plug-ins are installed and on how (and when, if ever) they store their settings. You would have to take all of this into account when implementing your own prefs-handling routines, which means a good deal of work.

== The Interface and its Functions ==

The [[Application_Library#Library Opening Chores|Library Opening Chores]] section of the Application Library documentation says that the library has two interfaces, called “application” and “prefsobjects”, respectively. If you want to implement your program preferences using the PrefsObjects system, you must obtain the “prefsobjects” interface: all the necessary functions and methods are contained therein. Naturally, your application must be registered before you can make use of PrefsObjects.

All operations related to settings – retrieving, adding and changing –, as well as all operations related to the prefs file itself – creation, loading and saving – are performed solely through the library functions. Some operations can even be automated, sparing the programmer from unnecessary hassle.

== Object Types ==

PrefsObjects tackles the task by seeing data as ''objects'', and by providing functions and methods for object manipulation. Loading, adding, updating or removing preference objects (be they single items or entire clusters of settings) then becomes a matter of calling the respective function – “invoking the method on the object”, as we say in object-oriented programming. If you are acquainted with this philosophy (as used, for example, in Intuition’s [[BOOPSI]] framework), you will find working with PrefsObjects very easy and straightforward.

PrefsObjects distinguishes between six object types:

{| class="wikitable"
! Object Type
! Description
|-
| Dictionary || A container to encapsulate (embed) other objects. The prefs file usually has a Dictionary object at the top level.
|-
| Array || A container to encapsulate other objects. The difference between a Dictionary and an Array is in object referencing: in Arrays encapsulated objects are referenced by an index, while in a Dictionary they are referenced by a name (key string).
|-
| Number || An object to carry a long integer, double, or a boolean value.
|-
| String || An object to carry a text string.
|-
| Date || An object to carry date and time information.
|-
| Binary || An object to carry arbitrary binary data. However, binary data should be avoided as much as possible because it's restrictive in its form and is not future-proof, as it does not enable addition or removal of data without compromising compatibility.
|}

== The Preferences File ==

The files generated by the Application Library's PrefsObjects system are standard XML documents. They are encoded in UTF-8 (which AmigaOS doesn't support directly) but that doesn't necessarily pose a problem. First, you rarely need to edit prefs files manually – nor are you encouraged to do so, unless the file has become corrupted or contains a setting that prevents the application from starting up or running properly. Second, characters beyond the ASCII range are rarely used in preferences, so the prefs files will likely be readable and editable even in a text editor that has no notion of UTF-8. And third, you can always use the dedicated [[PrefsObjectsEditor]], located in the Utilities drawer on your system disk, which allows easy and safe editing of PrefsObjects files (the usage of this tool is, however, out of the scope of this page).

As already mentioned above, all data access is handled by the Application Library. On the part of the programmer (or the application user), no actual knowledge of XML is required.

=== File Structure ===

The preferences file normally starts with a Dictionary object at the top level. The advantage of using a Dictionary is that objects stored in it are identified by a name (called a “key”). Using named objects is very practical. Unlike in Arrays, where objects are indexed, the order of data is quite irrelevant as long as you deal with objects on the same level. Your application can retrieve, add, modify, re-sequence or remove individual objects in an arbitrary order without having to worry about breaking anything: a named object will always be addressed properly if it exists.

Object names (keys) must be unique at each particular level. In other words, you cannot have two settings items (objects) with the same key in the same dictionary. However, identical object names can be used in different dictionaries. The following example shows a prefs file structure that embeds two separate dictionaries named “Screen settings” and “Window settings”. As you can see, identical keys (“Name”, “Width” and “Height”) are then used without collision:

<center>
<classdiagram type="orderly" scale="80" dir="prf">
[“Root”\n(Dictionary)]->[“Screen settings”\n(Dictionary)]
[“Window settings”\n(Dictionary)]->[“Height”\n(Number) ]
[“Window settings”\n(Dictionary)]->[“Width”\n(Number) ]
[“Window settings”\n(Dictionary)]->[“Name”\n(String) ]
[“Root”\n(Dictionary)]->[“Window settings”\n(Dictionary)]
[“Screen settings”\n(Dictionary)]->[“Height”\n(Number)]
[“Screen settings”\n(Dictionary)]->[“Width”\n(Number)]
[“Screen settings”\n(Dictionary)]->[“Name”\n(String)]
</classdiagram>
</center>

The diagram also illustrates the hierarchical nature of the PrefsObjects system: the fact that objects can be embedded inside other objects.

== Reading Preferences ==

In most cases, there will be just one preferences file associated with your application. If all you need is simply read settings from the file (and save them upon user request), it is recommended that you let the Application Library handle the file access. Registering your application like this

<syntaxhighlight>
appID = IApplication->RegisterApplication("AudioMonster",
REGAPP_URLIdentifier, "supercoders.com",
REGAPP_Description, "A media player",
REGAPP_LoadPrefs, TRUE,
TAG_END);
</syntaxhighlight>

will tell the library to access the prefs file automatically, under its default name and from the default location. The default naming scheme for prefs files uses the application name combined with the [[Application_Library#Application Identifiers|URL identifier]]. Also, the ''.xml'' extension is appended at the end of the name to identify the document format. So with this particular registration call, the default file name will be “AudioMonster.supercoders.com.xml” and the library will try to access it from the ENV: directory. (Don't worry, both the file name and location can be changed.)

If the file is found, the library will internally allocate a Dictionary object and read the settings into it. If the file is not found, the library will allocate an empty Dictionary for you. In either case the said Dictionary object will become the application's ''Main Prefs Dictionary'' and will be associated with the application as one of its attributes. (The application may use multiple prefs Dictionaries but at any given point in time, only one of them is main.)

After start-up and registration, the application will typically want to access the settings in order to configure itself. Having used ''REGAPP_LoadPrefs, TRUE'' in the registration call above, we should now have the application's Main Prefs Dictionary somewhere in memory, to which we need to obtain a pointer. This is done through the function GetApplicationAttrs() because as explained above, the Main Prefs Dictionary is an application attribute. After that we can use dedicated functions to access the individual objects (i.e. settings items) in the Dictionary.

The code fragment below assumes that our prefs file – already loaded by the registration routine and transformed into an object – contains three settings items:

* a boolean value stored in the file under the key of “Switch”;
* a numeric value of type uint32 stored under the key of “Number”;
* a text string stored under the key of “String”.

We first obtain the pointer to the prefs Dictionary object, retrieve the three values, and store them in a dedicated data structure:

<syntaxhighlight>
/* Default settings */
#define DEF_SWITCH TRUE
#define DEF_NUMBER 100
#define DEF_STRING "Play it again, Sam!"

struct Settings
{
BOOL switch;
uint32 number;
STRPTR string;
};

PrefsObject *myPrefsDict = NULL; /* Main Prefs Dictionary */
struct Settings mySettings; /* Structure to hold the settings */

/* Obtain the Dictionary object pointer */
IApplication->GetApplicationAttrs(appID, APPATTR_MainPrefsDict, &myPrefsDict, TAG_END);

if ( myPrefsDict )
{

/* Retrieve the settings values.

Note: here we need to cast the type of the number and of the string value
to avoid compiler warnings. This is because DictGetIntegerForKey()
and DictGetStringForKey() return int32 and CONST_STRPTR, respectively,
whereas our program declares them as uint32 and STRPTR.
*/
mySettings.switch = IPrefsObjects->DictGetBoolForKey(myPrefsDict, "Switch", DEF_SWITCH);
mySettings.number = (uint32) IPrefsObjects->DictGetIntegerForKey(myPrefsDict, "Number", DEF_NUMBER);
mySettings.string = (STRPTR) IPrefsObjects->DictGetStringForKey(myPrefsDict, "String", DEF_STRING);

/* Test out the string value. */
IDOS->Printf("All I want to say is: %s\n", mySettings.string);
}
</syntaxhighlight>

Should any of the settings items be missing, the respective default value is used. This will be the case, for example, when a physical XML prefs file is not present and the PrefsObjects system supplies an empty Dictionary.

(to be continued)

== Function Reference ==

The following are brief descriptions of the PrefsObjects-related functions. See the SDK/Autodocs for details on each function call.

{| class="wikitable"
! Function
! Description
|-
| BeginDeserialization()
| Begins the deserialization of a prefs object.
|-
| DictGetBoolForKey()
| Obtains a boolean value for a dictionary key.
|-
| DictGetIntegerForKey()
| Obtains an integer value for a dictionary key.
|-
| DictGetObjectForKey()
| Obtains an object for a dictionary key.
|-
| DictGetOptionForKey()
| Obtains a string from an option table.
|-
| DictGetStringForKey()
| Obtains a string value for a dictionary key.
|-
| DictSetObjectForKey()
| Sets an object for a dictionary key.
|-
| PrefsArray()
| PrefsObjects array object access function.
|-
| PrefsBaseObject()
| PrefsObjects base object access function.
|-
| PrefsBinary()
| PrefsObjects binary object access function.
|-
| PrefsDate()
| PrefsObjects date object access function.
|-
| PrefsDictionary()
| PrefsObjects dictionary object access function.
|-
| PrefsNumber()
| PrefsObjects number object access function.
|-
| PrefsString()
| PrefsObjects string object access function.
|-
| ReadPrefs()
| Reads a prefs dictionary from a file.
|-
| WritePrefs()
| Writes a prefs dictionary to a file.
|}

Libraries

2015-09-18T11:11:39Z

Daniel Jedlicka: Created a separate page for PrefsObjects because the Application Library documentation was getting too long.

== AmigaDOS ==

[[AmigaDOS Introduction]]

[[DOS Library]]
:[[AmigaDOS Data Structures|Data Structures]]
:[[Program Startup]]
:[[Basic Input and Output Programming]]
:[[Executing External Programs]]
:[[Cooperative Record Locking]]
:[[Notification]]
:[[Path Name Handling]]
:[[Pattern Matching]]
:[[Multiple Assigns]]
:[[AmigaDOS Packets|Packets]]
:[[AmigaDOS Vector-Port|Vector-Port]]
:[[Hard and Soft Links]]
:[[Writing a UserShell]]
:[[AmigaDOS Device Input and Output|Device Input and Output]]

== User Interface Libraries ==

[[Intuition Library]]
:[[Intuition Screens|Screens]]
::[[Custom_Screen_Type|Custom Screen Type]]
::[[Public_Screen_Type|Public Screen Type]]
:[[Intuition Windows|Windows]]
::[[Window Types|Types]]
::[[Window Structures and Functions|Structures and Functions]]
::[[Window Communication|Communicating with Intuition]]
::[[Window Display Preservation|Display Preservation]]
:[[Intuition Gadgets|Gadgets]]
::[[Boolean_Gadget_Type|Boolean Gadget Type]]
::[[Proportional_Gadget_Type|Proportional Gadget Type]]
::[[String_Gadget_Type|String Gadget Type]]
:[[Intuition Menus|Menus]]
::[[Intuition Classic Menus|Classic Menus]]
::[[Intuition Menu Class|Menu Class]]
::[[Intuition Context Menus|Context Menus]]
:[[Intuition Requesters|Requesters]]
:[[Intuition Alerts|Alerts]]
:[[Intuition Images, Line Drawing and Text|Images, Line Drawing and Text]]
::[[Intuition Images|Images]]
::[[Intuition Borders|Borders]]
::[[Intuition Text|Text]]
:[[Intuition Input and Output Methods|Input and Output Methods]]
:[[Intuition Mouse|Mouse]]
:[[Intuition Keyboard|Keyboard]]
:[[Intuition Pointer|Pointer]]
:[[Intuition Special Functions|Special Functions]]
:[[BOOPSI - Object Oriented Intuition]]
::[[BOOPSI Gadgets]]
::[[BOOPSI Images]]
::[[BOOPSI Class Reference]]

[[Workbench Library]]

[[Icon Library]]

[[Locale Library]]

[[GadTools Library]]
:[[GadTools Menus]]
:[[GadTools Gadgets]]

[[ASL Library]]
:[[ASL File Requester|File Requester]]
:[[ASL Font Requester|Font Requester]]
:[[ASL Screen Mode Requester|Screen Mode Requester]]

[[Application Library]]
:[[PrefsObjects]]

[[Preferences]]

== Graphics Libraries ==

[[Graphics Library]]
:[[Display Database]]
:[[Graphics Primitives|Primitives]]
::[[Classic Graphics Primitives|Classic Primitives]]
:[[Graphics Sprites, Bobs and Animation|Sprites, Box and Animation]]
::[[Hardware Sprites]]
::[[Virtual Sprites|Virtual Sprites (VSprites)]]
::[[Blitter Objects|Blitter Objects (Bobs)]]
:[[Graphics Library and Text|Text]]
:[[Graphics Regions|Regions]]

[[Layers Library]]

== Additional Libraries ==

[[AmigaGuide Library]]

[[Camd Library]]

[[Commodities Exchange Library]]

[[Datatypes Library]]
:[[Writing Datatype Classes]]

[[IFFParse Library]]
:[[Parsing IFF]]
:[[Writing IFF]]

[[Keymap Library]]

[[Newlib Library]]

[[PThreads Library]]

[[RealTime Library]]

[[Translator Library]]

== Third-Party Libraries ==

[[Expat Library]]

[[Filesysbox Library]]

== Appendices ==

[[Linker Libraries]]

== 68k Libraries ==

[[Math Libraries]]

GadTools Library

2015-09-13T16:13:56Z

Daniel Jedlicka: Reworded the chapter introduction to reflect the current situation in AmigaOS.

== GadTools Library ==

Originally, programming even straightforward user interfaces in [[Intuition_Library|Intuition]] could be rather complicated, and certainly difficult for first-time programmers. The GadTools toolkit was introduced in AmigaOS 2.x to simplify the task. It provided relatively easy-to-use, higher-level chunks to build [http://en.wikipedia.org/wiki/Graphical_user_interface GUIs] from, and to help programmers through what used to be a difficult chore.

{{Note|title=Note|text=As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended. Prefer using the object-oriented GUI programming framework based on [[BOOPSI]].}}

== Elements of GadTools ==

GadTools is the easy way to program gadgets and menus. With GadTools, the system handles the detail work required to control gadgets and menus so the application uses less code and simpler data structures.

Another key benefit of GadTools is its standardized and elegant look. All applications that use GadTools will share a similar appearance and behavior. Users will appreciate a sense of instant familiarity even the first time they use a product.

GadTools provides a significant degree of visual consistency across multiple applications that use it. There is also internal consistency between different elements of GadTools; the look is clean and orderly. Depth is used not just for visual embellishment, but as an important cue. For instance, the user is free to select symbols that appear inside a "raised" area, but "recessed" areas are informational only, and clicking in them has no effect.

GadTools is not amenable to creative post-processing or hacking by programmers looking to achieve a result other than what GadTools currently offers. Software developers whose needs extend beyond the standard features of GadTools should create custom gadgets that share the look and feel of GadTools by using either BOOPSI or by directly programming gadgets at a lower level. See [[Intuition_Gadgets|Intuition Gadgets]] and [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI]] for more information.

=== GadTools Tags ===

Many of the GadTools functions use TagItem arrays or ''tag lists'' to pass information across the function interface. These tag-based functions come in two types, one that takes a pointer to an array of tag items and one that takes a variable number of tag item arguments directly in the function call. In general, the second form, often called the ''varargs'' form because the call takes a variable number of arguments, is provided for convenience and is internally converted to the first form. When looking through the Autodocs or other Amiga reference material, the documentation for both forms is usually available in the array-based function description.

All GadTools tags begin with a leading "GT". In general, they also have a two-letter mnemonic for the kind of gadget in question. For example, slider gadgets recognize tags such as "GTSL_Level". The GadTools tags are defined in <libraries/gadtools.h>. Certain GadTools gadgets also recognize other Intuition tags such as GA_Disabled and PGA_Freedom, which can be found in <intuition/gadgetclass.h>.

For more information on tags and tag-based functions, be sure to see the [[Utility_Library|Utility Library]].

== GadTools Menus ==

GadTools menus are the preferred way to manage menus on AmigaOS.

See [[GadTools Menus]] for more information on how to use them.

== GadTools Gadgets ==

GadTools gadgets are largely superseded by BOOPSI-based GUI systems are to be avoided.

See [[GadTools Gadgets]] for more information about this obsolete GUI system.

== Function Reference ==

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

{| class="wikitable"
! Function
! Description
|-
| CreateGadgetA() CreateGadget()
| Allocate GadTools gadget.
|-
| FreeGadgets()
| Free all GadTools gadgets.
|-
| GT_SetGadgetAttrsA() GT_SetGadgetAttrs()
| Update gadget.
|-
| CreateContext()
| Create a base for adding GadTools gadgets.
|-
| CreateMenusA() CreateMenus()
| Allocate GadTools menu structures.
|-
| FreeMenus()
| Free menus allocated with CreateMenus().
|-
| LayoutMenuItemsA() LayoutMenuItems()
| Format GadTools menu items.
|-
| LayoutMenusA() LayoutMenus()
| Format GadTools menus.
|-
| GT_GetIMsg()
| GadTools gadget compatible version of GetMsg().
|-
| GT_ReplyIMsg()
| GadTools gadget compatible version of ReplyMsg().
|-
| GT_FilterIMsg()
| Process GadTools gadgets with GetMsg()/ReplyMsg().
|-
| GT_PostFilterIMsg()
| Process GadTools gadgets with GetMsg()/ReplyMsg().
|-
| GT_RefreshWindow()
| Display GadTools gadget imagery after creation.
|-
| GT_BeginRefresh()
| GadTools gadget compatible version of BeginRefresh().
|-
| GT_EndRefresh()
| GadTools gadget compatible version of EndRefresh().
|-
| DrawBevelBoxA() DrawBevelBox()
| Draw a 3D box.
|-
| GetVisualInfoA() GetVisualInfo()
| Get drawing information for GadTools.
|-
| FreeVisualInfo()
| Free drawing information for GadTools.
|}

GUI Programming

2015-09-13T15:39:40Z

Daniel Jedlicka: Added some notes about GadTools.

== Background ==

In AmigaOS, the face a program shows you – its [http://en.wikipedia.org/wiki/Graphical_user_interface graphical user interface] (GUI) – is created through a subsystem called [[Intuition_Library|Intuition]]. Older literature sometimes used to refer to Intuition as “the Amiga user interface” but this is really not the case. Despite being responsible for much of what you can ''see'' in the OS (including its windowing desktop environment, the [[UserDoc:Workbench|Workbench]]), Intuition itself remains ''invisible'' to the user. It is merely a system component providing ready-made [[#GUI elements|elements]] to build GUIs from, and a set of functions through which these elements are manipulated. Intuition also interconnects GUIs with the operating system and handles various communications that underlie application usage and control.

Intuition’s functionality is further extended by a number of auxiliary system components, or [[#GUI toolkits|toolkits]]. Like most AmigaOS subsystems, Intuition and its extensions are implemented as libraries of functions that can be accessed from a higher-level programming language like C, C++, Modula-2 or AmigaE.

== GUI Elements ==

Amiga programs do not look or behave very differently from, say, Mac or Windows applications because their user interface is based on shared metaphors and familiar elements. There may be differences in naming conventions or programming techniques but the building blocks are similar. The following table summarizes the building blocks (GUI elements) that are provided by Intuition and its various extensions:

{| class="wikitable"
|-
! GUI element types
! Description
! System component or toolkit providing this functionality
|-
| [[Intuition_Screens|screens]] || Virtual desktops on which windows are opened. || Intuition Library
|-
| [[Intuition_Windows|windows]] || Rectangular areas containing an interface through which a program communicates with the user, and vice versa. || Intuition Library, ReAction, MUI
|-
| [[Intuition_Menus|menus]] || Programmable sets of commands displayed as a pull-down list of options. || Intuition Library, GadTools Library
|-
| [[Intuition_Gadgets|gadgets]] || Various-purpose GUI controls (buttons, toolbars, gauges, text fields...) with a standardized look and behaviour. Often called “widgets” in other operating systems. || Intuition Library, GadTools Library, ReAction, MUI
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Images|images]] || Non-selectable elements showing graphics or text. || Intuition Library, ReAction, MUI
|-
| [[Intuition_Requesters|requesters]] || Means for displaying information and for requesting input from the user. They would be called “dialogs”, “dialog boxes” or “dialog windows” in other OSes. || Intuition Library, ASL Library, ReAction, MUI
|-
| [[Intuition_Alerts|alerts]] || A method of emergency communication (such as system errors). || Exec Library, Intuition Library
|-
| [[Application_Library#Pop-up_notifications_(Ringhio_messages)|pop-up notifications]] || Automatic messages informing the user when things happen. Unlike requesters, notifications are “unobtrusive” and do not require any input from the user. || [[Application Library]]
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Text|IntuiText]] || Formatted text to be placed at a specific position inside an Intuition element (screen, window, menu, gadget or requester). || Intuition Library
|-
| [[Intuition_Images,_Line_Drawing_and_Text#Creating_Borders|borders]] || Graphical structures made of lines that connect a series of defined points.. || Intuition Library
|}

== The Two Frameworks ==

GUI programming in AmigaOS does not have to be done within a single framework or [http://en.wikipedia.org/wiki/Application_programming_interface API]. This fact can be confusing to newcomers. There are two frameworks in Intuition representing fundamentally different approaches to GUI programming:

# The '''data structure-oriented framework''' is the original Intuition API. Within this framework, if you want to create a GUI element, you have to provide dedicated data structures for it; if you want to manipulate the element, you have to use a function designed for the particular action and type of element.

# The '''object-oriented framework''' (called [[BOOPSI]]: Basic Object-Oriented Programming System for Intuition) is the extendable API. Within this framework, if you want to create a GUI element, you have to instantiate an ''object'' based upon a particular ''class''. Objects are manipulated through a small set of ''methods'' which are really just functions.

Modern AmigaOS programmers generally do not directly use either of these frameworks. Although it is still possible to do so it also requires a lot more code to achieve even a simple GUI.

Instead, programmers are encouraged to use one or more of the various toolkits provided.

== GUI toolkits ==

While the Intuition Library originally provided a datastructure-based set of basic GUI elements (screens, windows, menus, buttons & string gadgets, etc.) they have been supplanted by more modern tools for user interface programming. Most of the GUI-related functionality is now provided through various extensions to Intuition, or ''toolkits''. The following toolkits are installed by default in AmigaOS:

=== GadTools ===

[[GadTools_Library|GadTools]] is a datastructure-based toolkit. It is implemented as a single library and is not easily extensible. What is most useful about GadTools is the [[GadTools_Library#GadTools_Menus|menu building functionality]] (most of the other toolkits still use the menu build aspect of GadTools).

GadTools was introduced in AmigaOS 2.x as a ready-made toolkit for easier, faster and more consistent GUI design. GadTools extended the original Intuition set with fancy new controls such as the [[GadTools_Library#Cycle_Gadgets|cycle gadget]], the [[GadTools_Library#Mutually-Exclusive_Gadgets|radiobutton]], or the [[GadTools_Library#Listview_Gadgets|listview]]. The gadgets shared similar imagery, thus giving Amiga GUIs a more uniform, standardized look. Apart from improving the gadget set, GadTools also greatly simplified the creation of menus (GadTools uses standard Intuition menus but provides its own build and layout system for them). On the other hand, there is a very limited support for images in GadTools.

As of AmigaOS 4.1 Final Edition, GadTools is basically a legacy toolkit retained for compatibility.

=== ASL ===

[[ASL_Library|ASL]] is a datastructure-based toolkit. It is implemented as a single library and is not extensible.

The Amiga Standard Library (ASL) is a toolkit designed to ease the programming of common requesters. There are currently three types of requester available: file requester, font requester and screenmode requester.

=== ReAction ===

[[ReAction]] is an object-oriented toolkit based on BOOPSI which is highly extensible.

ReAction is a more modern toolkit which hides much of the complexity. It covers all the functionality of GadTools and ASL and uses and extends the original BOOPSI class set built into Intuition Library. ReAction is considered to be the standard Amiga GUI toolkit. Over the years it has been integrated into the Intuition/BOOPSI framework, and is no longer considered a separate component.

=== MUI ===

[http://en.wikipedia.org/wiki/Magic_User_Interface Magic User Interface] is an object-oriented toolkit based on BOOPSI which is highly extensible.

MUI is a comprehensive third-party toolkit for application GUI design which can also incorporate GadTools menus and ASL. MUI is also available on older AmigaOS systems and various clone systems although the implementation differs so compatibility is not guaranteed.

=== Qt, REBOL/View and Others ===

Third party toolkits may also be used on AmigaOS just as well as the built-in toolkits listed above.

Such toolkits generally work by opening an Intuition Screen and then rendering directly into that screen to create the GUI environment. Toolkits may also incorporate Intuition Windows and use them as a basic element. Native Intuition Menus may or may not be used as well.

With the use of skinning, 3rd party GUIs can look and feel a lot like Amiga native GUIs. However, they can suffer from reduced speed due to the more intensive use of the CPU. Much of the speed problem can be alleviated through the use of hardware acceleration (e.g. compositing).

== Choosing Toolkits ==

* Choose the toolkit that works best for your application and your end users/customers.

* GadTools gadgets are incompatible with all others and have their own [[GadTools_Library#Function_Reference|set of functions]] to be used with. There is no automatic layout system: GadTools gadgets are not scalable and are at fixed positions and dimensions. Due to its inherent limitations, using GadTools in modern applications can no longer be recommended.

* If you require modern features like scalability, font sensitivity, automatic (re)layouting, or window iconification (the ability to collapse the program window into an icon on the Workbench screen), then use one of the object-oriented toolkits: ReAction or MUI.

* The ASL toolkit is utilized by ReAction and MUI through dedicated classes. There is little need to use ASL directly in object-oriented GUIs.

* The original BOOPSI class set built in Intuition is usable but somewhat limited. Some BOOPSI classes are now actually wrappers for ReAction classes.

* Prefer not to mix datastructure-oriented and object-oriented GUI programming. Functions designed for Intuition windows, gadgets or images are not meant to be used on GUI objects created via ReAction. BOOPSI objects must solely be manipulated using [[BOOPSI_-_Object_Oriented_Intuition#Function_Reference|BOOPSI functions]] (methods).

* Many new programmers seem to be confused about window programming. It's fairly easy:
** ReAction elements (objects) must reside in a ''ReAction window'', that is, a window created through the Window Class, which is part of the toolkit. Such a window is manipulated as any other BOOPSI object.
** Intuition or GadTools elements must reside in an ''Intuition window'', that is, a window created through functions OpenWindow() or OpenWindowTags(), which are both part of the Intuition Library. Such windows are manipulated using dedicated functions.

* Despite both being based on BOOPSI, MUI and ReAction classes are not interchangeable. You cannot extend the functionality of ReAction with MUI classes and vice versa.

UI Style Guide Keyboard

2015-09-13T07:56:56Z

Daniel Jedlicka: Updated for OS4, added a note on localizing menu shortcuts.

[[Category:User Interface Style Guide]]
== The Keyboard ==

Your application should make gadget and menu items selectable with the keyboard as well as with the mouse. Often these keyboard equivalents ("hotkeys") will provide shortcuts and a smoother workflow that is appreciated by the user. Also, allowing the choice conforms to the Amiga credo: "Power to the User".

The set of conventions you should follow to implement this style rule are presented in this section.

== Keyboard Conventions ==

The arrangement of the Amiga's keyboard varies from model to model, but in general there are always three sets of keys:
* the standard keyboard
* special keys
* modifier keys

=== The Standard Keyboard ===

The standard keys consist of the familiar alphanumeric keys found on any standard typewriter. (In English, this is referred to as the QWERTY keyboard, but in German, since the standard keys are arranged differently, it's known as the QWERTZ keyboard. It's called other names in other languages.)

The actual arrangement of the standard keys can vary. To handle this, AmigaOS uses a special facility known as a keymap that allows the user to change the way the keyboard input is mapped so it will correspond to his country's keyboard layout and characters. For example, to access all the standard German ASCII characters the user can type "Setmap d" in the Shell. Then German characters such as ü and ß will have the same key designations as they do on a standard German keyboard.

Use the keymap facility to handle key assignments on the standard keyboard.

=== Special Keys ===

The special keys include the function keys on the top row of your computer's keyboard, the Help key, the cursor (arrow) keys, the Del key, the backspace key and the Esc key.

=== Modifier Keys ===

The modifier keys are the Ctrl, Shift, Alt and Amiga keys found on either side of the space bar. Modifier keys don't do anything by themselves; they alter the meaning of a key that is pressed at the same time. They are also used to modify the meaning of a mouse selection. For example, holding down the Shift key while clicking with the mouse is used for multiple object selection.

==== Dead Keys ====

A "dead" key is a key, or combination, that does nothing immediately but modifies the output of the next key. For example, on an American keyboard, Alt-H will superimpose a caret (^) symbol over the next appropriate character.

Although relatively unimportant on the American keyboard, dead keys are important in many languages. Keep in mind that you need to work these in manually if you're doing your own raw key mapping.

== System Keyboard Shortcuts ==

To provide mouse functions from the keyboard, only three features a needed: a way to press the left mouse button, a way to press the right mouse button, and a way to move the mouse pointer. These are provided by the system. They are listed here so you are aware of them and can avoid using these key combinations for any other purpose.

{| class="wikitable"
! Keyboard Shortcut
! Equivalent Mouse Activity
|-
| Either Amiga + Left-Alt
| Same as clicking left mouse button
|-
| Either Amiga + Right-Alt
| Same as clicking right mouse button
|-
| Either Amiga + Cursor Key
| Moves mouse pointer
|-
| Either Amiga + Shift + Cursor Key
| Moves mouse pointer in larger steps
|}

Five additional Amiga system functions have keyboard shortcuts:

{| class="wikitable"
! Default Keyboard Shortcut
! Equivalent System Function
|-
| Left-Amiga + N
| Workbench screen to front
|-
| Left-Amiga + M
| Front screen to back
|-
| Left-Amiga + B
| Requester OK (leftmost gadget)
|-
| Left-Amiga + V
| Requester Cancel (rightmost gadget)
|-
| Left-Amiga + selection button
| Drags screen whether the pointer is on the title bar or not
|}

The first four functions listed above always use Left-Amiga in combination with another key. The second key in the combination can be changed by the user with the IControl preferences editor in your AmigaOS Prefs drawer. For the screen dragging shortcut, the user can change the modifier or combination of modifiers (Ctrl, Amiga, Shift, Alt) that need to be combined with the selection button.

=== The Left-Amiga Key ===

Keep in mind that the Left-Amiga key is reserved at all times for system operations and should never be used as a qualifier for an application keyboard shortcut!

== Application Keyboard Shortcuts ==

Your application should provide a way for the user to bind an application function or ARexx macro to a key or combination of keys. Keyboard access to program features and common functions can speed up workflow significantly.

On the other hand, it’s not necessary to provide hotkeys for every single function in your program: the user wouldn’t be able to remember them anyway. Plus, keyboard shortcuts work best if they are mnemonic and logical: "S" for "Save", "P" for "Print", etc. Therefore, save handy mnemonics for common and really important functions, don't waste them on secondary features.

If you provide a hotkey for an operation that can be dangerous (such as format disk or delete-type operations), make sure the user will get the opportunity to confirm or cancel the action should he/she make an inadvertent key press. The general rule of application design is: never put the user's data at stake!

=== Gadgets ===

Place an underscore under the letter in the gadget label that activates the gadget. (Note: although the letter is capitalized on the label, the
default action should react to the lower-case letter. Some Intuition gadgets have a different action for the shifted version of the letter. See the list in the table below.)

The following three rules should apply:

* All action should occur on the down press of the key.
* The same visual feedback should be given for keyboard activation as is given for mouse activation.
* Avoid assigning the Enter key to a gadget.

'''Feedback from Keystroke-Activated Gadgets'''

{| class="wikitable"
| Action button
| On the down press of the key, the gadget should appear to be pressed in. On release of the key, the gadget should come back out. (Note: at the time this manual was published, GadTools did not support this function.)
|-
| Check box
| Toggle the state of the check mark.
|-
| Scrolling list
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Radio button
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Cycle gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Selection gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Scroll gadget
| Unshifted would cycle forwards through the choices. Shifted would cycle backwards through the choices.
|-
| Slider
| Unshifted would increase the level by one unit. Shifted would decrease the level by one unit.
|-
| Text box
| Activate the gadget for entry.
|-
| Numeric entry
| Activate the gadget for entry.
|}

=== Menus ===

Use a Right-Amiga combination as the default keyboard shortcut for a menu item. Here is a list of common hotkeys for an application that has standard menus:

Project Menu
Right-Amiga + N New
Right-Amiga + O Open...
Right-Amiga + S Save
Right-Amiga + A Save As...
Right-Amiga + P Print
Right-Amiga + ? About...
Right-Amiga + Q Quit Program

Edit Menu
Right-Amiga + X Cut
Right-Amiga + C Copy
Right-Amiga + V Paste
Right-Amiga + Z Undo

The original User Interface Style Guide suggested in this section that menu shortcuts should be [[Locale_Library|localized]] to reflect the user's preferred language as set in the system. This recommendation has turned out to be rather short-sighted and impractical: certain hotkeys like the ones listed above are so common, universal and "dyed in the wool" that changing them based on the currently selected locale would only be confusing. Also remember that unlike in gadgets, where the user can see the actual shortcut (it is underscored in the gadget label), you get no direct visual cue when using menu hotkeys because they are hidden in the menu. Thus, a menu hotkey could potentially be dangerous if the user pressed a known key combination that has suddenly changed meaning due to locale change.

=== Requesters ===

Hotkeys for requester buttons should also be provided. Requesters require user interaction: they "get in the way" and can slow down workflow. The user would therefore appreciate requester buttons having keyboard shortcuts (unless there’s a good reason not to provide them, such as safety of operation).

== Use of the Special Keys ==

As stated previously, the special keys are the function keys, the Del key, the Help key, the cursor (arrow) keys and the Esc key.

=== Cursor Keys ===

Cursor keys are a convenient way to control the movement of the cursor inside an application. Here are some standard ways to use them:

==== Unmodified Cursor ====

Move a small amount in the specified direction. Often this is one unit such as a character in a word processor or a pixel in a paint package, but it could be several pixels in an application where navigation is more important than fine control.

==== Shift + Cursor ====

Move to the appropriate extreme of the window, or shift the view by one window full if you're already at that extreme.

In applications such as a word processor where the two directions are not symmetrical, shifted cursor keys could take on different meanings. Shifted up and down cursors would page through windowfuls while the shifted left and right cursors would show more on the left and right if there is more to show. Of course it is often the case that the width of the document fits in the window, so the shifted left and right cursors could act as beginning-and end-of-line commands (or edge of window if the cursor isn't constrained to the form of the text).

==== Alt-Cursor ====

This is used for application-specific functions. It's usually semantic units such as words in a text processor or fields in a spreadsheet.

==== Ctrl-Cursor ====

Move to the appropriate extreme of the project (beginning, end, extreme left, extreme right).

In the word processor example, the up and down cursor keys would take the cursor to the beginning and end of the file, respectively. But again, if the file fits within the width of the window, the left and right cursor keys combined with Alt would act like their shifted cousins.

==== Function Keys ====

Function keys should generally be reserved for the user to define. If your application does make use of them, then it should at least allow the user to redefine or modify them.

==== Help Key ====

If your application has built-in help, use the Help key to trigger it from the keyboard. Avoid giving the user that helpless feeling he gets when he presses the Help key and nothing happens.

Note that PC keyboards connected to an AmigaOS-compatible computer will not feature the Help key. On such keyboards the Help key will be mapped to the ScrollLock key.

Exec Memory Pools

2015-08-23T18:24:48Z

Daniel Jedlicka: Memory Pool Organization: fixed a typo.

== Introduction ==

A memory pool is a block of memory that an application allocates for all its memory needs. The application draws from this pool rather than the system's free memory list whenever it requires memory.

Memory pools add to the efficiency of the system and applications in two ways. The first is a potential decrease in memory fragmentation. Memory fragmentation is a condition where system memory is made up of blocks of allocated memory interspersed with blocks of free memory. The second benefit of memory pools is faster memory allocations and deallocations.

By having an application take a pool of memory and allocate from it, fragmentation of system memory is decreased. An application may require six allocations ranging from 20 to 678 bytes in size which can be scattered throughout system memory. However, if those same six allocations are taken from a pool, the fragmentation occurs within the pool, but as far as the system is concerned, it's missing one large block instead of six small ones.

An application using a memory pool will have faster memory allocations because the memory list of a pool is smaller, and therefore easier to traverse than the memory list of the system memory. For deallocations, it's even faster because deleting the pool itself deletes all the individual allocations made from it instead of having to deallocate each piece that was allocated.

If you know that your memory pool allocations will always be of the same size, prefer using an [[Exec_Item_Pools|item pool]].

== Memory Pool Organization ==

A memory pool consists of units called puddles. Other than that, it has no formal organization. There is no pool structure defined anywhere. All you know about a pool is its address. Exec's pool manager handles the rest of the details.

When you create a pool, you specify the size of its puddles and a threshold value, not the size of the pool. This is because memory pools are dynamic, they have no fixed size. The pool manager takes the memory for your application from the puddles. As you require memory, the pool manager expands the pool by adding puddles, and as you free memory, the pool manager shrinks the pool by deleting puddles.

The size of the puddles is important because the pool manager will try to use as much of a puddle as possible before adding a new puddle. Each time you allocate memory from the pool, the pool manager takes the memory from a puddle unless an allocation exceeds the amount of memory remaining in a puddle. If the allocation request exceeds the memory remaining in a puddle, the pool manager adds a new puddle. If the allocation exceeds the pool's puddle size, the pool manager will create a special over-sized puddle to accommodate the allocation.

The key is to use all the drops in a puddle. If you create a pool with puddles of 200 bytes and allocate 150 bytes at a time, you'll waste 50 bytes in every puddle. Set the puddle size in accordance with your memory requirements.

The threshold value is the size of the largest allocation to use within a single puddle. An allocation request larger than the threshold value causes the pool manager to add a new puddle. Ideally, the threshold value should be the size of the largest allocation you will make.

The relationship between puddle size and threshold can be tuned for optimal utilization of a pool. Threshold sizes cannot exceed puddle sizes and are recommended to be one half the puddle size, so that you can fit two of your largest allocations in a single puddle. However, if you are going to have a mix of large and small allocations, you might want to set a threshold value that allocates a majority of a puddle for a large allocation, and then uses up the remainder of the puddle with the smaller allocations.

== Creating a Memory Pool ==

You create a memory pool by calling AllocSysObject() with the ASOT_MEMPOOL type and specifying the puddle size, threshold size and memory type. The memory type must be of type MEMF_PRIVATE or MEMF_SHARED. The MEMF_ANY type may be used to indicate that either of these memory types is suitable. The MEMF_CLEARED flag may also be specified to automatically clear memory allocated from the pool.

If successful, AllocSysObject() returns the address of the memory pool.

<syntaxhighlight>
APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_Puddle, 4096,
ASOPOOL_Threshold, 2048,
TAG_END);

if (mem_pool != NULL)
{
// ...
}
else
IDOS->Printf("Pool could not be created.\n");
</syntaxhighlight>

The example above attempts to create a pool of memory with a puddle size of 4096 bytes and a threshold size of 2048 bytes.

If your application requires memory of different types (for example, private memory and shared memory), it must create a pool for each type.

Take note, again, that all you know about a pool is its address. Do not poke around it trying to figure out its organization. It's private for a reason!

== Allocating Memory from a Pool's Puddles ==

Memory is obtained from a pool's puddles by calling AllocPooled(). AllocPooled() requires a pointer to the memory pool and the size of the memory block needed. If successful, AllocPooled() returns a pointer to the memory.

<syntaxhighlight>
struct Rectangle *rect = IExec->AllocPooled(mem_pool, sizeof(struct Rectangle);

if (rect != NULL)
{
// ...
}
else
IDOS->Printf("Memory could not be allocated.\n");
</syntaxhighlight>

== Freeing Memory from a Pool's Puddles ==

An application can free a block of memory it allocated from a pool by calling FreePooled():

<syntaxhighlight>
IExec->FreePooled(mem_pool, mem_drop, mem_size);
</syntaxhighlight>

This function requires a pointer to the memory pool (mem_pool), a pointer to the block of memory being freed (mem_drop), and the size of the memory being freed (mem_size).

== Deleting a Memory Pool ==

A memory pool is deleted by calling FreeSysObject() with the ASOT_MEMPOOL type and a pointer to the memory pool you wish to delete.

<syntaxhighlight>
IExec->FreeSysObject(ASOT_MEMPOOL, mem_pool);
</syntaxhighlight>

Deleting a pool also frees the puddles in it. This is quicker than doing individual FreePooled() calls. For example, a text editor will allocate memory for each line of the file being edited. When the editor is exited, each of the allocations has to be freed. With FreeSysObject(), it would take only one call instead of many.

== Concurrent Access ==

Memory pools may be protected from concurrent access by specifying the ASOPOOL_Protected tag when creating the pool.

<syntaxhighlight>
APTR mem_pool = IExec->AllocSysObjectTags(ASOT_MEMPOOL,
ASOPOOL_MFlags, MEMF_SHARED,
ASOPOOL_Puddle, 4096,
ASOPOOL_Threshold, 2048,
ASOPOOL_Protected, TRUE,
TAG_END);
</syntaxhighlight>

In this case, the memory is being shared between two Tasks or Processes so it must be of type MEMF_SHARED. By specifying that the memory pool is protected we are guaranteed all operations performed on the memory pool are thread safe.

== Function Reference ==

The following table gives a brief description of the Exec functions that control memory pools. See the SDK/Autodocs for more details about each call.

{| class="wikitable"
! Function
! Description
|-
| AllocPooled()
| Allocate memory with the pool manager.
|-
| AllocSysObject(ASOT_MEMPOOL)
| Allocate and initialize a new memory pool.
|-
| AllocVecPooled()
| Allocate memory with the pool manager and track size.
|-
| FreePooled()
| Free pooled memory.
|-
| FreeSysObject(ASOT_MEMPOOL)
| Free a memory pool.
|-
| FreeVecPooled()
| Free pooled memory allocated with AllocVecPooled().
|}

These Exec functions are now practically obsolete and not recommended for use in new code:

{| class="wikitable"
! Function
! Description
|-
| CreatePool()
| Use AllocSysObject(ASOT_MEMPOOL) instead.
|-
| DeletePool()
| Use FreeSysObject(ASOT_MEMPOOL) instead.
|}

Datatypes Library

2015-08-23T16:03:37Z

Daniel Jedlicka: Unified spelling of system components. Slightly reworked the Introduction section.

= Introduction =

The purpose of the DataTypes Library is to provide tools for handling data in an object-oriented way. The object-oriented approach means that your application can work with numerous data file standards without having to worry about the complex details of each one. Instead you only need to understand the simple conventions of the library.

The DataTypes Library is built on Intuition's BOOPSI facility (BOOPSI is an acronym for Basic Object-Oriented Programming System for Intuition). Although not required, it is very helpful to know a little about [[BOOPSI_-_Object_Oriented_Intuition|how BOOPSI works]] before trying to use the DataTypes Library. Some familiarity with object-oriented theory and practice is also helpful, though not required.

Since the library uses the TagItem structure for passing parameters to functions, you will have to understand how TagItems work before you can call the library functions. For more information on TagItems refer to the [[Utility_Library|Utility Library]].

== Spelling Conventions ==

In software development, the term “datatype” or “data type” is often used in the general sense, whereas the AmigaOS DataTypes framework establishes a rather special context. In order to avoid possible confusion, this documentation uses capitalized spelling in reference to components and programming entities that are part of the said framework, such as: the DataTypes Library, a DataType subclass, a DataType object, Picture DataType, etc.

== Why Use DataTypes? ==

Here's a summary of main properties and features:

* Support for multiple file formats across various types of data (text, sound, image, animation etc.). Load data the easy way without having to write dedicated loader code!

* Simple and consistent handling of multiple data standards. Once you have learned how to manipulate one type of data with the DataTypes Library, you will find that the other types are handled in much the same way.

* Extensible. New data types can be added to those already supported.

* Clipboard support. The DataTypes Library provides a consistent and easy-to-use interface to the Amiga's [[Clipboard_Device|clipboard device]] to encourage data sharing between applications.

* Intuition gadget support. Because the DataTypes Library is implemented with BOOPSI, the data objects it handles can also be treated as gadgets. Gadget operations can be performed on data objects within Intuition's task context, the same as other BOOPSI gadgets.

* Automatic conversion from one format to another. Future versions of the DataTypes Library will support other types of data objects. Conversion from one format to another will be automatically handled by the library.

* Validation. For example, you can easily check to see if a file is a valid JPEG (AIFF, AmigaGuide etc.) or not.

= Classes, Objects and Methods =

The jargon used to describe the DataTypes Library may be a little confusing if you have never worked with object-oriented systems before. For instance, the kinds of data supported by the library are divided into ''classes'' and ''subclasses''. The term ''class'' is used here in a familiar way; the members of a class simply have a common set of properties. The members of a subclass have all the properties of the parent class (superclass) and additional properties specific to the subclass. (Each subclass can be further broken down into sub-subclasses and so on.)

{| class="wikitable"
| Class || Ungulate || Has hooves, can run.
|-
| Subclass || Cow || Has udder, can be milked (also has hooves and can run).
|-
| Object || Daisy || An instance of class Cow; can run and can be milked.
|}

An actual instance of a class or subclass is referred to as an ''object''. The term ''object'' is appropriate because in general we want to ignore the details of each individual case and concentrate instead on what we can do with an object based on its class. In the example above the Daisy object can run and can be milked. The operations that can be performed with an object are referred to as ''methods'' and the object is said to ''inherit'' the methods and other attributes of its parent class (which in turn inherits the methods and attributes of its parent class, if it has one).

The datatypes.library implements ''datatypesclass'' from which all other DataType classes inherit from. The following BOOPSI class diagram illustrates how the various DataTypes classes relate to each other.

<center>
<classdiagram type="orderly" scale="60" dir="rl">
[gadgetclass]->[rootclass]
[datatypesclass]->[gadgetclass]
[sound.datatype]->[datatypesclass]
[picture.datatype]->[datatypesclass]
[text.datatype]->[datatypesclass]
[amigaguide.datatype]->[datatypesclass]
[animation.datatype]->[datatypesclass]
[8svx.datatype]->[sound.datatype]
[aiff.datatype]->[sound.datatype]
[anim.datatype]->[animation.datatype]
[ascii.datatype]->[text.datatype]
[bmp.datatype]->[picture.datatype]
[cdxl.datatype]->[animation.datatype]
[gif.datatype]->[picture.datatype]
[ilbm.datatype]->[picture.datatype]
[jpeg.datatype]->[picture.datatype]
[png.datatype]->[picture.datatype]
[tiff.datatype]->[picture.datatype]
[wav.datatype]->[sound.datatype]
</classdiagram>
</center>

{| class="wikitable"
|+ DataTypes Library Object Classes
! Object Classes
! Autodoc File Showing the Methods Supported
! Type of Data Object
|-
| Picture class
| picture_dtc.doc
| IFF graphic image file
|-
| Sound class
| sound_dtc.doc
| IFF audio sample file
|-
| Text class
| text_dtc.doc
| ASCII characters
|-
| AmigaGuide class
| amigaguide_dtc.doc
| Hypertext databases
|-
| Animation class
| animation_dtc.doc
| Animations containing graphics and sound
|}

The examples programs listed below demonstrate how to perform some basic ''methods'' on ILBM and 8SVX class objects.

= DataTypes Class Attributes =

DataType classes have other attributes in addition to the methods (operations) that they support. For each attribute, there is a corresponding TagItem defined in the DataTypes Library that you can use to examine or set that attribute in a particular object. For example, picture objects have a display mode attribute. The tag that controls this attribute is named PDTA_ModeID and is described in the Autodoc file picture_dtc.doc. See the Autodoc files for each class (as shown in Table 1) for a complete list of all class attributes.

The class attribute descriptions in the include files also have a set of codes that indicate the ''applicability'' of the attribute. The codes are as follows:

{| class="wikitable"
| I - Initialize
| You can initialize the attribute when the object is created
|-
| S - Set
| You can set the attribute to a new value after the object is created
|-
| G - Get
| You can get the value of the attribute after the object is created
|-
| N - Notify
| Changing the attribute triggers the object to send notification
|-
| U - Update
| Attribute can be set using the object's OM_UPDATE method
|}

These codes may seem a little mysterious until you have actually tried using the DataTypes Library. The N and U codes in particular are for special applications that want to implement their own object classes, an advanced topic beyond the scope of this article.

= Basic Functions of the DataTypes Library =

If all these new concepts seem a little daunting, rest assured; the DataTypes Library uses conventional C language function calls to get the job done. The calls you will be using most often are listed below. Notice that for each of these basic functions of DataTypes Library there is an equivalent BOOPSI call in the Intuition Library.

{| class="wikitable"
! datatypes.library
! intuition.library
! Purpose
|-
| NewDTObject()
| NewObject()
| Create a DataType object in memory from a file or clip
|-
| DisposeDTObject()
| DisposeObject()
| Free an object created earlier with NewDTObject() (or NewObject() )
|-
| GetDTAttrs()
| GetAttr()
| Get attributes of a DataType object
|-
| SetDTAttrs()
| SetAttrs()
| Set attributes for a DataType object
|-
| DoDTMethod()
| IDoMethod()
| Perform the given method (operation) with a DataType object
|}

There are also additional functions used to access DataType objects.

{| class="wikitable"
! Function Name
! Purpose
|-
| AddDTObject() || Add a DataType object to a window.
|-
| RefreshDTObjectA() || Refresh the rendering of a DataType object.
|-
| RemoveDTObject() || Remove a DataType object from a window.
|-
| GetDTMethods() || Get a list of the methods that a DataTypes object supports. Write, Copy, and Select are examples of methods that an object may support.
|-
| GetDTTriggerMethods() || Get a list of the trigger methods that a DataType object supports. An action like Play, Pause, and Resume are examples of trigger methods that an object may support.
|-
| PrintDTObject() || Asynchronously print a DataType object.
|-
| GetDTString() || Get the localized text string for a DataTypes text id. Useful for obtaining localized error messages.
|}

In a typical application the sequence of calls might be performed
like this:

# Use NewDTObject() to create an object in memory from given data.
# Get (or perhaps set) attributes of the object using GetDTAttr() (or SetDTAttrs() ).
# Perform ''methods'' (operations) with the object using DoDTMethod().
# Free the object and any memory or other resources it was using with the DisposeDTObject() call.

= Basic Structures of the DataTypes Library =

There are a lot of structures used with DataTypes Library function calls; too many to summarize in this article. However, here's a listing of the relevant include files that contain the structure definitions of interest to class users.

{| class="wikitable"
| <datatypes/datatypes.h>
| Group IDs, error numbers plus library overhead
|-
| <datatypes/datatypesclass.h>
| Defines DataType methods and associated structures
|-
| <datatypes/picture.h>
| Structures specific to the picture class
|-
| <datatypes/sound.h>
| Structures specific to the sound class
|-
| <datatypes/text.h>
| Structures specific to the text class
|-
| <libraries/amigaguide.h>
| Structures and methods for AmigaGuide databases
|-
| <intuition/classusr.h>
| Defines general BOOPSI object methods
|-
| <intuition/gadgetclass.h>
| Defines gadget methods and associated structures
|}

The two most important definitions in these include files appear in <intuition/classusr.h>. The objects used with DataTypes Library functions (and the BOOPSI functions in Intuition) are defined as follows:

<syntaxhighlight>
typedef ULONG Object; /* abstract handle */
</syntaxhighlight>

Since we want to treat objects as black boxes and don't really care how they are implemented, this definition is very appropriate. When a method is performed with an object, the parameter used to identify the method is a Msg structure defined as follows:

<syntaxhighlight>
typedef struct {
ULONG MethodID;
/* method-specific data goes here */
} *Msg;
</syntaxhighlight>

Some methods require more information than just the method identifier. Such methods have a custom structure defined in the include files. All method structures, however, begin with a field that contains the method ID.

= Creating a DataType Object =

The DataTypes function NewDTObjectA() must be used to create a new DataType object.

<syntaxhighlight>
Object *dto = IDataTypes->NewDTObjectA (APTR name, struct TagItem *attrs);
</syntaxhighlight>

The pointer that NewDTObjectA() returns is a pointer to a BOOPSI object. Like other BOOPSI objects, DataType objects are "black boxes" and are not to be peeked and poked without using the provided interface.

To create a DataType object, NewDTObjectA() needs to know the where to obtain the data used to create the object. By default the name is treated as file name.

The attrs tag list is a list of tag/value pairs, each of which contains an initial value for an attribute. There are a number of attributes defined in <datatypes/datatypesclass.h> that can be used at creation time.

; DTA_SourceType
: Specify the type of the source data. The default is DTST_FILE.
:{| class="wikitable"
| DTST_RAM || Source data is in RAM.
|-
| DTST_FILE || Source data is a file. Name is the name of the file.
|-
| DTST_CLIPBOARD || Source data is in the clipboard. Name is the unit number. For example, (APTR)0, for clipboard unit zero.
|-
| DTST_HOTLINK || Reserved for future use.
|}

; DTA_Handle
: Can be used instead of the name field. If the source type is DTST_FILE then handle must be a valid BPTR file handle. If the source type is DTST_CLIPBOARD then handle must be a valid IFFHandle.

; DTA_DataType
: Can be used to specify the class for handling the data. Data must be a pointer to a valid DataType. This should only be used when attempting to create a new object that doesn't have source data, or could be handled by multiple classes (for example, could be used to force an object to be handled by the AmigaGuide class).

; DTA_GroupID
: If this tag is present, then the data must be of the specified type, or the object creation will fail with ERROR_OBJECT_WRONG_TYPE. This can be used by a Sound editor to ensure that only sounds can be loaded, for example.

There are additional attributes that can specified at creation time, but are dependant on the data type of the object being created. See the header files <datatypes/#?class.h> for more attributes.

The following attributes, which are defined in <intuition/gadgetclass.h>, are also valid.
{| class="wikitable"
! Tag !! Description
|-
| GA_Left || Specify the left edge of the gadget.
|-
| GA_RelRight || Specify the left edge of the gadget being relative to the right edge of the containing window.
|-
| GA_Top || Specify the top edge of the gadget.
|-
| GA_RelBottom || Specify the top edge of the gadget being relative to the bottom edge of the containing window.
|-
| GA_Width || Specify the width of the gadget.
|-
| GA_RelWidth || Specify the width of the gadget being relative to the width of the containing window.
|-
| GA_Height || Specify the heigh of the gadget.
|-
| GA_RelHeight || Specify the heigh of the gadget being relative to the height of the containing window.
|-
| GA_ID || Specify a ID associated with the gadget.
|-
| GA_UserData || Attach application data to the gadget.
|-
| GA_Immediate || Indicate that the application should be notified of gadget down events for this gadget.
|-
| GA_RelVerify || Indicate that the application should be notified of gadget up events for this gadget.
|-
| GA_Previous || For adding the gadget to a list of gadgets.
|-
| GA_DrawInfo || A pointer to a struct DrawInfo.
|}

In order for the application to receive information from the DataType object, it must set up a target for the notification attributes that the object sends out.

; ICA_TARGET
: Specify a target for the notification attributes that the DataType object sends out.

; ICA_MAP
: Specify an attribute mapping for the notification attributes that the DataType object sends out.

The usual method to obtain notification is to set up an ICA_TARGET of ICTARGET_IDCMP so that the application will receive the attributes via the IDCMP_IDCMPUPDATE Intuition message class. But it is also possible to set up another BOOPSI object as the receiver.

If NewDTObjectA() is successful, it returns a pointer to a DataType object. Otherwise it returns NULL and the reason for failure can be obtained using IoErr(). See the Autodocs for datatypes.library for more information.

= Obtaining Environment Information for a DataType =

In order to embed a DataType object in a window, it is neccessary to ask the object what its minimum environment is. For example, since the remap code doesn't handle remapping HAM pictures, they must be shown on a HAM screen, and therefore can't be added to a window that is on a non-HAM screen.

<syntaxhighlight>
ULONG modeid = INVALID_ID;
LONG nomwidth, nomheight;
BOOL useScreen = FALSE;
struct dtFrameBox dtf;
struct FrameInfo fri;

/* Get the attributes that we are interested in */
IDataTypes->GetDTAttrs(dto,
/* Get the mode ID */
PDTA_ModeID, &modeid,

/* Get the desired size */
DTA_NominalHoriz, &nomwidth,
DTA_NominalVert, &nomheight,

TAG_END);

/* Clear the structures */
IUtility->ClearMem(&dtf, sizeof (struct dtFrameBox));
IUtility->ClearMem(&fri, sizeof (struct FrameInfo));

/* Fill in the message */
dtf.MethodID = DTM_FRAMEBOX;
dtf.dtf_FrameInfo = &fri;
dtf.dtf_ContentsInfo = &fri;
dtf.dtf_SizeFrameInfo = sizeof (struct FrameInfo);

/* Perform the frame method */
if (IDataTypes->DoDTMethodA (dto, NULL, NULL, (Msg) &dtf))
{
/* Check to see if the object requires a HAM screen */
if (fri.fri_PropertyFlags & DIPF_IS_HAM)
{
IDOS->Printf ("HAM\n");
useScreen = TRUE;
}
/* Check to see if the object requires an ExtraHalfBrite screen */
else if (fri.fri_PropertyFlags & DIPF_IS_EXTRAHALFBRITE)
{
IDOS->Printf ("ExtraHalfBrite\n");
useScreen = TRUE;
}
/* A safety check to see if a screen is required */
else if ((fri.fri_PropertyFlags == 0) && (modeid & 0x800) && (modeid != INVALID_ID))
{
IDOS->Printf ("ModeID=0x%08lx\n", modeid);
useScreen = TRUE;
}
}
else
{
/* No special environment required, can be attached to any screen mode */
}
</syntaxhighlight>

= Adding a DataType Object to a Window =

A DataType object must be added to a window using the AddDTObject() function of DataTypes.

<syntaxhighlight>
LONG AddDTObject (struct Window *w, struct Requester *r, Object *dto, LONG pos)
</syntaxhighlight>

This function will add a DataTypes object to the existing gadget list for the specified window. The recommended value for pos is -1 which will cause the DataType object to be added to the end of the list.

DataType objects should not be added using the WA_Gadgets attribute to OpenWindowTagList() or by using the AddGList() function. There is special information that DataTypes requires that will not obtained if any method other than AddDTObject() is used.

When the DataType object is added to the window, the layout method for the object will be invoked. It is possible that the layout will take a while to perform, in that case the object will spawn a process to handle the layout asynchronously. In order to refresh the object's visual information, it is necessary to obtain IDCMP_IDCMPUPDATE messages from the object and refresh the object when a DTA_Sync attribute is received.

The following code fragment illustrates adding a DataType object to a window.

<syntaxhighlight>
Object *dto;

struct IntuiMessage *imsg;
struct Window *win;
ULONG sigr;

struct TagItem *tstate, *tags;
ULONG tidata;
ULONG errnum;

BOOL going = TRUE;

/* Set the pertinent attributes of the DataType object */
IDataTypes->SetDTAttrs (dto, NULL, NULL,

/* Set the dimensions of the object */
GA_Left, win->BorderLeft,
GA_Top, win->BorderTop,
GA_Width, win->Width - win->BorderLeft - win->BorderRight,
GA_Height, win->Height - win->BorderTop - win->BorderBottom,

/* Make sure we receive IDCMP_IDCMPUPDATE messages from
* the object */
ICA_TARGET, ICTARGET_IDCMP,
TAG_END);

/* Add the object to the window */
IDataTypes->AddDTObject (win, NULL, dto, -1);

/* Refresh the DataType object */
IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);

/* Keep going until we're told to stop */
while (going)
{
/* Wait for an event */
sigr = IExec->Wait ((1L << win->UserPort->mp_SigBit) | SIGBREAKF_CTRL_C);

/* Did we get a break signal */
if (sigr & SIGBREAKF_CTRL_C)
going = FALSE;

/* Pull Intuition messages */
while (imsg = (struct IntuiMessage *) IExec->GetMsg (win->UserPort))
{
/* Handle each message */
switch (imsg->Class)
{
case IDCMP_IDCMPUPDATE:
/* Get a pointer to the attribute list */
tstate = tags = (struct TagItem *) imsg->IAddress;

/* Step through the attribute list */
while (tag = IUtility->NextTagItem (&tstate))
{
tidata = tag->ti_Data;
switch (tag->ti_Tag)
{
/* Change in busy state */
case DTA_Busy:
if (tidata)
IIntuition->SetWindowPointer (win, WA_BusyPointer, TRUE, TAG_END);
else
IIntuition->SetWindowPointer (win, WA_Pointer, NULL, TAG_END);
break;

/* Error message */
case DTA_ErrorLevel:
if (tidata)
{
errnum = IUtility->GetTagData (DTA_ErrorNumber, NULL, tags);
IDOS->PrintErrorMsg (errnum, (STRPTR) options[OPT_NAME]);
}
break;

/* Time to refresh */
case DTA_Sync:
/* Refresh the DataType object */
IDataTypes->RefreshDTObjects (dto, win, NULL, NULL);
break;
}
}
break;
}

/* Done with the message, so reply to it */
IExec->ReplyMsg ((struct Message *) imsg);
}
}
</syntaxhighlight>

= Removing a DataType Object from a Window =

A DataType object must be removed from the window using the RemoveDTObject() function.

<syntaxhighlight>
LONG RemoveDTObject (struct Window *w, Object *dto)
</syntaxhighlight>

This function removes the DataType object from the window's gadget list.

This is the only way that a DataType object should be removed from the window list. Using RemoveGList() is not supported, nor is removing the object manually.

= Setting an Existing DataType Object's Attributes =

An objects attributes are not necessarily static. An application can ask an object to set certain attributes using the SetDTAttrs() function.

<syntaxhighlight>
ULONG SetDTAttrsA (Object *dto, struct Window *w, struct Requester *r, struct TagItem *attrs)
</syntaxhighlight>

The return value is DataType object specific, but generally a non-zero value means that the object needs to be visually refreshed.

The following fragment illustrates how to set the current top values for a DataType object, using the VarArgs version of SetDTAttrsA().

<syntaxhighlight>
IDataTypes->SetDTAttrs(dto, window, NULL,
DTA_TopVert, 0,
DTA_TopHoriz, 0,
TAG_END);
</syntaxhighlight>

This will cause the DataType object to update its vertical and horizontal top values. If the object has been added to a window, then the display will be updated accordingly.

Note that it is not OK to call SetGadgetAttrs() or SetAttrs() on a DataType object.

= Getting a DataType Object's Attributes =

The DataTypes function GetDTAttrsA() is used to obtain the values for a list of attributes from a DataType object.

<syntaxhighlight>
ULONG GetDTAttrsA (Object *dto, struct TagItem *attrs)
</syntaxhighlight>

Where dto is a pointer to a DataType object returned by NewDTObjectA().

And attrs is a TAG_END terminated array of attributes. Where the data element of each pair contains the address of the storage variable for that attribute.

This function will return a number that indicates that number of attributes that it was able to obtain. For example if four attributes asked for and GetDTAttrs returns a four, then all the attributes were obtained.

The following code fragment illustrates how to get the current top values
for a DataTypes object using the VarArgs form of GetDTAttrsA().

<syntaxhighlight>
LONG topv, toph;

if (IDataTypes->GetDTAttrs (dto, DTA_TopVert, &topv, DTA_TopHoriz, &toph, TAG_END) == 2)
{
IDOS->Printf ("Top: vertical=%ld, horizontal=%ld\n", topv, toph);
}
else
{
IDOS->Printf ("couldn't obtain the top values\n");
}
</syntaxhighlight>

= A Simple DataTypes Example =

The example program listed here should clarify some of the concepts discussed so far. Suppose you have a communications program and want to add the capability of playing back a user-specified 8SVX sample file for the bell sound (Ctrl-G). The program below shows how to play a sound with the DataTypes Library.

In this program, objects are of class 8SVX (a subclass of the Sound DataType). The method performed with the object is named DTM_TRIGGER (described in the Autodoc file sound_dtc.doc). The DTM_TRIGGER method (with type set to STM_PLAY) causes a sampled sound to be played on the Amiga's audio hardware. Since the DTM_TRIGGER method requires other information in addition to the method ID, a dtTrigger structure is used. This structure is defined in <datatypes/datatypesclass.h>.

Note that if the Sound DataType is enhanced to support other types of sound files in a future version of AmigaOS, the code given here will automatically support the new type. This example expects the file name and path to a sound file.

<syntaxhighlight>
/* Run from CLI only. */

#include <exec/types.h>
#include <datatypes/datatypesclass.h> /* This includes other files we need */

#include <proto/exec.h> /* Prototypes for system functions */
#include <proto/intuition.h>
#include <proto/datatypes.h>
#include <proto/dos.h

struct IntuitionIFace *IIntuition = NULL;
struct DataTypesIFace *IDataTypes = NULL;

int main(int argc, char **argv)
{
APTR dtobject = NULL /* Pointer to a DataTypes object */
struct dtTrigger mydtt; /* A trigger structure for the DTM_TRIGGER method */

if(argc <= 1 ) /* CLI only, at least one argument please. */
{
IDOS->Printf("Give a file name too.\n");
return RETURN_FAIL;
}

struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

struct Library *DataTypesBase = IExec->OpenLibrary("datatypes.library", 50);
IDataTypes = (struct DataTypesIFace*)IExec->GetInterface(DataTypesBase, "main", 1, NULL);

if (IIntuition != NULL && IDataTypes != NULL)
{
/* Attempt to make an 8svx sound object from the file name the user */
/* specified in the command line. For a list of possible error */
/* returns, see the Autodocs for NewDTObjectA(). The group ID tag */
/* will allow only Sound DataType files to be accepted for the call.*/
if (dtobject = IDataTypes->NewDTObject(argv[1], DTA_GroupID, GID_SOUND,
TAG_END) )
{
mydtt.MethodID = DTM_TRIGGER; /* Fill in the dtTrigger struct */
mydtt.dtt_GInfo = NULL;
mydtt.dtt_Function = STM_PLAY;
mydtt.dtt_Data = NULL;

/* The return value of the DTM_TRIGGER method used with the 8svx */
/* Sound DataType is undefined in V39. This is likely to change */
/* in future versions of the Amiga operating system. */
uint32 dores = IDataTypes->DoDTMethodA(dtobject, NULL, NULL, &mydtt);

// Let the 8svx sound finish playing. Another way is to use
// SDTA_SignalTask and SDTA_SignalBit to find out when it is
// finished playing.
IExec->Wait(SIGBREAKF_CTRL_C);

IDataTypes->DisposeDTObject(dtobject);
}
else IDOS->Printf("Couldn't create new object or not a sound data file\n");
}
else IDOS->Printf("Can't open interfaces\n");

IExec->DropInterface((struct Interface*)IDataTypes);
IExec->CloseLibrary(DataTypesBase);

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

return 0;
}
</syntaxhighlight>

In addition to playing back a sampled sound, the DataTypes Library allows sound objects to become gadgets (the library includes default imagery for a sound gadget). Since all DataTypes are implemented as a subclass of the BOOPSI ''gadgetclass'', they all support the methods of gadget objects as described in the [[BOOPSI_-_Object_Oriented_Intuition|BOOPSI chapter]] in the Libraries section.

= Embedding DataTypes =

Since DataTypes are a subclass of the Intuition ''gadgetclass'', DataType objects can be attached to an Intuition window in a similiar way that gadgets can be added to a window. DataTypes use a parallel set of functions because it requires additional information that the Intuition functions weren't able to provide.

Currently the handling of the data is limited to reading, writing, printing, viewing (audio or visual), and clipboard access. Utilities like MultiView or MultiViewer are examples of applications that can embed DataType objects.

= Determining Data Type =

One of the main features of the DataTypes system is its ability to determine the type of a block of data. This data block can reside in a file or the clipboard.

The following functions are used to determine the DataType of a data block:

{| class="wikitable"
| ObtainDataTypeA() || Obtain the DataType descriptor for a data block.
|-
| ReleaseDataType() || Release the DataType descriptor for a data block.
|}

The data type detection functions use the DataType structure.

<syntaxhighlight>
struct DataType
{
struct Node dtn_Node1;
struct Node dtn_Node2;
struct DataTypeHeader *dtn_Header;
struct List dtn_ToolList;
STRPTR dtn_FunctionName;
struct TagItem *dtn_AttrList;
ULONG dtn_Length;
};
</syntaxhighlight>

The DataType structure is read-only. The only pertinent field is the dtn_Header field, which points to a DataTypeHeader structure.

<syntaxhighlight>
struct DataTypeHeader
{
STRPTR dth_Name;
STRPTR dth_BaseName;
STRPTR dth_Pattern;
WORD *dth_Mask;
ULONG dth_GroupID;
ULONG dth_ID;
WORD dth_MaskLen;
WORD dth_Pad;
UWORD dth_Flags;
WORD dth_Priority;
};
</syntaxhighlight>

The DataTypeHeader structure fields are as follows:

; dth_Name
: Descriptive name of the data type. For example, the description for an ILBM data type could possibly be "Amiga BitMap Picture".

; dth_BaseName
: This is the base name for the data type and is used to obtain the class that handles this data type.

; dth_GroupID
: This identifies the general type of data that the object contains. Following are the possible values:
:{| class="wikitable"
| GID_SYSTEM || Fonts, Executables, Libraries, Devices, etc...
|-
| GID_TEXT || Formatted or unformatted text.
|-
| GID_DOCUMENT || Formatted text with embedded DataTypes (such as pictures).
|-
| GID_SOUND || Audio samples.
|-
| GID_INSTRUMENT || Audio samples used for playing music.
|-
| GID_MUSIC || Musical scores.
|-
| GID_PICTURE || Graphic picture or brush.
|-
| GID_ANIMATION || Moving picture or cartoon.
|-
| GID_MOVIE || Moving picture or cartoon with sound.
|}

; dth_ID
: This is an individual indentifier for the DataType. For IFF files it is the same as the FORM type, for example ILBM for an Amiga BitMap picture. For non-IFF files, it is the first four characters of dth_Name.

; dth_Flags
: The flags field contains, among other information, the coarse type of data. The type can be obtained by ANDing DTF_TYPE_MASK with this field.
:{| class="wikitable"
| DTF_IFF || Interchange File Format
|-
| DTF_BINARY || Non-readable characters
|-
| DTF_ASCII || Readable characters
|-
| DTF_MISC || Disks and drawers
|}

; dth_Pattern
; dth_Mask
; dth_MaskLen
; dth_Priority
: These fields are used by the detection code in datatypes.library for determining the data type. See the "Defining a DataType Descriptor" section for more information.

Following is a code fragment that shows how to determine the data type of a file. This fragment uses functions from the DataTypes Library, DOS Library, and IFFParse Library.

<syntaxhighlight>
STRPTR name = "somefilename";
BPTR lock;

struct DataTypeHeader *dth;
struct DataType *dtn;
UBYTE idesc[5];
STRPTR tdesc;
STRPTR gdesc;
UWORD ttype;

/* Obtain a lock on the file that we want information on */
if (lock = IDOS->Lock (name, ACCESS_READ))
{
/* Get a pointer to the appropriate DataType structure */
if (dtn = IDataTypes->ObtainDataTypeA (DTST_FILE, (APTR)lock, NULL))
{
/* Get a pointer to the DataTypeHeader structure */
dth = dtn->dtn_Header;

/* Get the coarse type */
ttype = dth->dth_Flags & DTF_TYPE_MASK;

/* Get a pointer to the text strings */
tdesc = IDataTypes->GetDTString (ttype + DTMSG_TYPE_OFFSET);
gdesc = IDataTypes->GetDTString (dth->dth_GroupID);

/* Convert the ID to a string. */
IIFFParse->IDtoStr (dth->dth_ID, idesc);

/* Display the information */
IDOS->Printf (" Description: %s\n", dth->dth_Name);
IDOS->Printf (" Base Name: %s\n", dth->dth_BaseName);
IDOS->Printf (" Type: %d - %s\n", ttype, tdesc);
IDOS->Printf (" Group: %s\n", gdesc);
IDOS->Printf (" ID: %s\n", idesc);

/* Release the DataType structure now that we are done with it */
IDataTypes->ReleaseDataType (dtn);
}

/* Release the DOS lock on the file */
IDOS->UnLock (lock);
}
</syntaxhighlight>

= A Picture Class Example =

Here is a second, more complex example showing how to use all the DataTypes Library functions described so far. In this example the objects used are of class ILBM, a subclass of the Picture DataType.

Two methods will be performed with the object, DTM_PROCLAYOUT and DTM_FRAMEBOX. Both these methods have associated structures (gpLayout and dtFrameBox respectively). DTM_PROCLAYOUT makes the object available within the context of your application task (as opposed to Intuition's). DTM_FRAMEBOX queries the display environment required by the picture.

Other attributes of the picture are obtained with a call to GetDTAttrs() and then a matching Intuition screen is created and the ILBM object is displayed. This example expects the file and path name of a picture file.

<syntaxhighlight>
; /* Compiled with SAS/C 6.56. Run from CLI only.
sc DATA=NEAR NMINC STRMERGE NOSTKCHK IGNORE=73 dtpic.c
slink from lib:c.o dtpic.o TO dtpic LIBRARY lib:sc.lib lib:amiga.lib
quit ; */

#include <exec/types.h>
#include <datatypes/datatypes.h> /* DataTypes definitions we need */
#include <datatypes/pictureclass.h>
#include <stdio.h>

#include <clib/exec_protos.h> /* Prototypes for system functions */
#include <clib/intuition_protos.h>
#include <clib/alib_protos.h>
#include <clib/datatypes_protos.h>
#include <clib/graphics_protos.h>

#ifdef LATTICE
int CXBRK(void) { return(0); } /* Disable SAS/C CTRL-C handling */
int chkabort(void) { return(0); }
#endif

struct Library *IntuitionBase=NULL; /* System library bases */
struct Library *GfxBase=NULL;
struct Library *DataTypesBase=NULL;

VOID main(int argc, char **argv)
{
APTR dtobject=NULL; /* Pointer to a DataTypes object */
ULONG res; /* Variable for function return values */
struct dtFrameBox mydtFrameBox; /* Use this with DTM_FRAMEBOX method */
struct FrameInfo myFrameInfo; /* For info returned from DTM_FRAMEBOX */
struct gpLayout mygpLayout; /* Use this with DTM_PROCLAYOUT method */

ULONG modeID = INVALID_ID; /* Variables for storing the display */
struct Screen *myScreen=NULL; /* environment information obtained */
struct BitMap *bm = NULL; /* the DataType object. */
ULONG *cregs = NULL;
ULONG i,r,g,b,numcolors;

if (IntuitionBase=OpenLibrary("intuition.library",39L))
{
if (GfxBase=OpenLibrary("graphics.library",39L))
{
if(DataTypesBase=OpenLibrary("datatypes.library",0L))
{
if(argc > 1 ) /* CLI only, at least one argument please. */
{
/* Attempt to create a picture object in memory from the file */
/* name given by the user in the command line. If we wanted to */
/* show the picture in a screen set up ahead of time, we could */
/* set PDTA_Remap to TRUE and provide a pointer to the screen */
/* with the PDTA_Screen tag (datatypes.library handles the rest).*/
/* However in this case we want to first find out the attributes */
/* of the picture object and set up a matching screen and do the */
/* remapping later. Therefore PDTA_Remap is set to false. */
/* The group ID tag ensures that we get only a picture file type.*/
if (dtobject = NewDTObject(argv[1], PDTA_Remap, FALSE,
DTA_GroupID, GID_PICTURE,
TAG_END) )
{
/* Here we want to find the display environment required by */
/* this picture. To do that, perform the DTM_FRAMEBOX method */
/* on the object. The DataTypes Library fills in the struct */
/* FrameBox you give it with the info on the display needed. */
mydtFrameBox.MethodID = DTM_FRAMEBOX;
mydtFrameBox.dtf_GInfo = NULL;
mydtFrameBox.dtf_ContentsInfo = NULL;
mydtFrameBox.dtf_FrameInfo = &myFrameInfo;
mydtFrameBox.dtf_SizeFrameInfo= sizeof (struct FrameInfo);
mydtFrameBox.dtf_FrameFlags = 0L;

/* The return value from DTM_FRAMEBOX is currently undefined */
res = DoMethodA(dtobject, &mydtFrameBox);

/* OK, now do the layout (remap) of the object on our process */
mygpLayout.MethodID = DTM_PROCLAYOUT;
mygpLayout.gpl_GInfo = NULL;
mygpLayout.gpl_Initial= 1L;

/* The return value of DTM_PROCLAYOUT is non-zero for success */
if( res = DoMethodA(dtobject, &mygpLayout) )
{
/* Get the attributes of this picture object. You could */
/* use a series of GetAttr() function calls here instead. */
res = GetDTAttrs(dtobject, PDTA_ModeID, &modeID,
PDTA_CRegs, &cregs,
PDTA_BitMap, &bm,
TAG_END);

/* Did we get all threee attributes? */
if( (modeID!=INVALID_ID) && (cregs) && (bm) )
{
/* Open a screen that matches the picture object */
if( myScreen = OpenScreenTags( NULL,
SA_Width, myFrameInfo.fri_Dimensions.Width,
SA_Height, myFrameInfo.fri_Dimensions.Height,
SA_Depth, myFrameInfo.fri_Dimensions.Depth,
SA_DisplayID, modeID,
SA_BitMap, bm,
TAG_END) )
{
/* Now fill in the color registers for this screen */
numcolors = 2<<(myFrameInfo.fri_Dimensions.Depth-1);
for( i=0; i < numcolors; i++ )
{
r = cregs[i * 3 + 0];
g = cregs[i * 3 + 1];
b = cregs[i * 3 + 2];
SetRGB32(&myScreen->ViewPort, i, r, g, b);
}

printf("Ctrl-C in this window to quit\n");
/* Wait for the user to have a look... */
Wait(SIGBREAKF_CTRL_C);

CloseScreen(myScreen);
}
else printf("Couldn't open required screen\n");
}
else printf("Couldn't get picture attributes\n");

DisposeDTObject(dtobject);
}
else printf("Couldn't perform PROC_LAYOUT\n");
}
else printf("Couldn't create new object or not a picture file\n");
}
else printf("Give a file name too.\n");

CloseLibrary(DataTypesBase);
}
else printf("Can't open DataTypes Library\n");

CloseLibrary(GfxBase);
}
else printf("Can't open V39 graphics\n");

CloseLibrary(IntuitionBase);
}
else printf("Can't open V39 Intuition\n");
}
</syntaxhighlight>

As with 8SVX objects, the DataTypes Library allows ILBM objects to be treated as gadgets. Remember that all DataTypes are a subclass of the BOOPSI ''gadgetclass'' and therefore support the gadget methods described in [[BOOPSI_-_Object_Oriented_Intuition|the BOOPSI chapter]].

= Function Reference =

(to be provided)

Input Device

2015-08-22T19:46:55Z

Daniel Jedlicka:

[[Category:Devices|Input]]{{CodeReview}}
== Input Device ==

The input device is the central collection point for input events disseminated throughout the system. The best way to describe the input device is a manager of a stream with feeders. The input device itself and other modules such as the file system add events to the stream; so do input device “users”—programs or other devices that use parts of the stream or change it in some way. Feeders of the input device include the keyboard, timer and gameport devices. The keyboard, gameport, and timer devices are special cases in that the input device opens them and asks them for input. Users of the input device include Intuition and the console device.

== Input Device Commands and Functions ==

{| class="wikitable"
! Command
! Command Operation
|-
| CMD_FLUSH || Purge all active and queued requests for the input device.
|-
| CMD_RESET || Reset the input port to its initialized state. All active and queued I/O requests will be aborted. Restarts the device if it has been stopped.
|-
| CMD_START || Restart the currently active input (if any) and resume queued I/O requests.
|-
| CMD_STOP || Stop any currently active input and prevent queued I/O requests from starting.
|-
| IND_ADDEVENT || Propagate an input event to all handlers, updating event qualifiers.
|-
| IND_ADDHANDLER || Add an input-stream handler into the handler chain.
|-
| IND_ADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes.
|-
| IND_GETHANDLERLIST || Obtain a pointer to the list of input handlers.
|-
| IND_GETKDEVICE || Query the name and unit number of the device keyboard input events are collected from.
|-
| IND_GETMDEVICE || Query the name and unit number of the device mouse input events are collected from.
|-
| IND_GETPERIOD || Get the key repeat period.
|-
| IND_GETTHRESH || Get the key repeat threshold.
|-
| IND_IMMEDIATEADDNOTIFY || Add a hook which will be invoked whenever a configuration option changes. The hook will be invoked on the current configuration first.
|-
| IND_REMHANDLER || Remove an input-stream handler from the handler chain.
|-
| IND_REMOVENOTIFY || Remove a hook previously installed with the IND_ADDNOTIFY command.
|-
| IND_SETKDEVICE || Choose the device to collect keyboard input events from.
|-
| IND_SETMDEVICE || Choose the device to collect mouse input events from.
|-
| IND_SETMPORT || Set the controller port to which the mouse is connected.
|-
| IND_SETMTRIG || Set conditions that must be met by a mouse before a pending read request will be satisfied.
|-
| IND_SETMTYPE || Set the type of device at the mouse port.
|-
| IND_SETPERIOD || Set the period at which a repeating key repeats.
|-
| IND_SETTHRESH || Set the repeating key hold-down time before repeat starts.
|-
| IND_WRITEEVENT || Propagate an input event stream to all devices.
|}

{| class="wikitable"
|+ Input Device Functions
| PeekQualifier() || Return the input device’s current qualifiers.
|}

== Device Interface ==

The input device operates like the other Amiga devices. To use it, you must first open the input device, then send I/O requests to it, and then close it when finished. See [[Exec_Device_I/O|Exec Device I/O]] for general information on device usage.

A number of structures are used by the input device to do its processing. Some are used to pass commands and data to the device, some are used to describe input events like mouse movements and key depressions, and one structure is used to describe the environment for input event handlers.

The I/O request used by the input device for most commands is IOStdReq.

<syntaxhighlight>
struct IOStdReq
{
struct Message io_Message; /* message reply port */
struct Device *io_Device; /* device node pointer */
struct Unit *io_Unit; /* unit */
UWORD io_Command; /* input device command */
UBYTE io_Flags; /* input device flags */
BYTE io_Error; /* error code */
ULONG io_Length; /* number of bytes to transfer */
APTR io_Data; /* pointer to data area */
};
</syntaxhighlight>

See the include file exec/io.h for the complete structure definition.

Two of the input device commands—IND_SETTHRESH and IND_SETPERIOD—require a time specification and ''must'' use a TimeRequest structure instead of an IOStdReq.

<syntaxhighlight>
struct TimeRequest
{
struct IORequest Request;
struct TimeVal Time;
};
</syntaxhighlight>

As you can see, the TimeRequest structure includes an IORequest structure. The io_Command field of the IORequest indicates the command to the input device and the TimeVal structure sets the time values. See the include file devices/timer.h for the complete structure definition.

{{Note|title=In Case You Feel Like Reinventing the Wheel...|text=You could define a “super-IORequest” structure for the input device which would combine the IOStdReq fields with the TimeVal structure of the TimeRequest structure.}}

=== Opening the Input Device ===

Three primary steps are required to open the input device:

* Create a message port using AllocSysObject() and ASOT_PORT type. Reply messages from the device must be directed to a message port.
* Create an extended I/O request structure of type IOStdReq or TimeRequest using AllocSysObject() and ASOT_IOREQUEST type. The I/O request created by the AllocSysObject() function will be used to pass commands and data to the input device.
* Open the Input device. Call OpenDevice(), passing the I/O request.

<syntaxhighlight>
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

The above code will work for all the input device commands except for the ones which require a time specification. For those, the code would look like this:

<syntaxhighlight>
#include <devices/timer.h>

struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (InputMP != NULL)
{
struct TimeRequest *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct TimeRequest),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (ClipIO != NULL)
{
if (IExec->OpenDevice("input.device", 0, (struct IORequest *)InputIO, 0))
IDOS->Printf("input.device did not open\n");
</syntaxhighlight>

=== Input Device Event Types ===

The input device is automatically opened by the console device when the system boots. When the input device is opened, a task named “input.device” is started. The input device task communicates directly with the keyboard device to obtain raw key events. It also communicates with the gameport device to obtain mouse button and mouse movement events and with the timer device to obtain time events. In addition to these events, you can add your own input events to the input device, to be fed to the handler chain (see below).

The keyboard device is accessible directly (see [[Keyboard_Device|Keyboard Device]]). However, once the input.device task has started, you should not read events from the keyboard device directly, since doing so will deprive the input device of the events and confuse key repeating.

The gameport device has two units. As you view the Amiga, looking at the gameport connectors, the left connector is assigned as the primary mouse input for Intuition and contributes gameport input events to the input event stream.

The right connector is handled by the other gameport unit and is currently unassigned. While the input device task is running, that task expects to read the input from the left connector. Direct use of the gameport device is covered in [[Gameport_Device|Gameport Device]].

The timer device is used to generate time events for the input device. It is also used to control key repeat rate and key repeat threshold. The timer device is a shared-access device and is described in [[Timer_Device|Timer Device]].

The device-specific commands are described below. First though, it may be helpful to consider the types of input events that the input device deals with. An input event is a data structure that describes the following:

* The class of the event — often describes the device that generated the event.
* The subclass of the event — space for more information if needed.
* The code — keycode if keyboard, button information if mouse, others.
* A qualifier such as “Alt key also down,”or “key repeat active”.
* A position field that contains a data address or a mouse position count.
* A time stamp, to determine the sequence in which the events occurred.
* A link-field by which input events are linked together.
* The class, subclass, code and qualifier of the previous down key.

The full definitions for each field can be found in the include file devices/inputevent.h. You can find more information about input events in [[Gameport_Device|Gameport Device]] and [[Console_Device|Console Device]].

The various types of input events are listed below.

{| class="wikitable"
|+ Input Device Event Types
| IECLASS_NULL || A NOP input event
|-
| IECLASS_RAWKEY || A raw keycode from the keyboard device
|-
| IECLASS_RAWMOUSE || The raw mouse report from the gameport device
|-
| IECLASS_EVENT || A private console event
|-
| IECLASS_POINTERPOS || A pointer position report
|-
| IECLASS_TIMER || A timer event
|-
| IECLASS_GADGETDOWN || Select button pressed down over a gadget (address in ie_EventAddress)
|-
| IECLASS_GADGETUP || Select button released over the same gadget (address in ie_EventAddress)
|-
| IECLASS_REQUESTER || Some requester activity has taken place.
|-
| IECLASS_MENULIST || This is a menu number transmission (menu number is in ie_Code)
|-
| IECLASS_CLOSEWINDOW || User has selected the active window’s Close Gadget
|-
| IECLASS_SIZEWINDOW || This window has a new size
|-
| IECLASS_REFRESHWINDOW || The window pointed to by ie_EventAddress needs to be refreshed
|-
| IECLASS_NEWPREFS || New preferences are available
|-
| IECLASS_DISKREMOVED || The disk has been removed
|-
| IECLASS_DISKINSERTED || The disk has been inserted
|-
| IECLASS_ACTIVEWINDOW || The window is about to be been made active
|-
| IECLASS_INACTIVEWINDOW || The window is about to be made inactive
|-
| IECLASS_NEWPOINTERPOS || Extended-function pointer position report
|-
| IECLASS_MENUHELP || Help key report during Menu session
|-
| IECLASS_CHANGEWINDOW || The Window has been modified with move, size, zoom, or change
|}

There is a difference between simply receiving an input event from a device and actually becoming a handler of an input event stream. A handler is a routine that is passed an input event list. It is up to the handler to decide if it can process the input events. If the handler does not recognize an event, it leaves it undisturbed in the event list.

{{Note|title=It All Flows Downhill|text=Handlers can themselves generate new linked lists of events which can be passed down to lower priority handlers.}}

The InputEvent structure is used by the input device to describe an input event such as a keypress or a mouse movement.

<syntaxhighlight>
struct InputEvent
{
struct InputEvent *ie_NextEvent; /* the chronologically next event */
UBYTE ie_Class; /* the input event class */
UBYTE ie_SubClass; /* optional subclass of the class */
UWORD ie_Code; /* the input event code */
UWORD ie_Qualifier; /* qualifiers in effect for the event*/
union
{
struct
{
WORD ie_x; /* the pointer position for the event*/
WORD ie_y;
} ie_xy;
APTR ie_addr; /* the event address */
struct
{
UBYTE ie_prev1DownCode; /* previous down keys for dead */
UBYTE ie_prev1DownQual; /* key translation: the ie_Code */
UBYTE ie_prev2DownCode; /* & low byte of ie_Qualifier for */
UBYTE ie_prev2DownQual; /* last & second last down keys */
} ie_dead;
} ie_position;
struct timeval ie_TimeStamp; /* the system tick at the event */
};
</syntaxhighlight>

The IEPointerPixel and IEPointerTablet structures are used to set the mouse position with the IECLASS_NEWPOINTERPOS input event class.

<syntaxhighlight>
struct IEPointerPixel
{
struct Screen *iepp_Screen; /* pointer to an open screen */
struct
{ /* pixel coordinates in iepp_Screen */
WORD X;
WORD Y;
} iepp_Position;
};

struct IEPointerTablet
{
struct
{
UWORD X;
UWORD Y;
} iept_Range; /* 0 is min, these are max */
struct
{
UWORD X;
UWORD Y;
} iept_Value; /* between 0 and iept_Range */

WORD iept_Pressure; /* -128 to 127 (unused, set to 0) */
};
</syntaxhighlight>

See the include file devices/inputevent.h for the complete structure definitions.

For input device handler installation, the Interrupt structure is used.

<syntaxhighlight>
struct Interrupt
{
struct Node is_Node;
APTR is_Data; /* server data segment */
VOID (*is_Code)(); /* server code entry */
};
</syntaxhighlight>

See the include file exec/interrupts.h for the complete structure definition.

=== Closing the Input Device ===

Each OpenDevice() must eventually be matched by a call to CloseDevice(). All I/O requests must be complete before CloseDevice(). If any requests are still pending, abort them with AbortIO():

<syntaxhighlight>
if (!(IExec->CheckIO(InputIO)))
{
IExec->AbortIO(InputIO); /* Ask device to abort request, if pending */
}
IExec->WaitIO(InputIO); /* Wait for abort, then clean up */
IExec->CloseDevice((struct IORequest *)InputIO);
</syntaxhighlight>

== Using the Mouse Port With the Input Device ==

To get mouse port information you must first set the current mouse port by passing an IOStdReq to the device with IND_SETMPORT set in io_Command and a pointer to a byte set in io_Data. If the byte is set to 0 the left controller port will be used as the current mouse port; if it is set to 1, the right controller port will be used.

<syntaxhighlight>
int8 port = 1; /* set mouse port to right controller */

InputIO->io_Data = &port;
InputIO->io_Flags = IOF_QUICK;
InputIO->io_Length = 1;
InputIO->io_Command = IND_SETMPORT;
IExec->BeginIO((struct IORequest *)InputIO);
if (InputIO->io_Error)
IDOS->Printf("\nSETMPORT failed %ld\n", InputIO->io_Error);
</syntaxhighlight>

{{Note|title=Put That Back!|text=The default mouse port is the left controller. Don’t forget to set the mouse port back to the left controller before exiting if you change it to the right controller during your application.}}

=== Setting the Conditions for a Mouse Port Report ===

You set the conditions for a mouse port report by passing an IOStdReq to the device with IND_SETMTRIG set in io_Command, the address of a GamePortTrigger structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct GamePortTrigger InputTR;

InputIO->io_Data = (APTR)InputTR; /* set trigger conditions */
InputIO->io_Command = IND_SETMTRIG; /* from InputTR */
InputIO->io_Length = sizeof(struct GamePortTrigger);
IExec->DoIO(InputIO);
</syntaxhighlight>

The information needed for mouse port report setting is contained in a GamePortTrigger data structure which is defined in the include file devices/gameport.h.

<syntaxhighlight>
struct GamePortTrigger
{
UWORD gpt_Keys; /* key transition triggers */
UWORD gpt_Timeout; /* time trigger (vertical blank units) */
UWORD gpt_XDelta; /* X distance trigger */
UWORD gpt_YDelta; /* Y distance trigger */
};
</syntaxhighlight>

See the [[Gameport Device]] chapter of this manual for a full description of setting mouse port trigger conditions.

== Adding an Input Handler ==

You add an input-stream handler to the input chain by passing an IOStdReq to the device with IND_ADDHANDLER set in io_Command and a pointer to an Interrupt structure set in io_Data.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO

InputHandler->is_Code = ButtonSwap; /* Address of code */
InputHandler->is_Data = NULL; /* User Value passed in A1 */
InputHandler->is_Node.ln_Pri = 100; /* Priority in food chain */
InputHandler->is_Node.ln_Name = NameString; /* Name of handler */

InputIO->io_Data = (APTR)inputHandler; /* Point to the structure */
InputIO->io_Command = IND_ADDHANDLER; /* Set command ... */
IExec->DoIO((struct IORequest *)InputIO); /* DoIO( ) the command */
</syntaxhighlight>

Intuition is one of the input device handlers and normally distributes most of the input events.

Intuition inserts itself at priority position 50. The console device sits at priority position 0. You can choose the position in the chain at which your handler will be inserted by setting the priority field in the list-node part of the interrupt data structure you pass to this routine.

{{Note|title=Speed Saves|text=''Any'' processing time expended by a handler subtracts from the time available before the next event happens. Therefore, handlers for the input stream ''must'' be fast.}}

=== Rules for Input Device Handlers ===

The following rules should be followed when you are designing an input handler:

* If an input handler is capable of processing a specific kind of an input event and that event has no links (ie_NextEvent = 0), the handler can end the handler chain by returning a NULL (0) value.

* If there are multiple events linked together, the handler is free to unlink an event from the input event chain, thereby passing a shorter list of events to subsequent handlers. The starting address of the modified list is the return value.

* If a handler wishes to add new events to the chain that it passes to a lower-priority handler, it may initialize memory to contain the new event or event chain. The handler, when it again gets control on the next round of event handling, should assume nothing about the current contents of the memory blocks attached to the event chain. Lower priority handlers may have modified the memory as they handled their part of the event. The handler that allocates the memory for this purpose should keep track of the starting address and the size of this memory chunk so that the memory can be returned to the free memory list when it is no longer needed.

Your handler routine should be structured similar to the following pseudo-language statement:

<syntaxhighlight>
newEventChain = yourHandlerCode(oldEventChain, yourHandlerData);
</syntaxhighlight>

where:

; yourHandlerCode
: is the entry point to your routine.
; oldEventChain
: is the starting address for the current chain of input events.
; yourHandlerData
: is a user-definable value, usually a pointer to some data structure your handler requires.
; newEventChain
: is the starting address of an event chain which you are passing to the next handler, if any.

When your handler code is called, the event chain and the handler data is passed in. When your code returns, it should return the pointer to the event chain. If all of the events were removed by the routine, return NULL. A NULL (0) value terminates the handling thus freeing more CPU resources.

Memory that you use to describe a new input event that you have added to the event chain is available for reuse or deallocation when the handler is called again or after the IND_REMHANDLER command for the handler is complete. There is no guarantee that any field in the event is unchanged since a handler may change any field of an event that comes through the food chain.

Because IND_ADDHANDLER installs a handler in any position in the handler chain, it can, for example, ignore specific types of input events as well as act upon and modify existing streams of input. It can even create new input events for Intuition or other programs to interpret.

=== Removing an Input Handler ===

You remove a handler from the handler chain by passing an IOStdReq to the device IND_REMHANDLER set in io_Command and a pointer to the Interrupt structure used to add the handler.

<syntaxhighlight>
struct Interrupt *InputHandler;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)InputHandler; /* Which handler to REM */
InputIO->io_Command = IND_REMHANDLER; /* The REM command */
IExec->DoIO((struct IORequest *)InputIO); /* Send the command */
</syntaxhighlight>

== Writing Events to the Input Device Stream ==

Typically, input events are internally generated by the timer device, keyboard device, and input device.

An application can also generate an input event by setting the appropriate fields for the event in an InputEvent structure and sending it to the input device. It will then be treated as any other event and passed through to the input handler chain. However, I/O requests for IND_WRITEVENT cannot be made from interrupt code.

You generate an input event by passing an IOStdReq to the device with IND_WRITEEVENT set in io_Command, a pointer to an InputEvent structure set in io_Data and the length of the structure set in io_Length.

<syntaxhighlight>
struct InputEvent *FakeEvent;
struct IOStdReq *InputIO;

InputIO->io_Data = (APTR)FakeEvent;
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);
</syntaxhighlight>

{{Note|title=You Know What Happens When You Assume|text=This command propagates the input event through the handler chain. The handlers may link other events onto the end of this event or modify the contents of the data structure you constructed in any way they wish. Therefore, do not assume any of the data will be the same from event to event.}}

=== Setting the Position of the Mouse ===

One use of writing input events to the input device is to set the position of the mouse pointer. The mouse pointer can be positioned by using the input classes IECLASS_POINTERPOS and IECLASS_NEWPOINTERPOS.

There are two ways to set the position of the mouse pointer using the input class IECLASS_POINTERPOS:

* At an absolute position on the current screen.
* At a position relative to the current mouse pointer position on the current screen.

In both cases, you set the Class field of the InputEvent structure to IECLASS_POINTERPOS, ie_X with the new x-coordinate and ie_Y with the new y-coordinate. Absolute positioning is done by setting ie_Qualifier to 0 and relative positioning is done by setting ie_Qualifier to IEQUALIFIER_RELATIVEMOUSE.

Once the proper values are set, pass an IOStdReq to the input device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

There are three ways to set the mouse pointer position using IECLASS_NEWPOINTERPOS:

* At an absolute x-y coordinate on a screen—you specify the exact location of the pointer and which screen.
* At an relative x-y coordinate—you specify where it will go in relation to the current pointer position and which screen.
* At a normalized position on a tablet device—you specify the maximum x-value and y-value of the tablet and an x-y coordinate between them and the input device will normalize it to fit.

The basic steps required are the same for all three methods.

* Get a pointer to the screen where you want to position the pointer. This is not necessary for the tablet device.
* Set up a structure to indicate the new position of the pointer.

For absolute and relative positioning, you set up an IEPointerPixel structure with iepp_Position.X set to the new x-coordinate, iepp_Position.Y set to the new y-coordinate and iepp_Screen set to the screen pointer. You set up an InputEvent structure with ie_SubClass set to IESUBCLASS_PIXEL, a pointer to the IEPointerPixel structure set in ie_EventAddress, IECLASS_NEWPOINTERPOS set in Class, and ie_Qualifier set to either IEQUALIFIER_RELATIVEMOUSE for relative positioning or 0 for absolute positioning.

For tablet positioning, you set up an IEPointerTablet structure with iept_Range.X set to the maximum x-coordinate and iept_Range.Y set to the maximum y-coordinate, and iept_Value.X set to the new x-coordinate and iept_Value.Y set to the new y-coordinate. You set up an InputEvent structure with a pointer to the IEPointerTablet structure set in ie_EventAddress, ie_SubClass to IESUBCLASS_TABLET and Class set to IECLASS_NEWPOINTERPOS.

Finally, for all three methods, pass an IOStdReq to the device with a pointer to the InputEvent structure set in io_Data and io_Command set to IND_WRITEEVENT.

The following example sets the mouse pointer at an absolute position on a public screen using IECLASS_NEWPOINTERPOS.

<syntaxhighlight>
/*
* Set_Mouse.c
*
* This example sets the mouse at x=100 and y=200
*
* Run from CLI only
*/

#include <exec/types.h>
#include <exec/memory.h>
#include <devices/input.h>
#include <devices/inputevent.h>
#include <intuition/screens.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

int main()
{
struct MsgPort *InputMP = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);
if (InputMP != NULL)
{
struct InputEvent *FakeEvent = IExec->AllocVecTags(sizeof(struct InputEvent),
AVT_Type, MEMF_SHARED,
TAG_END);

if (FakeEvent != NULL)
{
struct IEPointerPixel *NeoPix = IExec->AllocVecTags(sizeof(struct IEPointerPixel),
AVT_Type, MEMF_SHARED,
TAG_END);

if (NeoPix != NULL)
{
struct IOStdReq *InputIO = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, InputMP,
TAG_END);

if (InputIO != NULL)
{
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace*)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Screen *PubScreen;
/* Get pointer to screen and lock screen */
if (PubScreen = (struct Screen *)IIntuition->LockPubScreen(NULL))
{
/* Set up IEPointerPixel fields */
NeoPix->iepp_Screen = (struct Screen *)PubScreen; /* WB screen */
NeoPix->iepp_Position.X = 100; /* put pointer at x = 100 */
NeoPix->iepp_Position.Y = 200; /* put pointer at y = 200 */

/* Set up InputEvent fields */
FakeEvent->ie_EventAddress = (APTR)NeoPix; /* IEPointerPixel */
FakeEvent->ie_NextEvent = NULL;
FakeEvent->ie_Class = IECLASS_NEWPOINTERPOS; /* new mouse pos */
FakeEvent->ie_SubClass = IESUBCLASS_PIXEL; /* on pixel */
FakeEvent->ie_Code = IECODE_NOBUTTON;
FakeEvent->ie_Qualifier = 0; /* absolute positioning */

InputIO->io_Data = (APTR)FakeEvent; /* InputEvent */
InputIO->io_Length = sizeof(struct InputEvent);
InputIO->io_Command = IND_WRITEEVENT;
IExec->DoIO((struct IORequest *)InputIO);

IIntuition->UnlockPubScreen(NULL, PubScreen); /* Unlock screen */
}
else
IDOS->Printf("Could not get pointer to screen\n");
}
else
IDOS->Printf("Error: Could not open intuition.library\n");

IExec->DropInterface((struct Interface*)IIntuition);
IExec->CloseLibrary(IntuitionBase);

IExec->CloseDevice((struct IORequest *)InputIO);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, InputIO);
}
else
IDOS->Printf("Error: Could not create IORequest\n");

IExec->FreeVec(NeoPix);
}
else
IDOS->Printf("Error: Could not allocate memory for NeoPix\n");

IExec->FreeVec(FakeEvent);
}
else
IDOS->Printf("Error: Could not allocate memory for FakeEvent\n");

IExec->FreeSysObject(ASOT_PORT, InputMP);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

== Setting the Key Repeat Threshold ==

The key repeat threshold is the number of seconds and microseconds a user must hold down a key before it begins to repeat. This delay is normally set by the Preferences tool or by Intuition when it notices that the Preferences have been changed, but you can also do it directly through the input device.

You set the key repeat threshold by passing a TimeRequest with IND_SETTHRESH set in io_Command and the number of seconds to delay set in Seconds and the number of microseconds to delay set in Microseconds.

<syntaxhighlight>
#include <devices/timer.h>

struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 1; /* 1 second */
InputTime->Time.Microseconds = 500000; /* 500,000 microseconds */
InputTime->Request.io_Command = IND_SETTHRESH;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above will set the key repeat threshold to 1.5 seconds.

== Setting the Key Repeat Interval ==

The key repeat interval is the time period, in seconds and microseconds, between key repeat events once the initial key repeat threshold has elapsed. (See "Setting the Key Repeat Threshold" above.) Like the key repeat threshold, this is normally issued by Intuition and preset by the Preferences tool.

You set the key repeat interval by passing a TimeRequest with IND_SETPERIOD set in io_Command and the number of seconds set in Seconds and the number of microseconds set in Microseconds.

<syntaxhighlight>
struct TimeRequest *InputTime; /* Initialize with AllocSysObject(ASOT_IOREQUEST) before using */

InputTime->Time.Seconds = 0;
InputTime->Time.Microseconds = 12000; /* 0.012 seconds */
InputTime->Request.io_Command = IND_SETPERIOD;
IExec->DoIO((struct IORequest *)InputTime);
</syntaxhighlight>

The code above sets the key repeat interval to 0.012 seconds.

{{Note|title=The Right Tool For The Right Job|text=As previously stated, you ''must'' use a TimeRequest structure with IND_SETTHRESH and IND_SETPERIOD.}}

== Determining the Current Qualifiers ==

Some applications need to know whether the user is holding down a qualifier key or a mouse button during an operation. To determine the current qualifiers, you call the input device function PeekQualifier().

PeekQualifier() returns what the input device ''considers'' to be the current qualifiers at the time PeekQualifier() is called (e.g., keyboard qualifiers and mouse buttons). This does not include any qualifiers which have been added, removed or otherwise modified by input handlers.

In order to call the function, you must set a pointer to the input device base address and get the interface. Once you set the interface pointer, you can call the function. ''You must open the device in order to access the device base address and interface.''

PeekQualifier() returns an unsigned word with bits set according to the qualifiers in effect at the ''time'' the function is called. It takes no parameters.

<syntaxhighlight>
int main()
{
struct IOStdReq *InputIO; /* I/O request block */
uint16 Quals; /* qualifiers */
.
.
.
if (!IExec->OpenDevice("input.device", NULL, (struct IORequest *)InputIO, NULL))
{
/* Set input device base address in InputBase */
struct Library *InputBase = (struct Library *)InputIO->io_Device;
struct InputIFace *IInput = (struct InputIFace *)IExec->GetInterface(InputBase, "main", 1, NULL);

/* Call the function */
Quals = IInput->PeekQualifier();
.
.
.
IExec->DropInterface((struct Interface *)IInput);
IExec->CloseDevice(InputIO);
}
}
</syntaxhighlight>

The qualifiers returned are listed in the table below.
{| class="wikitable"
! Bit
! Qualifier
! Key or Button
|-
| 0 || IEQUALIFIER_LSHIFT || Left Shift
|-
| 1 || IEQUALIFIER_RSHIFT || Right Shift
|-
| 2 || IEQUALIFIER_CAPSLOCK || Caps Lock
|-
| 3 || IEQUALIFIER_CONTROL || Control
|-
| 4 || IEQUALIFIER_LALT || Left Alt
|-
| 5 || IEQUALIFIER_RALT || Right Alt
|-
| 6 || IEQUALIFIER_LCOMMAND || Left-Amiga
|-
| 7 || IEQUALIFIER_RCOMMAND || Right-Amiga
|-
| 12 || IEQUALIFIER_MIDBUTTON || Middle Mouse
|-
| 13 || IEQUALIFIER_RBUTTON || Right Mouse
|-
| 14 || IEQUALIFIER_LEFTBUTTON || Left Mouse
|}

== Input Device and Intuition ==

There are several ways to receive information from the various devices that are part of the input device. The first way is to communicate directly with the device. This method is not recommended while the input device task is running – which is most of the time. The second way is to become a handler for the stream of events which the input device produces. That method is shown above.

The third method of getting input from the input device is to retrieve the data from the console device or from the IDCMP (Intuition Direct Communications Message Port). These are the preferred methods for applications in a multitasking environment because each application can receive juts its own input (i.e., only the input which occurs when one of its window is active). See the [[Intuition_Input_and_Output_Methods|Intuition Input and Output Methods]] for more information on IDCMP messages. See [[Console_Device|Console Device]] for more information on console device I/O.

== Example Input Device Program ==

=== Swap_Buttons.c ===

<syntaxhighlight>
#include <exec/types.h>
#include <exec/memory.h>
#include <exec/interrupts.h>
#include <devices/input.h>
#include <intuition/intuition.h>

#include <proto/dos.h>
#include <proto/exec.h>
#include <proto/intuition.h>

struct IntuitionIFace *IIntuition = NULL;

UBYTE NameString[] = "Swap Buttons";

struct NewWindow mywin={50,40,124,18,0,1,CLOSEWINDOW,
WINDOWDRAG|WINDOWCLOSE|SIMPLE_REFRESH|NOCAREREFRESH,
NULL,NULL,NameString,NULL,NULL,0,0,0,0,WBENCHSCREEN};

extern VOID ButtonSwap();

/*
* This routine opens a window and waits for the one event that
* can happen (CLOSEWINDOW) This is just to let the user play with
* the swapped buttons and then close the program...
*/
VOID WaitForUser(VOID)
{
struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);

if (IIntuition != NULL)
{
struct Window *win = IIntuition->OpenWindow(&mywin);
if (win != NULL)
{
IExec->WaitPort(win->UserPort);
IExec->ReplyMsg(IExec->GetMsg(win->UserPort));

IIntuition->CloseWindow(win);
}
}

IExec->DropInterface((struct Interface *)IIntuition);
IExec->CloseLibrary(IntuitionBase);
}

int main()
{
struct MsgPort *inputPort = IExec->AllocSysObjectTags(ASOT_PORT, TAG_END);

if (inputPort != NULL)
{
struct Interrupt *inputHandler = IExec->AllocSysObjectTags(ASOT_INTERRUPT,
ASOINTR_Code, ButtonSwap,
TAG_END);

if (inputHandler != NULL)
{
struct IOStdReq *inputReqBlk = IExec->AllocSysObjectTags(ASOT_IOREQUEST,
ASOIOR_Size, sizeof(struct IOStdReq),
ASOIOR_ReplyPort, inputPort,
TAG_END);

if (inputReqBlk != NULL)
{
if (!IExec->OpenDevice("input.device", NULL,
(struct IORequest *)inputReqBlk, NULL))
{
inputHandler->is_Node.ln_Pri = 100;
inputHandler->is_Node.ln_Name = NameString;

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_ADDHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

WaitForUser();

inputReqBlk->io_Data = (APTR)inputHandler;
inputReqBlk->io_Command = IND_REMHANDLER;
IExec->DoIO((struct IORequest *)inputReqBlk);

IExec->CloseDevice((struct IORequest *)inputReqBlk);
}
else
IDOS->Printf("Error: Could not open input.device\n");

IExec->FreeSysObject(ASOT_IOREQUEST, inputReqBlk);
}
else
IDOS->Printf("Error: Could not create I/O request\n");

IExec->FreeSysObject(ASOT_INTERRUPT, inputHandler);
}
else
IDOS->Printf("Error: Could not allocate interrupt\n");

IExec->FreeSysObject(ASOT_PORT, inputPort);
}
else
IDOS->Printf("Error: Could not create message port\n");

return 0;
}
</syntaxhighlight>

=== InputHandler.a ===

<pre>
****************************************************************************
* InputHandler.a
*
* InputHandler that does a Left/Right mouse button swap...
*
* See Swap_Buttons.c for details on how to compile/assemble/link...
*
************************************************************************
*
* Required includes...
*
INCDIR "include:"
INCLUDE "exec/types.i"
INCLUDE "exec/io.i"
INCLUDE "devices/inputevent.i"
*
************************************************************************
*
* Make the entry point external...
*
xdef _ButtonSwap
*
************************************************************************
*
* This is the input handler that will swap the
* mouse buttons for left handed use.
*
* The event list gets passed to you in a0.
* The is_Data field is passed to you in a1.
* This example does not use the is_Data field...
*
* On exit you must return the event list in d0. In this way
* you could add or remove items from the event list.
*
* The handler gets called here...
*
*
_ButtonSwap: move.l a0,-(sp) ; Save the event list
*
* Since the event list could be a linked list, we start a loop
* here to handle all of the events passed to us.
*
CheckLoop: move.w ie_Qualifier(a0),d1 ; Get qualifiers...
move.w d1,d0 ; Two places...
*
* Since we are changing left and right mouse buttons, we need to make
* sure that we change the qualifiers on all of the messages. The
* left and right mouse buttons are tracked in the message qualifiers
* for use in such things as dragging. To make sure that we continue
* to drag correctly, we change the qualifiers.
*
CheckRight: btst #IEQUALIFIERB_RBUTTON,d1 ; Check for right
beq.s NoRight
bset #IEQUALIFIERB_LEFTBUTTON,d0 ; Set the left...
beq.s CheckLeft
NoRight: bclr #IEQUALIFIERB_LEFTBUTTON,d0 ; Clear the left...
*
CheckLeft: btst #IEQUALIFIERB_LEFTBUTTON,d1 ; Check for left
beq.s NoLeft
bset #IEQUALIFIERB_RBUTTON,d0 ; Set the right...
beq.s SaveQual
NoLeft: bclr #IEQUALIFIERB_RBUTTON,d0 ; Clear the right...
*
SaveQual: move.w d0,ie_Qualifier(a0) ; Save back...
*
* The actual button up/down events are transmitted as the
* code field in RAWMOUSE events. The code field must the be
* checked and modified when needed on RAWMOUSE events. If the
* event is not a RAWMOUSE, we are done with it.
*
cmp.b #IECLASS_RAWMOUSE,ie_Class(a0) ; Check for mouse
bne.s NextEvent ; If not, next...
*
move.w ie_Code(a0),d0 ; Get code...
move.w d0,d1 ; Save...
and.w #$7F,d0 ; Mask UP_PREFIX
cmp.w #IECODE_LBUTTON,d0 ; Check for Left...
beq.s SwapThem ; If so, swap...
cmp.w #IECODE_RBUTTON,d0 ; Check for Right...
bne.s NextEvent ; If not, next...
*
SwapThem: eor.w #1,d1 ; Flip bottom bit
move.w d1,ie_Code(a0) ; Save it...
*
* The event list is linked via a pointer to the next event
* in the first element of the structure. That is why it is not
* nessesary to use: move.l ie_NextEvent(a0),d0
*
* The reason I move to d0 first is that this also checks for zero.
* The last event in the list will have a NULL ie_NextEvent field.
* This is NOT as standard EXEC list where the node after the last
* node is NULL. Input events are single-linked for performance.
*
NextEvent: move.l (a0),d0 ; Get next event
move.l d0,a0 ; into a0...
bne.s CheckLoop ; Do some more.
*
* All done, just return the event list... (in d0)
*
move.l (sp)+,d0 ; Get event list back...
rts ; return from handler...
</pre>

== Additional Information on the Input Device ==

Additional programming information on the input device can be found in the include files and the autodocs for the input device. Both are contained in the SDK.

{| class="wikitable"
! Includes
|-
| devices/input.h
|-
| devices/inputevent.h
|}

{| class="wikitable"
! AutoDocs
|-
| input.doc
|}