Builders and Wizards (and Bears, Oh My!)

"Visual FoxPro ships with several wizards. Wizards are interactive programs that help you quickly accomplish common tasks such as creating forms, formatting reports, setting up queries, importing and upsizing data, graphing, creating mail merge output, generating pivot tables, creating crosstab reports, and publishing in HTML format for the Web.

"By answering questions or choosing options on the series of wizard screens, you are telling the wizard to build a file or perform a task based on your responses."

—VFP Help, under "Wizards, overview"

"Builders are tools that aid in setting properties of controls on a form. Unlike wizards, builders are reentrant, so you can reopen a builder on a particular control repeatedly.

"Visual FoxPro includes a number of generic builders for many of the common form controls including grids, list boxes, combo boxes, check boxes, command groups, and option groups."

—VFP Help, under "Builders, introduction"

• A builder is any mechanism used to construct software.
• A wizard is a builder that starts a construction task.

Builders

How Builders are Engineered in VFP

The _BUILDER System Memory Variable

The Builder.APP Builder Manager Program

Invoking Builders

• Builder Lock on the Form Controls toolbar
• On the Forms page of the Options dialog, check the Builder Lock check box
• The "Builder" option on the Form and Class Designer context menus

• Manual invocation from the Command Window.
• From our own custom toolbars—equivalent to manual invocation, only easier.
• By drag and drop to _SCREEN from the Class Browser or the Component Gallery.

The Builder.DBF Registry Table

Registering Builders

1.      Use the Form Wizard to create a form to converse with Builder.DBF. Register this form as a builder. You'll need a wrapper program for this because Builder.APP can't call an SCX directly. Here is the wrapper:

* BLDRUTIL.PRG
PARAMETERS X, Y, Z
DO FORM BUILDER.SCX

2.      Create the following record in Builder.DBF:

LPARAMETERS uP1, uP2, uP3, uP4, uP5, uP6, ;
            uP7, uP8, uP9, uP10, uP11, uP12
* Accept parameters passed by the builder system.
 
#DEFINE ccMAIN "MYGREATBUILDER"  && This is what you've named the
                                 && builder PRG.
 
LOCAL nOldSelect
 
* Self-register if called directly.
IF PROGRAM(0) == ccMAIN
    nOldSelect = SELECT()
    SELECT 0
    USE HOME() + "Wizards\Builder" AGAIN
    LOCATE FOR Name = "My Great Builder"
    IF NOT FOUND()
        m.Name = "My Great Builder"
        m.Descript = "<describe My Great Builder>"
        m.Type = "ALL"
        m.Program = SYS(16)
        INSERT INTO Builder FROM MEMVAR
    ENDIF
    
    USE IN Builder
    SELECT (nOldSelect)
ENDIF
 
* Run the actual builder.
DO FORM ADDBS(JUSTPATH(SYS(16))) + "MyGreatBuilder" WITH ;
   uP1, uP2, uP3, uP4, uP5, uP6, ;
   uP7, uP8, uP9, uP10, uP11, uP12
 
RETURN

"Builder" Custom Property

Native Builders

How Builder.APP Handles Multiple Selections

Parameters Passed to _BUILDER by VFP

Parameters Passed to Builders by Builder.APP

Problems with Builder.APP

What Custom Builders Can Do

Builders Can Set Properties

Builders Can Add Objects

*-- You can execute this builder from the 
*-- command window without touching _BUILDER
*-- or BUILDER.DBF.
*-- Start a Form Designer session.
MODI FORM Junk NOWAIT
 
*-- Find the parent container, in this case the form.
=ASELOBJ( laObjectArray, 1)
 
*-- Add a label named lblHello.
laObjectArray[1].AddObject( "lblHello", "Label")
 
*-- Add a command button named cmdQuit.
laObjectArray[1].AddObject( "cmdQuit", "Commandbutton")
 
*-- Set some properties. 
WITH laObjectArray[1].lblHello
  .Caption= "Hello"
  .Top= 10
