Class Documentation
Create |
1.0 |
ID_CREATE |
Stable |
Command |
February 2002 |
Rocklyte Systems |
Rocklyte Systems (c) 2001-2002. All rights reserved. |
Description
The Create class provides a means to dynamically create new objects during
script processing. It is also used in graphical interfaces that require
objects to be created when certain user events occur.
To create a new object with this class, you need to know the name of the
Class that will be used in the creation process. You may
set a Target container for newly created objects, along
with optional Flags that affect the creation process.
Any fields that you want to set in the new object can be defined through the
unlisted fields mechanism.
The following example illustrates how to create a new Picture object:
<create class="picture" name="mypicture" &location="athene:pictures/screenshot.png"/>
If necessary, a Create object can be defined as static for situations
where you need to create a new object during run-time operations. You
can also use the Activate option to automatically activate a new object
when it is created. For example:
<create static activate class="script" &src="$[text.input]$"/>
Actions
The Create class supports the following actions:
Activate | Activates a Create object. |
ClosingTag | If the object is non-static, this action will cause the Create object to activate and then self-destruct. |
Structure
The Create object consists of the following public fields:
Activate | Set to TRUE if created objects should be automatically activated. |
Class | Set this field to the name or ID of the class that the new object will be created from. |
Execute | Set to TRUE if created objects should be automatically killed. |
Flags | This field contains optional flags that affect object creation. |
Object | Reflects the ID of the last object that was created. |
ObjectName | This field determines the name that is given to newly created objects. |
Static | Set to TRUE to make a Create object static. |
Target | Defines the target container that new objects will be intialised to. |
Field: | Activate |
Short: | Set to TRUE if created objects should be automatically activated. |
Type: | LONG |
Status: | Read/Write |
If you set the Activate field to TRUE, newly created objects will be
activated using the Activate action. This behaviour is useful if you are
creating a new object for execution purposes.
|
|
Field: | Class |
Short: | Set this field to the name or ID of the class that the new object will be created from. |
Type: | STRING/LONG |
Status: | Get/Set |
You will need to set this field so that it refers to the class that will
be used when creating a new object. If the Class field is not set or is
invalid, the Create object will fail when activated.
This field can be set with an integer that reflects a class ID, or a string
that reflects the name of a registered class.
|
|
Field: | Execute |
Short: | Set to TRUE if created objects should be automatically killed. |
Type: | LONG |
Status: | Read/Write |
If you set the Execute field to TRUE, newly created objects will be
activated using the Activate action, then they will be immediately freed
from the system. This behaviour is useful if you do not require an object's
services after creating it.
|
|
Field: | Flags |
Short: | This field contains optional flags that affect object creation. |
Type: | LONG |
Status: | Read/Write |
You can specify a number of optional flags in this field that affect
object creation. These flags are identical to those listed in the object
kernel's NewObject() function. The
currently supported flags are:
NF_NOTRACK | An object created with this flag will not be tracked back to the object that created it. If combined with the NF_PUBLIC flag, the object can also remain in memory when the object's related Task is terminated. |
NF_PUBLIC | By using the NF_PUBLIC flag, you can allocate public objects rather than the default private type. A public object can be accessed and interacted with by any application directly, because the object structure and its data lies in public memory. |
NF_SHARED | Use this flag if you want to provide foreign tasks with a means of finding and talking to the created object. If you have already specified the NF_PUBLIC field, it is not necessary to use the NF_SHARED flag, as all public objects have shared attributes. |
|
|
Field: | Object |
Short: | Reflects the ID of the last object that was created. |
Type: | OBJECTID |
Status: | Read |
After you have created a new object through the Activate action, you can
read the Object field to find out the new object's ID. If you intend to
create more than one new object, you may want to store the values set in
this field as they will be over-written each time a new object is created.
|
|
Field: | ObjectName |
Short: | This field determines the name that is given to newly created objects. |
Type: | STRING |
Status: | Get/Set |
If you want an object to be given a name at the moment of creation, set
this field to the name that it should be given. Please note that there is a
limitation on the amount of characters available for naming; we recommend
that you do not exceed 25 characters in the name string. Extraneous
characters will be cut short.
|
|
Field: | Static |
Short: | Set to TRUE to make a Create object static. |
Type: | BOOLEAN |
Status: | Read/Init |
To make a Create object static, set this field to TRUE. If the Static
field is not set, then the object will self-destruct when a closing tag is
received.
|
|
Field: | Target |
Short: | Defines the target container that new objects will be intialised to. |
Type: | OBJECTID |
Status: | Read/Write |
It is highly recommended that you specify a target container before
creating new objects. The object that you refer to in the Target field
will determine who owns a newly created object. This will affect resource
tracking, so when the target object dies, the created object will die with
it.
If you do not set the Target field, new objects will be contained by
the container of the Create object. This may or may not cause problems for
you, which is why we recommend setting the Target yourself.
|
|