Components of a Customized Builder

Components of a Customized BuilderPage 1

Microsoft® Visual FoxPro for Windows / ®
Versions: / 3.0 / Product Support Services
Subject: / Components of a Customized Builder / Application Note
Contents: / 11Pages, No Disk / 12/95  FW1223

INFORMATION PROVIDED IN THIS DOCUMENT AND ANY SOFTWARE THAT MAY ACCOMPANY THIS DOCUMENT (collectively referred to as an Application Note) IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE. The user assumes the entire risk as to the accuracy and the use of this Application Note. This Application Note may be copied and distributed subject to the following conditions: 1) All text must be copied without modification and all pages must be included; 2) If software is included, all files on the disk(s) must be copied without modification (the MS-DOS® utility diskcopy is appropriate for this purpose); 3) All components of this Application Note must be distributed together; and 4) This Application Note may not be distributed for profit.
Copyright © 1995 Microsoft Corporation. All Rights Reserved.
Microsoft, MS-DOS, FoxPro, and Windows are registered trademarks of Microsoft Corporation.
This document was created using Microsoft Word for Windows®.

Microsoft Product Support Services

Components of a Customized BuilderPage 1

Table of Contents

INTRODUCTION...... 1

Overview of the Builders that Ship with Visual FoxPro...... 2

Characteristics of a Builder...... 3

Components of the Builder Application...... 4

Step-by-Step Example of a Custom Builder...... 5

Developing a Custom Builder...... 8

How to Register a Builder...... 8

Registering a Builder Using the BUILDER.DBF Table...... 8

Registering a Builder Using the Builder Property...... 9

How to Call the Builder Application Under Program Control...... 9

How to Reference a Selected Object...... 9

How to Read Properties from the Property Sheet...... 9

How to Write Method Code for the Selected Control...... 10

Other Methods Useful in Developing a Builder...... 10

Hints and Commonly Asked Questions...... 11

INTRODUCTION

A builder is a tool provided by Visual FoxPro for Windows to assist users in the design of objects. The tool presents a series of choices that set properties used in building an object. A builder allows you to quickly design a form by simplifying the process of setting properties for controls. A builder is similar in concept to a Wizard. Both are essential components of Rapid Application Development (RAD), but they differ in their implementation. The goal of a Wizard is to take you step by step through a process to accomplish a common task, whereas a builder lets you adjust the attributes of existing objects at design time.

Visual FoxPro ships with 10 predefined builders: the Edit Box builder, the Option Group builder, the List Box builder, the Grid builder, the Form builder, the Combo Box builder, the Command Group builder, the AutoFormat builder, the Text Box builder, and the Referential Integrity builder. You can call a builder interactively from the shortcut menu in the Form Designer or the Visual Class designer, the Builder button in the Property sheet, or the Builder Lock button in the Form Control toolbar. You can also call the builder from the Command window with a DO command. To set preferences for the Builder Lock button, click the Forms tab in the Options dialog box.

In addition to providing these existing builders, Visual FoxPro offers an open architecture that allows a developer to register and develop new custom builders.

Overview of the Builders that Ship with Visual FoxPro

The following table lists the builders shipped with Visual FoxPro. The first column lists the builder, the second column provides a short description of the builder; the third column documents the characteristics of the control that the builder modifies, and the fourth column lists properties that are changed when the attribute is modified.

Builder / Description / Characteristics / Noteworthy Corresponding Properties
Edit Box / Creates and sets properties for an EditBox control. / Format / AllowTabs, Scrollbars,ReadOnly, Format, Enabled, HideSelection
Style / SpecialEffect, Alignment, BorderStyle
Value / ControlSource
List Box / Creates and sets properties for a ListBox control. / List Source
Style (3D)
Dimensions
Incremental Searching
Column Layout
Return Value Source / RowSourceType,
RowSource
Data Stored Location / BoundColumn
Grid / Creates and sets properties for a Grid control. / Grid Source
Presentation Style / RecordSource
Column Layout / SpecialEffect
Column Control Type / Width
Source Data / ControlSource
Relationship / RelationalExpr
Combo Box / Creates and sets properties for a ComboBox control. / List Source / RowSourceType, RowSource
Style (3D)
Combo or List
Incremental Searching
Column Layout
Return Value Source
Data Stored Location / IncrementalSearch
Command Group / Creates and sets properties for buttons in a command group. / Number of Buttons
/ ButtonCount
Captions
Graphics
Horizontal or Vertical Layout
Spacing
Border Style / Caption
AutoFormat / Applies a style to selected controls on a form. / Border
Colors / BorderStyle
BackColor, Forecolor, BorderColor
Fonts
Layout
3D Effects / BackStyle
Option Group / Creates and sets properties for buttons in an option group. / Number of buttons / ButtonCount
Standard or Graphical Appearance
Horizontal or Vertical Layout / Style
Spacing between Buttons
Data Source / BorderStyle
Form / Adds controls to a form using fields and a style the user specifies. / Presentation Style
Horizontal or Vertical Layout
Multiple Column Options
Data Source
Referential Integrity / Creates triggers and stored procedures that enforce referential integrity between tables in your database. / Rules for Updating
Rules for Deleting
Rules for Inserting / CREATE TRIGGER command

