Action List

This document lists and describes all of the actions that are available in the Pandora Engine. For information on how to execute actions, refer to the Action(), ActionMsg() and ActionTags() functions in the Object Kernel Manual. Please note that the objects created in the Pandora Engine will support only the actions that the developer has deemed to be a requirement. To know outright whether an object supports a particular action, you will need to check its class manual.

Object Management Actions
Free
GetUnlistedField
Init
SetUnlistedField

GUI Actions
Draw
Focus
Move
MoveToBack
MoveToFront
MoveToPoint
Resize
Scroll
UserClick
UserClickRelease
UserMovement

Locking Actions
Lock
Unlock

General Actions
Activate
Clear
Clipboard
ClosingTag
CopyData
DataChannel
Deactivate
Disable
Enable
Flush
HealthCheck
Hide
OpeningTag
Query
Refresh
Rename
Reset
Show

File Actions
Read
SaveImage
SaveToObject
Seek
Write

 

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

Calling this action causes an object to perform its "native activity". The activity in question can be extremely varied, as the Activate action is intentionally ambiguous. Here are a few examples of what some existing classes do when their objects are activated:

  • Sound - Plays audio data.
  • Script - Executes object script files.
  • JoyPort - Reads the current status of the joyport device.

The only way to know what may result from calling the Activate action is to check the documentation for the class that the object belongs to.

Some objects will continue to perform their native activity after they return back to you - for example, activating a Sound object will cause it to play audio in the background while you continue processing. If for some reason you wish to cancel an Activate action, you can attempt to stop it with a Deactivate call.

 

Action:Clear
Short:Clears an object's data.
Arguments:  None

This action will clear an object of all its data. While it is typically used to clear graphics, it can be used to erase any type of information. Here some typical examples:

  • File - Clears file data by reducing the file length down to 0.
  • Text - Deletes all lines of text.
  • Bitmap - Clears the entire Bitmap of visible data.

 

Action:Clipboard
Short:Used to copy and paste information to and from Clipboard objects.
Arguments: 
OBJECTID ClipboardID  Must refer to a valid Clipboard object.
LONG Mode  The mode that you want to use in shifting data between the target object and the clipboard system.

The Clipboard action is used on objects for the purpose of shifting data between them and the standard clipboard system. Generally, you 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.

You will need to supply a reference to a valid Clipboard object and indicate the operation mode when using this action. The easiest way to find a valid clipboard object is to search the system for the 'SystemClipboard' object, which is automatically created when Athene is loaded. If this object does not exist, you have the option of creating a new Clipboard object from scratch. Please refer to the Clipboard documentation for information on how the Clipboard class works.

Three modes are currently available for performing clip operations, as illustrated 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.

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.

 

Action:ClosingTag
Short:The ClosingTag action is reserved for the use of script-based classes.
Arguments: None

The ClosingTag action complements the OpeningTag action. Although specifically designed for classes that process object scripts, there can be occasions where you may need to call it if you want to emulate the execution process that scripting normally follows. For more information, refer to the OpeningTag action.

 

Action:CopyData
Short:This action can be used to copy data from one object to another.
Arguments:  
OBJECTID DestinationID  The unique ID of the object that you are copying the data to.

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 DestinationID 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, if you copy the data from one Bitmap to another Bitmap, the image data of the source will be drawn to the destination, thus avoiding a raw data copy.

Check the documentation for the source object's class if you need to be sure as to whether or not it features special functionality for the CopyData action.

 

Action:DataChannel
Short: The DataChannel action is used to send described data to objects.
Arguments:  
OBJECTID ObjectID  Must refer to the unique ID of the object that you represent. If you do not represent an object, set this argument to the current Task ID.
LONG DataType  The type of data that you are sending. Options include DATA_TEXT, DATA_KEYPRESS, DATA_RAW, DATA_JOYPORT and DATA_XML.
LONG Version  The version is set in accordance with the type of data being sent. Set this value to 1 unless you are using an updated data type.
APTR Buffer  Points to the data that you are sending to the destination object.
LONG Size  The size of the buffered data must be specified here, in bytes.
LONG TotalEntries   The size of the array represented in the buffered data must be specified here. The correct value needs to be calculated according to the DataType that you have used.

