Getting Started

A Wizard is a module that runs in its own window. The recommended way of structuring the Wizard module is to have an outer module with two states, with all the necessary initialization done on the transition between these, and a child module containing the Wizard code, which is launched as the final step. For these notes, the use of this model is assumed. The term "Parent" refers to the outer module, and "Wizard" refers to the Wizard code module.

Parent Module, parameters and variables:

If you intend to pass parameters to the Wizard, do so as you would for any module:

{  Receive any required parameters from the calling environment ...  }
(
  Param1;
  Param2;  { etc as required. }
)

  Constant LHS     = 8    { LHS of the message panel                       };
  Constant TOP     = 60   { Top of the message panel                       };
  Protected BOT           { Y coord of horiz line above buttons            };
  Protected RHS           { RHS of the drawing panel                       };
  Protected MID           { Centre of drawing panel                        };
  Protected Split         { Horizontal division of drawing panel           };
  Root                    { Object value of Wizard - useful for tag config  };

Window Parameters

If running the Wizard in its own window, the recommended window parameters are:

  Width  = 520;
  Height = 360;
  Style  = 0b1010010100000111;

Note that the height of the top and bottom bars of the window are fixed at 30 and 40 pixels respectively.

Alternatively, you can run a Wizard within a Display Manager page. To do this, the following attributes should be defined in the page's source file:

Constant PageWidth  = 520;
Constant PageHeight = 360;
Constant WinFlag    = 1;
Constant PageStyle  = 0;
Constant PagWinOpt  = 0b1010010100000111;
Constant NoStretch  = 1;
Constant Bitmap;
Constant Color      = -17 { Background color for page - #SYSCOLOR_BUTTONFACE };
SecBit                    { Set page security as required                    };
WindowCloseFlag     = 1   { Flag tells DispMgr not to close our window       };

Tag Configuration

In general, if the Wizard is being used to perform Tag configuration then the simplest way to do this is to start the Wizard with a Parms array parameter of the correct size for the Tag type and to fill in the Parms array as you proceed. It is usually possible to call a Tag's ConfigFolder since (with Root pointing to Self and the Parms array provided) the calling environment is correct. If it is required to configure multiple Tags, then create multiple parameter arrays and swap them in and out of "Parms" as needed.

{== Sample variables for tag configuration ===============================}
{ Parameter indices - these are standard, add others as required          }
  Constant #Name        = 0;
  Constant #Area        = 1;
  Constant #Description = 2;
  #IODevice;
  Protected TmpCfg;
  Parms;
{============== End parent module variable declarations ==================}
]

Parent Module Initialization

The Parent performs the initialization of resources required by the Wizard. It is also likely that in its main state, it has to monitor a Cancel flag and to tear down the structure if the flag is set.

If running as a Display Manager page, the Init state should launch the Wizard child module before running the main state, which will watch for a Cancel from the user. If running as a Window, the main state should call the Window function, passing the Wizard child module as a parameter.

The example wizard (C:\VTScada\Examples\Wizard.SRC) shows how to write code that can be used either way. The following assumes the Wizard will run in a Display Manager page.

WizardInit [
  If 1 WizardMain;
  [
    { Setup instance }
    SetInstanceName(Self, \SecurityManager\GetAccountID());
    { Setup some basic metrics }
    RHS = PageWidth - 8;
    BOT = PageHeight - 40;
    MID = Int(PageWidth / 2);
    Split = MID + 40;

If you are going to be configuring Tags, then you will likely need a parms array and various offsets into that array. You can establish these dynamically as follows...

    { Get a module/object handle to the required tag type, where "SampleTag" 
      is to be replaced by the module name of the type you require.         }
    TmpCfg    = Scope(\Code, "SampleTag");

    { Get its parameter indices }
    #IODevice = GetDefaultValue(FindVariable("#IODevice", TmpCfg, 0, 0));
    { ... etc. }
    Parms     = New(FormalParms(TmpCFG));

Or, alternatively:

    #IODevice = GetDefaultValue(FindVariable("#IODevice", Variable("SampleTag"), 0, 0));
    { ... etc. }
    Parms     = New(FormalParms(Variable("SampleTag")));

Finally, launch the wizard:

    { Running as a DisplayManager page - launch a Wizard }
    Wizard(Parms);
  ]
]    {===== End WizardInit ======}

Parent Module Main State

WizardMain [
  { Running as a DisplayManager page }
  If Cancel;
  [
    \DisplayManager\StopPage(Self);
  ]
]

 VTScada includes a wizard template that has been provided to assist programmers in creating their own wizards. This template is installed with the VTScada software, and can be found in the Example folder within the VTScada installation directory: C:\VTScada\Examples\Wizard.SRC.
You can import this module as a page in the Idea Studio (File menu >> Import). Make sure that you add the page to the menu, then close the Idea Studio and open the wizard page. The sample wizard will open in a pop-up, demonstrating several features that you can use in your own wizards. (Wizard pages are generally not added to the menu, but rather are opened explicitly, when required.)