`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 ] [ initializer ] ]
    [ statements ]
End [ New | class_name ] ]

Parts

@Shared: Optional – There can be only one instance for all classes or procedure calls.
New: Usually optional keyword.; Mandatory if the statement is a nested member of 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 initializer or statement. It must come after the keyword Call. If you supply Call without method_name, the default is Add.
initializer: Optional on the same line after method_name. It must be a list of values with a comma between each, all between braces ({ }).
statements: Mandatory in the block construct and if there is no initializer, one or more object-creation statements. See the section “Permitted members” for more information.
End: Completes the block construct. You can also use one of End New or End class_name.

Instructions

The statement New has many of the same functions as the statement Dim, 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:

It can declare and initialize only one variable of a reference type.
If the variable is nullable, it is always given a value.
If a constructor of the given type has an array parameter, you can declare elements with the block construct.
If you must enter data into the variable with many calls to the same method, there is a construct for that.

block construct

Usually you 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

New
Argument list
Object
Procedure call

`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. Because of how frequently this occurrs, ViviFire has a special symbol equivalent to #Null. You can use a vertical bar (|) with optional hyphens (-) after it as an argument. There is no limit on the number of hyphens, but this manual usually uses 4 hyphens (|----).

`Object` members

A statement of the type 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.

Changes in syntax with @Option

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

@Option New
@Option End Block and @Option End

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&rdquo. Between these two items we write a vertical bar, which shows as a separator. This symbol is an alternative to #Null that you can use only in argument lists. 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 re-write the example as a block construct. It starts the same as before, until we get to the first command. Before the commands, we must write the keyword Begin on one line. Then we write each item on separate lines. The vertical bar can have hyphens after it without limits. Then we write End New to complete the statement.

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

Call 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. We write Add after Begin Call to give the method to call for each item in an array. (Although we give it here, this name is not necessary because Add is the default.) We supply the items in an array initializer. The initializer must be on the same line that starts with Begin. We can use the automatic line continuation of braces and commas to make the code easier to read.

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

New Statement