Advanced Visual FoxPro
Controls
This document is reprinted
from the Microsoft DevCon 95 Speaker materials and is provided "as-is."
This document and any associated demo files were created using Visual
FoxPro 3.0. Some features discussed may have changed in Visual FoxPro
5.0.
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 ToolRestores 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 describ
e 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:
CaptionThe 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:
ClickThe 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.