Failed to open XML data source.
-Failed to open XML data source.
-This document lists and describes all of the actions that are available in the Parasol Framework. For information on how to execute actions, refer to the
While the object kernel's
When a program calls AccessObject(), a check will be made to see if your class supports the AccessObject action. If it does, a call will be made to your support routine. If you do not have a support routine, AccessObject() will assume that you do not wish to be informed, and will proceed to grant the exclusive lock.
-If you return an error code other than ERR_Okay, AccessObject() will abort and return that error code to the program that made the exclusive call.
-This action will need to be supported by your class if you have called the
The ActionNotify action is called after or during the execution of a monitored object's support routine. You will receive information telling you the ID of the object and the action that was called, the arguments that were passed and an error code that indicates whether or not the call was successful. There are no restrictions on how you should respond to an ActionNotify call. The error code that you return from this action will be ignored.
-You can terminate an action subscription by calling the
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:
-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
The Activate action is the most abstract of those that are available, which means that you are free to implement a support routine that does whatever you like (so long as it is in the spirit of the object's context). For example, a Music class would play audio, a Command class would execute a command and an Effect class would start drawing graphics.
-If your object performs an action that continues in the background after returning to the program, you may also want to support the Deactivate action to provide a cancellation service.
-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:
-The state of the object will normally remain intact - so object settings will not be affected by a clear.
-Clearing is an interesting action as it can have a very different meaning for each object. Clearing a graphic for example will often leave a black area on the screen, while clearing a File might delete it from the file system. Depending on your object type, you will have to make the most logical decision as to how you might support this action.
-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 a UI object is created. 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:
-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.
-If you want to provide support for the system-wide clipboard service then you will need to write code for the Clipboard action. This action is closely related to the Clipboard class, as you will be passed a clipboard object in the ClipboardID argument and will be expected to interact with that object. The Mode reflects the type of action that you should perform. Available Mode types are listed in the following table:
-Copy and cut operations are identical apart from the fact that cutting data will require you to delete the information after pasting it into the clipboard. To paste data into a clipboard, you can use any of the mechanisms supported by the Clipboard class, such as the DataChannel action. Please refer to the documentation for the Clipboard class for more information.
-To paste data from a clipboard into one of your objects, you need to scan the clipboard object's data store and load the data off the file system in order to retrieve it. You may be 'selective' in the data that you retrieve from the clipboard, for instance, if the next clip is an image and your class only supports text data, you can ignore the image and extract the text data instead. The documentation for the Clipboard class has more information on how to scan the data store.
-The ClosingTag action complements the
If you are developing a class that is designed for use in object scripts, or potentially could be used in an object script, then you should support the ClosingTag action.
-The ClosingTag action is called just after a script interpreter has created an object, set its fields, initialised it and attached children to that object. By calling the ClosingTag action the process is basically telling you that "You've been completely initialised, so if you need to do something important, do it now".
-You can use this as an opportunity to
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
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.
-The CopyData action is provided so that data in one object can be copied across to another. This may or may not involve data conversion. For example, copying data between files is a very straight forward process. However, copying data between two Bitmap's would be more complicated, because we need to consider clipping and type conversion issues. Copying between different classes is also permitted, for example copying a Picture to a File could output the image as raw data.
-If you wish to write your routine so that it only supports a limited number of object types, return ERR_NoSupport when you detect a destination object that does not belong to a supported class. If you wish to support all object types, use the
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.
- -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.
- -This is a special data type used by the
This format is used to declare file paths that contain data intended to be transferred between objects. It is frequently used to speed up data transfers where loading file data into a buffer and passing it through the data channel system would be cumbersome.
- -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
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:
- -If the DeltaX, DeltaY and DeltaZ fields are set to zero, 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 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:
- -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
The
Available network operation codes are as follows:
- -Sending raw data to an object is the data channel's equivalent of calling the
In response to a DATA_REQUEST from an object, a RECEIPT will be sent to the requesting object via the data channel system. The receipt will contain a null-terminated XML string with the data that has been requested. Please refer to the documentation for the DragDrop action for further information.
- -The REQUEST data type is primarily designed for drag and drop operations, but theoretically can be used for any type of data transfer between objects where uniquely numbered items may be prevalent. A data request is made to another object by passing it a unique item ID and indicating up to 3 types of supported data formats that would be accepted from the source. The structure for managing the request is configured as follows:
- -The data types indicated in the Preference field can be any of the pure data types supported by the DataChannel action, for example DATA_TEXT or DATA_XML. Any unused elements of the Preference array must be driven to zero, including the 4th.
- -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.
-The DataChannel action is available for classes that need to have an open port for receiving various types of data from other objects. It can be extremely useful in cases where you want your class to be able to receive miscellaneous commands or formatted information for internal processing. For example, the Keyboard class supports the DataChannel action so that it can receive virtual keypresses from software, rather than being restricted to hardware input.
-The DataChannel action is closely linked to the
Descriptions of the data formats that can be sent through this action are described in the DataChannel section of the Action User Guide.
-The Custom action is provided to simplify the passing of custom messages through the action system. Calls to the Custom action need to be monitored by a listener that checks the Number and String values for a meaningful message. If no listener has subscribed to the Custom action then no activity will occur (classes do not apply any support of their own to this action).
-In summary, through the use of the Custom action you can effectively add actions to your program in a way that is meaningful to specific objects. For more information on how to listen to an action, refer to the
It is recommended that no class should support the Custom action directly as its purpose is undefined (we would suggest that you create a new method or field rather than support this action). -
Deactivating an object that has recently been activated through the
If your class supports the Activate action then you may also want to write support code to deactivate an object. In most cases this only applies to objects that support background processing. For example, after activating a Sound object an audio sample will play in the background. Because the Sound class supports the Deactivate action, it is possible for a program to cut the audio short whenever it wants to.
-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
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 an impact on the creation of the graphical user interface, or those that have a close proximity to the actions performed by the user.
-You need to make a judgment as to what support areas will be deactivated when a Disable call is made to one of your objects. Generally you should not deactivate all areas of an object as the point is not to render it useless. Only the interactive elements of the object should be disabled (your interpretation of what is interactive will depend on the type of class being developed).
-If necessary you can write your own code to nest any multiple calls to the Disable action, although this would be considered to be the exception to the rule. If you are going to support nesting, you must document this fact in the documentation for your class.
-Support for the Disable action should also be matched with support for the Enable action. This will allow your disabled objects to return to a normal state, as disablement is usually only a temporary measure.
-The DragDrop action provides the core functionality of a universal drag and drop system. The process of drag and drop works as follows:
-When the item is dropped by releasing the mouse button over a surface, the following occurs:
-Data for drag and drop activity is defined in XML format. The following skeletal structure 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:
-DATA_AUDIO: <audio path="[FilePath]" object="[SoundObject]"/>
Either path or object may be set. The object must belong to the Sound class.
DATA_FILE: <file path="[FilePath]"/>
DATA_IMAGE: <audio path="[FilePath]" object="[Object]"/>
Either path or object may be set. The object must belong to either the Picture or Bitmap classes.
DATA_RAW: <raw path="[FilePath]" object="[Object]"/>
Either path or object may be set. The object must support the Read action for reading the data.
DATA_TEXT: <text>[UTF8Content]</text>
DATA_XML: <xml>[XMLContent]</xml>
Custom data that does not fit the above formats is permitted, but must be declared with the 'custom:' prefix prior to the name of the element.
- -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 you should send a DATA_REQUEST (via data channels) to the indicated Source object. The rest of your support code for drag and drop will need to be written in your
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, the Draw action is usually called on
The Draw action is provided for classes that need graphical support. A programmer will typically set up an object so that it can be drawn according to your specifications, then call the Draw action with the expectation that the object will be drawn to a graphical object (such as a Bitmap). The exact technical details of the process are for you to define.
-The dimension arguments are provided so that the programmer can declare the precise region that needs to be drawn. Your support of these arguments is entirely optional, so if they are not appropriate for your class, just ignore them.
-Note that if you are writing a GUI based class then you will probably want to use an action subscription to listen to Draw action activity, rather than supporting the Draw action directly. This is best observed by looking at the source code to one of the existing graphical classes.
-The Enable action is provided for the purposes of reactivating objects that have been disabled with the
The Enable action must be supported in situations where you have decided to include support for the Disable action in your class. The code that you write for this action must be able to undo all the changes made in your support for the Disable action. If your Disable code includes support for nesting then you will also need to take this into consideration.
-If a call is made to this action on an object which is not disabled, you should do nothing apart from returning ERR_Okay to indicate that the object is already enabled.
-If you have called the
The event information will be returned to you with a description of the event ID, followed by a set of optional information that will only be set if it is relevant to the event. The data format of the various event types is described in the
You can terminate an event subscription by calling the
If you have called the
In supporting this action you will receive information that tells you the ID of the object and the field ID whenever the value of the monitored field has been altered. There are no restrictions on how you respond to this in your routine. If you need to know the new value of the field, you can retrieve it using conventional means.
-You can terminate a field subscription by calling the
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
Flush is a useful action for buffered objects such as files. The concept of buffering is often used to speed up data processing, for example reading and writing to memory is a lot faster than to a hard drive or floppy disk. However, it can sometimes be important for the physical data to represent the data as if it were not buffered. By supporting the Flush action, you can ensure that this is possible if your class buffers information.
-When Flush is called on one of your objects, you will be expected to dump all of the buffered data to its 'physical' location, then you should clear your buffer of its contents.
-The Focus action is primarily used within the UI 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
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 activity so that they know when to start responding to keyboard input.
-This action is usually called on drawable objects (e.g. Render objects) when the user interacts with them. Your class should only support this action if it is used in an area that is in close proximity to the user's actions.
-If your class requires notification when a drawable object has received the focus, do not write support for the Focus action. You should instead use the
If your class needs to be informed when one of its objects has lost the focus, you will need to support the
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
This function is called whenever the programmer wants to free one of your objects from the system. If you have written a base class, you must undo all of the allocations that belong to the object at the time of its destruction. If you have written a sub-class, you only need to support this action if your code makes extra allocations on top of those made by the base class.
-To prevent allocations between a base class and sub-class from being confused, if you free any fields make sure that you drive them to NULL afterwards. Remember that if your sub-class requires its own private data fields, there is a MID_ChildPrivate field for this purpose in every objects' Stats structure.
-This action can be useful in rare circumstances where you might want to prevent an object from being freed from the system. Usually when an object has the Free action called upon it then the situation is terminal, but you can circumvent this by creating a FreeWarning support routine.
-If you support the FreeWarning action then the termination process will call your routine to check if it is possible to free the object. If you return an error code of ERR_InUse, then the object's termination will be aborted. Any other error code that you return will cause the object to be removed as normal.
-The GetVar 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 by the Core will have all of their fields defined by the class specification that they originate from, allowing you to access them through
Unless an object has specially documented behaviour for GetVar support, this action is only able to retrieve fields that have previously been set through a call to
To retrieve a variable field, set the Field, 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.
-If your class design allows for variable fields then you will need to support this action. A 'variable field' is a field that is not officially listed as part of an object's structure. This provides a great way of being able to store miscellaneous data through the standard field mechanisms, or for supporting special field descriptors. The GetVar action is specifically used for the retrieval of variable field data, while the SetVar action is used for creating and setting variable fields.
-If this action is called then you will be provided with information on the field name and a string Buffer that you need to write the data to. The Size argument defines the length of the Buffer - you must be careful not to write out more data than the Buffer can hold or you can crash the process. If you do not have any record of the specified Field, return an error code of ERR_UnsupportedField. Otherwise, write the field data to the buffer and return ERR_Okay. If there is not enough buffer space to write out the value, just make do with the space that is available and return ERR_Okay anyway (if necessary, you can print a warning to the debugger).
-Please note that if you support this action then it is recommended that you provide a reasonable amount of documentation so that the developer knows just how your class supports variable fields.
-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.
-The HealthCheck action is provided for classes that wish to protect the integrity of their objects in cases where an object's structure and/or data has been compromised. This action is usually called when the system runs a health check, or when the object kernel suspects that there may be something wrong with an object.
-When writing a support routine for this action, your goal is to check the object structure and fix any problems that you find along the way. If you encounter a terminal issue that is impossible for you to fix, return an error code of ERR_ObjectCorrupt. This will cause the system to flag the object as being terminally ill.
-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
If your class is designed to create objects that are 'visible' to the user (for example, a GUI class) then you may also want to provide a way to make it invisible. You can do this by providing support for the Hide action. It is recommended that you also support the Show action so that it is possible to make a hidden object visible again.
-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
If the initialisation of an object fails due to a support problem (for example, if you ask a
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.
-This action is called when a program initialises an object that belongs to your class. The purpose of this action is to prepare the object for the necessary handling for other actions such as Draw, Activate, Show etc.
-If your class is data-centric, then in cases where you cannot handle the data (e.g. an IFF class tries to interpret a JPEG file) then your routine must undo any changes it has made to the object's structure. You must then return an error code of ERR_NoSupport. This will cause the initialisation management routine to look for a sub-class that can support the object correctly. If the object was recognised but initialisation fails due to a system error or similar, then any error-code can be returned (except for ERR_NoSupport and ERR_Okay). This will cause the initialisation action to fail immediately and return to the program.
-It is highly recommended that before proceeding with full initialisation of an object, you always check the data sources and ensure that you understand them. If you check the data near the middle or end of your routine, you may make things difficult to undo if you find that you need to return ERR_NoSupport.
-You must never free your object while inside the initialisation routine. If your routine fails then the object will be freed at a time when it is appropriate to do so.
-This is an internal function that can only be called by the Document class. Class developers should refer to the supporting documentation for this action in order to write supporting code for it.
-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
Please be aware that locking an object and gaining exclusive access to an object are not the same thing. To clarify, the
Locking is provided for developers that want to prevent objects from physically moving position (e.g. files and directories) and prevents tasks from performing certain actions and changes to an object. Locks can either be shared or exclusive to tasks, depending on what is suitable for the object.
-As a result of locking, the object will be fixed in place and cannot be moved or deleted, even by the task that holds the lock, until the object is unlocked with the Unlock action. As the class programmer, you have a responsibility to enforce your own rules to support locks. Feel free to place other restrictions on the object where appropriate.
-It is extremely important that you document the behaviour of locking for your particular object. The issue of shared/exclusive locking on public objects is an important issue for you to consider.
-You must also support the
This is an internal action managed by the
This action is usually called on drawable objects (e.g. Render objects) when the user stops interacting with them and takes an interest in other objects. Your class should only support this action if it is used in an area that is in close proximity to the user's actions.
-If your class requires notification when a drawable object has lost the focus, do not write support for the LostFocus action. You should instead use the
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 X and Y 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 DeltaZ argument is ignored unless the object supports 3 dimensional space.
-If your class supports a coordinate system (this is typically the case for all graphical classes) then you should support the Move action. Movement originating from this action is relevant to the current position of the object, rather than being based on absolute coordinates. If for example a program wishes to move your object 5 units to the left, it will set the DeltaX argument to -5 and the other arguments to zero.
-If there is a limit as to how far an object can move in any direction, you can limit its movement by reducing the number of units if they would place the object in an out-of-bounds position. For example, if an object is at position (15,18) and a program wants to move it 40 units upwards, you could reduce that value to 18 units if you wanted to prevent the object moving into negative space. You should still return an error code of ERR_Okay in such a case.
-In conjunction with your support of the Move action, your class definition should define X and Y fields if it is 2-dimensional and a Z field if it is 3-dimensional. If you do not support these standard fields then it will be difficult for a program to determine the position of your objects.
-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.
-In many instances where displayable objects are on screen, the graphics will inevitably overlap each other. If you support the MoveToBack and MoveToFront actions, you can provide the developer with some assistance in the arrangement of an object in relation to other objects.
-If your class supports the Lock action, it may be best for a locked object to hold its position when the MoveToBack action is called. Whether you decide to do this or not is up to you, so document the class' behaviour in this area.
-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.
-In many instances where displayable objects are on screen, the graphics will inevitably overlap each other. If you support the MoveToBack and MoveToFront actions, you can provide the developer with some assistance in the arrangement of an object in relation to other objects.
-If your class supports the Lock action, it may be best for a locked object to hold its position when the MoveToFront action is called. Whether you decide to do this or not is up to you, so document the class' behaviour in this area.
-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 X and Y 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.
-If you need to be aware of occasions where an object has inherited a new child object from the
In some rare circumstances it may be necessary for a new child to be automatically 'passed through' to another object that would be better suited as an owner. If you want to do this, your support routine should call the SetOwner() function to pass the child through to another object, then you should return an ERR_OwnerPassThrough error code to indicate that a pass-through has occurred. Any other error code will be interpreted as failure, which would cause the process to abort.
-If you need to be aware of occasions where a program is changing the owner of an object with the
The error code that you return will not have an impact on the
This action is called whenever a new instance of an object belonging to your class has been created. The routine that you place here should be fairly simple as the object kernel will take care of the creation process - all you need to do is take care of any extra resource allocations. Some classes also like to write default values to their objects as a pre-initialisation process.
-If you return an error code then the object creation process will fail.
-The OpeningTag action is typically used by classes that perform object execution processing, as in the
The effect of calling the OpeningTag action is extremely similar to calling the
If you are not performing batch-style processing it is often a better idea to use an
If you are developing a class that is designed for use in object scripts, or potentially could be used in an object script, then you may want to support the OpeningTag action.
-The OpeningTag action is used just after a script interpreter has created an object, set its fields and initialised it. This provides you with an indication that the object has gone through significant preparation but has not yet had any children initialised to it. If you would rather wait until the object has been fully prepared, you should support the ClosingTag action instead.
-This action is provided for resource management purposes. It is also makes it possible to detect that an object will be destroyed due to the destruction of its owner.
-This action is called by the object kernel on the termination of all objects going through the free process.
-It is not possible to write support code for this action as it is managed internally.
-Calling the Query action will update the target object so that it reflects all changes in status since the last Query or
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.
-Query is a commonly supported action that programs can use to get updated information on an object. It is commonly supported by data-centric objects as well as objects that support dynamic hardware values originating from devices such as keyboards and joyports. If you want to support the Query action, then you will need to decide what fields you are going to update in your support routine, then document this behaviour accordingly.
-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
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
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.
-The Read action was initially provided in order to support reading and writing data to Files. Despite this intention, a class which supports a data storage area should support the Read action for managing raw data.
-The Buffer argument points directly to the area that will receive data from your Object. The Length will indicate the amount of bytes that a program wants to retrieve from your object. If the Length is larger than the amount of data that is actually available, just write out the maximum amount of bytes that are in the object.
-Your class should support a Position field in its structure to indicate the byte position from which the Read action will start reading data. After the Read operation, you must increment the Position field by the amount of bytes that were read from the object's data store. This will provide the developer with more versatility when it comes to reading and writing data. You should also consider supporting the
Before returning, your support routine must set the Result parameter to indicate the total amount of bytes that were read from the object. If no bytes were read, you should still return ERR_Okay but make sure that the Result is set to zero.
-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 object contains other drawable objects, they will often respond by adjusting their dimensions to the new size. The exact result will depend on what children are contained by the target object and how they are programmed.
-If you need to resize only one area 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. If the Z coordinate represents a zoom factor, a setting of 1.0 would represent the normal size of the target object.
-Calling Redo will reverse previous calls to the
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.
-If your class represents a view of an 'external' data source, you may need to support the Refresh action. The purpose of a refresh is to re-read the origins of an object's data and then update the object to reflect any differences between the object and its data source.
-If your Refresh support code fails, it is recommended that you leave the object in its original state when returning a fail code.
-If you wish to be informed when a program is releasing an exclusive lock from an object, you may write a support routine for this action. This is entirely optional, and the
The error code that you return from your support routine will be ignored.
-Objects that support naming conventions will typically support renaming through the Rename action. The
If your class supports naming (e.g. for the purpose of representing a data location such as a file name) then you may want to support the Rename action. How you support this action is entirely dependent on the focus of the class, as this action does not require you to adhere to any restrictions. If there is a limit on the amount of characters that are supported by your routine, you should document this fact in the class manual.
-Please note that an internal name as defined by your class is not the same as a public object name, as defined by the
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
Resetting an object is not the same as using the
The most common reason for supporting the Reset action is to allow an object to get itself back to a refreshed state, similar to when the object was first initialised. Examples could be resetting a file position back to the beginning, or restarting a running procedure from scratch. It is recommended that you do not actually destroy any data in your Reset support routine, although you may manipulate it as much as necessary.
-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 UI for manipulating drawable areas that represent gadgets like windows, buttons and scrollbars. This means that it is typically applied to
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.
-If a class is designed to represent a 2-dimensional or 3-dimensional space then it should support the Resize action if that space is intended to be adjustable. In conjunction with this action the class must support Width and Height fields, as well as a Depth field if the object is 3-dimensional. After a successful resize has taken place, these fields must be updated to reflect the object's new dimensions.
-If the developer only wants to resize a particular dimension such as the Width, then only the Width argument will be set and the others will be driven to zero.
-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
In some cases, the SaveImage and
This action is provided for classes that wish to make a distinction between the image of an object and the data of an object. For instance, saving a GUI object could store information on the object's construction, while saving its image would store the object as a graphic (like a camera snapshot).
-When supporting this action you should store the image using the Picture or Bitmap class so that the data can be saved in the user's preferred format. Otherwise, you should
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.
-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 DestID argument should be a
By supporting the SaveToObject action, you can make it possible to save an object's data to a File or other data storage object. This action is considered to be extremely important in creating functional data-centric objects based on pictures, sounds, documents and so forth.
-When your SaveToObject support routine is called, you will be sent a Destination object which is initialised and is supportive of Write calls. All you are required to do is Write your data to the given object. You must save your file information in a format that is recognised by your class, so that it can be loaded back at a later time.
-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
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.
-This action is typically supported by GUI components that have scrollable contents. The coordinate parameters can be interpreted as you wish - usually in pixels, but the exact details are up to you. Make sure that you document how coordinate alterations are interpreted by your class.
-The ScrollToPoint action allows graphical objects to be scrolled to new coordinates within their viewing area. The shift to the requested position is usually immediate and causes a redraw. Scrolling may be subject to limitations, for instance, it may not be possible to scroll to coordinates that would place part of the object outside of the visible page space. The support routine can still succeed if it was not possible to scroll to the exact coordinates given, but to the nearest approximation. If you need to determine the coordinates of the object after scrolling, read the X and Y fields to determine the current position of the object.
-The coordinate values that you provide will almost always need to be equal or less than zero if the top-left origin of the object is (0,0).
-You are required to set the STF_X, STF_Y and/or STF_Z flags according to the parameters that you have specified. This feature allows you to scroll the object along a single axis for example.
-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.
-If your object supports the Read and Write actions, you will most probably want to support Seek as well. Seeking is used to position the 'read/write head' so that the next time some I/O occurs, it will start at the seeked position.
-Your class is required to define a Position field that always reflects the current byte position in your object's data. When the Seek action is called, the Position must be altered to reflect the absolute byte position that the program has seeked to.
-When writing your support routine, you must write code for each of the three different modes - POS_START, POS_CURRENT and POS_END. POS_START refers to the beginning of the data, POS_CURRENT refers to the current byte position and POS_END refers to the end of the data. The Position argument can be set to both negative and positive values when the POS_CURRENT mode is used, but in the POS_START and POS_END modes the sign of the Position is not relevant (for this reason, it is recommended that you ensure that the Position is interpreted as an absolute value that is offset in the appropriate direction according to the Mode).
-Seeking beyond the boundaries of an object's data is not permitted. In other words, the resulting byte position from a Seek action cannot be less than zero, and cannot be greater than the data size. If the boundary will be broken, you should restrict the Position field to the appropriate boundary value.
-The SetVar action is used to set object fields that are not officially listed as part of an object's structure. Most class definitions will declare their supported fields, allowing you to access them through
Variable 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
Please note that the SetVar action can only be used on objects that specifically offer support for variable fields.
-If your class design allows for variable fields then you will need to support this action. A 'variable field' is a field that is not officially listed as part of an object's structure. This provides a way of being able to store miscellaneous data through the standard field mechanisms, or for supporting special field descriptors. The SetVar action is specifically used for storing variable field names and data, while the GetVar action is used for retrieving variable field values.
-If this action is called then you will be provided with information on the field name and a string Value that contains the field data. Unless you are going to dynamically interpret the field value in your routine, you will have to store the field value in the object. To do this you should come up with a simple mechanism to store multiple field names and values in a buffer that belongs to the object. You should also develop your routine so that it checks whether or not a value for the Field already exists at the time of calling. If the Field exists, then your routine should delete the existing value and replace it with the new Value that has been provided.
-Please note that if you support this action then it is recommended that you provide a reasonable amount of documentation so that the developer knows just how your class supports variable fields.
-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
If your class is designed to create objects that are 'visible' to the user (for example, a GUI class) then you may want to provide support for the Show and Hide actions to manage object visibility. Generally you should automatically show an object to the user on its initialisation, but by supporting the Show and Hide actions you can provide the developer with a little extra flexibility in this area after initialisation has taken place.
-Objects that contain multiple items can be sorted with this action. The sort will be in ascending order (A - Z or 0 - 9) unless the object is configured for a descending sort. The sort will be based on the default value elected for the items - this will typically be an ID value if available, or the name of each item.
-If you have called the
In supporting this action you will receive the number of milliseconds that have passed since the last Timer call. There are no restrictions on how you write your routine to respond to Timer notifications. The error code that you return will be ignored.
-You can terminate a timer subscription by calling the
The Undo action reverses the last data process performed by the object. Objects that support this action maintain an internal stack of all data 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.
-The Unlock action complements the
If you
This action serves as an accompanient to the Lock action. It is not compulsory to support Unlock if you have written a Lock routine, but it would be an unusual case if you were not to write a support routine for this action.
-What you do for your Unlock support is entirely up to you, so long as you do not allocate any resources in the routine.
-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
The Buttons 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 Surface object, the X and Y parameters 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
Most classes expect a UserClick action to be followed by a
If your class requires graphical user interaction, you need to support this action. You will normally receive UserClick actions from the Pointer class, but they can of course come from anywhere. After receiving a UserClick, you can typically expect to receive a UserClickRelease shortly thereafter.
-The coordinates supplied to your object are relative to the top left corner of the object. The purpose of the coordinates is to tell you where the user click occurred. If there is no exact coordinate, the coordinates will be driven to zero.
-The UserClickRelease action complements the
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 DeltaX, DeltaY and DeltaZ arguments specify the shift in position from the point where the original UserClick action was called.
-If you need to be informed when the user has clicked and then released a button on one of your objects, you must support UserClickRelease. This action is commonly supported for achieving drag and drop functionality. If the user is trying to drag an object somewhere, you can find out where that is by checking the OverObject argument. Note that the DeltaX, DeltaY and DeltaZ arguments specify the shift in position from the point where the original UserClick action was called.
-The UserClickRepeat action extends on the
You will need to check the position of the mouse pointer to calculate the X, Y and Z coordinates in relation to the target object, as well as determining the object that the pointer is positioned over. The Buttons parameter should reflect the button state of the pointing device at the time the call is made.
-The required repeat rate for calls made to UserClickRepeat is undefined. However we do recommend that a rate of 50 calls per second is used so that the timing matches regular display and animation frequencies.
-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:
-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 DeltaX, DeltaY and DeltaZ values must reflect the change in direction since the last time that the pointing device was moved.
-To detect the movement of the user when he/she moves a pointing device over your object, add support for this action. There are two cases for when you might be called by this action:
-You can tell what type of movement is occurring by checking the OverObject argument - if it is equal to your object, then movement is occurring within your object. If the OverObject is some other object pointer, the user has moved away from your object.
-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
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.
-The Write action was initially provided in order to support the writing of data to Files. Despite this intention, any class that supports a data storage area should support the Write action for managing raw data.
-The Buffer argument points directly to the area that contains the data that should be written to your object. The Length argument indicates the byte size of the Buffer. If the Length exceeds the total amount of space available for writing data, return an error code of ERR_LowCapacity.
-Your class should support a Position field in its structure to indicate the byte position from which the Write action will start writing data. After the Write operation, you must increment the Position field by the amount of bytes that were written to the object's data store. This will provide the developer more versatility when it comes to reading and writing data. You should also consider supporting the Seek action to manipulate the Position field.
-Before returning, your support routine must set the Result parameter to indicate the total amount of bytes that were written to the object.
-This guide provides you with the necessary information on how to write class and module documentation that is compatible with Parasol's internal standards. This applies to developer related materials only - there is no official standard for documenting technical information.
- -Although our technical manuals are distributed in XML format, all code written by Parasol is self-documented in a format that is referred to as "Section Based Formatting", or SBF. It is from these files that the XML is produced. The code that performs the necessary processing is found in the DocCompiler class. You can see real-world examples of SBF source files by viewing almost any of the existing source files in the Parasol Framework. To see how it works, try processing one of these files through the DocCompiler and observe the output.
- -Writing self-documenting source code as opposed to writing raw document files is helpful for a number of reasons, including:
- -Before you start writing documentation for your source code, it is recommended that you read the rest of this manual to ascertain the specifics of writing self-documenting source files.
- -When documenting areas that require formatting, you should limit the number of tags that you use. Under no circumstances should you attempt to embed code or custom styling in your documentation - in other words, keep it pure. For style, we reommend that you only use the i, b and pre tags. Custom links are not recommended as we provide helper tags for linking to functions, classes and methods for example.
- -Embedded pictures and diagrams are not currently supported in our technical manuals.
- -When writing developer documentation you should treat it as a technical whitepaper, meaning it must be presented in a professional manner that is easy to read. Flashy presentation, changes in fonts and pretty pictures only serve as a distraction rather than an aid, so keep it simple and consistent.
- -It is recommended that you write documentation for your code once your progress is 50% towards completion. Do not document your code from the beginning as you may need to re-write much of it at the end of your development cycle.
- -A benefit of Section Based Formatting is that it allows you to spread your documentation throughout the entire source file, rather than writing it as a long stream of text. If your source code is split across multiple source files then that's no problem either, as the compiler can read them all from the one directory if need be. Make sure that you take full advantage of this as it will make your life easier when making future updates to your code.
- -There are two different types of SBF source files - one style for modules and another style for classes. The type of documentation that you are writing is determined by the first 'mark', which must be either a Module or Class mark. This is followed by a set of definitions, all of which are optional but generally you will want to set the Name, Version, Date and Copyright information as a bare minimum. After that you can enter a description with the Description mark and add any important notes through the Note mark. In most cases you will then want to end the section with an End mark before documenting the functions and/or fields of the source code.
- -Let's look at this in more detail, starting with the header for a class document. In this example we have used all possible attributes for the class header and entered a description of the type of information you should enter for each attribute:
- -###CLASS###
-Name: The name of the class.
-Version: The version number of the class.
-ID: If the class has an ID then type it in here, otherwise enter 'Dynamic'.
-Category: The class should belong to a standard category - e.g. Command, GUI,
- Tool, IO or Effect. Available categories are listed in your
- system:modules/ directory.
-Include: If applicable, the include file for the class should be referred
- to here.
-Date: The month and year that this code was last updated must be entered
- here, e.g. 'February 2001'.
-Author: You or your company name should be entered here.
-Copyright: The copyright owner and the year of copyright must be specified here.
-Keywords: A comma-separated list of keywords can be listed in this attribute.
-Short: A short (80 character) description of what the class does can be
- entered here.You should immediately follow-up the class header with a description of the class. The compiler will analyse the description for paragraphs - a paragraph will be assumed when two line-breaks are discovered following each other. Your description may contain tags, which should be organised into paragraphs. If necessary you can add any extra notes through a Note header, after which you should end the class header with an End mark. Example:
- -###DESCRIPTION###
-The description of my class is entered here.
-
-###NOTES###
-If I need to alert the reader through any notes, I can do so through this
-mark.
-
-###END###If you are writing documentation for a module then the premise is much the same as that used for classes, but you will use a Module marker and slightly different attribute settings. This next example illustrates all of the available attributes for a module header:
- -###MODULE###
-Name: The name of the module.
-Version: The version number of the module.
-Date: The month and year that this code was last updated must be entered
- here, e.g. 'February 2001'.
-Author: You or your company name should be entered here.
-Copyright: The copyright owner and the year of copyright must be specified here.
-Classes: If the module includes one or more classes, enter a comma-separated
- list of all class names here.
-Keywords: A comma-separated list of keywords can be listed in this attribute.
-Short: A short (80 character) description of what the module does can be
- entered here.Following the module detail you should enter more information using the Description mark and follow with an End mark, in the same way as we did for the class header.
- -If you are developing a standard module interface then you may wish to export one or more public functions. The definition for a standard function header is as follows:
- -###FUNCTION###
-Name: The name of the function.
-Short: A short description of the function's purpose.
-Synopsis: A C/C++ compatible synopsis for the function must be specified
- here, e.g. LONG RandomNumber(LONG Number).The compiler can usually generate an accurate synopsis from the function definition in the module, so if you are using a standard synopsis then you will not need to declare it in the header.
- -After entering a description you will need to document the input parameters (if the function takes arguments) and the results of the function call. If the function was to take arguments named XCoord and YCoord for example, then the Input section would be as follows:
- -###INPUT###
-XCoord: Description for the XCoord argument.
-YCoord: Description for the YCoord argument.You have two options for documenting the results section depending on whether or not the function returns an error-code. If the function is not returning an error-code then you can describe the results in the same format as a description section. If error-codes are returned then each individual error-code used by the function should be documented using a definition list. Example:
- -###RESULT###
-ERR_Okay: Description for this code.
-ERR_AllocMemory: Description for this code.
-ERR_InvalidDimension: Description for this code.The function must be terminated with an ###END### mark.
- -If you are writing a class document then each field that forms part of the class structure must be documented. Fields are documented individually, starting with a Field header, then a Description, See Also mark and an End termination. Here is a descriptive analysis of the field header:
- -###FIELD###
-Name: The name of the field.
-Short: A short (80 character) description of the field's purpose.
-Prefix: If the field represents a lookup table or set of flags,
- there should be a prefix prior to each flag or lookup
- definition. Example: The prefix for FILE_READ is FILE.
-Type: If this is a custom field type, declare the type here.After following up the field header with a description, you have the option of adding a See Also mark. This mark is helpful for providing the reader with references to other documented areas that may be of relevance to the topic. Here is an example that refers to the XCoord and YCoord fields of the current class:
- -###SEE ALSO###
-Fields: XCoord, YCoordOther valid See Also references are Function, Method and Action. If you need to refer to the documentation of another class or module, specify the name of the class or module, followed by a dot and then the reference. E.g. "Function: FileSystem.MoveFile".
- -If you are writing a class that implements one or more methods, they must be documented so that the developer knows how to use them correctly. If necessary, you may also document any actions supported by the class if you need to add clarification as to how they are supported. The Action and Method marks both use Name and Short definitions, while methods also allow for a C synopsis if one exists as a macro. Example:
- -###METHOD###
-Name: The name of the method.
-Short: A short description of the method's purpose.
-Synopsis: Optional - define if a C macro has been created for the method.The header must be followed with a Description, then Input, Result and See Also marks. For clarification on how to write Input and Result information, refer to the Documenting Functions section of this document.
- -This is all the information that you need in order to write a valid self-documenting source file. If you need to know the specifics of how the
This event is triggered when a Task object starts a new process. Any processes created outside of the Parasol sandbox will not be captured by this event.
- - -The following structure is passed when this event is triggered:
-typedef struct { EVENTID EventID; OBJECTID TaskID; OBJECTID ProcessID; } evTaskCreated;The TaskID reflects the object ID of the task that created the process. The ProcessID is the identifier that has been assigned to the process by the host system.
- -When a process created by a
The following structure is passed when this event is triggered:
-typedef struct { EVENTID EventID; OBJECTID TaskID; OBJECTID ProcessID; } evTaskRemoved;
- The TaskID reflects the object ID of the task that was removed. The ProcessID is the identifier that has been assigned to the process by the host system.
-
- Failed to open XML data source.
-No further information is documented for this event.
-Failed to open XML data source.
-System events are messages that are broadcast to all programs when an event is triggered.
- -Events are typically managed by their relevant modules - for instance, filesystem events are managed by the FileSystem module and power management events are handled by the PowerSave module. However, there are no restrictions on who can send events for any given category and it is also possible for developers to create custom events for broadcasting from their own applications.
- -To subscribe to a system event, call the
The following list describes the standard system events that are provided by Parasol. For readability, events are described in their string format of 'group.subgroup.event'.
- -