Class Documentation

Name:Create
Version:1.0
ID:ID_CREATE
Status:Stable
Category:Command
Date:February 2002
Author:Rocklyte Systems
Copyright:  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:

FlagDescription
NF_NOTRACKAn 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_PUBLICBy 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_SHAREDUse 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.