Characteristics of a Builder

A builder interface is usually a tabbed dialog box, and lets the user set attributes of an object. Builders are usually used with Form objects, but they are not limited to visual objects. If you want to develop a customized builder, you should consider the following design goals:

Characteristic / Description
Simplicity / A builder presents a set of properties to the user in a logical way. Users should be able to modify these properties easily. A builder is typically used to build controls, but you can use it to construct the properties of a non-visual object as well.
Ability to modify objects at design time / A builder is used at design time and immediately modifies the properties of a selected object.
Ability to cancel changes / A user should be allowed to cancel the changes that have been made. Therefore, a builder should save the initial state of an object when it is accessed.
Reentrant builder / Users should be able to invoke the builder at any time. The same builder can be used several times to build an object. When the builder is started, it takes the state of the object at start up time.
Modality / All the builders shipped with Visual FoxPro use modal dialog boxes. With this design, the Command window and the rest of the product cannot be accessed while the builder is running. Using modal dialog boxes removes complexity from your application.
Error handling / Builders should have a routine that processes potential errors.

Components of the Builder Application

BUILDER.APP

This is a Visual FoxPro application that serves as a main driver for a builder program. Its main purpose is to locate the appropriate routine to run among the registered builders, and start it. All builders that interface with the form use this application. The Referential Integrity builder uses a different engine, which is not discussed here.

_BUILDER

This system memory variable points to the application that controls the builders. When you install a builder, it is set by default to BUILDER.APP. If you decide to write another driver program, you must modify the content of this variable.

BUILDER.DBF

This is the table that stores the registration of existing builders and is an essential part of the application. The table is by default installed in the Wizards directory off the main Visual FoxPro directory. This table has the same structure as the Wizard.dbf table.

Field Type Dec / Name / Width
NAME / Character / 45
DESCRIPT / Memo
BITMAP / Memo
TYPE / Character / 20
PROGRAM / Memo
CLASSLIB / Memo
CLASSNAME / Memo
PARMS / Memo

• The Name field contains the name you give to the builder. This field cannot be empty.
• The Descript field contains a description of the builder.
• The Bitmap field is not used by the builder application.
• The Type field is the basis of the builder application. It stores the type of object that calls the builder. When the builder application is invoked, it looks at the Class and the BaseClass properties of the object, and compares it with the content of the Type field. For example, the Type field holds the value COMMANDBUTTON for a command button builder. The AutoFormat builder uses the MULTISELECT value because it is run against multiple selected controls.

When the builder application compares the Type field and the class of the object, the appropriate routine is started if there is a match. If there is no match, an alert is displayed that indicates there is no registered builder. If there are several builders suitable for the class, the following dialog box is displayed.

• The Program field holds the name of any specific program or application that is started with the builder. This field is blank for all the builders shipped with Visual FoxPro because they were developed as classes.
• The ClassLib and ClassName fields hold the name of the Visual Class Library (.VCX) and the class corresponding to the builders. The builder application creates an instance of the class when it is invoked.
• The Parms field lists additional parameters passed to the builder program.

By default, the BUILDER.APP application passes three parameters to a builder program:

The first parameter is the string wbReturnValue. You can use this parameter if your customized builder needs to return a value to a higher level program. WbReturnValueis the name of the memory variable in the builder application that the builder should update with the value that is returned by BUILDER.APP.

The second parameter is the string from the Parms field in the BUILDER.DBF registration table. The literal string is passed to your customized builder program. For example, if the Parms field contains the value CmdButtonOnly, the builder program receives this string as a parameter.

The third parameter contains optional information that might have been passed to the BUILDER.APP builder application. For example, certain keywords such as NOUI might be passed to BUILDER.APP to specify that the builder should be run without a user interface. This option is also passed to the custom builder program.

Your Customized Builder Program

The builder application provides hooks that allow you to develop and register your program as a builder for a specific control or group of controls. Your program provides an interface to the user, and modifies the properties of the selected items.

In the rest of this document, the "builder application" refers to the driver program, BUILDER.APP. The "builder program" refers to the custom builder or the specific interface that modifies the properties of a control.

Step-by-Step Example of a Custom Builder

This section provides a step-by-step example that shows how to build and register a custom builder from start to finish. The purpose of this exercise is to introduce you to custom builders with a simplified working program. The sample program provides a way to change the font of all selected controls. Please note that because this example has been kept as simple as possible, it does not contain an error routine. However, a real-world custom builder will likely include an error routine.

1.Verify that the _BUILDER builder system memory variable points to the correct application. By default:

_BUILDER="C:\VFP\BUILDER.APP"

2.Write your custom builder program, which provides an interface and modifies the properties of the selected control. The following sample program presents the font selection dialog box to the user, and changes the FontName, FontBold, and FontItalic properties of the selected control. Copy and paste this code to a program called CHGFONT.PRG and save it to the VFP\WIZARDS directory.

