Advanced Visual FoxPro Controls

John M. Miller

Perpetual Data Systems

Introduction

Controls are the means by which the user interacts with a Visual FoxPro Application. Therefore the quality and capabilities of an application, as measured by the end-user, are directly related to how well the user is able to manipulate the application through the application’s controls. No matter how well a data model is implemented, the application cannot be considered a success if the user-interface is clumsy or inefficient. The goal of this session is to describe in detail the Visual FoxPro control set and demonstrate how to implement good solid user interfaces using Visual FoxPro controls. Major topics to be covered are:

Containers v. Controls	Read Only Controls
The Timer Control	Combo Boxes
OLE Custom Controls	Visual Classes
Subclassing Objects	User Properties & Methods
Using Header Files	Common Properties & Methods

Controls Overview

Before the Visual FoxPro control set can be covered in any depth a fundamental understanding of the nature of the control set and the means by which controls are implemented in a Visual FoxPro application is required. This material will not be covered in any depth during the session and it is recommended that the introductory session be attended or the following material be reviewed before attending the session.

The new Visual FoxPro form designer allows the developer a great deal more flexibility than the 2.x screen builder. Not only are more different type of controls supported, the developers ability to alter the appearance and behavior of the controls has been greatly improved making it much easier to create good user interfaces. Like the screen builder, controls are placed on a form by selecting a control from a palette or toolbar and then selecting the location on the form where the control should be located.

The Visual FoxPro Controls ToolBar

The Controls Toolbar is normally available whenever the form designer is activated. However since the Controls Toolbar is a free standing window and is no longer attached to the form designer it is possible to close the Controls ToolBar window. To reactivate the Controls ToolBar select Form Controls ToolBar from the View menu pad. The Controls ToolBar can be docked by dragging the ToolBar window onto the Visual FoxPro ToolBar or the Status Bar or to the left or right sides of the screen. The ToolBar contains a variety of icons representing various control related functions. These function include:

Selection Tool	Restores the default tool for selecting and arranging objects
Class Library	Displays a list of all standard Visual FoxPro controls, registered class libraries and OLE controls. When the class library is changed by selecting a different library from the list, the tool bar is updated to reflect the objects in the new library. Only the object in a single library are displayed at any one time. The user can also add additional libraries to the list by selecting ‘Add...’ from the list
Textbox	Selects the Text tool. The object’s Caption property must be set to change the displayed text.
Separator	Allows the addition of separators when creating Toolbars using the Class Designer. Not available when creating Forms
Button Lock	Controls the selection tool. When Button Lock is off control returns to the selection tool once an object is placed on the form. Set Button Lock on to quickly create many objects of the same type.
Builder Lock	When set on, builders will be automatically be invoked when controls are inserted

The ToolBar can be modified by adding and removing class libraries. Class libraries are maintained through the Controls tab on the Option dialog and can also be added by selecting ‘Add’ from the Class Library Tool. Only selected libraries are included in the ToolBar.

Events

The Visual FoxPro event model allows the developer to easily trap user and system events and then specify code to respond to the event. The Visual FoxPro set of events is fixed. You cannot create new events, you can only respond to the existing events. You respond to events by associating a method with the event. The method is then executed whenever the event occurs. All of the events that a control is capable of responding to are listed under the Methods tab of the Properties dialog.

In order to properly implement controls it is helpful to understand the order in which events are triggered by Visual FoxPro in response to user interaction and system functions. The following table, provided by David T. Anderson, lists the triggering of events from the launching of the form to the releasing of the form.

