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.