The DataChannel action provides a simple mechanism for sending "described data" to objects. Currently it can send text, keypresses, raw data, joyport instructions and XML information. Sending information to an object is as simple as setting up the DataChannel argument structure and calling the DataChannel action on the target object. The target object will analyse the information to see if it can support it, and if so, will process the data according to what is appropriate for the object's class.

The most commonly supported data type is DATA_TEXT, which is used for sending text information. Support for raw data, keyboard instructions, joyport instructions and XML data is included. How you set up the argument structure is dependent on what type of data you are sending to the target object, so we will briefly explain what each data type is for and how the argument structure should be set up for them.

DATA_TEXT

Use the text data type when you are sending printable text to an object. This is one of the easier types to set-up - simply set the Buffer argument to point to the text, set the Size to the total length of the buffer, and the TotalEntries argument to 1. The text data that is being sent to the object should not include any zero byte values.

DATA_KEYPRESS

The keypress data type is used to send simulated key-presses to objects. It can be useful for sending key-presses to the SystemKeyboard object, to make it look as if the user is typing at the keyboard. To send keypress information, you need to create an array using the dcKeyEntry structure and specify the keypress values for each array entry. The dcKeyEntry structure is defined as follows:

   struct dcKeyEntry {
      WORD Flags;       /* Key Qualifiers */
      WORD Value;       /* ASCII Key Value */
   };

Setting the correct qualifiers in the Flags field is vital - each keypress must be represented by a KQ_PRESSED flag the first time that a given key is pressed and each keypress must be followed up with a KQ_RELEASED flag to indicate that it is no longer being held. Repeated key-presses should be qualified with KQ_PRESSED|KQ_REPEATED. If necessary, a combination of KQ_PRESSED|KQ_RELEASED can be used to simplify singular key-presses.

The TotalEntries argument must be set to the total number of key entries used in the array, and the Size argument must be calculated using the formula "sizeof(struct dcKeyEntry) * TotalEntries".

Refer to the "input/keyboard.h" include file for a complete list of keyboard qualifier flags, as well as the Keyboard class for keyboard related documentation.

DATA_JOYPORT

The joyport data type is used to send simulated joyport activity to objects. For instance, you can use it to send mouse activity to the SystemMouse object to forcibly move the mouse pointer around the display. The Joyport class also uses this data type to send information to objects that want to receive raw joyport data.

To send joyport data, you need to create an array using the dcJoyEntry structure and write a value to every field in the array. The dcJoyEntry structure is defined as follows:

   struct dcJoyEntry {
      DOUBLE XChange;
      DOUBLE YChange;
      DOUBLE ZChange;
      DOUBLE AbsX;
      DOUBLE AbsY;
      DOUBLE AbsZ;
      LONG ButtonPressFlags;
      LONG ButtonReleaseFlags;
   };

The XChange, YChange and ZChange fields indicate the amount of units moved in each direction by the virtual joyport device. If all of the three aforementioned fields are set to NULL, then the AbsX, AbsY and AbsZ fields can be set to the absolute coordinates of the pointing device represented by the virtual joyport. Otherwise, the absolute coordinate values should all be set to a value of -1.

The ButtonPressFlags can be used to indicate button clicks. A maximum of 32 buttons are supported, with (from right) bit 1 supporting the left mouse button, bit 2 the right mouse button and bit 3 the middle mouse button. Refer to the "input/joyport.h" include file for a list of pre-defined button definitions.