3.0 Form Events:	SCOPE	program()
Formset1.Load	M	formset1.load
Form1.Load	W	formset1.test.load
Object1.Init	W	formset1.test.pageframe1.page1.object1.init
Object2.Init	W	formset1.test.pageframe1.page1.object2.init
Page1.Init	W	formset1.test.pageframe1.page1.init
Pageframe1.Init	W	formset1.test.pageframe1.init
Form1.Init	W	formset1.test.init
Formset1.Init	W	formset1.init
Formset1.Show	P W	formset1.show
Formset1.Activate	P W	formset1.activate
Page1.Activate	P W	formset1.test.pageframe1.page1.activate
Form1.Activate	P W	formset1.test.activate
Object1.When	P W	formset1.test.pageframe1.page1.object1.when
Object1.GotFocus	P W	formset1.test.pageframe1.page1.object1.gotfocus
Object1.KeyPress(120, 0)	P W	formset1.test.pageframe1.page1.object1.keypress
Object1.InteractiveChange	P W	formset1.test.pageframe1.page1.object1.interactivechange
Object1.KeyPress(13, 0)	P W	formset1.test.pageframe1.page1.object1.keypress
Object1.Valid	P W	formset1.test.pageframe1.page1.object1.valid
Object1.LostFocus	P W	formset1.test.pageframe1.page1.object1.lostfocus
Object2.When	P W	formset1.test.pageframe1.page1.object2.when
Object2.GotFocus	P W	formset1.test.pageframe1.page1.object2.gotfocus
Object2.Valid	P W	formset1.test.pageframe1.page1.object2.valid
Object2.LostFocus	P W	formset1.test.pageframe1.page1.object2.lostfocus
Formset1.Destroy	W	formset1.destroy
Form1.Destroy	W	formset1.test.destroy
Pageframe1.Destroy	W	formset1.test.pageframe1.destroy
Page1.Destroy	W	formset1.test.pageframe1.page1.destroy
Object2.Destroy	W	formset1.test.pageframe1.page1.object2.destroy
Object1.Destroy	W	formset1.test.pageframe1.page1.object1.destroy
Form1.Unload	W	formset1.test.unload
Formset1.Unload		formset1.unload

SCOPE LEGEND: P=Form Property, M=Memvar declared in Formset.Load, W=WEXIST()

Common Control Properties

Each control on a form has a number of attributes or properties that the designer of the control makes available to the application developer to describe the specifics of each object. Properties can be set either at design-time in the form design tool or at run-time in a procedure or method. Some of the properties that are common to many controls are:

Caption	The text to displayed on the form. This is the displayed text for a text control. You can assign hot keys by including the characters “\<” in the caption before the character to be made hot.
Enabled	Controls whether the user can interact with the control
MousePointer	0 through 12. The type of cursor that should be displayed when the user moves the mouse over the object. For instance, this should be set to 12 (No Drop) when an object cannot be dragged onto the control.
ToolTipText	The tip to be displayed in the tool tip box.
Visible	Controls when the control is displayed on the screen. If you find yourself making lot of controls invisible look into pageframes as an alternative.
BackColor	The objects background color.
DisabledBackColor	Background color of the object when disabled.
DisabledForeColor	Foreground color of the object when disabled.
FontBold	.t. if the text associated with the control bolded.
FontItalic	.t. if the text associated with the control italic.
FontName	Font of the text associated with the control.
FontOutline	.t. if the text associated with the control is outlined (Mac only)
FontShadow	.t. if the text associated with the control is shadowed (Mac only)
FontSize	Size of the text associated with the control.
FontStrikethru	.t. if the text associated with the control is stricken thru.
FontTransparent	.t. if the text associated with the control is transparent.
FontUnderline	.t. if the text associated with the control is underlined.
ForeColor	Foreground color of the control.
Format	Specifies the appearance of a value in a control. Similar to GET picture templates and functions.
Top	Position of the object on the form in relation to the top of the form in the forms scale mode.
Left	Position of the object on the form in relation to the left side of the form in the forms scale mode.
Height	Vertical size of the control in the forms scale mode.
Width	Horizontal size of the control in forms scale mode.
SpecialEffect	Specifies different display options for the control. (3D)
StatusBarText	Specifies the text to appear in the status bar when the control has focus.
TabStop	Specifies whether the user can use the TAB key to set focus to the control.
Value	Current state of the control.

Common Control Events

Events are the means by which the developer establishes or alters the control’s responses to user actions or system messages. By assigning methods to events, the developer can replace or augment the inherited behavior of the control. Some of the events common to many controls are:

Click	The user clicked on the control
DblClick	The user double-clicked on the control.
Destroy	The control is being destroyed
Error	The control has generated an error
ErrorMessage	The excuse to give the user as to why the control no longer works.
Init	The control is being created
MouseDown	The user pressed a mouse button
MouseMove	The user moved the mouse.
MouseUp	The user let the mouse button up.
GotFocus	The control has received user focus through either a keyboard action or a mouse click.
LostFocus	The current control has lost focus to another control either through a keyboard action or a mouse click

Controls and Data

