`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 ] ]
      argument_list
      …
  End [ New | class_name ] ]

Parts

@Shared: Optional modifier – There can be only one instance for all classes or procedure calls.
New: Optional keyword.; 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: One or more expressions with a comma between each.; Optional on the initial line.; Mandatory between Begin and Eng. You can write each one on a different line. Alternatively, you can write many on one line with a semicolon (;) between each.
Begin: Keyword that starts the block construct.
default_type: Optional data type that the compiler will use for the subsequent argument lists, if the data type is not specified.
method_name: Optional name of the method of class_name to call for each argument list. It must come after the keyword Call. If you supply Call without method_name, the default is “Add”.
End: Completes the block construct. You can also use (1) End New or (2) 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:

It can declare and initialize only one variable of a reference type.
If the variable can be null, 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

TODO

You can write the arguments between parentheses (( )) or without them. This manual always writes them without parentheses.

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.

Passing an array argument

You can use the block construct when a constructor for a class has an object-array parameter. Each argument list between Begin and End makes a new object. These objects go into the array in the sequence given.

An argument list does not let you give the reference a name. If you must give an object a name, use Dim, New, or Object, then subsequently pass it as an argument.

If necessary, you can use a child class of the data type of the parameter. You write the class name after the keyword Begin. To use a different child class, you must start the argument list with the name of the class between brackets ([ ]) and a comma.

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 (|----).

Initializing a collection

This block construct looks almost the same as the usual block construct. One 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”.

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”. 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",
    Begin
        "&File", DoNewFile
        "Fol&der", DoNewFolder
    End
    "&Open...", DoOpen
    |----
    "E&xit", DoExit
End

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

New Statement