New Statement

Makes an instance of an object and initializes it.

Syntax

[ @Shared ] _
[ New ] class_name object_name [ , argument_list ]
[ Begin [ default_type | Call [ method_name ] ]
    [ statements ]
End [ New | class_name ] ]

Parts

@Shared
Optional modifier – There can be only one instance for all classes or procedure calls.
New
At the start of the statement, the keyword is usually optional.
Mandatory if the statement is nested in a different statement of the same type.
Mandatory if the module contains the directive @Option New.
class_name
Mandatory name of a class.
object_name
Mandatory name for the object.
argument_list
Optional – One or more expressions with a comma between each.
Begin
Optional keyword that starts the block construct.
default_type
Optional data type that the compiler will use for the subsequent statements, if the data type is not specified. The data type must be related to the type specified in a constructor of class_name.
method_name
Optional name of the method of class_name to call for each argument list in statements. It must come after the keyword Call. If you supply Call without method_name, the default is Add.
statements
Mandatory in the block construct, one or more object-creation statements. See the sections “Permitted members” for more information.
End
Completes the block construct. You can also use one of End New or End class_name. And you can make one of these mandatory with the directive @Option.

Instructions

The statement New has many of the same functions as Dim (or Var), but there are important differences. Dim can declare and initialize many scalar variables and arrays of value types and reference types.

How New is different:

Passing an array argument

You can use the block construct when a constructor for a class has an object-array parameter. Each object-creation statement between Begin and End puts a reference to that object into the array.

Permitted members

The array-passing construct lets you use four (4) different statements:

New members

The statement block of New can contain other such statements. You can nest them to a large depth. But, we recommend that you keep the number of levels to a minimum.

The keyword New is optional in the first line of the statement. But, New is mandatory for some statements in the block construct.

It is mandatory if: (1) the statement also uses the block construct, or (2) it has a different data type from default_type.

Argument-list members

It is not necessary to write the keyword New and class_name again and again. If the statement block has many objects with the same data type, you can supply only the argument list. You can write the arguments between parentheses ((…)) or without them. This manual always writes them without parentheses.

You can use a child class of the declared data type for most or all of the statements. You write the class name after the keyword Begin. For all other statements with a different data type, you must use the full statement with New and the data type.

Some objects use #Null for special effects. For example, the class menu uses it to show a separator. ViviFire lets you use a vertical bar (|) as an alternative to #Null when passed as an argument. you can also write one or more hyphens after this symbol to help it show better. There is no limit on the number of hyphens, but this manual usually uses 4 hyphens (|----).

Object members

The statement Object makes an instance of a child class. If you do not supply a parent class for the object, the default is the type of the array argument (or default_type, if given). But if you do supply the parent, it must be a child of the default class.

Procedure-call members

Procedure calls in the block construct can only be methods and properties of the class class_name. They must start with a dot (.) before the procedure name.

Initializing a collection

This block construct looks almost the same as the usual block construct. The first difference is the line that starts with Begin call. After these keywords, you can optionally write the name of a method. The method must be one supplied by the type class_name. If you do not give a method, the Default name is Add.

Permitted members

With the collection-initializer construct, the only permitted member is the argument list. If you want, you can write two or more argument lists on one line. You put a semicolon (;) between each argument list. A semicolon at the end of a line is also permitted.

Changes in syntax with @Option

There are two areas where you can change the syntax of the statement:

See @Option Directive for more information.

Examples

One-line constructs

' Find all text files in the current directory.
Files txtFiles, "*.txt"

For Each file In txtFiles
    PrintLine file.Name
End For

One-line construct compared to the block construct

First we make a menu with a one-line statement. It shows “File” on the menu bar. In the related popup menu, it shows two commands: “Open…” and “Exit”. There is also a separator between these two items. If you select one of the commands, it calls the related procedure.

' Make a menu.
Menu FileMenu, "&File", "&Open...", DoOpen, |, "E&xit", DoExit

Then we write the example again as a block construct.

New Menu FileMenu, "&File"
Begin
    "&Open...", DoOpen
    |----
    "E&xit", DoExit
End New

In the next example, we add a sub-menu to the menu with the text “New”. The sub-menu has two commands: “File” and “Folder”. We cannot add a sub-menu to the one-line construct. But the block construct does not have this limit.

Menu FileMenu, "&File"
Begin
    New menu newMenu, "&New"
    Begin
        "&File", DoNewFile
        "Fol&der", DoNewFolder
    End Menu
    "&Open...", DoOpen
    |----
    "E&xit", DoExit
End Menu

Collection-initializer construct

In this example, we declare a list of strings and add some items. The class List has a method (Add) to add one item at a time. Although we give it here, this name is not necessary because Add is the default. We supply the items in some argument lists, one for each call.

List[String] fruits
Begin Call Add
    "apple"; "banana"; "cherry";
    "peach"; "pear"; "pineapple";
End

See also