A Form object.

Syntax

[<oRef> =] new Form([<title expC>])

<oRef>

A variable or property in which to store a reference to the newly created Form object.

<title expC>

An optional title for the Form object. If not specified, the title will be "Form".

Properties

The following tables list the properties, events, and methods of the Form class. With the exception of the onClose event, all Form events require the form to be open in order to fire.

Property

Default

Description

activeControl

 

The currently active control

allowDrop

false

Whether dragged objects can be dropped on the Form's surface

appSpeedBar

2

Whether to hide or display the Standard Toolbar when a form recieves focus. 0=Hide, 1=Display, 2=Use the current _app object's speedBar setting.

autoCenter

false

Whether the form automatically centers on-screen when it is opened

autoSize

false

Whether the form automatically sizes itself to display all its components

background

 

Background image

baseClassName

FORM

Identifies the object as an instance of the Form class

className

(FORM)

Identifies the object as an instance of a custom class. When no custom class exists, defaults to baseClassName

clientEdge

false

Whether the edge of the form has the sunken client appearance

colorNormal

BtnFace

Background color

designView

 

A view that is used when designing the form

elements

 

An array containing object references to the components on the form

escExit

true

Whether pressing Esc closes the form

first

 

The first component on the form in the z-order

hWndClient

 

The Windows handle for the form's client area

hWndParent

0

When used in conjunction with the showTaskBarButton property; determines, or specifies, the hWnd property for the parent window of a form

icon

 

An icon file or resources that displays when the form is minimized

inDesign

 

Whether the form was instantiated by the Form designer

maximize

true

Whether the form can be maximized when not MDI

mdi

true

Whether the form is MDI or SDI

menuFile

 

The name of the form’s .MNU menu file

metric

Chars

Units of measurement (0=Chars, 1=Twips, 2=Points, 3=Inches, 4=Centimeters, 5=Millimeters, 6=Pixels)

minimize

true

Whether the form can be minimized when not MDI

moveable

true

Whether the form is moveable when not MDI

nextObj

 

The object that’s about to receive focus

persistent

false

Determines whether custom control, datamodule, menu or procedure files associated with a form are loaded in the persistent mode.

popupMenu

 

The form’s Popup menu object

refreshAlways

true

Whether to refresh the form after all form-based navigation and updates

rowset

 

The primary rowset

scaleFontBold

false

Whether the base font used for the Chars metric is boldface

scaleFontName

Arial

The base font used for the Chars metric

scaleFontSize

10

The point size of the base font used for the Chars metric

scrollBar

Off

When a scroll bar appears for the form (0=Off, 1=On, 2=Auto, 3=Disabled)

scrollHOffset

 

The current position of the horizontal scrollbar in units matching the form or subform's current metric property

scrollVOffset

 

The current position of the vertical scrollbar in units matching the form or subform's current metric property

showSpeedTip

true

Whether to show tool tips

showTaskBarButton

true

Whether to display a button for the form on the Windows Taskbar

sizeable

true

Whether the form is resizeable when not MDI

smallTitle

false

Whether the form has the smaller palette-style title bar when not MDI

sysMenu

true

Whether the form’s system menu icon and close icon are displayed when not MDI

text

 

The text that appears in the form’s title bar

topMost

false

Whether the form stays on top when not MDI

useTablePopup

false

Whether to use the default table navigation popup when no popup is assigned as the form’s popupMenu.

view

 

The query or table on which the form is based

windowState

Normal

The state of the window (0=Normal, 1=Minimized, 2=Maximized)

 

Event

Parameters

Description

canClose

 

When attempting to close form; return value allows or disallows closure

canNavigate

<workarea expN>

When attempting to navigate in work area; return value allows or disallows leaving current record

onAppend

 

After a new record is added

onChange

<workarea expN>

After leaving a record that was changed, before onNavigate

onClose

 

After the form has been closed

onDragEnter

<left expN>
<top expN>
<type expC>
<name expC>