Controls can be bound to a data source. When a control that is bound to a data source is changed by the user the data source is updated to reflect the change. See the session on binding controls to data for more information.

Forms

Forms and Form sets are containers for controls. Forms have their own properties and methods that allow the developer to control the appearance and behavior of the form. See the session on Forms for more information.

Containers v. Controls

There are two main class hierarchies in the Visual FoxPro object model. All objects in Visual FoxPro are based on one or the other of these two base classes. Containers are objects that are designed to hold other controls. A form is a good example of a container. Other examples of containers are Grids, Grid Columns, PageFrames and ButtonGroups.

Controls are objects designed to manipulate data. A command button is a good example of a control. Other examples of controls are Text Boxes, Edit Boxes, List Boxes and Spinners.

One important thing to remember about controls and containers are the way in which they respond to events. Since controls and containers are different families of classes they don’t usually respond to each others events. For example if you assign a method to the Click event of a form and then place a command button on the form. The Click method would only be triggered when the user clicked on the form outside of the button. Nothing would happen when the user clicked on the button until you assigned a method to the click event of the button. This is because the button is based upon the control class and the form is based on the container class.

Advanced Uses of Visual FoxPro Controls

The following in a brief overview of the Visual FoxPro control set. Each control is described and any methods and properties specific to the control are explained.

Presentation Controls

Labels

Labels are equivalent to the FoxPro 2.x Text objects. However, unlike Text objects which are static and cannot be changed at runtime, Labels are fully integrated into the Visual FoxPro event model that support their own properties and methods. Labels can be changed at runtime by changing the labels Caption property. They can be moved on form dynamically by setting the Top and Left properties. Their appearance can be changed by setting the Font and color properties.

Lines

Like labels, Lines can now be changed dynamically in Visual FoxPro. Lines can also be drawn at any angle rather than simply horizontally or vertically as in FoxPro 2.x. A Line in Visual FoxPro is defined by a box on the form. The size of the box determines the length and angle of the line with the LineSlant property determining whether the line goes from the top, left corner to bottom, right corner or from the bottom, left corner to the top, right corner.

Properties
LineSlant	The direction of the lines slant. 0 = upper left to lower right. 1 = lower left to upper right.
Left, Top, Height, Width	Describe a location and size of a box that will contain the line. The direction of the line is determined by the LineSlant property

Images

Images are bitmaps displayed on the form. Image objects can respond to click events making them similar in function 2.x picture buttons. Note: Command buttons in Visual FoxPro also have picture properties.

Properties
Picture	The bitmap to display
BorderColor	The RGB color of the border
BorderStyle	0 = None, 1 = Fixed Single. The picture frame.
Stretch	Specifies how an image is sized to fit an Image Control.

Data Controls

Check Boxes

Check boxes are primarily used for changing logical values. The check box can either a box with a caption or two pictures.

Properties
Caption	The text message to display
Alignment	0=Left (Default), 1=Right. Controls the position of the box in relation to the caption.
Picture	The bitmap to display for the false state
DownPicture	The bitmap to display for the true state
Value	Contains the state of the switch.
Events
Click	Fired each time the user clicks the object.

Spinners

Spinners allow the mouse to manipulate numeric data. Spinners can now support a different range of allowable values for the keyboard and the mouse.

Properties
KeyboardHighValue	Highest value that can be entered using the keyboard.
KeyboardLowValue	Lowest value that can be entered using the keyboard.
SpinnerHighValue	Highest value that can be entered using the mouse.
SpinnerLowValue	Lowest value that can be entered using the mouse.
Increment	Specifies the value by which the spinner is incremented or decremented when up or down arrow is selected.
Value	Contains the current state of the spinner.

Text Boxes

Used for fixed length character data entry. Similar to 2.x GET objects. Text objects can now respond to individual user keystrokes. Portions of the contents of the Text Box can be selected programmatically. The font and style of the text can be selected dynamically.

Properties
MaxLength	The maximum number of characters allowed.
SelStart	Start position of the selected text
SelLength	Length of the selected text.
ForeColor	Foreground color of the text
InputMask	Specifies the data entry rule each character must follow.
ReadOnly	Prevents the user from changing the value of the text.
BorderStyle	0=No border, 1=Single line border
HideSelection	Controls whether the selected text appears highlighted when the edit control has lost focus.
SelectedBackColor	Background color of selected text.
Alignment	0=Left (Default), 1=Right, 2=Center
SelectedForeColor	Foreground color of selected text.
Methods
RangeHigh	Specifies the higher range for the text
RangeLow	Specifies the lower range for the text