ENDWITH
WITH laObjectArray[1].cmdQuit
  .Caption= "Quit"
  .Top= 100
ENDWITH

Builders Can Load Array Members

Builders Can Add Custom Members

*-- Open the New Method dialog.
KEYBOARD "{f10}cm"
*-- Input the new method name.
KEYBOARD "FooFoo3"
*-- Navigate to, and fill, the description field.
KEYBOARD( "{Tab}{Tab}FooFoo description")
*-- Hit the Add button.
KEYBOARD( "{Tab}{enter}")
*-- Navigate to, and select, the Close button.
KEYBOARD( "{Tab}{Tab}{Tab}{Tab}{Enter}")

Builders Can Manipulate the Data Environment

 
*-- Start the Form Designer. This will do.
MODIFY FORM JUNK NOWAIT
*-- Store the DataEnvironment reference in MyArray[1].
=ASELOBJ( MyArray, 2)
? MyArray[1].Baseclass     && "Dataenvironment"

Builders Can "Drill Down" to Members Inside Container Classes

1.      Find the parent container (if required).

2.      Process the container (if required).

3.      Process every object in the container.

4.      Repeat steps 2 and 3 as required.

**********************************************************
* Colormix.PRG
* Demonstrates a drill-down builder.
*
* Danger: This will randomly change colors in 
*         the Form Designer.
*
* Also an example of using recursion in builders.
*
*
PARAMETERS oSource, cOther
  LOCAL i
  LOCAL ARRAY laSelObj[1]
 
  * /////////////////////////////////////////////
  * Your recurring builder code goes here in this block.
  *-- If there's a Forecolor property, change it randomly.
  IF TYPE("oSource.ForeColor") <> "U"
    oSource.ForeColor= RAND() * 256^3-1
  ENDIF
  *-- If there's a Backcolor property...
  IF TYPE("oSource.BackColor") <> "U"
    oSource.BackColor= RAND() * 256^3-1
  ENDIF
  * End of your code
  * \\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\\
 
  * Are we in a container and, more to the point,
  * are there any objects inside?
  IF ( AMEMBERS( laSelObj, oSource, 2) > 0)
    FOR EACH oObject in oSource
      
      *-- Recursion hook.
      =colormix( oObject )
    ENDFOR
  ENDIF
RETURN

Referential Integrity (RI) Builder ... and Future Wrappers

When multiple copies of a function are found in the same FoxPro source file, the last one gets executed. This means that you can append code to the RI code in the Stored Procedures, and your versions of duplicated functions will execute.

Query Property Expressions with ReadExpression

CREATE FORM SYS(3) NOWAIT
=ASELOBJ( aForm, 1)
oForm=aForm[1]
 
oForm.Caption= "Form Title"
? oForm.Caption                  && "Form Title"
? oForm.ReadExpression("Caption")&& "" -- Take Note!
 
oForm.Caption= CDOW(DATE())
? oForm.Caption                  && "Monday"
? oForm.ReadExpression("Caption")&& "" -- Take Note!
 
oForm.WriteExpression("Caption", "=CDOW( DATE())")
? oForm.Caption                  && "Monday" -- Take Note!
? oForm.ReadExpression("Caption")&& "=CDOW( DATE()+1)" ;
  + CHR(0)

oForm[1].Caption= CDOW(DATE())

Read Method Code with ReadMethod

Reset Events and Methods to Default

Save a VCX-based Form or FormSet with SaveAs

Create New Classes with SaveAsClass

*-- Create a VCX-Based form class called MyForm
Foo= CREATEOBJECT("Form")
Foo.SaveAsClass("MyClasses","MyForm") 
*-- MyForm is now VCX-based.
 
SET CLASSLIB TO MyClasses
*-- A code grandchild of MyForm
Foo= CREATEOBJECT("MyExpandDialogForm")  
 
*-- Create a VCX of the grandchild.
Foo.SaveAsClass("MyClasses","MyExpandedDialogForm") 
 
 
*-- SUPPORTING CLASSES
*-- Code transformation, creating a code class 
*-- from MyForm VCX class.
DEFINE CLASS MyDialogForm as MyForm 
  Width    = 200  
  Height   = 200
  Caption  = "Dialog Form"
  BackColor= RGB(192, 192, 192)