When the mouse enters the Form's display area during a Drag&Drop operation

onDragLeave

 

When the mouse leaves the Form's display area without having dropped an object

onDragOver

<left expN>
<top expN>
<type expC>
<name expC>

While the mouse drags an object over the Form's display area during a Drag&Drop operation

onDrop

<left expN>
<top expN>
<type expC>
<name expC>

When the mouse button is released over the Form's display area during a Drag&Drop operation

onMove

 

After the form has been moved

onNavigate

<workarea expN>

After navigation in a work area

onSelection

<control ID expN>

After the form is submitted

onSize

<expN>

After the form is resized or changes windowState

 

Method

Parameters

Description

abandonRecord( )

 

Abandons changes to the current record

beginAppend( )

 

Starts append of new record

close( )

 

Closes the form

isRecordChanged( )

 

Checks whether the current record buffer has changed

open( )

 

Loads and opens the form

pageCount( )

 

Returns the highest pageno of any component

print( )

 

Prints the form

readModal( )

 

Opens the form modally

refresh( )

 

Redraws the form

saveRecord( )

 

Saves changes to the current or new record

scroll( )

<horizontal expN>, <vertical expN>

Programatically scrolls the client area (the contents) of a form

showFormatBar( )

<expL>

Displays or hides the formatting toolbar

 

The following table lists the common properties, events, and methods of the Form class:

Property

 

Event

 

Method

enabled
height

helpFile

helpId

hWnd

left

mousePointer
pageno

statusMessage

s
ystemTheme
top

visible

width

beforeRelease
onClose
onDesignOpen

onGotFocus

onHelp

onLeftDblClick

onLeftMouseDown

onLeftMouseUp

onLostFocus

onMiddleDblClick

onMiddleMouseDown
onMiddleMouseUp

onMouseMove

onMouseOut

onMouseOver

onOpen

onRightDblClick

onRightMouseDown

onRightMouseUp
move( )

release( )

setFocus( )

Description

A Form object acts as a container for other visual components (also known as controls) and the data objects that are linked to them. Consequently, releasing a form object from memory automatically releases the objects it contains.

An object reference to all the visual components in a form is stored in its elements array. All of the visual components have a form property that points back to the form.

The form has a rowset property that refers to its primary rowset. Components can access this rowset in their event handlers generically with the object reference form.rowset. For example, a button on a form that goes to the first row in the rowset would have an onClick event handler like this:

function firstButton_onClick()

form.rowset.first() 

Note: With the exception of the onClose event, all Form events require the form to be open in order to fire.

If the form has more than one rowset, each one can be addressed through the rowset property of the Query objects, which are properties of the form. For example, to go to the last row in the rowset of the Query object members1, the onClick event handler would look like this:

function lastMemberButton_onClick()

form.members1.rowset.last() 

A form can consist of more than one page. One way to implement multi-page forms is to use the pageno property of controls to determine on which page they appear, and use a TabBox control to let users easily switch between pages. You may also use a NoteBook control to create a multi-page container in a form.

You can create two types of forms: modal and modeless. A modal form halts execution of the routine that opened it until the form is closed. When active, it takes control of the user interface; users can't switch to another window in the same application without exiting the form. A dialog box is an example of a modal form; when it is opened, program execution stops and focus can't be given to another window until the user closes the dialog box.

In contrast a modeless form window allows users to freely switch to other windows in an application. Most forms that you create for an application will be modeless. A modeless form window conforms to the Multiple Document Interface (MDI) protocol, which lets you open multiple document windows within an application window.

To create and use a modeless form, set the mdi property to true and open the form with the open( ) method. To create and use a modal form, set mdi to false and open the form with the readModal( ) method.

You can also create SDI (Single Document Interface) windows that appear like application windows. To do so, set the mdi property to false and use SHELL(false). SHELL(false) hides the standard dBASE Plus environment and lets your form take over the user interface. The dBASE Plus application window disappears, and the form name appears in the Windows Task List.