Action Support Guide

Version:1.2
Status:N/A
Date:February 2002
Author:Rocklyte Systems
Copyright:  Rocklyte Systems 1996-2002. All rights reserved.
Short:  Describes the minimum requirements for supporting the available system actions.



Description

If you're writing a new class, you will need to consider what actions you will need to support, and know what is expected of your source code when you are supporting each action. This document provides you with full details on how your class is expected to handle the various actions, as well as advice on the basic requirements and potential pitfalls.

If you have not read the Class Manual and Class Development Guide yet, make sure that you read these first to develop an understanding on how the action mechanism works internally.

Action Index

AccessObject  Used for intercepting exclusive locks.
ActionNotify  Used for supporting subscriptions originating from the SubscribeAction() function.
Activate  Performs the native action of an object.
Clear  Used for clearing an object's data.
Clipboard  Used to manage cut, copy and paste operations with Clipboard objects.
ClosingTag  Provided for the purpose of script execution.
CopyData  Copies one object's data to another.
DataChannel  Provides a mechanism for sending formatted data betweeen objects.
Deactivate  Stops the processing of an object's native action.
Disable  Disables an object's interactive functionality.
Draw  Draws an object inside its drawable container.
Enable  Enables a disabled object.
EventMessage  Used for supporting event subscriptions originating from the Broadcast class.
FieldNotify  Used for supporting subscriptions originating from the SubscribeField() function.
Flush  Flushes buffered data from an object.
Focus  Used to inform objects that they have the focus.
Free  This action must be supported for the purposes of resource deallocation.
FreeWarning  Used for receiving an early warning before an object is freed.
GetUnlistedField  Used for the purpose of supporting unlisted field settings.
HealthCheck  This action can be supported in the interests of preventing data corruption to an object.
Hide  Used for hiding an object from the user.
Init  Called when an object is initialised.
Lock  Used when a programmer wants to lock the functionality of an object.
LostFocus  This action is called when an object loses the user focus.
Move  Used for moving objects to new coordinates.
MoveToBack  Moves an object to the back of its container.
MoveToFront  Moves an object to the front of its container.
NewChild  Used by classes that need to be alerted when an object receives a new child.
NewOwner  Called when the owner of an object is about to change.
NewObject  Called when a new object has been created from a base class.
OpeningTag  Provided for the purpose of script execution.
Query  Used to query the information represented by an object.
Read  Used for reading raw data from an object.
Refresh  Refreshes the state of an object.
ReleaseObject  Used for intercepting the release of exclusive locks.
Rename  Used for renaming objects.
Reset  Resets an object to its original state.
Resize  Used for resizing the dimensions of an object.
SaveImage  Saves an object's image to a data storage object.
SaveToObject  Saves an object's data to a data storage object.
Scroll  Scrolls the contents of an object.
Seek  Seeks to a new position within an object.
SetUnlistedField  Used for the purpose of supporting unlisted field settings.
Show  Makes an object visible to the user.
Timer  This action must be supported if the class requires regular timing messages.
Unlock  Unlocks an object's functionality.
UserClick  Used by drawable classes that need to respond to user clicks.
UserClickRelease  Used by drawable classes that need to respond to user click releases.
UserMovement  Used for detecting and responding to user movement.
Write  Used for writing raw data to an object.
Action:AccessObject
Short:Used for intercepting exclusive locks.

Although the object kernel's AccessObject() function works on all objects regardless of their support for this action, you may want to be informed when an exclusive lock is about to be granted. By supporting this action, you can take a more active role in your object's locking behaviour.

When a program calls AccessObject(), a check will be made to see if your class supports the AccessObject action. If it does, a call will be made to your support routine. If you do not have a support routine, AccessObject() will assume that you do not wish to be informed, and will proceed to grant the exclusive lock.

If you return an error code other than ERR_Okay, AccessObject() will abort and return that error code to the program that made the exclusive call.

 

Action:ActionNotify
Short:Used for supporting subscriptions originating from the SubscribeAction() function.
Arguments:
ACTIONID ActionID  The ID of the action that was called.
OBJECTID ObjectID  The ID of the object that received the action call.
APTR Args  If arguments were specified, this pointer will refer to them.
LONG Size  Indicates the size of the Args structure.
ERROR Error  Indicates the error code that was returned from the action support routine.

This action will need to be supported by your class if you have called the SubscribeAction() function to monitor the action/s of a foreign object. By supporting ActionNotify, you will be able to receive action notification messages originating from the subscription service.