ENDDEFINE
 
*-- Subsequent transformation, creating a code class 
*-- from another code class.
DEFINE CLASS MyExpandDialogForm as MyDialogform 
  Width    = 400   
ENDDEFINE

Globally Set Properties of Many Objects with SetAll

_SCREEN.ActiveForm.SetAll('ForeColor', RGB(0,255,0), 'Page')

Write Property Expressions with WriteExpression

*-- WriteExpression() Example
*--   Places a date expression inside a command button.
 
*-- Start the Form Designer. This will do.
MODI FORM Junk91 NOWAIT
 
*-- Find the parent container of the selected object.
=ASELOBJ( laObjectArray, 1)
*-- Add a command button.
laObjectArray[1].ADDOBJECT( "Command1", "CommandButton")
 
*-- Take Note!  VFP expects "=".
laObjectArray[1].Command1.WriteExpression( "Caption","=DTOC(DATE())")

Write Code to Methods with WriteMethod

* AppendClick.PRG
* Skeleton builder demonstrating
* adding "Hello World" to Form.Click.
PARAMETERS toPassedObject, tcContextString
LOCAL loForm, lcMessage
 
*-- Create the Hello World code.
*-- Begin and end with a CR for safety's sake.
lcMessage= CHR(13)+ ;
           "=MESSAGEBOX('Hello World')"+ ;
           CHR(13)
 
*-- Locate the Form object.
loForm= toPassedObject
DO WHILE loForm.Baseclass <> "Form"
  loForm= loForm.Parent
ENDDO
 
*-- Append the 'Hello World' code to any existing code
*-- in the Click method.
loForm.WriteMethod( "Click", ;
                    loForm.ReadMethod("Click") + lcMessage)

Create a Builder Framework

What Builders Cannot Do

Builders Cannot Modify Certain Properties

Wizards

The _WIZARD System Memory Variable

The Wizard.APP Wizard Manager Program

Invoking Wizards

There are a number of places in Visual FoxPro where you can easily invoke a wizard. Many of the wizards can be invoked from the File | New dialog in the main menu. Similarly, in the Project Manager, the New button leads to wizards for many types of files.

DO (_WIZARD) WITH 'FORM'

The Wizard.DBF Metadata Table

Wizards In VFP 7

Parameters Passed to _WIZARD by VFP

Parameters Passed to Wizards by Wizard.APP

• Your wizards must provide a nine-element PARAMETER statement to handle the call from Wizard.APP.
• The first parameter is useful only if you want to have the wizard output reflected in the Project Manager, and if the wizard emanates from the Wizard button on the New dialog in the Project Manager.

Extending the Form Wizard

The FrmStyle.DBF Styles Registry Table

1. Set the default directory to HOME()+"Wizards"
2. Start the Form Wizard with DO WZFORM.APP—this trick won't work otherwise.
3. From the Program menu, choose "Suspend".
4. In the Command Window, execute the following commands:

SELECT FormStyles
COPY TO HOME()+"Wizards\FrmStyle"

The Form Wizard automatically consults the WizStyle.VCX class library. Therefore, this is a good place to add your own custom styles. If you decide to use your own VCX, you need to specify that in the VCXFile field. Make sure to include a path so the Form Wizard can locate it.

The WizStyle.VCX Class Library

A modification we recommend is to interactively change WizStyle.VCX to point the items based directly on base classes to use subclasses instead. This will make forms created with the Form Wizard more maintainable.

Creating Form Wizard Styles

1.      Create your own custom style by subclassing BaseForm or one of its subclasses (for example, EmbossedForm) in WizStyle.VCX. This new form can be saved to WIZSTYLE or another class library of your choosing. We start with BaseForm or its subclasses because they contain all the custom properties required by WIZARD.APP.