The ButtonReleaseFlags must be set as a follow-up to flags that have been previously set in the ButtonPressFlags field, in order to indicate that the previously clicked buttons have been released. If you are not going to send a follow-up message, set the ButtonReleaseFlags to the same flag values that you set for the ButtonPressFlags field.

DATA_RAW

Sending raw data to an object is the data channel's equivalent of calling the Write action. To send raw data, set the Size to the byte length of the data and the TotalEntries argument to 1.

DATA_XML

The XML data type has the same attributes as the DATA_TEXT type, except it represents text that has been structured using XML formatting. How the information is interpreted by the object receiving the data is dependent on how that class has been designed to process XML information. It is recommended that you check the class' documentation to see if and in what way XML data is supported.

 

Action:Deactivate
Short:Stops an object from performing its native activity.
Arguments:  None

Deactivating an object that has recently been activated through the Activate action will cause it to halt the execution of its native activity. If the object is not performing any activity, then this action will do nothing.

 

Action:Disable
Short:Disables an object.
Arguments:  None

The Disable action is used to put an object into a state where it can no longer respond adequately to outside interaction. It is typically used to temporarily "turn off" objects in the interface. For instance, disabling a Render object will cause it to drop user events coming from mouse clicks and pointer movement. An object will remain in a disabled state until you enable it again with the Enable action.

Multiple calls to the Disable action will not nest unless the documentation for the object's class states otherwise.

 

Action:Draw
Short:Draws object graphics to drawable areas.
Arguments:  
DOUBLE XCoord   The horizontal coordinate of the region to be drawn.
DOUBLE YCoord   The vertical coordinate of the region to be drawn.
DOUBLE Width   The width of the region to be drawn.
DOUBLE Height   The height of the region to be drawn.

This action will draw an object's graphic, either to the video display or to a virtual drawing space, according to the object type and your 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 arguments specify the size of the region that you want to draw. If you wish, you may choose not to supply these arguments if the entire region of the object should be drawn.

To draw graphics in Athene, the Draw action is usually called on Render objects to update the video display. Refer to the Render class for more information on interface-based drawing. For information on drawing primitive graphics to drawable areas, refer to the Bitmap class.

 

Action:Enable
Short:Enables a disabled object.
Arguments:  None

The Enable action is provided for the purposes of reactivating objects that have been disabled with the Disable action. When an object is enabled, all the changes caused by disablement are undone.

 

Action:Flush
Short:Flush buffered data from an object.
Arguments:  None

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.

 

Action:Focus
Short:The Focus action is used to focus on objects within the user interface.
Arguments:  None

The Focus action is primarily used within Athene for focussing on areas of the graphical user interface. Objects supporting the Focus action are typically members of the Drawable category, of which only the Render class currently qualifies.

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 rendered areas often listen to Focus activity so that they know when to start responding to keyboard input.

 

Action:Free
Short:Frees an object and any of its associated resources.
Arguments:  None

After you have finished working with an object, you will need to free it from the system to stop its use of memory and other resources. If the object has one or more child objects attached to it, they will also be removed as a result of calling this action. Once the object has been freed from the system, you should proceed to drive all unique ID or pointer variables that reference the object to NULL, in order to prevent subtle bugs from appearing in your program.

It is important to note that if you have an exclusive lock on the object from AccessObject() at the time of calling the Free action, the object will only be marked for deletion. This means that the object will continue to remain in memory until the last lock is removed with a matching ReleaseObject() function call.

 

Action:GetUnlistedField
Short:This action retrieves field values that are not defined by an object's structure.
Arguments: 
STRING FieldName  The name of the field value that is to be obtained.
STRING Buffer  Pointer to a buffer space large enough to hold the retrieved value.
LONG Size  Must be set to the total size of the buffer space pointed to by the Buffer argument.

The GetUnlistedField action is used to retrieve object fields that are not officially listed as part of an object's structure. Generally the objects that are created in the Pandora Engine will have all of their fields defined by the class specification that they originate from, allowing you to access them through GetField() and SetField() functionality. However, there are cases where dynamic field manipulation is required, and this is what both the GetUnlistedField and SetUnlistedField actions are for.