The ActionNotify action is called after or during the execution of a monitored object's support routine. You will receive information telling you the ID of the object and the action that was called, the arguments that were passed and an error code that indicates whether or not the call was successful. There are no restrictions on how you should respond to an ActionNotify call. The error code that you return from this action will be ignored.

You can terminate an action subscription by calling the UnsubscribeAction() function.

 

Action:Activate
Short:Performs the native action of an object.

The Activate action is the most abstract of those that are available, which means that you are free to implement a support routine that does whatever you like (so long as it is in the spirit of the object's context). For example, a Music class would play audio, a Command class would execute a command and an Effect class would start drawing graphics.

If your object performs an action that continues in the background after returning to the program, you may also want to support the Deactivate action to provide a cancellation service.

 

Action:Clear
Short:Used for clearing an object's data.

Clearing is an interesting action as it can have a very different meaning for each object. Clearing a graphic for example will often leave a black area on the screen, while clearing a File might delete it from the file system. Depending on your object type, you will have to make the most logical decision as to how you might support this action.

 

Action:Clipboard
Short:Used to manage cut, copy and paste operations with Clipboard objects.

If you want to provide support for the system-wide clipboard service then you will need to write code for the Clipboard action. This action is closely related to the Clipboard class, as you will be passed a Clipboard object in the ClipboardID argument and will be expected to interact with that object. The Mode reflects the type of action that you should perform. Available Mode types are listed in the following table:

TypeDescription
CLIP_CUTCut (copy and delete) the currently selected data from the target object and copy it into the Clipboard.
CLIP_COPYCopy the currently selected data from the target object into the Clipboard.
CLIP_PASTEPaste the most recent data from the Clipboard into the target object.

Copy and cut operations are identical apart from the fact that cutting data will require you to delete the information after pasting it into the Clipboard. To paste data into a Clipboard, you can use any of the mechanisms supported by the Clipboard class, such as the DataChannel action. Please refer to the documentation for the Clipboard class for more information.

To paste data from a Clipboard into one of your objects, you need to scan the Clipboard object's data store and load the data off the file system in order to retrieve it. You may be 'selective' in the data that you retrieve from the Clipboard, for instance, if the next clip is an image and your class only supports text data, you can ignore the image and extract the text data instead. The documentation for the Clipboard class has more information on how to scan the data store.

 

Action:ClosingTag
Short:Provided for the purpose of script execution.

If you are developing a class that is designed for use in object scripts, or potentially could be used in an object script, then you should support the ClosingTag action.

The ClosingTag action is called just after a script interpreter has created an object, set its fields, initialised it and attached children to that object. By calling the ClosingTag action the process is basically telling you that "You've been completely initialised, so if you need to do something important, do it now".

You can use this as an opportunity to Activate the object's native functionality and if necessary, you can destroy the object if it serves no further purpose after being activated. This type of behaviour is particularly common for members of the Command category. On the other hand, classes in the GUI category will typically draw themselves to the display after receiving a ClosingTag action and remain in memory until they are destroyed.

 

Action:CopyData
Short:Copies one object's data to another.
Arguments:
OBJECTID Destination  The unique ID of the destination object.

The CopyData action is provided so that data in one object can be copied across to another. This may or may not involve data conversion. For example, copying data between files is a very straight forward process. However, copying data between two Bitmap's would be more complicated, because we need to consider clipping and type conversion issues. Copying between different classes is also permitted, for example copying a Picture to a File could output the image as raw data.

If you wish to write your routine so that it only supports a limited number of object types, return ERR_NoSupport when you detect a Destination object that does not belong to a supported class. If you wish to support all object types, use the Write action to feed data to the Destination object.

 

Action:DataChannel
Short:Provides a mechanism for sending formatted data betweeen objects.
Arguments:
OBJECTID ObjectID  Refers to the unique ID of the object that sent the information.
LONG DataType  Indicates the type of data that has been sent.
LONG Version  The version is set in accordance with the type of data being sent.
APTR Buffer  Points to the actual data that is being sent to you.
LONG Size  The size of the buffered data is specified here, in bytes.
LONG TotalEntries  The size of the array represented in the buffered data is specified here. The value is calculated according to the DataType that has been used.

The DataChannel action is available for classes that need to have an open port for receiving various types of data from other objects. It can be extremely useful in cases where you want your class to be able to receive miscellaneous commands or formatted information for internal processing. For example, the Keyboard class supports the DataChannel action so that it can receive virtual keypresses from software, rather than being restricted to hardware input.

The DataChannel action is closely linked to the SubscribeChannel() and UnsubscribeChannel() functions. If you want to set up an object so that it can receive data from a remote object, then you must first subscribe to it with the SubscribeChannel() function. The remote object will then start sending information through to the DataChannel action, which you can intercept with your support routine. When you no longer want to receive data, the channel can be closed with a call to UnsubscribeChannel().

Descriptions of the data formats that can be sent through this action are described in the DataChannel section of the Action List manual.

 

Action:Deactivate
Short:Stops the processing of an object's native action.

If your class supports the Activate action then you may also want to write support code to deactivate an object. In most cases this only applies to objects that support background processing. For example, after activating a Sound object an audio sample will play in the background. Because the Sound class supports the Deactivate action, it is possible for a program to cut the audio short whenever it wants to.

 

Action:Disable
Short:Disables an object's interactive functionality.

The Disable action is provided for the purposes of disabling the interactive elements of an object. It is typically supported by classes that have an impact on the creation of the graphical user interface, or those that have a close proximity to the actions performed by the user.

You need to make a judgment as to what support areas will be deactivated when a Disable call is made to one of your objects. Generally you should not deactivate all areas of an object as the point is not to render it useless. Only the interactive elements of the object should be disabled (your interpretation of what is interactive will depend on the type of class being developed).

If necessary you can write your own code to nest any multiple calls to the Disable action, although this would be considered to be the exception to the rule. If you are going to support nesting, you must document this fact in the documentation for your class.

Support for the Disable action should also be matched with support for the Enable action. This will allow your disabled objects to return to a normal state, as disablement is usually only a temporary measure.

 

Action:Draw
Short:Draws an object inside its drawable container.
Arguments:
DOUBLE XCoord  The horizontal coordinate of the drawable region.
DOUBLE YCoord  The vertical coordinate of the drawable region.
DOUBLE Width  The width of the drawable region.
DOUBLE Height  The height of the drawable region.

The Draw action is provided for classes that need graphical support. A programmer will typically set up an object so that it can be drawn according to your specifications, then call the Draw action with the expectation that the object will be drawn to a graphical object (such as a Bitmap). The exact technical details of the process are for you to define.

The dimension arguments are provided so that the programmer can declare the precise region that needs to be drawn. Your support of these arguments is entirely optional, so if they are not appropriate for your class, just ignore them.

Note that if you are writing a GUI based class then you will probably want to use an action subscription to listen to Draw action activity, rather than supporting the Draw action directly. This is best observed by looking at the source code to one of the existing graphical classes.

 

Action:Enable
Short:Enables a disabled object.

The Enable action must be supported in situations where you have decided to include support for the Disable action in your class. The code that you write for this action must be able to undo all the changes made in your support for the Disable action. If your Disable code includes support for nesting then you will also need to take this into consideration.

If a call is made to this action on an object which is not disabled, you should do nothing apart from returning ERR_Okay to indicate that the object is already enabled.

 

Action:EventMessage
Short:Used for supporting event subscriptions originating from the Broadcast class.
Arguments:
LONG EventID  The ID of the event that is sending you notification.
OBJECTID ObjectID  The ID of the object related to the event, if applicable.
LARGE Integer  A 64-bit integer that may have meaning according to the event ID.
APTR Buffer  Points to a data buffer, if applicable to the event.
LONG Size  The byte size of the data buffer, if applicable.

If you have called the SubscribeEvent() method of a Broadcast object to force some of your objects to listen to a particular event, your class will need to support this action so that event messages can be received and interpreted.

The event information will be returned to you with a description of the event ID, followed by a set of optional information that will only be set if it is relevant to the event. The data format of the various event types is described in the Broadcast class manual.

You can terminate an event subscription by calling the UnsubscribeEvent() method of the Broadcast object that you originally subscribed to.

 

Action:FieldNotify
Short:Used for supporting subscriptions originating from the SubscribeField() function.
Arguments:
FIELD FieldID  The unique ID of the field that is reporting the event.
OBJECTID ObjectID  The unique ID of the object that is reporting the event.

If you have called the SubscribeField() function to force some of your objects to monitor the field/s of another object, you will need to support this action so that field messages can be received and interpreted.

In supporting this action you will receive information that tells you the ID of the object and the field ID whenever the value of the monitored field has been altered. There are no restrictions on how you respond to this in your routine. If you need to know the new value of the field, you can retrieve it using conventional means.

You can terminate a field subscription by calling the UnsubscribeField() function.

 

Action:Flush
Short:Flushes buffered data from an object.

Flush is a useful action for buffered objects such as Files. The concept of buffering is often used to speed up data processing, for example reading and writing to memory is a lot faster than to a hard drive or floppy disk. However, it can sometimes be important for the physical data to represent the data as if it were not buffered. By supporting the Flush action, you can ensure that this is possible if your class buffers information.

When Flush is called on one of your objects, you will be expected to dump all of the buffered data to its 'physical' location, then you should clear your buffer of its contents.

 

Action:Focus
Short:Used to inform objects that they have the focus.

This action is usually called on drawable objects (e.g. Render objects) when the user interacts with them. Your class should only support this action if it is used in an area that is in close proximity to the user's actions.

If your class requires notification when a drawable object has received the focus, do not write support for the Focus action. You should instead use the SubscribeAction() function to listen to the Focus action of the drawable object that you are interested in.

If your class needs to be informed when one of its objects has lost the focus, you will need to support the LostFocus action.

 

Action:Free
Short:This action must be supported for the purposes of resource deallocation.

This function is called whenever the programmer wants to free one of your objects from the system. If you have written a base class, you must undo all of the allocations that belong to the object at the time of its destruction. If you have written a sub-class, you only need to support this action if your code makes extra allocations on top of those made by the base class.

To prevent allocations between a base class and sub-class from being confused, if you free any fields make sure that you drive them to NULL afterwards. Remember that if your sub-class requires its own private data fields, there is a MID_ChildPrivate field for this purpose in every objects' Stats structure.

 

Action:FreeWarning
Short:Used for receiving an early warning before an object is freed.

This action can be useful in rare circumstances where you might want to prevent an object from being freed from the system. Usually when an object has the Free action called upon it then the situation is terminal, but you can circumvent this by creating a FreeWarning support routine.

If you support the FreeWarning action then the termination process will call your routine to check if it is possible to free the object. If you return an error code of ERR_InUse, then the object's termination will be aborted. Any other error code that you return will cause the object to be removed as normal.

 

Action:GetUnlistedField
Short:Used for the purpose of supporting unlisted field settings.
Arguments:
STRING FieldName  The name of the field value that is to be retrieved.
STRING Buffer  Points to a buffer space that will hold the retrieved value.
LONG Size  Indicates the total byte size of the Buffer.

If your class design allows for unlisted fields then you will need to support this action. An 'unlisted field' is a field that is not officially listed as part of an object's structure. This provides a great way of being able to store miscellaneous data through the standard field mechanisms, or for supporting special field descriptors. The GetUnlistedField action is specifically used for the retrieval of unlisted field data, while the SetUnlistedField action is used for creating and setting unlisted fields.

If this action is called then you will be provided with information on the field name and a string Buffer that you need to write the data to. The Size argument defines the length of the Buffer - you must be careful not to write out more data than the Buffer can hold or you can crash the process. If you do not have any record of the specified FieldName, return an error code of ERR_UnsupportedField. Otherwise, write the field data to the buffer and return ERR_Okay. If there is not enough buffer space to write out the value, just make do with the space that is available and return ERR_Okay anyway (if necessary, you can print a warning to the debugger).

Please note that if you support this action then it is recommended that you provide a reasonable amount of documentation so that the developer knows just how your class supports unlisted fields.

 

Action:HealthCheck
Short:This action can be supported in the interests of preventing data corruption to an object.

The HealthCheck action is provided for classes that wish to protect the integrity of their objects in cases where an object's structure and/or data has been compromised. This action is usually called when the system runs a health check, or when the object kernel suspects that there may be something wrong with an object.

When writing a support routine for this action, your goal is to check the object structure and fix any problems that you find along the way. If you encounter a terminal issue that is impossible for you to fix, return an error code of ERR_ObjectCorrupt. This will cause the system to flag the object as being terminally ill.

 

Action:Hide
Short:Used for hiding an object from the user.

If your class is designed to create objects that are 'visible' to the user (for example, a GUI class) then you may also want to provide a way to make it invisible. You can do this by providing support for the Hide action. It is recommended that you also support the Show action so that it is possible to make a hidden object visible again.

 

Action:Init
Short:Called when an object is initialised.

This action is called when a program initialises an object that belongs to your class. The purpose of this action is to prepare the object for the necessary handling for other actions such as Draw, Activate, Show etc.

If your class is data-centric, then in cases where you cannot handle the data (e.g. an IFF class tries to interpret a JPEG file) then your routine must undo any changes it has made to the object's structure. You must then return an error code of ERR_NoSupport. This will cause the initialisation management routine to look for a sub-class that can support the object correctly. If the object was recognised but initialisation fails due to a system error or similar, then any error-code can be returned (except for ERR_NoSupport and ERR_Okay). This will cause the initialisation action to fail immediately and return to the program.

It is highly recommended that before proceeding with full initialisation of an object, you always check the data sources and ensure that you understand them. If you check the data near the middle or end of your routine, you may make things difficult to undo if you find that you need to return ERR_NoSupport.

You must never free your object while inside the initialisation routine. If your routine fails then the object will be freed at a time when it is appropriate to do so.

 

Action:Lock
Short:Used when a programmer wants to lock the functionality of an object.

Locking is provided for developers that want to prevent objects from physically moving position (e.g. files and directories) and prevents tasks from performing certain actions and changes to an object. Locks can either be shared or exclusive to tasks, depending on what is suitable for the object.

As a result of locking, the object will be fixed in place and cannot be moved or deleted, even by the task that holds the lock, until the object is unlocked with the Unlock action. As the class programmer, you have a responsibility to enforce your own rules to support locks. Feel free to place other restrictions on the object where appropriate.

It is extremely important that you document the behaviour of locking for your particular object. The issue of shared/exclusive locking on public objects is an important issue for you to consider.

You must also support the Unlock action, this is the only way that you can receive information on the unlocking of an object.

 

Action:LostFocus
Short:This action is called when an object loses the user focus.

This action is usually called on drawable objects (e.g. Render objects) when the user stops interacting with them and takes an interest in other objects. Your class should only support this action if it is used in an area that is in close proximity to the user's actions.

If your class requires notification when a drawable object has lost the focus, do not write support for the LostFocus action. You should instead use the SubscribeAction() function to listen to the LostFocus action of the drawable object that you are interested in.

 

Action:Move
Short:Used for moving objects to new coordinates.
Arguments:
DOUBLE XChange  The amount of units to move along the horizontal axis.
DOUBLE YChange  The amount of units to move along the vertical axis.
DOUBLE ZChange  The amount of units to move along the Z axis.

If your class supports a coordinate system (this is typically the case for all graphical classes) then you should support the Move action. Movement originating from this action is relevant to the current position of the object, rather than being based on absolute coordinates. If for example a program wishes to move your object 5 units to the left, it will set the XChange argument to -5 and the other arguments to zero.

If there is a limit as to how far an object can move in any direction, you can limit its movement by reducing the number of units if they would place the object in an out-of-bounds position. For example, if an object is at position (15,18) and a program wants to move it 40 units upwards, you could reduce that value to 18 units if you wanted to prevent the object moving into negative space. You should still return an error code of ERR_Okay in such a case.

In conjunction with your support of the Move action, your class definition should define XCoord and YCoord fields if it is 2-dimensional and a ZCoord field if it is 3-dimensional. If you do not support these standard fields then it will be difficult for a program to determine the position of your objects.

 

Action:MoveToBack
Short:Moves an object to the back of its container.

In many instances where displayable objects are on screen, the graphics will inevitably overlap each other. If you support the MoveToBack and MoveToFront actions, you can provide the developer with some assistance in the arrangement of an object in relation to other objects.

If your class supports the Lock action, it may be best for a locked object to hold its position when the MoveToBack action is called. Whether you decide to do this or not is up to you, so document the class' behaviour in this area.

 

Action:MoveToFront
Short:Moves an object to the front of its container.

In many instances where displayable objects are on screen, the graphics will inevitably overlap each other. If you support the MoveToBack and MoveToFront actions, you can provide the developer with some assistance in the arrangement of an object in relation to other objects.

If your class supports the Lock action, it may be best for a locked object to hold its position when the MoveToFront action is called. Whether you decide to do this or not is up to you, so document the class' behaviour in this area.

 

Action:NewChild
Short:Used by classes that need to be alerted when an object receives a new child.
Arguments:
OBJECTID NewChildID  Indicates the unique ID of the new child.

If you need to be aware of occasions where an object has inherited a new child object from the SetOwner() function, you should support the NewChild action. By supporting this action you can respond to the arrival of new children, as well as preventing objects from forming direct attachments if they do not meet your criteria (simply by returning an error code).

In some rare circumstances it may be necessary for a new child to be automatically 'passed through' to another object that would be better suited as an owner. If you want to do this, your support routine should call the SetOwner() function to pass the child through to another object, then you should return an ERR_OwnerPassThrough error code to indicate that a pass-through has occurred. Any other error code will be interpreted as failure, which would cause the process to abort.

 

Action:NewOwner
Short:Called when the owner of an object is about to change.
Arguments:
OBJECTID NewOwnerID  The unique ID of the new owner.
CLASSID ClassID  The class ID of the new owner.

If you need to be aware of occasions where a program is changing the owner of an object with the SetOwner() function, you should support the NewOwner action. This will allow you to respond to the alteration of an object's owner as you see fit.

The error code that you return will not have an impact on the SetOwner() process.

 

Action:NewObject
Short:Called when a new object has been created from a base class.

This action is called whenever a new instance of an object belonging to your class has been created. The routine that you place here should be fairly simple as the object kernel will take care of the creation process - all you need to do is take care of any extra resource allocations. Some classes also like to write default values to their objects as a pre-initialisation process.

If you return an error code then the object creation process will fail.

 

Action:OpeningTag
Short:Provided for the purpose of script execution.

If you are developing a class that is designed for use in object scripts, or potentially could be used in an object script, then you may want to support the OpeningTag action.

The OpeningTag action is used just after a script interpreter has created an object, set its fields and initialised it. This provides you with an indication that the object has gone through significant preparation but has not yet had any children initialised to it. If you would rather wait until the object has been fully prepared, you should support the ClosingTag action instead.

 

Action:Query
Short:Used to query the information represented by an object.

Query is a commonly supported action that programs can use to get updated information on an object. It is commonly supported by data-centric objects as well as objects that support dynamic hardware values originating from devices such as keyboards and joyports. If you want to support the Query action, then you will need to decide what fields you are going to update in your support routine, then document this behaviour accordingly.

 

Action:Read
Short:Used for reading raw data from an object.
Arguments:
APTR Buffer  Points to the data area that will accept information from the Object.
LONG Length  An abstract indicator of how much data should be written.
LONG Result  You are required to set this value to the amount of bytes that were read into the Buffer before returning.

The Read action was initially provided in order to support reading and writing data to Files. Despite this intention, a class which supports a data storage area should support the Read action for managing raw data.

The Buffer argument points directly to the area that will receive data from your Object. The Length will indicate the amount of bytes that a program wants to retrieve from your object. If the Length is larger than the amount of data that is actually available, just write out the maximum amount of bytes that are in the object.

Your class should support a Position field in its structure to indicate the byte position from which the Read action will start reading data. After the Read operation, you must increment the Position field by the amount of bytes that were read from the object's data store. This will provide the developer with more versatility when it comes to reading and writing data. You should also consider supporting the Seek action to manipulate the Position field.

Before returning, your support routine must set the Result parameter to indicate the total amount of bytes that were read from the object. If no bytes were read, you should still return ERR_Okay but make sure that the Result is set to zero.

 

Action:Refresh
Short:Refreshes the state of an object.

If your class represents a view of an 'external' data source, you may need to support the Refresh action. The purpose of a refresh is to re-read the origins of an object's data and then update the object to reflect any differences between the object and its data source.

If your Refresh support code fails, it is recommended that you leave the object in its original state when returning a fail code.

 

Action:ReleaseObject
Short:Used for intercepting the release of exclusive locks.

If you wish to be informed when a program is releasing an exclusive lock from an object, you may write a support routine for this action. This is entirely optional, and the ReleaseObject() function does not depend on your support for this.

The error code that you return from your support routine will be ignored.

 

Action:Rename
Short:Used for renaming objects.
Arguments:
STRING Name  The new name for the object.

If your class supports naming (e.g. for the purpose of representing a data location such as a file name) then you may want to support the Rename action. How you support this action is entirely dependent on the focus of the class, as this action does not require you to adhere to any restrictions. If there is a limit on the amount of characters that are supported by your routine, you should document this fact in the class manual.

Please note that an internal name as defined by your class is not the same as a public object name, as defined by the SetName() function.

 

Action:Reset
Short:Resets an object to its original state.

The most common reason for supporting the Reset action is to allow an object to get itself back to a refreshed state, similar to when the object was first initialised. Examples could be resetting a file position back to the beginning, or restarting a running procedure from scratch. It is recommended that you do not actually destroy any data in your Reset support routine, although you may manipulate it as much as necessary.

 

Action:Resize
Short:Used for resizing the dimensions of an object.
Arguments:
DOUBLE Width  The new width of the object.
DOUBLE Height  The new height of the object.
DOUBLE Depth  The new depth of the object.

If a class is designed to represent a 2-dimensional or 3-dimensional space then it should support the Resize action if that space is intended to be adjustable. In conjunction with this action the class must support Width and Height fields, as well as a Depth field if the object is 3-dimensional. After a successful resize has taken place, these fields must be updated to reflect the object's new dimensions.

If the developer only wants to resize a particular dimension such as the Width, then only the Width argument will be set and the others will be driven to zero.

 

Action:SaveImage
Short:Saves an object's image to a data storage object.
Arguments:
OBJECTID Destination  Refers to an object that you have to write the image data to.

This action is provided for classes that wish to make a distinction between the image of an object and the data of an object. For instance, saving a GUI object could store information on the object's construction, while saving its image would store the object as a graphic (like a camera snapshot).

When supporting this action you should store the image using the Picture or Bitmap class so that the data can be saved in the user's preferred format. Otherwise, you should Write the image to the Destination using a widely recognised image format.

 

Action:SaveToObject
Short:Saves an object's data to a data storage object.
Arguments:
OBJECTID Destination  Refers to an object that you have to write the data to.

By supporting the SaveToObject action, you can make it possible to save an object's data to a File or other data storage object. This action is considered to be extremely important in creating functional data-centric objects based on pictures, sounds, documents and so forth.

When your SaveToObject support routine is called, you will be sent a Destination object which is initialised and is supportive of Write calls. All you are required to do is Write your data to the given object. You must save your file information in a format that is recognised by your class, so that it can be loaded back at a later time.

 

Action:Scroll
Short:Scrolls the contents of an object.
Arguments:
FLOAT XChange  The amount of units to scroll along the horizontal axis.
FLOAT YChange  The amount of units to scroll along the vertical axis.
FLOAT ZChange  The amount of units to scroll along the Z axis.

This action is typically supported by GUI components that have scrollable contents. The coordinate parameters can be interpreted as you wish - usually in pixels, but the exact details are up to you. Make sure that you document how coordinate alterations are interpreted by your class.

 

Action:Seek
Short:Seeks to a new position within an object.
Arguments:
FLOAT Position  The byte position that is to be seeked to, relative to the Mode argument.
LONG Mode  Either POS_START, POS_CURRENT or POS_END.

If your object supports the Read and Write actions, you will most probably want to support Seek as well. Seeking is used to position the 'read/write head' so that the next time some I/O occurs, it will start at the seeked position.

Your class is required to define a Position field that always reflects the current byte position in your object's data. When the Seek action is called, the Position must be altered to reflect the absolute byte position that the program has seeked to.

When writing your support routine, you must write code for each of the three different modes - POS_START, POS_CURRENT and POS_END. POS_START refers to the beginning of the data, POS_CURRENT refers to the current byte position and POS_END refers to the end of the data. The Position argument can be set to both negative and positive values when the POS_CURRENT mode is used, but in the POS_START and POS_END modes the sign of the Position is not relevant (for this reason, it is recommended that you ensure that the Position is interpreted as an absolute value that is offset in the appropriate direction according to the Mode).

Seeking beyond the boundaries of an object's data is not permitted. In other words, the resulting byte position from a Seek action cannot be less than zero, and cannot be greater than the data size. If the boundary will be broken, you should restrict the Position field to the appropriate boundary value.

 

Action:SetUnlistedField
Short:Used for the purpose of supporting unlisted field settings.
Arguments:
STRING FieldName  The name of the field that is to be set.
STRING Value  The value that will be written to the unlisted field in string format.

If your class design allows for unlisted fields then you will need to support this action. An 'unlisted field' is a field that is not officially listed as part of an object's structure. This provides a way of being able to store miscellaneous data through the standard field mechanisms, or for supporting special field descriptors. The SetUnlistedField action is specifically used for storing unlisted field data, while the GetUnlistedField action is used for retrieving unlisted field values.

If this action is called then you will be provided with information on the field name and a string Value that contains the field data. Unless you are going to dynamically interpret the field value in your routine, you will have to store the field value in the object. To do this you should come up with a simple mechanism to store multiple field names and values in a buffer that belongs to the object. You should also develop your routine so that it checks whether or not a value for the FieldName already exists at the time of calling. If the FieldName exists, then your routine should delete the existing value and replace it with the new Value that has been provided.

Please note that if you support this action then it is recommended that you provide a reasonable amount of documentation so that the developer knows just how your class supports unlisted fields.

 

Action:Show
Short:Makes an object visible to the user.

If your class is designed to create objects that are 'visible' to the user (for example, a GUI class) then you may want to provide support for the Show and Hide actions to manage object visibility. Generally you should automatically show an object to the user on its initialisation, but by supporting the Show and Hide actions you can provide the developer with a little extra flexibility in this area after initialisation has taken place.

 

Action:Timer
Short:This action must be supported if the class requires regular timing messages.
Arguments:
LONG MilliSeconds  The number of milliseconds (1/1000th of a second) that have passed since the last Timer call.

If you have called the SubscribeTimer() function to force some of your objects to receive regularly timed processor calls, you will need to support this action so that the timer messages can be received and interpreted.

In supporting this action you will receive the number of milliseconds that have passed since the last Timer call. There are no restrictions on how you write your routine to respond to Timer notifications. The error code that you return will be ignored.

You can terminate a timer subscription by calling the UnsubscribeTimer() function.

 

Action:Unlock
Short:Unlocks an object's functionality.

This action serves as an accompanient to the Lock action. It is not compulsory to support Unlock if you have written a Lock routine, but it would be an unusual case if you were not to write a support routine for this action.

What you do for your Unlock support is entirely up to you, so long as you do not allocate any resources in the routine.

 

Action:UserClick
Short:Used by drawable classes that need to respond to user clicks.
Arguments:
LONG ButtonFlags  Associated flags for the user click are specified here. Available flags are based on joyport standards, e.g. JD_LMB, JD_MMB, JD_RMB. Refer to the "input/joyport.h" include file for a list of all available flags.
DOUBLE XCoord  The horizontal coordinate of the user click, relative to the object's top left corner.
DOUBLE YCoord  The vertical coordinate of the user click, relative to the object's top left corner.
DOUBLE ZCoord  The Z coordinate of the user click, relative to the object's top left corner.

If your class requires graphical user interaction, you need to support this action. You will normally receive UserClick actions from the Pointer class, but they can of course come from anywhere. After receiving a UserClick, you can typically expect to receive a UserClickRelease shortly thereafter.

The coordinates supplied to your object are relative to the top left corner of the object. The purpose of the coordinates is to tell you where the user click occurred. If there is no exact coordinate, the coordinates will be driven to zero.

 

Action:UserClickRelease
Short:Used by drawable classes that need to respond to user click releases.
Arguments:
OBJECTID OverObject  The object that the user device is currently positioned over.
DOUBLE XCoord  The current horizontal coordinate in relation to your object.
DOUBLE YCoord  The current vertical coordinate in relation to your object.
DOUBLE ZCoord  The current depth-based coordinate in relation to your object.
DOUBLE XChange  The change in direction from the user's position since the initial UserClick call.
DOUBLE YChange  The change in direction from the user's position since the initial UserClick call.
DOUBLE ZChange  The change in direction from the user's position since the initial UserClick call.
LONG ButtonFlags  Indicates the buttons that have been released since the initial UserClick call.

If you need to be informed when the user has clicked and then released a button on one of your objects, you must support UserClickRelease. This action is commonly supported for achieving drag and drop functionality. If the user is trying to drag an object somewhere, you can find out where that is by checking the OverObject argument. Note that the XChange, YChange and ZChange arguments specify the shift in position from the point where the original UserClick action was called.

 

Action:UserMovement
Short:Used for detecting and responding to user movement.
Arguments:
OBJECTID OverObject  The object that the user is currently positioned over (not necessarily your object).
DOUBLE XCoord  The current position of the user in relation to your object's top left corner.
DOUBLE YCoord  The current position of the user in relation to your object's top left corner.
DOUBLE ZCoord  The current position of the user in relation to your object's top left corner.
DOUBLE XChange  The change in direction since the last UserMovement call.
DOUBLE YChange  The change in direction since the last UserMovement call.
DOUBLE ZChange  The change in direction since the last UserMovement call.

To detect the movement of the user when he/she moves a pointing device over your object, add support for this action. There are two cases for when you might be called by this action:

  1. Movement has occurred within one of your objects. This is the most simple type of user movement.
  2. Movement has occurred from one object to another. In this case, two calls to UserMovement are used - one to tell the previous object that the user has moved away, and another to the new object to inform it that the user has moved into it. You need to cater for both types of movement in this case.

You can tell what type of movement is occurring by checking the OverObject argument - if it is equal to your object, then movement is occurring within your object. If the OverObject is some other object pointer, the user has moved away from your object.

 

Action:Write
Short:Used for writing raw data to an object.
Arguments:
APTR Buffer  Points to the data that needs to be written to the Object.
LONG Length  An abstract indicator of how much data should be written.
LONG Result  You are required to set this parameter to the total number of bytes that were written by your support routine.

The Write action was initially provided in order to support the writing of data to Files. Despite this intention, any class that supports a data storage area should support the Write action for managing raw data.

The Buffer argument points directly to the area that contains the data that should be written to your Object. The Length argument indicates the byte size of the Buffer. If the Length exceeds the total amount of space available for writing data, return an error code of ERR_LowCapacity.

Your class should support a Position field in its structure to indicate the byte position from which the Write action will start writing data. After the Write operation, you must increment the Position field by the amount of bytes that were written to the object's data store. This will provide the developer more versatility when it comes to reading and writing data. You should also consider supporting the Seek action to manipulate the Position field.

Before returning, your support routine must set the Result parameter to indicate the total amount of bytes that were written to the object.