DEFINE

Topic group

Creates an object from a class.

Syntax

DEFINE <class name> <object name>
[OF <container object>]
[FROM <row, col> TO <row, col> > | <AT <row, col>]
[PROPERTY <stock property list>]
[CUSTOM <custom property list>]

<class name>

The class of the object to create.

<object name>

The identifier for the object you create. <object name> will become an object reference variable, or a named property of the container if a <containter object> is specified.

OF <container object>

Identifies the object that contains the object you define.

FROM <row>, <col> TO <row>, <col> | AT <row>, <col>

Specifies the initial location and size of the object within its container. FROM and TO specify the upper left and lower right coordinates of the object, respectively. AT specifies the position of the upper left corner.

PROPERTY <stock property list>

Specifies values you assign to the built-in properties of the object.

CUSTOM <custom property list>

Specifies new properties you create for the object and the values you assign to them.

Description

Use DEFINE to create an object in memory. DEFINE provides an alternate, shorthand syntax for creating objects that directly maps to using the NEW operator. The equivalence depends on whether the object created with DEFINE is created inside a container object. With no container,

define <class name> <object name>

is equivalent to:

<object name> = new <class name>( )

With a container,

define <class name> <object name> of <container object>

is equivalent to:

new <class name>( <container object>, "<object name>" )

where <object name> becomes an all-uppercase string containing the specified name. These two parameters, the container object reference and the object name, are the two properties expected by the class constructors for all stock control classes such as PushButton and Entryfield. For example, these two sets of statements are functionally identical (and you can use the first statement in one set with the second statement of the other set):

define Form myForm

define PushButton cancelButton of myForm

myForm = new Form( )

new PushButton( myForm, "CANCELBUTTON" )

The FROM or AT clause of the DEFINE command provide a way to specify the top and left properties of an object, and the TO coordinates are used to calculate the object’s height and width.

The PROPERTY clause allows assignment to existing properties only. Attempting to assign a value to a non-existent property generates an error at runtime. This will catch spelling errors in property names, when you want to assign to an existing property; it prevents the creation of a new property with the misspelled name. Using the assignment-only (:=) operator has the same effect when assigning directly to a property in a separate assignment statement. In contrast, the CUSTOM clause will create the named property if it doesn’t already exist.

While the DEFINE syntax offers some amenities, it is not as flexible as using the NEW operator and a WITH block. In particular, with DEFINE you cannot pass any parameters to the class constructor other than the two properties used for control containership, and you cannot assign values to the elements of properties that are arrays.