Unless an object has specially documented behaviour for GetUnlistedField support, this action is only able to retrieve fields that have previously been set through a call to SetUnlistedField. Unlisted fields are always handled as strings for ease of use, so if you need to store integers or floating point numbers you will need to convert them to and from their equivalent string values (the Strings module provides various functions for this purpose).

To retrieve an unlisted field, set the FieldName, then the Buffer argument to point to an area of reserved space that is large enough to hold the string that you expect to receive. The Size argument must be set to the total size of the provided buffer in order to prevent an overflow from occurring.

If the requested field does not exist, the ERR_UnsupportedField error code will usually be returned from the object's class.

 

Action:HealthCheck
Short:Objects that are suspected to be damaged can sometimes be repaired by making a health-check.
Arguments:  None

Some object classes support the HealthCheck action to recover from data corruption. This action is usually called in dire situations detected by the system management routines, but can also be used as part of regular processing to check up on an object's integrity.

Any object passing a health-check will return an ERR_Okay error code. If serious problems were detected that could not be repaired, ERR_ObjectCorrupt will be returned.

 

Action:Hide
Short:Hides a visible object from the view of the user.
Arguments:  None

Hiding is an action that is used to remove objects from the sight of the user. Examples of this include hiding Screen and File objects. After you have hidden an object, call the Show action if you need to make it visible again.

 

Action:Init
Short:Initialises an object so that it is ready for active use.
Arguments:  None

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, GetUnlistedField and SetUnlistedField actions.

If the initialisation of an object fails due to a support problem (for example, if you ask a Picture object to load a JPEG file when it only supports IFF), the Init action will look for a sub-class that can handle the data. If a sub-class that can provide ample support 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.

If an object does not support the data or specifications that have been set for it, an error code of ERR_NoSupport will be returned to indicate that the base class does not support the object data.

 

Action:Lock
Short: Locks an object's 'physical' position and other attributes.
Arguments:  None

The Lock action can be used on an object when you don't want it to be physically moved or deleted for a short period of time. The most common example of locking under any system is in the file system. For instance, locking a file prevents it from being deleted or moved to a new location, which is useful if you want it to stay in one place while you are reading or writing to it.

The original and any subsequent calls to Lock must be matched with calls to the Unlock action, because locks will nest. Once all locks have been removed, the ability to physically manipulate the object becomes available 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 tasks could still read the file). The object you are attempting to lock should have specific documentation on this. If it doesn't, work on the assumption that other tasks will have some limited access to the object's data.
  • The object will be fixed in place and cannot be moved or deleted, even by your own task, until it is unlocked.
  • If you Free a locked object, its class will automatically reverse all locks that exist at the time of termination.

Please be aware that locking an object and gaining exclusive access to an object are not the same thing. To clarify, the AccessObject() function is used on public and shared objects to gain temporary access. On the other hand, an object's locking behaviour is always defined by the controlling class, which does not affect access to the object itself, although it can affect access to the physical data or equivalent representation of the object.

 

Action:Move
Short:Moves the physical representation of an object to a new location.
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.

The Move action is provided to move graphical objects to new coordinates within drawable areas. The result of moving an object is determined by the object's current coordinates in combination with the unit changes that you want to apply. For instance, if the object is at position (43x, 95y) and you apply movement arguments of (-3x, 2y, 0) then the object will be moved to position (40x, 97y). If you need to know the current coordinates of an object in order to move it to a specific location, read its XCoord and YCoord fields to determine its current position.

Please note that while most graphical objects will support the ability to be moved on the X and Y axis, the ZChange argument is ignored unless the object supports 3 dimensional space.

 

Action:MoveToBack, MoveToFront
Short:Move an object to the back or front of its current location.
Arguments: None