Edit Boxes

Used for variable length character data entry. Similar to 2.x Edit Region objects. Visual FoxPro Edit Boxes allow a great deal more control of the editing process.

Properties
AllowTabs	Permits the entry of tab characters. Prevents the tab key from moving focus on to the next control.
HideSelection	Controls whether the selected text appears highlighted when the edit control has lost focus.
ReadOnly	Prevents the user from changing the text.
ScrollBars	Does the Edit control have a scroll bar.
SelectedBackColor	Background color of selected text.
SelectedForeColor	Foreground color of selected text.

Action Controls

Command Buttons

Command buttons allow the user to take actions.

Properties
Default	Specifies the default command button
Caption	The text to be displayed
DisabledPicture	Bitmap to be displayed when the button becomes disabled.
DownPicture	Bitmap to display when the button is pressed.
Enabled	Controls whether the button can be pressed.
Picture	Bitmap to display on the button
Events
Click	Fired when the user presses the button

Option Buttons

Option buttons are used to present the user with a small number of distinct choices. Similar to the 2.x Radio Button object, Option buttons can be treated as individual buttons or as an option button group.

Properties
Alignment	Should the caption appear on the right or left of the button.
DownPicture	The bitmap displayed when the button is selected
Picture	The bitmap displayed when the button
Methods
Click	Fired when the user presses the button

Option Buttons can be used to filter lists by filtering and refreshing the list object from the click method of the option button.

List Controls

List Boxes

Used to present a list of choices to the user for selection. Similar to 2.x Lists and Popups

Properties
Columns	The number of columns in the list
ControlSource	Source of data to which the control is bound
ControlSourceType	None, Value, Table, SQL Statement, Query, Array, Fields, Files, Structure, Popup
MoverBars	Mover Bars allow users to reorder the list.
MultiSelect	Controls the ability of the user to select multiple items from the list.
ColumnWidths	Widths of each column
RowSource	Specifies the source of the values. Can be a comma delimited list of values
Methods
AddItem	Adds an item to the list
RemoveItem	Removes an item from the list.

Combo Boxes

Combo boxes are a combination of text object and list object. Like a text object, the user can type the desired value directly into the box. Like a list object, the user can select the desired value from the list.

Properties
Style	The type of Dropdown, List or Combo
ControlSource	Source of data to which the control is bound
IncrementalSearch	Should the list be incrementally searched as the user types?
RowSource	Source of the list
RowSourceType	Type of source for the values in the list
Methods
AddItem	Add an item to the list.
RemoveItem	Remove an item from the list.

Other Controls

Timer Control

The timer control allows the developer to interrupt execute at regular intervals and perform some periodic function. The timer control is not visible at run-time and does not respond to user actions.

Properties
Interval	The number of milliseconds between events. Must be between 0 and 2,147,483,647. Timer events do not have a duration. The interval determines how often an event occurs. Timer events consume processor resources and can effect overall performance. Larger intervals are better than smaller intervals. Also there is a potential for error in the regularity of timer events. For example setting the interval to 500 milliseconds does not guarantee an event every half second. Therefore you should request more events than you need and test the system clock for greater accuracy.
Enabled	Specifies whether the control can respond to user events
Event
Timer	Fired each time the interval elapses.

Grids

Grid controls are a new and powerful Visual FoxPro feature. A grid control is like a browse command that is embedded onto a form. Grid controls are much configurable than browse commands have been. You can create multiple line rows, specify different fonts and colors for individual columns or cells. You can even embed other controls or even other grids within the columns of a grid control. Due to the complexity of the new grid control, two other sessions are devoted strictly to this control.

OLE Controls

OLE Controls are external to Visual FoxPro. They are written to conform to a standard design specification and the control designers expose to Visual FoxPro (and therefore the Visual FoxPro developer) the properties and methods necessary to modify the controls behavior. Since each control is different and the number of controls changes constantly they cannot be described specifically.

Containers

PageFrames

