-
-
Notifications
You must be signed in to change notification settings - Fork 2
Action Reference Manual
Actions are an implementation of the design-by-contract approach to object orientation. Common activities such as showing and hiding an object on the display, or reading and writing data have been given a dedicated action interface. The 'contract' exists in the strict objectives of each action, as documented in this manual. For instance, calling Show and Hide actions on a UI object will change its visibility as one would expect.
If an action isn't applicable to an object, calling it is legal but will do nothing.
This document describes the available action interfaces, including the expectations of behaviour for the client, as well as implementation details of each contract.
Where necessary, classes will often clarify the details of how they support their actions. These details are documented in the class manuals.
The Core API provides multiple functions for action related tasks. Action() is used to make immediate calls, and requires an object pointer. ActionThread() launches the action in a separate thread and returns immediately. QueueAction() is a pure messaging function, requiring only the object UID and delaying the call until the next message processing cycle. The aforementioned functions are documented completely in the Core API.
For C++ users, additional macros are also provided. All actions listed in this document will have an associated stub function prefixed with ac. For example, acShow(Object) and acSetKey(Object, Key, Value). Automated header generation also ensures that relevant methods are created at class level, meaning Object->show() and Object->setKey(Key, Value) are similarly valid.
Fluid users can call actions with the acName template, in this case object.acShow() and object.acSetKey(Key, Value) would be equivalent to the C++ counterpart.
Run-time inspection is supported with the Core API's CheckAction() function, which confirms if an object's class supports a given action. The ActionList() function provides insight into all known actions and their parameters.
Finally, the SubscribeAction() function provides a monitoring feature that will call a custom function whenever a given action has been executed for a target object.
Activate Clear | Clipboard | CopyData | DataFeed | Deactivate | Disable | DragDrop | Draw | Enable | Flush | Focus | Free | GetKey | Hide | Init | Lock | Move | MoveToBack | MoveToFront | MoveToPoint | Next | Prev | Query | Read | Redimension | Redo | Refresh | Rename | Reset | Resize | SaveImage | SaveSettings | SaveToObject | Seek | SetField | SetKey | Show | Signal | Undo | Unlock | Write
These actions are implemented for use internally, and must never be called from client code.
FreeWarning LostFocus | NewChild | NewObject | NewOwner
ERR acActivate(Object)
Activate causes an object to perform its "native activity". Although ambiguous, the activity should be relevant to the class in question. Here are a few examples of what some existing classes do when their objects are activated:
| Class | Description |
|---|---|
| Sound | Plays audio data. |
| Script | Runs a scripted program. |
| Picture | Loads a source image. |
It is typical for most classes that support the loading and processing of data to do so in their Activate support.
Some objects will continue to perform their native activity after they return back to the client - for example, activating a Sound object will cause it to play audio in the background. If background processing needs to be cancelled, this should be done with a Deactivate call.
The Activate action is intentionally ambiguous, giving free reign as to the nature of the implementation. Even so, it should be intuitively clear what the user would expect from the activation process. If that is not the case, the Activate action should probably go unsupported.
Remember to support the Deactivate action if background activity can be cancelled.
ERR acClear(Object)
This action will clear an object of all its data. Typical use cases are the clearing of graphics and data records. Here are some examples:
| Class | Description |
|---|---|
| File | Clears file data by reducing the file length down to 0. |
| Text | Deletes all lines of text. |
| Bitmap | Clears the bitmap of graphics data. |
The overall state of the object will normally remain intact - so clearing a file will not cause the file handle to be closed for instance.
ERR acClipboard(Object, OBJECTID Clipboard, CLIPMODE Mode)
| Name | Type | Description |
|---|---|---|
| Mode | CLIPMODE | The mode that will be used to shift data between the target object and clipboard system. |
The Clipboard action is used on objects for the purpose of shifting data between them and the clipboard system. Generally, clients should only use this action when the user has done something that requires it to be called, for instance, holding the CTRL+C keys to make a copy operation.
Three modes are currently available for performing clip operations, as illustrated in the following table:
| CLIPMODE | Description |
|---|---|
| CUT | Cut (copy and delete) the currently selected data from the target object and copy it into the clipboard. |
| COPY | Copy the currently selected data from the target object into the clipboard. |
| PASTE | Paste the most recent data from the clipboard into the target object. |
The specifics of how a target object interacts with a clipboard is down to the developer of the object's class. If you need more information on how an object might interface with the clipboard system, check its class documentation.
Supporting the system-wide clipboard service requires code to be written for the Clipboard action. This action is closely related to the Clipboard class, which you will need to instantiate as necessary. The Mode reflects the type of action that needs to be performed.
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 copy data to a clipboard, use any of the mechanisms supported by the Clipboard class, such as the AddText() method. Please refer to the documentation for the Clipboard class for more information.
To paste data from a clipboard into one of your objects, call the GetFiles() method to retrieve the data from the file system. 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.
ERR acCopyData(Object, OBJECTID Dest)
| Name | Type | Description |
|---|---|---|
| Dest | OBJECTPTR | The unique ID of the destination object. |
The CopyData action is used to copy data between objects. To execute the copy process, call the CopyData action on the source object, and set the Dest to the object that you are copying the data to. If the source object does not recognise the destination object type, it will make calls to the Write action to copy the data across. If it does understand the destination object type, it may make an 'intelligent' copy. For instance, when copying the data from one Bitmap to another, the image source will be drawn to the destination.
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 straight forward process of copying a raw binary stream. However, copying data between two Bitmaps would be more complicated, because we need to consider clipping and colour 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 recognised classes, return ERR::NoSupport for those at are unsupported. To support all classes, include a fallback that uses the Write action to stream data to the destination object.
ERR acDataFeed(Object, OBJECTID Object, DATA Datatype, APTR Buffer, LONG Size)
ERR acDataXML(Object, CSTRING Buffer)
ERR acDataContent(Object, CSTRING Buffer)
ERR acDataText(Object, CSTRING Buffer)
| Name | Type | Description |
|---|---|---|
| Object | OBJECTPTR | Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID. |
| Datatype | DATA | The type of data being sent. |
| Buffer | APTR | The data being sent to the target object. |
| Size | LONG | The size of the data in Buffer. |
The DataFeed action provides a mechanism for writing typed data to objects. The target Object will check the Datatype to determine if the Buffer content is supported, and if so, will process the data according to what is appropriate for the object's class.
The following Datatype values are supported:
This is a special datatype used by the Document class to pass XML content to embedded objects. Although this duplicates the DATA::XML type, it may be desirable to parse such data differently to DATA::XML due to nature of the content.
This datatype is used to declare a file path that contains the data to be transferred. It is frequently used to speed up data transfers where loading file data into a buffer and passing it through the DataFeed system would be inefficient. Set the Size to the path's string length, including the null byte.
Sending raw binary data to an object is equivalent to calling the Write action. Set the Size to the byte length of the data.
In response to a DATA::REQUEST from an object, a RECEIPT must be sent to the requesting object. The receipt will contain a null-terminated XML string with the data that has been requested. Please refer to the DragDrop action for further information.
The REQUEST datatype is intended for supporting drag and drop operations, but theoretically can be used for any type of data transfer between objects where uniquely numbered items may be used.
A request for data is achieved by passing an Item UID and indicating up to three types of data formats that would be accepted from the source. The dcRequest structure for managing the request is configured as follows:
| Field | Type | Description |
|---|---|---|
| Item | LONG | Item to retrieve from the source. |
| Preference | DATA [4] | Data preferences for the returned item(s). |
The datatypes indicated by the Preference field can be any of the pure datatypes supported by the DataFeed action, for example DATA::TEXT or DATA::XML. Any unused elements of the Preference array must be set to zero.
Use the TEXT datatype when sending UTF-8 text to an object. The Size of the string must include the null byte.
The XML datatype shares the same qualities as DATA::TEXT, but explicitly declares the content as being XML formatted. How the information is interpreted by the receiving class is context dependent. It is recommended that you check the class' documentation to see the level of support that is offered.
ERR acDeactivate(Object)
Deactivating an object that is still in an active state from the Activate action will cause it to halt its activity. If the object is not in an active state, this action does nothing.
A class that supports the Activate action should consider support for Deactivate if the object's active state persists beyond the original Activate call.
If the target object is in an inactive state at the time of the Deactivate call, do nothing and return ERR::Okay to the client.
ERR acDisable(Object)
The Disable action is used to put an object into a state where it cannot respond to user interaction. It is typically used to temporarily "turn off" objects in the interface. For instance, disabling a Vector object will cause it to drop incoming user events such as button clicks and cursor motion. An object will remain in a disabled state until enabled again with the Enable action.
Multiple calls to the Disable action will not nest unless the documentation for the object's class states otherwise.
The Disable action is provided for the purposes of disabling the interactive elements of an object. It is typically supported by classes that have a presence in the UI, or have some other form of user interaction.
It is important that only the user-interactive elements of the object are disabled. The object should not be disabled to the point of being useless, as non-interactive changes are still valid.
If necessary, a class can nest multiple calls to the Disable action, although this would be considered to be an exception to the rule. If you are going to support nesting, document this fact in the 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.
ERR acDragDrop(Object, OBJECTID Source, LONG Item, DATA Datatype)
| Name | Type | Description |
|---|---|---|
| Source | OBJECTPTR | Refers to the object containing the source data. |
| Item | LONG | An item ID, relevant to the source object. |
| Datatype | DATA | The type of data represented by the source item. |
The DragDrop action provides the core functionality of a universal drag and drop system. The process of drag and drop works as follows:
- The user initiates a drag and drop operation by clicking and holding the mouse button on an interface item.
- The owner of that item will monitor click and motion activity that could instigate a drag and drop operation.
- On detecting the initial stages of the drag and drop operation, the object will create a new graphics
Surfaceutilising theCOMPOSITEandSTICK_TO_FRONTflags. The Display API'sStartCursorDrag()function is called to link this surface to the mouse pointer. No further action needs to be taken until the mouse button is released.
When the item is dropped by releasing the mouse button over a Surface, the following occurs:
- The mouse pointer will hide the draggable surface that was attached to it.
- The
DragDropaction will be called on the surface that is under the pointer's hot spot. TheSource,Itemnumber and datatype originally passed toStartCursorDrag()will be included in this action call. - If a listener is subscribed to the
DragDropaction of the targeted surface, it will be able to respond to the drag and drop operation. The listener will need to send aDATA::REQUESTvia theDataFeedaction to the object that is referenced in theSourceparameter. The listener can indicate supported datatypes that it will accept from the source (see theDataFeedaction for further information) and the Item number received from theDragDropaction. - The source object will respond by sending a
DATA::RECEIPTmessage via theDataFeedaction. This contains the item data in one of the requested formats.
Data for drag and drop activity is defined in XML format. The following template must be adhered to:
<receipt id="[SourceID]" totalItems="[Total]>
...list of items...
</receipt>
The official list of items that can be contained in the receipt are as follows:
<audio path="[FilePath]" object="[SoundObject]"/>
A choice can be made between defining a path or object. The object must belong to the Sound class.
<file path="[FilePath]"/>
<audio path="[FilePath]" object="[Object]"/>
A choice can be made between defining a path or object. The object must belong to either the Picture or Bitmap classes.
<raw path="[FilePath]" object="[Object]"/>
A choice can be made between defining a path or object. The object must support the Read action for reading the data.
<text>[UTF8Content]</text>
<xml>[XMLContent]</xml>
To support drag and drop, do not write a routine specifically targeting the DragDrop action. Instead, use SubscribeAction() to listen to the DragDrop action of the surface that is used by your object. In response to the receipt of a DragDrop action, send a DATA::REQUEST (via data feed) to the indicated Source object. The rest of your support code for drag and drop will need to be written in your DataFeed support routine.
ERR acDrawArea(Object, LONG X, LONG Y, DOUBLE LONG, LONG Height)
ERR acDraw(Object)
| Name | Type | Description |
|---|---|---|
| X, Y | LONG | The top-left position of the region to be drawn. |
| Width, Height | LONG | The size of the region to be drawn. |
This action will draw an object's graphics, either to the video display or to a virtual drawing space, according to the object state and class specifications. If the object is not linked to a drawable area, or if the object belongs to a non-graphical class, calling this action will usually have no effect and an error code will be returned.
The dimension parameters specify the size of the region that will be drawn. The Width and Height can both be zero if the entire region of the object should be drawn.
The Draw action is provided for classes that need graphics support. The client should configure the object with sufficient information to draw something of value. A 'target' field will be needed in the class spec so that Draw has an appropriate graphics destination. The exact technical details of the process are for you to define.
The dimension parameters are provided so that the client can declare the precise region that needs to be drawn. Supporting these parameters is optional - if they are not appropriate for the class, ignore them.
ERR acEnable(Object)
The Enable action is provided for the purposes of reactivating objects that have been disabled with the Disable action. When an object is enabled, it should be operating in its normal state.
The Enable action is implemented as a counter to Disable. If your Disable code includes support for nesting then you will also need to take this into consideration.
If an Enable call is made to an object that is not disabled, do nothing and return ERR::Okay.
ERR acFlush(Object)
This action will flush all buffered data from an object. Flushing can be useful when applied to I/O based objects that buffer data to speed up processing times. As a result of flushing, unwritten data will either be dumped to its physical location or related output device, depending on the object specifications.
Note that any object using a buffering technique will automatically flush its data when you Free it.
Flush is a useful action for buffered objects such as files, as it ensures that buffered content is permanently saved to its destination. Novel applications for data flushing are also possible, for instance the flushing of a series of graphics commands to the display would be valid. In general, if a class is designed to buffer content then giving consideration for Flush should be a priority.
ERR acFocus(Object)
The Focus action is primarily used within the UI for focussing on interactive widgets. Objects supporting the Focus action are typically members of the Drawable category, of which the Surface and Vector classes currently qualify.
When a drawable object receives the focus it will usually do very little, but external objects that are listening for focus activity will respond to the change accordingly. For instance, input based objects within surface areas often listen to focus changes so that they know when to start responding to keyboard input.
This action is usually called on drawable objects (e.g. Surface 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, support the LostFocus action.
ERR FreeResource(Object)
Objects are permanently removed with the Free action, which is achieved via a call to FreeResource(). If the object has one or more child objects attached to it, they will also be removed as a result of calling this action. After calling Free, remove any UID and pointer references to the object as a measure of bug prevention.
If an exclusive lock is active at the time of calling Free, the object will be marked for deletion only. The object will not be permanently removed until the last lock is released.
NOTE: The means of terminating an object can vary between languages. C++ uses FreeResource(), while in Fluid, objects are manually terminated with the obj:free() interface, or automatically via garbage collection. The specifics of this should be documented in your language of choice.
Free support is essential for all classes that allocate resources. It is correctly implemented by removing all resources that were created during an object's life-cycle.
Sub-classes need to support this action if their code tracks resources seperately to the base class. To prevent allocations between a base-class and sub-class from being confused, the fields that reference resources should be driven to NULL after their termination. If your sub-class requires its own private data area for resource management, the ChildPrivate field is available for this purpose.
This is an internal action that is used for receiving a warning prior to an object being freed. It should never be called from client code.
FreeWarning is useful for preventing an object from being terminated when it is in an unready state. This is achieved by returning an error code of ERR::InUse. All other error codes are ignored.
If an object is in a collecting state, for instance if the app is shutting down, then it will not be possible to abort termination. If this is an important factor for your code, use the C++ collecting() method to verify the object's state.
ERR acGetKey(Object, STRING Key, STRING Value, LONG Size)
| Name | Type | Description |
|---|---|---|
| Key | STRING | The name of a key value. |
| Value | STRING | Pointer to a buffer space large enough to hold the retrieved value. |
| Size | LONG | Indicates the byte size of the Buffer. |
The GetKey action is used to retrieve custom key-values from an object. Keys can either be functional, as is the case for XML's xpath support, or they can be created by the client using SetKey.
To retrieve a key-value, set the Key and use Value to point to a buffer large enough to hold the string that is expected. The Size declares the maximum number of bytes that can be written to Value, including the null terminator.
Key names are case-insensitive unless documented otherwise. If the requested Key doesn't exist, ERR::UnsupportedField will typically be returned from the object's class.
If your class design allows for key-values then you will need to support GetKey. This can include support for functional keys, which are key names that are documented in advance and backed by coded functionality. The XML class is one such example that does this to support the xpath standard.
Keys should be case-insensitive by default. If this is not the case, document this fact for the client.
If the requested Key does not exist, return an error code of ERR::UnsupportedField.
Use the Size parameter to prevent overwriting the Value buffer. If there is insufficient space, clip the outgoing string and return ERR::Okay (a warning message printed to the log may be advised).
Adequate documentation for the client is strongly recommended when supporting this action.
ERR acHide(Object)
Hiding is used to remove objects from the sight of the user. Examples of this include hiding Vector and File objects. Use the Show action to make the object visible again.
If a class represents objects that are visible to the user (for example, a UI class) then being able to control that visibility is usually necessary.
If the visible state of the object is already hidden, do nothing and return ERR::Okay.
Changing the visible state of a graphics object can trigger a redraw of the display, but this is at your discretion. Documenting whether or not the changes will be immediately visible is advised.
Hide and Show should always be supported in tandem as would be expected by the client.
ERR acInit(Object)
This action initialises objects so that they can be used for their intended purpose. The process of initialisation is compulsory, and you may not use any other actions on an object until it has been initialised. Exceptions to this rule only apply to the Free, GetKey and SetKey actions.
If the initialisation of an object fails due to a support problem (for example, if you ask a Picture object to load a TIFF image when it only supports PNG), the Init action can look for a sub-class that handles the data. If a supporting sub-class exists, a partial transfer of ownership will occur and the object's management will be shared between both the base-class and the sub-class.
Part of the initialisation process is to check a client's configuration settings up-front, and a suitable error code will be returned if these checks are failed.
C++ users can check the initialisation state of an object by calling its initialised() method.
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.
Data-centric classes that fail to recognise the source data should always return ERR::NoSupport (e.g. a PNG class cannot process a JPEG file). Your code should also strive to keep the object state untarnished. The initialisation manager will look for a sub-class that can support the object correctly. If your class supports the data but initialisation fails due to a system error or similar, return any error-code other than ERR::NoSupport and ERR::Okay. This will cause the initialisation process to fail immediately and return to the program.
It is a requirement that the object state is sufficiently validated when Init is called. Do not assume that the object is configured correctly by the client.
Never free an object from inside its own initialisation routine; this is a matter for the client.
ERR acLock(Object)
The Lock action can be used on an object when you don't want it to be moved, deleted or otherwise altered by other processes for a period of time. This is commonly needed for files.
Each initial and subsequent calls to Lock must be matched with calls to the Unlock action, because locks will nest. Once all locks have been removed, manipulation of the object is possible again. The following conditions apply to locking behaviour:
- Other tasks may be able to gain limited access to the object's data after you have locked it (e.g. locking a file may prevent writing, but other processes could still read the file). The class should document this behaviour. If it doesn't, work on the assumption that other processes will have read access to the object's data.
- The object will be fixed in place and cannot be moved or deleted, even by your own process, until it is unlocked.
- If you
Freea locked object, its class will automatically reverse all locks that exist at the time of termination.
Please be aware that the Lock action and LockObject() are functionally very different. To clarify, the LockObject() function is used to gain exclusive, temporary access to the use of an object's interface. It has no impact on the material use of the underlying data that the object might be referencing.
Locking is provided for developers that need to prevent object data from being altered. Locks can either be shared or exclusive to processes, depending on what is suitable for the object and its class.
As a result of locking, the object will be fixed in place and cannot be moved or deleted, even by the process that holds the lock, until the object is unlocked with the Unlock action. As the developer, you have a responsibility to enforce your own rules to support locks. Feel free to place other restrictions on the object where appropriate.
Detailed documentation on locking behaviour is strongly recommended for the client.
Supporting the Unlock action is required in tandem with Lock. Multiple locking calls are expected to nest, and a counter should be used to ensure that this is the case.
This is an internal action managed by the Surface class. It should never be called by the client.
This action is automatically called on Surface objects when they lose the user focus. Other UI classes are not expected to support it.
ERR acMove(Object, DOUBLE DeltaX, DOUBLE DeltaY, DOUBLE DeltaZ)
| Name | Type | Description |
|---|---|---|
| DeltaX, DeltaY, DeltaZ | DOUBLE | The number of units to move along each axis. |
The Move action is provided to move graphical objects to a new position. Coordinates are specified as a delta, so the current position of the object will be taken into account. If the current coordinates of an object are needed to compute the desired target position, reading the X and Y fields is the most typical way of doing so.
Note: The DeltaZ parameter is ignored if the target does not support three dimensions.
The MoveToPoint action may also be available as an alternative choice to Move, and uses absolute positioning.
If a class supports a coordinate system (typically the case for all graphics classes) then supporting the Move action is advised. Movement is achieved with delta values, so the current X, Y and Z positions will need to be tracked and available to the client via equivalent field values.
If there is a limit as to how far an object can move in any direction, keeping the object to the edge of its bounds is permitted. You should still return an error code of ERR::Okay in cases where it was not possible to move by the requested amount.
ERR acMoveToBack(Object)
The MoveToBack and MoveToFront actions are used for shuffling objects to the back or front of their containers. Generally this is applied to graphics classes, but other class types can support these actions for sorting purposes.
In some instances it may not be possible for an object to be moved completely to the front or back, in which case the object will move as close to the requested position as possible. This situation will typically occur when groups of objects are locked to their position, preventing others from being promoted ahead of them.
Support MoveToBack and MoveToFront to allow the client to make adjustments to the sort order of overlapping objects.
If your class supports the Lock action, it may be appropriate for locked objects to hold their position when at the front of the queue. This is a design choice, so documenting the class' behaviour in this area is recommended.
ERR acMoveToFront(Object)
The MoveToBack and MoveToFront actions are used for shuffling objects to the back or front of their containers. Generally this is applied to graphics classes, but other class types can support these actions for sorting purposes.
In some instances it may not be possible for an object to be moved completely to the front or back, in which case the object will move as close to the requested position as possible. This situation will typically occur when groups of objects are locked to their position, preventing others from being promoted ahead of them.
Support MoveToBack and MoveToFront to allow the client to make adjustments to the sort order of overlapping objects.
If your class supports the Lock action, it may be appropriate for locked objects to hold their position when at the front of the queue. This is a design choice, so documenting the class' behaviour in this area is recommended.
ERR acMoveToPoint(Object, DOUBLE X, DOUBLE Y, DOUBLE Z, MTF Flags)
| Name | Type | Description |
|---|---|---|
| X, Y, Z | DOUBLE | The new position to move the object to. |
| Flags | MTF | Set the relevant MTF flag for each provided parameter. |
The MoveToPoint action is provided to move graphical objects to a new position. The shift to the new position is immediate, but may be subject to certain conditions - for instance it may not be possible to move to negative coordinates. Limitations may be circumstantial and subject to class specifications. An ERR::Okay code will be returned irrespective of whether or not movement to the requested position was succesful. The coordinates of the object can be confirmed after the move by reading the X and Y fields.
The client is required to set the MTF::X, MTF::Y and/or MTF::Z flags according to the parameters that were specified. This feature allows you to move the object to a specific horizontal coordinate without altering the vertical position, for example.
The Move action may also be available as an alternative choice to MoveToPoint, and uses relative positioning.
| Name | Type | Description |
|---|---|---|
| NewChild | OBJECTPTR | Pointer to the new child. |
For internal use only.
The NewChild action is used to alert an object that it has inherited a new child from the Core's SetOwner() function. By supporting this action you can respond to the presence of new children immediately, as well as preventing objects from forming an attachment if they fail your own criteria (return an error code to do this).
In some circumstances it may be necessary for a new child to be forwarded to another object that is better suited as the owner. To do this legitimately, call the SetOwner() function to forward the child to the other object, then return ERR::OwnerPassThrough. Any other error code will be interpreted as failure, which would cause the process to abort.
| Name | Type | Description |
|---|---|---|
| NewOwner | OBJECTPTR | Pointer to the new owner. |
For internal use only.
The NewOwner action is used to alert an object that its owner has been changed successfully. Supporting this action provides an opportunity to respond to the change before the client next uses the object.
The error code returned by your function will have no effect on the SetOwner() process.
For internal use only.
NewObject is called when a new object instance from your class has been created. It is recommended that your support routine performs the bare necessities only, meaning the setting of default values and allocating resources without initialising them. Anything more important should occur in the Init action.
Returning an error code will cause the object creation process to fail.
ERR acQuery(Object)
Calling the Query action will update the target object's state to match its source, typically in the form of a file or hardware device.
Check the class documentation for the target object before utilising Query, as the exact nature of the process will be implementation dependent.
Query is useful action for ensuring that an object's state is reflective of the external source that it represents. Classes that are linked to some form of hardware will often benefit by supporting it. A basic example is the Time class, which updates its time values whenever Query is used.
It is advised that your documentation specifies the exact fields that are updated after a successful Query call.
ERR acRead(Object, APTR Buffer, LONG Length, LONG *Result)
| Name | Type | Description |
|---|---|---|
| Buffer | APTR | Points a buffer that will receive the data. |
| Length | LONG | The total number of bytes to read from the object. This value cannot exceed the size of the Buffer. |
| Result | LONG | The Read action will write this parameter with the total number of bytes read into the Buffer. |
Use the Read action to read data from an object and into a supplied memory buffer. While commonly used for file I/O, Read is useful for many situations involving the streaming of data from an external source.
Making a Read call will result in the object reading the total number of bytes defined by Length into the provided Buffer. If the class supports a seek marker, the read will start from the Position field's index. The Position will be incremented by the amount of bytes read if the call succeeds. Altering the position of the seek marker is possible with the Seek action, if the class supports it.
If the Length exceeds the total number of bytes left in the object, Read will only read as many bytes as there are available. If the class supports a Size field then it can be used to determine the number of bytes that are left to read.
The Result parameter will be updated to reflect the total amount of data that was read into the supplied Buffer. If an error occurred, or if no data is left to read, the Result will be set to zero.
The Read action is commonly used to read data from files, but can theoretically be used in any circumstance involving data storage and streaming content.
The Buffer parameter points directly to the area that will receive data from your object. The Length will indicate the number of bytes that a program wants to retrieve. If the Length is larger than the amount of data that is available, write out the full amount of data remaining.
Your class should support a Position field to indicate the current byte position from which the Read action will start. Increment the Position by the number of bytes that were read from the object's data store before returning to the client. Also consider supporting the Seek action to manipulate the Position value.
Your class should also support a Size field if the total amount of available data is a known quantity. If the source is a stream of unknown size then the Size should be set to zero, and the client should be given a means to determine that the source is streaming.
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 data is available to read, return ERR::Okay and make sure that the Result is set to zero.
ERR acRedimension(Object, DOUBLE X, DOUBLE Y, DOUBLE Z, DOUBLE Width, DOUBLE Height, DOUBLE Depth)
| Name | Type | Description |
|---|---|---|
| X, Y, Z | DOUBLE | The new position to apply to the target object. |
| Width, Height, Depth | DOUBLE | The new size of the target object. |
Use Redimension to reposition and resize an object in a single action call. This is considered to be more optimal than moving and resizing an object with sequential calls to the Move and Resize actions. By default, the target object will be redrawn automatically as a result of calling this action.
If the target contains other drawable objects, they will often respond by adjusting their dimensions to the new size. The exact result will depend on their configuration.
Setting any of the Width, Height and Depth values to zero is permitted if the existing dimension should be unchanged.
The Depth parameter is typically used for objects supporting a Z-order or Z-axis, and can be set to zero if not applicable. If the Z coordinate represents a scale factor, a setting of 1.0 would represent the normal size of the target object.
ERR acRedo(Object)
Calling Redo will reverse previous calls to the Undo action. This action can be called once for every previous call to Undo. If there is nothing to undo, ERR::NothingDone will be returned.
ERR acRefresh(Object)
Some classes support the Refresh action if their objects represent external data sources. For example, the Document class can be refreshed if the source has changed.
If a Refresh action fails, the object should remain in its original state unless the object's class states otherwise.
A class that represents a view of an 'external' data source should typically 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 the refresh process fails, avoid allowing the object to fall into an invalid state. It is recommended that either the object is left in its original state, or that the object reports the error in a way that makes it known to the user.
ERR acRename(Object, STRING Name)
| Name | Type | Description |
|---|---|---|
| Name | STRING | The new name for the object. |
Objects that support naming conventions will typically support the Rename action. The File class is a typical example of a class that provides this kind of support to change filenames.
Rename does not impose limits on the length of the supplied Name, but the underlying system might; for instance all filesystems impose a hard limit on filename length.
If your class supports naming (e.g. for the purpose of representing a data location such as a filename) then support the Rename action. If there is a limit on the number of characters that are supported by your code, document this restriction in the class manual.
ERR acReset(Object)
Using Reset on an object will revert its state to one that is similar to when it was first initialised.
The exact behaviour of a reset is class dependent, but as a rule, object data will not be destroyed as a result of calling this action (the Clear action is typically used for this purpose). A common example of a reset is to Seek back to a position of zero, stop any currently running activity, then reset the object state back to normal.
Be wary of confusing the consequences of a Reset with the Flush action. Some objects will flush themselves as a consequence of a Reset, but the key difference is that calling Flush will not result in a change of state.
The most common reason for supporting the Reset action is to allow an object to get back to its most basic 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 strongly recommended that you do not destroy any data in your support routine, but you may manipulate the object's state as required.
ERR acResize(Object, DOUBLE Width, DOUBLE Height, DOUBLE Depth)
| Name | Type | Description |
|---|---|---|
| Width, Height, Depth | DOUBLE | The new size of the object. |
The Resize action is used to alter the size of an object with a single action call. Resizing is commonly used in the UI for manipulating vector dimensions.
If a resized object contains other drawable objects, they may respond to the resize by adjusting their dimensions to the new size. The exact result will dependent on their configuration.
Setting any of the Width, Height and Depth values to zero is permitted if the existing dimension should be unchanged.
ERR acSaveImage(Object, OBJECTID Dest)
| Name | Type | Description |
|---|---|---|
| Dest | OBJECTPTR | Refers to an object that will receive the encoded image data. |
| ClassID | CLASSID | The Picture class to use for encoding the image data. |
SaveImage is used to save an object's graphics to a storage object of your choosing. The process of saving the image will leverage the Picture class, which by default saves images in PNG format. If an alternative image format provided by a Picture sub-class is desired, it can be referenced in the ClassID parameter. For instance, specifying ID_JPEG in ClassID is sufficient to save an image in JPEG format.
The object referenced in Dest must be from a class that supports the Write action. Typically this would be a File object, but this is not imposed as a restriction.
In some cases, the SaveImage and SaveToObject actions will both save image information (for example the Picture and Bitmap classes will do this) but objects that can be represented as an image and in a native data format will make a clear distinction between the two.
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, using SaveToObject on a GUI object could store its meta information, while SaveToImage can save the object as it is seen by the user.
When supporting this action you must save the image using the Picture class so that the data can be saved in the user's preferred format.
ERR acSaveSettings(Object)
The SaveSettings action exists to simplify the saving of configuration information to a default file path. In some classes it can also save altered object data back to its origin file.
ERR acSaveToObject(Object, OBJECTID Dest, CLASSID ClassID)
| Name | Type | Description |
|---|---|---|
| Dest | OBJECTPTR | Refers to an object that will receive the encoded data. |
| ClassID | CLASSID | Can refer to a sub-class that should be used when encoding the data. |
This action will save an object's data to a storage object of your choosing. The data will be saved in a file format that can be reloaded at a later time using the same class.
The object referenced in Dest must be from a class that supports the Write action. Typically this would be a File object, but this is not imposed as a restriction.
The ClassID is optional, and can be used to specify a sub-class that is preferred for encoding the object data. For example, the Sound class supports WAV data by default, but we could save audio in MP3 format if the MP3 class was referenced here.
By supporting the SaveToObject action, you can make it possible to save an object's data to a File or similar data storage object.
It is a requirement that the data being saved can be loaded by the class at a later time.
ERR acSeek(Object, DOUBLE Offset, LONG Position)
ERR acSeekStart(Object, DOUBLE Offset)
ERR acSeekEnd(Object, DOUBLE Offset)
ERR acSeekCurrent(Object, DOUBLE Offset)
| Name | Type | Description |
|---|---|---|
| Offset | DOUBLE | The desired offset to seek to, relative to the Position parameter. |
| Position | POS | The position that defines the starting point for Offset. |
The Seek action defines the next read/write position for the Read and Write actions. In some cases this can affect live tracking, for instance seeking to a new position in an active MP3 object has an immediate effect on audio playback.
The Position can be set to POS::START, POS::CURRENT or POS::END to indicate the relative start position. For example, +20 from POS::CURRENT is 20 bytes from the current position, while -20 would be 20 bytes back from the current position. In POS::START and POS::END modes the Position should be unsigned; if the value is negative then the sign will be dropped.
You cannot seek beyond the 'end' of an object, nor can you seek to a position less than zero.
To get the current position of an object, read its Position field.
A class that supports the Read and Write actions should support Seek wherever possible. 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 parameter can be either negative or positive when used in conjunction with POS::CURRENT, but in the POS::START and POS::END modes the sign of the Position is ignored (i.e. read it as an absolute value and then offset in the appropriate direction).
Seeking beyond the boundaries of an object's data is not permitted. If the client makes such a request, the new position value must be clamped and ERR::Okay should still be returned.
ERR acSetKey(Object, STRING Key, STRING Value)
| Name | Type | Description |
|---|---|---|
| Key | STRING | The name of the target key. |
| Value | STRING | The string value to associate with Key. |
The SetKey action is used to set custom key-values on an object. Keys can either be functional, as is the case for XML's xpath support, or they can be created by the client ad-hoc and permanently stored with the object.
Key names are case-insensitive unless documented otherwise, and can be retrieved with the GetKey action.
If your class design allows for key-values then you will need to support SetKey as the mechanism for setting the values.
The general recommendation for C++ developers to use a std::unordered_map to store the key values. Be sure that your method can overwrite existing values when the same key is set more than once.
Keys should be case-insensitive by default. If this is not the case, document this fact for the client.
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 key values.
ERR acShow(Object)
Calling this action will make the target object visible to the user. While graphics objects are the obvious use-case for this action, non-visual objects such as files can also support visibility changes.
Showing an object that is already visible has no effect. To make the target object invisible, call the Hide action.
If a class represents objects that are visible to the user (for example, a UI class) then being able to control that visibility is usually necessary.
If the visible state of the object is already true, do nothing and return ERR::Okay.
Changing the visible state of a graphics object can trigger a redraw of the display, but this is at your discretion. Documenting whether or not the changes will be immediately visible is advised.
Hide and Show should always be supported in tandem as would be expected by the client.
ERR acSignal(Object)
The signalling of objects is a feature created specifically for the Core API's WaitForObjects() function. By calling Signal on an object that has been referenced in a WaitForObjects() call, the process will be woken up.
Further detail is available in the WaitForObjects() documentation.
ERR acUndo(Object)
The Undo action reverses the last activity performed by the object. Objects that support this action maintain an internal stack of operations that have been performed since the creation of the object (subject to undo buffer limits). You may call Undo for as many operations as have been recorded on the stack.
There is no distinction between user and automated operations performed against the object's data - both are treated equally.
Some class types may need to be configured before they will initialise an undo buffer that can be utilised by this action.
ERR acUnlock(Object)
The Unlock action complements Lock in order to provide the necessary means for releasing locks. Unlocking an object will release all the locking conditions that have been placed on it (but bear in mind that multiple locks will nest).
If you Free an object that is still under lock conditions, the object will automatically unlock itself.
ERR acWrite(Object, APTR Buffer, LONG Length, LONG Result)
| Name | Type | Description |
|---|---|---|
| Buffer | APTR | A buffer containing the data that will be written to the object. |
| Length | LONG | The total number of bytes to write to the object. |
| Result | LONG | This parameter with be updated with the total number of bytes written from the buffer. |
Use the Write action to write data from a buffer to an object. While commonly used for file I/O, Write is useful for many situations involving the streaming of data to an external source.
Making a Write call will write Length number of bytes from the provided Buffer to the object. If the class supports a seek marker, it will start the write operation from the point determined by the Position field. The Position field will be incremented to Position + Length if the call succeeds. Altering the position of the seek marker is possible with the Seek action, if the class supports it.
If the object is at capacity then it may attempt to increase its space to write out the entire Buffer that has been provided. If it cannot do this, it will attempt to write as much information as possible and return an ERR::Okay code. If it cannot write out any data, it will return a fail code. If the object's class has a Size field, this may be expanded as a result of the call.
To confirm how much data was written after a successful Write call, check the Result parameter and compare it to the Length that was supplied.
The Write action is commonly used to write data to files, but can theoretically be used in any circumstance involving data storage and streaming content.
If the Length exceeds the total amount of space available for writing data and nothing further can be written, return an error code of ERR::LowCapacity.
Your class should support a Position field to indicate the current byte position from which the Write action will start. Increment the Position by the number of bytes that were written to the object's data store before returning to the client. Also consider supporting the Seek action to manipulate the Position value.
Your class should also support a Size field if the size of its objects is discrete. If an object is functioning as a stream, the Size should be set to zero, and the client should be given a means to determine that the object is in streaming mode.
Before returning to the client, your support routine must set the Result parameter to indicate the total number of bytes that were written to the object.