The MoveToBack and MoveToFront actions are used for shuffling objects to the back or front of their containers. Generally this is applied to graphical classes, but other class types can support these actions for more obscure purposes (sorting for example).

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 can only move as close to the requested position as possible. This situation will often occur when groups of objects are locked at specific positions, preventing others from getting ahead of them.

 

Action:MoveToPoint
Short:Moves the physical representation of an object to a new location.
Arguments: 
DOUBLE XCoord  The horizontal coordinate to move the object to.
DOUBLE YCoord  The vertical coordinate to move the object to.
DOUBLE ZCoord  The depth position to move the object to.
LONG FlagsFlags that indicate the parameters that you have specified. (MTF_X, MTF_Y and MTF_Z respectively).

The MoveToPoint action is provided to move graphical objects to new coordinates within drawable areas. The shift to that 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 imposed depending on the circumstances and are subject to class specifications. An Okay error code will be returned irrespective of whether or not movement to the requested location was succesful. If you need to determine the coordinates of the object after calling for a move, read the XCoord and YCoord fields to determine the current position of the object.

You are required to set the MTF_X, MTF_Y and/or MTF_Z flags according to the parameters that you have specified. This feature allows you to move the object to a specific horizontal coordinate without altering the vertical position, for example.

 

Action:OpeningTag
Short:The OpeningTag action is used to 'execute' objects.
Arguments:  None

The OpeningTag action is typically used by classes that perform object execution processing, as in the Script and CommandLine classes. If you want to emulate the execution process for objects, follow this procedure:

  1. Create the object using the NewObject() function.
  2. Set the object fields.
  3. Call the Init action on the target object.
  4. Call the OpeningTag action on the target object.
  5. If the object will contain children, create and initialise them to the parent object using this same procedure.
  6. Call the ClosingTag action on the target object.

The effect of calling the OpeningTag action is extremely similar to calling the Activate action - in fact, for some objects the result is identical. For this reason, do not follow-up an OpeningTag action with an Activate call, or you could end up activating the object twice.

If you are not performing batch-style processing it is often a better idea to use an Activate call, as it can be quicker and achieve the same result in most cases.

 

Action:Query
Short:Gets the latest information on a particular object.
Arguments: None

Calling the Query action will update the target object so that it reflects all changes in status since the last Query or Init call. Querying is typically used to get information on object data and for analysing objects that have constant status updates originating from an external source.

It is recommended that you check the documentation for the target object before calling the Query action, as there is no clear-cut procedure for classes to follow in supporting this action.

 

Action:Read
Short: Reads raw data information from objects.
Arguments: 
APTR Buffer   Set this parameter to point to an empty memory buffer that will receive the data.
LONG Length   Must be set to the amount of bytes that you want to read from the object. This value cannot exceed the size of your Buffer.
LONG Result   Set this parameter to NULL - the Read action will update this argument to reflect the total number of bytes read into the Buffer before returning.

Use the Read action to read data from an object and into a supplied memory buffer. While the most obvious use for this action is in File I/O, it can be supported by any class that can store data or retrieve it from an external source.

Making a Read call will result in the object reading the total amount of bytes defined by Length, into the memory area pointed to by the Buffer argument. If positioning is supported, the object will start reading from the point defined in its Position field. The Position field will be incremented by the amount of bytes read if the call succeeds. This means that further calls to Read will begin from the position set by the last Read call. If you need to alter the current data position of an object, make a call to the Seek action.

If the Length exceeds the total amount of data left in the object, the Read action will only read as many bytes as there are left in the object. If you want to know how many bytes are left to read, get the Position and Size field values from the object and subtract the Position from the Size to get the amount of bytes left.

Make sure that the Length value that you specify is not larger than the size of your Buffer, or an overflow will occur that could potentially crash your program.

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 parameter will be set to zero.

 

Action:Refresh
Short:The Refresh action is used to refresh object states.
Arguments:  None