LPARAMETERS tobject, tsource, txt

LOCAL nNumberOfObjects, cNewFont, cNewFontName, cNewFontSize,cNewFontStyle

LOCAL ARRAY atest(1,2)

nNumberOfObjects=ASELOBJ(atest)

cNewFont=GETFONT()

IF NOT EMPTY(cNewFont)

cNewFontName=SUBSTR(cNewFont,1,AT(',',cNewFont)-1)

cNewFontSize=SUBSTR(cNewFont,AT(',',cNewFont)+1,(AT(',',cNewFont,2)-;

AT(',',cNewFont)-1))

cNewfontstyle=SUBSTR(cNewFont,AT(',',cNewFont,2)+1)

FOR i=1 TO nNumberOfObjects

IF INLIST(atest(i).BaseClass,"Checkbox","Column","Combobox",;

"Commandbutton","Editbox","Grid", "Label","Listbox",;

"Optionbutton", "Page", "Spinner","Textbox" )

* Verifies that the control has a fontname property

atest(i).FontName=cNewFontName

atest(i).FontSize=VAL(cNewFontSize)

DO CASE

CASE cNewfontStyle=="N"

atest(I).FontBold=.F.

atest(I).FontItalic=.F.

CASE cNewFontStyle=="B"

atest(I).FontBold=.T.

atest(I).FontItalic=.F.

CASE cNewFontStyle=="I"

atest(I).FontBold=.F.

atest(I).FontItalic=.T.

CASE cNewFontStyle=="BI"

atest(i).FontItalic=.T.

atest(i).FontBold=.T.

ENDCASE

ENDIF

ENDFOR

ENDIF

The ASELOBJ() function places object references to currently selected controls in the active Form Designer into a memory variable array.

3.The next step is to register your custom builder by adding a record to the BUILDER.DBF table. To achieve this:

a. Open the BUILDER.DBF table, located in the WIZARDS directory off the main Visual FoxPro directory.

b. BROWSE the table and APPEND a new record. You can press ctrl+y to append a record.

c. Enter the following values for the following fields:

Name: The Builder That Changes Fonts

Descript: This builder modifies the font of all selected controls.

Type: MULTISELECT. This type specifies that the builder is invoked when several objects are selected.

Program: CHGFONT.PRG

The BROWSE window should appear as follows:

Your custom builder is now registered.

4.To use the builder, create a form, and then place two text boxes, two check boxes, and a command button on the form. Modify the caption of the check boxes to Bold for the first check box, and Italic for the second check box. Type RELEASE THISFORM in the Click event handler for the command button. Your form should appear as follows:

5.Select two controls and right-click the form. From the shortcut menu, select Builder. Because there are two builders with the MULTISELECT type, the following dialog box is displayed. Select "The Builder That Changes Fonts."

6.The GETFONT dialog box is displayed. Select Arial, Italic, 12, and click OK. You are returned to the form, which should look as follows:

Developing a Custom Builder

The builder application, BUILDER.APP, can run your customized builders. These can be registered as programs or class libraries. If they are registered as programs, BUILDER.APP runs the program. If your customized builder is a class library, BUILDER.APP creates an instance of the class. This section discusses what to consider when writing a builder, and functions and methods you can use to reference objects and their properties.

How to Register a Builder

You can register a builder using the BUILDER.DBF table or the Builder property.

Registering a Builder Using the BUILDER.DBF Table

You can add a record to the BUILDER.DBF table located in the WIZARDS directory off the main Visual FoxPro directory to register your builder. There is one record per builder. The structure of the table is detailed in the COMPONENTS section. The following two entries in the table are essential:

• The Type field contains the class of the object that should invoke the builder. If you create a builder that you want to start after multiple objects have been selected, store the MULTISELECT value in the Type field. If the Type field is empty, the builder is never invoked. Conversely, if a builder is registered with the ALL type, it is always started.
• One of the following fields must have a value:

The Program field contains the name of the program to execute. This can be a PRG, a FXP, an APP or an EXE. To run the correct program, BUILDER.APP requires that the extension be specifically added to the filename in the Program field. This field can be empty if the ClassLib and ClassName fields are filled.

The ClassLib and ClassName fields contain the class library and class names of the builders. This is the approach used with the builders shipped with Visual FoxPro.

If both the Program and ClassLib fields are empty, the error "There are no registered builders of this type" is displayed when you attempt to start the builder. When both the Program and the ClassLib fields contain a non-blank value, the program takes precedence and is run.

If you do not specify a path to the program or the visual class library, BUILDER.APP looks for the custom builder in the following order:

1.The WIZARDS directory

2.The default directory set with the CD or the SET DEFAULT commands

3.The Visual FoxPro directory

4.The Visual FoxPro path set with the SET PATH command.

Registering a Builder Using the Builder Property

You can bypass BUILDER.DBF and create a custom property called Builder. This property of a control holds the name of the builder program. If you are using a builder for a control on a form, this method requires that you create a class for the object that will use the builder, because it is not possible to create a new property for a control on a form. The following step-by-step procedure illustrates how to register a builder using the Builder property.