## The `New' method

Argument: See text
Result: None

Valid for: Any class of object except the System object

### Using the `New` method with dot notation

The `New` method is used to create new objects which are children of existing objects. It is thus special in that it can be invoked on an object which does not yet exist. The basic syntax is:

                 ParentRef.ObjectName.New ClassName

where ObjectName is the name of the object you want to create, and ClassName is the class of object you want to create, as a character vector. The name of the object must not already be in use for another object, and the class must be one of the standard APLX object class names, such as 'Button' or 'Edit'. Objects are created initially with all properties having the default values for the class of object.

For example, the following sequence creates a window containing an 'OK' button:

         W„'Ś' ŚNEW 'Window'
         W.size„8 12 Ş W.title„'Demo'
         W.But.New 'Button'
         W.But.where„5 9 Ş W.But.title„'OK'

Once the object has been created, and any properties specified have been set, the object is usually automatically opened, except in the case of the Printer and APL (child task) classes where you need to call the `Open` method explicitly. In addition, visual objects are automatically displayed (unless you have set the `visible` property to 0), except for the pre-defined dialog classes (ChooseFont, ChooseColor, ChooseDir, OpenFile, SaveFile and MsgBox) where the dialog does not appear until you call the `Show` method. However, for a window object (Window, Form, Document or Dialog), the window is not actually opened until the first of the following occurs:

° APL desk-calculator mode is reached

° Your program checks for events using ŚWE.

° Your program creates another top-level object using the `New` method.

° Your program invokes the `Open` or `Show` method for the window.

The reason for deferring the actual display of a window in this way is so that your program can build up the objects in the window after creating it, without the user seeing objects being created, moved, resized etc as the objects are defined.

### Using the `New` method with ŚWI

Using ŚWI syntax, the `New` method can be used to create either top-level or child objects. It can also can optionally set one or more properties for the newly-created object, by following the Class name with a list of Property-Value pairs. The following sequence is equivalent to the dot-notation example above; it creates a window containing an 'OK' button:

         'Win' ŚWI 'New' 'Window'
         'Win' ŚWI 'size' 8 12
         'Win' ŚWI 'title' 'Demo'
         'Win.But' ŚWI 'New' 'Button'
         'Win.But' ŚWI 'where' 5 9
         'Win.But' ŚWI 'title' 'OK'

You could achieve the same result as follows:

         'Win' ŚWI 'New' 'Window' ('size' 8 12) ('title' 'Demo')
         'Win.But' ŚWI 'New' 'Button' ('where' 5 9) ('title' 'OK')

If an object of the same name already exists when you try to use the `New` method, a `DOMAIN ERROR` will be generated. As an alternative, you can use the `Create` method, which is identical except that any object of the same name is automatically deleted before the new object is created.

Topic: APLX Help : System Classes : Methods : New

[ Previous | Next | Contents | Index ]