Some classes support the Refresh action if their objects represent external data sources. For example, the FileView class represents a view of the file system, which is external to a FileView object. If the file system changes, manually refreshing the FileView will update it to reflect those changes.

If a Refresh action fails, the object should remain in its original state unless the documentation for the object class states otherwise.

 

Action:Rename
Short:Renames an object.
Arguments:  
STRING Name  The new name for the object.

Objects that support naming conventions will typically support renaming through the Rename action. The File class is a typical example of a class that provides this kind of support. Although Rename does not impose limits on the length of the supplied name, you should read the object's documentation for what limits might be imposed.

 

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

This action will reset an object to a state that is similar to when the object was first initialised. The resulting behaviour depends greatly on the object that you are trying to reset, 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 response to resetting is to Seek back to a position of zero, stop any currently running activity, then reset the object state back to normal.

Resetting an object is not the same as using the Flush action. Some objects will flush themselves automatically on receiving a Reset action, others may not. It depends on the circumstances, but if you want the data flushed then use the Flush action instead.

 

Action:Resize
Short:Resizes objects that are represented by two or three dimensional graphics.
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.

The Resize action is used to alter the width, height and depth of an object with a single action call. Resizing is commonly used in the Athene interface for manipulating drawable areas that represent gadgets like windows, buttons and scrollbars. This means that it is typically applied to Render objects, but it can also be useful for quickly adjusting the dimensions of graphical objects like boxes and ellipses.

If a resized object contains other drawable objects, they will often respond to the resize by adjusting their dimensions to the new size. The exact result will depend on what children are contained by the target object and how you have programmed them.

If you only want to resize a particular dimension (for example if you want to resize the Width and leave the Depth and Height "as is"), set the other arguments to zero. The Depth argument is only used for 3-Dimensional objects - set it to zero if you know that the object is represented in 2D only.

 

Action:SaveImage
Short:Saves an object's image to a destination object.
Arguments: 
OBJECTID DestinationID   Must refer to an initialised object that the class should save the image data to.

The SaveImage action is used to save the visual representation of an object to a storage object of your choosing. The image will be saved in a file format that can be reloaded using the Picture class. In most cases the object that you specify in the DestinationID argument should be a File object, although you can use any object type that you wish if its class supports the Write action and the concept of data storage.

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.

 

Action:SaveToObject
Short:Saves an object's data to a destination object.
Arguments: 
OBJECTID DestinationID   Must refer to an initialised object that the class should save data to.

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 re-loaded at a later time using the object's documented mechanism for loading data. In most cases the object that you specify in the DestinationID argument should be a File object, although you can use any object type that you wish if its class supports the Write action and the concept of data storage.

 

Action:Scroll
Short:Scroll the contents of a container.
Arguments: 
DOUBLE XChange  The amount of units to scroll along the horizontal axis.
DOUBLE YChange  The amount of units to scroll along the vertical axis.
DOUBLE ZChange  The amount of units to scroll along the Z axis.

The Scroll action is used to scroll the graphical contents of drawable objects. Simply provide the necessary values to indicate the shift in direction and apply the action to the target object to scroll its contents.

Sending a Scroll action to a drawable object will always succeed, because the object itself will not respond to scrolling activity. However, objects that are listening for scroll requests will detect the action call and respond accordingly. The Text class is a good example of a class that has extensive support for scrolling activity. Whether or not a foreign object succeeds in its processing is not reflected in the returned error-code.

The interpretation of the parameters that you supply are relative to the object you are scrolling. In most cases the scroll direction will be measured in pixels, but not always. The documentation for the object you are trying to scroll will specify how it interprets the scrolling distance if it is not pixel based.

 

Action:Seek
Short:Seek to a new position in an object.
Arguments: 
DOUBLE Offset   The position that you want to seek to, relative to the Position argument.
LONG Position   Either POS_START, POS_CURRENT or POS_END.