A PageFrame is a collection of pages. Pages defines a region of the form as having multiple layers. Users can only interact with a single layer or Page at a time. Controls from other pages are hidden from the users view. The user changes pages by selecting one of several tabs along the edge of the frame relating to the desired page. The selected page is then brought forward and made active and the previous page is hidden.

Properties
ActivePage	Returns the number of the active page in the PageFrame
PageCount	The total number of pages
PageHeight	The height of the page.
PageWidth	The width of the page.
TabStrech	Controls the behavior of the pageframe when the caption of the page exceeds the width of the tab. When Clipped the Caption is truncated at the width of the tab. When stacked the page frames are stacked and tabs are adjusted to the width of the page.
TabStop	Controls the behavior of the tab key within a page.
Methods
AddObject	Add an object to the page.
RemoveObject	Remove an object from the page.

Button Groups

A button group can be changed dynamically at run-time to alter the member list for the group allowing you to add, delete or change buttons in the group.

Option Groups

Properties
ButtonCount	The number of buttons in the group.
Value	Specifies the current state of the control
Methods
SetAll	This allows all members of the group to be assigned a property setting

Command Groups

Properties
ButtonCount	The number of buttons in the group.
Methods
SetAll	This allows all members of the group to be assigned a property setting.

Visual Classes

Individual controls and selected groups of controls can be saved as a Visual Class. Saving a control as a Visual Class allows the control to be included in many forms while maintaining a single definition of the control. This allows the class definition to be modified and the change reflected in all objects based on the visual class.

You create a Visual Class from a control by selecting the control and choosing Save As Class from the File menu pad. You save a group of controls as a class by first selecting the controls before choosing Save As Class. Note that when you save a group of controls as a class the class becomes a container class where as when save an individual control the class is a control class.

User Properties and Methods

You can create new properties and methods for a visual class with the New Property and New Method options of the Class menu pad. The Class menu pad is only available when the Class Designer is open. You can open the class designer with the MODIFY CLASS command.

By default user properties and methods are exposed to the user of the class. Exposed properties can be examined and changed and design time and at run time. Exposed methods can be called at run time. User Properties and Methods can protected by selecting the Protected checkbox on the New Property and New Methods dialogs. A protected property is not visible outside of the class. A protected method can only be called from within the class or a subclass of it.

Subclassing Visual Classes

Visual Classes can be based upon other Visual Classes. This allows you take generic classes and make increasingly specific classes from them. Since classes are definitions of objects and not objects in and of themselves any changes made to any class that and object is based upon are automatically inherited by the object.

Drag & Drop

Visual FoxPro now supports Drag and Drop functionality. Drag and Drop allows the user to drag objects on a form onto another object. By definition Drag and Drop involves two controls. The control being dragged and the control that the dragged object is dropped onto. Implementing Drag and Drop requires configuring the controls to be dragged and enabling the Drop controls to respond to object dropped onto them.

Properties
DragMode	Determines manual or automatic drag mode for a drag and drop operation.
DragIcon	Determines the icon displayed as the pointer during a drag and drop operation.
Methods
Drag	Begins, ends or cancels dragging controls
DragDrop	Occurs when a control is dropped over a form or a control and the mouse button is released. Can also occur by executing the drag method.
DragOver	Occurs when a drag and drop operation is in progress.

To configure a control for dragging you set the DragMode property to either Automatic or Manual mode. When set to automatic, the control is ready to be dragged when the form is loaded. Note however that when DragMode is automatic the control will not respond to normal mouse events. Automatic mode is useful for simple controls such as label and buttons but not for lists and grids.

When DragMode is set to Manual (the default) dragging is initiated by calling the Drag method. Passing the Drag method a parameter of 1 begins the drag operation. Passing a parameter of 2 ends the Drag operation or drops the object. A parameter of 0 cancels the drag operation. The initiation of a drag operation in manual mode is usually accomplished through the MouseDown event. Note that the MouseDown method should take care to not interfere with the normal operation of the control. The drop operation is initiated in manual mode through the MouseUp event.

The DragIcon property allows the developer to define a cursor that should be used represent the control while it is being dragged. If no DragIcon is specified the outline of the control is displayed.

To respond to a dropped object a control must assign a method to the DragDrop event. The method associated with the event requires three parameters. The first is a reference to object being dropped, the second and third are the coordinates of the mouse within the control. You can examine or change properties and call methods through the reference to the dropped object passed to the method.