Development Team Blog

Have you ever wanted to write your own wizard and add it to the Studio's Create New dialog?

Adding a wizard application to the Create New dialog is managed by the "Configure Create New" option in the "Tools" menu. That is the easy part, But how can your wizard access the important information about your workspace that it needs in order to do anything useful? Come to think of it, how do the "standard wizards" get the Studio to open the files that they just created once they are done?

In this article I will explain the mechanism the Studio uses to pass information to, and retrieve information from, any wizard launched from the Create New dialog.

Disclaimer: The information presented here describes implementation details that are undocumented and are internal to the Studio. Feel free to use this information as you require but at your own risk. Data Access does not pretend to support these techniques and reserves the right to change the way this works at their discretion.

This information is valid for Visual DataFlex versions 14.1 - 15.1. Some of the information presented here is not applicable prior to VDF 14.1, I will try to point out these cases.

Temporary Config Files and the Command Line

Before the Studio launches a Create New wizard, it generates a config file in your system's user temp folder. The filename is random and is determined by the Windows operating system, however the Studio passes the name of this file to your wizard via the command line. For example...

Code:

c:\wizards\MyWizard.exe T=C:\Users\John-h\AppData\Local\Temp\DF150D.tmp

where:

c:\wizards\MyWizard.exe - is the path and filename of the wizard being launched.
'T' - is the command-line switch which indicates that the name of a temporary config file follows.

The Studio passes this parameter to the launched wizard automatically. You do not need to add anything in the
"Configure Create New" dialog to make this happen.

The following example demonstrates how you can get the name of the config file that is passed to your Wizard application.

Code:

Object oApplication is a cApplication
    Set pbPreserveEnvironment to True
    Set peHelpType to htHtmlHelp
    
    Property String psConfigfile ""

    Procedure OnCreate
        String sArg sSwitch
        Handle hoCommandLine
        Integer icArg

        Forward Send OnCreate
        
        // Read the Config Filename....
        Get phoCommandLine to hoCommandLine
        Get CountOfArgs of hoCommandLine to icArg

        If (icArg > 0) Begin
            Get Argument of hoCommandLine 1 to sArg        // reads the first commandline parameter

            // Test for "T="
            Move (Uppercase(Left(sArg,2))) to sSwitch

            If (sSwitch = "T=") Begin
                Set psConfigfile to (Remove(sArg, 0, 2))
            End
        End
    End_Procedure
End_Object

Here the cApplication object's OnCreate event is used to access the command line via its built-in command line handler object.

Config File Structure

The config file is generated as a standard Windows INI file. Briefly this is a text file containing a series of Name=Value pairs (called parameters). The parameters are grouped into named 'sections'. Section names must be unique and appear inside square braces. The section name precedes the set of parameters which belong to it.

Below is a snippet from a config file sent by the Studio to a Create New wizard...

Code:

[Workspace]
Name=C:\Visual DataFlex 15.1 Examples\Order Entry\Order Entry.sws
CurrentProject=Order.src
[DDClassList]
File=C:\Users\John-h\AppData\Local\Temp\DF4703.tmp

The important sections in this config file are:

[Workspace]

This section contains two name/value pairs:

1) the path and filename of the current workspace's .sws file. e.g.

Name=C:\Visual DataFlex 15.1 Examples\Order Entry\Order Entry.sws

This file is another config file which can be opened by your wizard and used to read more information about the workspace.

2) The name of the current project you are working on in this workspace. e.g.

CurrentProject=Order.src

This tells you which project the Wizard is modifying.

[DDClassList]

This section contains a reference to another temporary file that is created before running the wizard and destroyed after the wizard is completed. It is a reference to an .xml file which contains a list of each data dictionary class name, table number and filename. e.g.

File=C:\Users\John-h\AppData\Local\Temp\DFE620.tmp

This is the same set of classes that you see in the data dictionary branches of the Studio's Table Explorer panel. This information can be used by your wizard to determine the name of the data dictionary class to use when generating a data dictionary object for a particular table.

Class Preferences

Following the [ddClassList] section is a series of sections providing information about a predetermined set of UI classes. The section names correspond to the generic names of each predetermined UI class. below is an example of one of these class sections.

Code:

[dbForm]
Class=dbForm
File=DFEntry.pkg

This example is for the generic dbForm class. The first name/value pair says that the default class name to use is also called dbForm (Class=dbForm). The second name/value pair says that the filename where the dbForm class is located is DFEntry.pkg.

This is the same information that is presented in the "Configure Workspace Properties" dialog's "Class Preferences" tab (see Tools Menu, Configure Workspaces). Whenever you change the default classname for a class in this dialog, then the changed information will be passed to the wizard.

Wizards can use this information to determine which class to use for a particular type of UI object that it is generating. This is how our wizards support subclassing, where each workspace can have a different subclass of a particular control.

[ClassFiles]

The final section in the config file is the [ClassFiles] section. This is basically a list of all the classes in your workspace's Class Palette and the filename where that class is declared. e.g.

Code:

[ClassFiles]
BitmapContainer=dfBitmap.pkg
Button=Windows.pkg
etc.

This information can be used to generate the correct Use statement for any class that is instanciated by your wizard.

Passing Instructions Back to the Studio

Once your wizard has finished, it should write some information back into the config file. This information will be processed by the Studio and instructs the Studio what to do with the results of the wizard.

The full set of information which can be passed back is fairly invloved and can instruct the Studio to perform some sophisticated tasks. We will look at this in detail in a future blog article. In this overview we will just look at the first section that is processed by the Studio.

[ReturnValues]

This section contains a single name/value pair which tells the Studio whether or not the Wizard was cancelled.

WasCancelled=True or False

If WasCancelled is True, then the Studio stops processing the config file and does nothing more. The Create New dialog remains open waiting for the user to make another selection.

If WasCancelled is False, then the Studio closes the Create New dialog and continues processing the config file.

Conclusion

This article was an introductory overview to the information passing mechanizim between the Studio and external Create New wizard applications.

In Part two we will take a look at how to get more information about your workspace and workspace paths.

In part three we will look at the DDClassList .xml file and see how this can be used to choose a data dictionary class for any table.

In part four we will take a closer look at the rest of the information that is passed back and processed by the Studio.