The Seek action sets the read/write position for the target object. This position is used by both the Read and Write actions as a place to start reading or writing. In some cases it can also affect other areas of object behaviour, for instance seeking to a new position of an audio based object can affect the point at which it will play-back the audio.

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.

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.

 

Action:SetUnlistedField
Short:This action sets field values that are not defined by an object's structure.
Arguments: 
STRING FieldName  The name of the field that you want to set.
STRING Value  The value that will be written to the unlisted field, specified in string format.

The SetUnlistedField action is used to set object fields that are not officially listed as part of an object's structure. Generally the objects that are created in the Pandora Engine will have all of their fields defined by the class specification that they originate from, allowing you to access them through GetField() and SetField() functionality. However, there are cases where dynamic field manipulation is required, and this is what both the GetUnlistedField and SetUnlistedField actions are for.

Unlisted fields are always handled in string format, so if you need to store integers or floating point numbers, you will need to convert the values to their equivalent string format first (the Strings module provides various functions for this purpose).

Please note that the SetUnlistedField action can only be used on objects that specifically offer support for unlisted fields.

 

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

Calling this action will make the target object visible to the user. If the object is represented visually then it will usually appear on the video display. Non-visual objects such as files may simply have a permission switch changed. If you show an object that is already visible, there will be no effect.

If you want to make the target object invisible, call the Hide action.

 

Action:Unlock
Short:Remove a lock from an object.
Arguments:  None

The Unlock action complements the Lock action in order to provide the necessary means for releasing locks. Once you have unlocked an object, all of the locking conditions placed on that object will be removed (although locks will nest, so you will need to call Unlock for every Lock that is still waiting to be freed).

If you Free an object with locks that are still waiting to be unlocked, the object will automatically undo Free action will automatically Unlock them for you.

 

Action:UserClick
Short: Use this action to inform drawable objects that a user click has occurred.
Arguments: 
LONG ButtonFlags  Associated flags for the user click should be 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 XCoordThe horizontal coordinate of the user click, relative to the object's top left corner.
DOUBLE YCoordThe vertical coordinate of the user click, relative to the object's top left corner.
DOUBLE ZCoordThe Z coordinate of the user click, relative to the object's top left corner.

The UserClick action is used to tell drawable objects that the user is attempting to interact with them through a pointing device. A "user click" is typically defined as a user hitting a mouse button, or touching an area on a touch screen. Classes such as the Pointer are typically responsible for sending UserClick actions to drawable objects when buttons have been clicked using external devices.

The ButtonFlags argument must be set in accordance with one or more of the bit-flags listed in the "input/joyport.h" file. Bit 1, also known as JD_LMB is the most common flag setting as it represents the primary button (the left-hand button on the mouse).

The coordinates supplied to the object must be relative to the object's graphical representation, for instance if the mouse pointer is centered over position (16,4) of a Render object, the XCoord and YCoord arguments will be set to those values respectively.

Sending a UserClick action to a drawable object will always succeed, because they themselves do not respond to user activity. However, objects that are listening to user activity will detect the action call, and respond accordingly. Objects belonging to the OnClick class are the most obvious example. Whether or not these external objects succeed in their processing is not reflected in the returned error-code.

Most classes expect a UserClick action to be followed by a UserClickRelease, so for this reason you must call the UserClickRelease action at some point after making a UserClick call. It is illegal to call UserClick using the same ButtonFlags more than once without a matching UserClickRelease. It is possible to call UserClick consecutively in situations where the user was to hold the left mouse button, then the right mouse button, then release the left mouse button for example. However, you will still need to make two calls to UserClickRelease in such a situation, or set both bit-flags in a single release call.

 