2.      Modify the LayoutSty object on the form to provide the configuration you want. The LayoutSty object is a container of shapes that controls the horizontal and vertical spacing of objects as they are laid out on the form. This is the "prototype" referred to earlier. See Figure 5-17 for an interpretation of the layout determinants. This figure shows the default styles, shapes and sizes for most of the objects to be placed upon the generated form. Your custom form title can be based upon the style and positioning of the default label. Three shapes are added to the body of the form to specify the styles and horizontal and vertical placement of objects on the form.

3.      Create and register data type classes. Each visual form style specifies a set of classes used for adding fields based on data type. For example, a class containing an edit box is used for Memo fields. Logical fields use check boxes, and so on. Once you have created a set of your data classes, they need to be registered under specific custom properties of the form style.

4.      Finally, register this new style in FrmStyle.DBF so the Form Wizard can display a reference to it in its selection dialogs.

Figure 5-17: Spacing in Wizard forms is determined by the LayoutSty object.

Rules for Creating Form Wizard Styles

• Derive your form style from the BaseForm form class. Why? BaseForm contains the properties needed by the wizard.
• Be aware that your event code (Init, Load, Activate, Deactivate, Destroy) can interfere with code placed there by the Form Wizard, which could cause puzzling errors. Since we don't have the source to the Form Wizard, there isn't much we can do but keep this in mind and hope for the best.
• A form uses an object derived from the LayoutSty class to provide dimensional information for field layout. There are four shapes and custom properties in the LayoutSty container class:
  • The LayoutSty.oLabel1 property contains a reference to the object in LayoutSty, representing the starting position for the field layout.
  • The LayoutSty.oLabel2 property contains an object reference and represents the vertical spacing between fields (difference between oLabel1 and oLabel2).
  • The LayoutSty.oCol2 property is used with LayoutSty.oLabel1 to determine the column width. The Form Wizard attempts to lay out fields vertically if it can fit all of the fields on the form; otherwise, it reverts to laying them out horizontally in columns based on the column width derived from this property.
  • The LayoutSty.oDimensions property references the shape representing the physical boundary on which fields can be laid out.

BaseForm and its subclasses have a number of custom properties which let you specify the classes to be used for your style and other characteristics of the style:

• The form can stretch to the Maximum Design area setting in your Options dialog if the WizFormStretch property on the form is set (.T.). Only this portion of the form stretches. The header and footer remained fixed in height. The Form Wizard supports only vertical stretching.
• The LayoutSty class included in WizStyle.VCX is referenced by the WizLayout custom property on your form. Your form must have this property set to a valid layout class such as LayoutSty.
• The Form.WizField property contains a reference to a class having a normal text box used for fields with character, number and date data types. Similarly, the Form.WizMemo property points to an edit box class, and so on. The Form.WizLogic property is optional—without this class reference, the Form Wizard defaults to using the Form.WizField class.
• Style objects can come from singular or composite classes. Singular classes (such as Standard and Embossed) consist of a single control like a text box. The label style that accompanies singular style classes is specified by the form's WizLabel property.
• You can place a number of objects inside a container to form a composite style class. Composite style classes are used by styles like Shadow to create special effects. Each container must have a label and a data control (such as a text box). Because the label is stored in the container, the object specified by the form's WizLabel property is ignored.
• You cannot mix singular and composite classes in a visual style.
• When the wizard places an object on the form, its width is based on the underlying table field or caption width.

The WizShape class that is stored in WIZSTYLE should be used for prototyping container objects for composite classes. Put a box based on WizShape around the label/control combination. WizShape has a custom property called WizEffect that controls stretching (see Table 5-5).

Table 5-5: The WizEffect property takes these values to control stretching.

Table 5-6: Custom properties contained in the BaseForm class.

If you follow these guidelines of style creation, then you've got all the flexibility you need to make the Form Wizard create forms just as you like them. In the end, it is easiest to just subclass an existing style and modify the subclass to suit.

Back to Table of Contents

Copyright © 2002-2018 by Tamar E. Granor, Ted Roche, Doug Hennig, and Della Martin. Click for license .