Action:UserClickRelease
Short:Informs an object that a user click has been released.
Arguments: 
OBJECTID OverObject   The object that the user is currently positioned over.
DOUBLE XCoord The current horziontal coordinate in relation to the OverObject.
DOUBLE YCoord The current vertical coordinate in relation to the OverObject.
DOUBLE ZCoord The current Z coordinate in relation to the OverObject.
DOUBLE XChange The change in direction from the user's position since the previous call to UserClick.
DOUBLE YChange The change in direction from the user's position since the previous call to UserClick.
DOUBLE ZChange The change in direction from the user's position since the previous call to UserClick.
LONG ButtonFlags   The flags used in the matching UserClick call must be specified here.

The UserClickRelease action complements the UserClick action in order to provide a means of indicating the release of a clicked button. There are many circumstances where a component needs to be informed of the user clicking and then releasing that click - which is something that can happen instantly, or over a period of seconds. For example, when a button is clicked, it may change its graphical look to show that it has been selected. The selection state may remain until the click is released, whereupon the graphics return to normal. The only way for the button to detect a click release is for the sender of the original UserClick to return a corresponding UserClickRelease action.

Because it is possible for the user to move the focus while holding down a clicked button (common usage for drag and drop), the OverObject argument specifies where the user has shifted the focus to while holding down one or more buttons. Objects that support drag and drop may use the OverObject argument to identify the new container. In relation to this, 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 to inform components of user movement.
Arguments: 
OBJECTID OverObject  The object that the user is currently positioned over.
DOUBLE XCoord The current position of the user in relation to the target object's top left corner.
DOUBLE YCoord The current position of the user in relation to the target object's top left corner.
DOUBLE ZCoord The current position of the user in relation to the target 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.

The UserMovement action controls the heart of user interactivity. It is typically used to reflect incoming movement from user devices like mouse pointers, graphics tablets and touch-screens. This action allows objects participating in the user interface to detect the current focus as the user moves the pointing device over them.

There are two types of user movement that can detected by objects:

  1. Basic movement within a drawable object.
  2. Movement from one drawable object to another. In a case such as this, it is necessary to make two UserMovement action calls - one to tell the previous object that the user has moved away, and another to the new object so that it knows that the user has moved into its region.

The OverObject argument is used to indicate what object the pointing device is currently positioned over. Objects that detect user movement will check this argument to see if it refers back to themselves. If it it doesn't, they know that the user has moved out of their graphical region and into the region of the indicated object.

The coordinate values must reflect the position of the pointing device in relation to the target object. If the user is positioned 10 pixels left and 40 pixels above the top left corner of the target object, the correct coordinate values will be (-10, -40, 0). The XChange, YChange and ZChange values must reflect the change in direction since the last time that the pointing device was moved.

 

Action:Write
Short: Writes data to objects that provide storage or output services.
Arguments: 
APTR Buffer   Points to a memory area that contains the data that will be written to the object.
LONG Length   The total amount of bytes to write to the object.
LONG Result   Set this parameter to NULL - the Write action will update this argument to reflect the total number of bytes written before returning.

The Write action is used to write buffered data directly to an object's data storage area. Objects that support the Write action are typically developed to provide data storage or data output services. This normally involves use of the local file-system, but memory and other storage or output mediums can be employed by some objects. You could for instance, write data to a printer, a command line, or an audio output device.

Making a Write call will result in the object reading the total amount of bytes from the provided Buffer, as indicated by the Length argument. If positioning is supported by the object, it will start the write operation from the point determined by its Position field. The Position field will be incremented to "Position + Length" if the Write call succeeds. Further calls to Write will typically begin from the position set by previous Write calls. If you need to alter the current data position of an object, make a call to the Seek action.

If the object is at capacity (i.e. it cannot store or output any more data) then it may attempt to increase its data space to write out the entire buffer that you have provided. If it cannot do this, it will try to write out as much information as it can and return an ERR_Okay error code. If it cannot write out any data, it will return a fail code.

To check how much data was written during a Write call, check the Result parameter to see if it matches the Length value that you originally supplied.

 


Copyright (c) 1996-2001 Rocklyte Systems. All rights reserved. Contact us at feedback@rocklyte.com.