Class: dbForm

Properties  Events  Methods    Index of Classes

Supports data entry for one table column



Library: Windows Application Class Library

Package: Dfentry.pkg

Mixins: Extended_DEO_Mixin Extended_DEO_Status_Help_Mixin Extended_DEO_Prompt_Mixin Extended_DEO_Status_Help_Tooltip_Mixin


The dbForm class is used to support data entry for one table column via an Entry_Item.

Related controls are dbComboForm, dbSuggestionForm, dbCheckBox, dbSpinForm.

Standard Data Binding

Use dfEntry.pkg

Object MyForm is a DbForm
    Set Size to 13 100
    Set Location to 15 70

    Entry_Item Customer.Address

    Set Label to "Address"


You can use an Expression for the Entry_Item, which can be a straightforward calculation (see sample below). When used with an expression, the dbForm will be read only.

Object MyExpression is a DbForm
    Set Size to 13 100
    Set Location to 15 70

    Entry_Item (Customer.Balance / 12)

    Set Label to "Average"
    Set Currency_Mask to 8 2


You can call a Function in an Entry_Item, which can perform much more complex calculations and return a result (see sample below). When used with a function, the dbForm will be read only.

Function SampleFunc Returns Number
    Number nResult
    // perform calculation, look up, etc
    Function_Return nResult

Object MyExpression is a DbForm
    Set Size to 13 100
    Set Location to 15 70

    Entry_Item (SampleFunc(Self))

    Set Label to "Average"
    Set Currency_Mask to 8 2


Use dfEntry.pkg

// when data field is connected to a DataDictionary object (DDO)
Object oObjectName is a dbForm
    Set Size to Height Width
    Set Location to Row Column

    // Server is often inherited from parent object instead of being set here
    Set Server to DDOName

    Entry_Item Table.Column

    Set Label to text
    Set Label_Justification_Mode to mode
    Set Label_Row_Offset to Num
    Set Label_Col_Offset to Num
    Set Enabled_State to True | False

    Procedure OnChange

    Procedure OnSetFocus

    Procedure OnKillFocus


// when connected to data-dictionary objects or using a variable or expression:
Object oObjectName is a dbForm
    Set Size to Height Width
    Set Location to Row Column

    Entry_Item { variable | expression }

    Set Label to text
    Set Label_Justification_Mode to mode
    Set Label_Row_Offset to integer
    Set Label_Col_Offset to integer

    Set Form_DataType to mode
    Set Form_Margin to mode
    Set Form_Mask to mask-string
    Set Numeric_Mask to leftDigits rightDigits {template}
    Set Currency_Mask to leftDigits rightDigits {template}

    Set Enabled_State to true|false
    Set Status_Help to text

    Procedure OnChange

    Procedure OnSetFocus

    Procedure OnKillFocus



Although this object is is complex and contains many messages, its actual usage is quite simple. When this class is used in conjunction with data dictionaries, very few properties need to be set within this object. Usually a dbForm object will contain a label, a size, and location setting, and an Entry_Item statement.

DbForms should always be placed inside a dbView object or a data-aware container (dbContainer3d, dbGroup, dbTabPage, dbTabView). The DataDictionary used by the entry form should be above the entry form in the source code and inside the entry-view container.

DbForms can be used for entry to fields of all types except Text and Binary.

Data Entry Object

This object is a data entry object (DEO). A DEO is an object (in this case a form) whose native capabilities are augmented with data-aware behaviors. These behaviors include:

These data-aware "skills" are added to all DEO classes through a series of mix-in classes. The messages are listed here but documented in the mix-in classes. You are encouraged to study the documentation of the mix-in classes. Information provided in the documentation of these classes may be applied to all DEO classes (all db... classes). Those classes are: Nesting_Mixin, Navigate_Mixin, Verify_Mixin, Server_Mixin, Find_Edit_Mixin, Entry_Item_Mixin, DEO_Delegate_Mixin, Validate_Mixin and Clear_Defaults_Mixin.


This class supports input and display masking for a variety of data types (text, numeric, currency, and dates). When using data dictionaries, the mask and mask type of an object will usually be defined within the data file's data-dictionary subclass. The only time you will need to deal with masks is when you are creating masks for non-data-dictionary-based objects (expressions and variables).

When manually setting masks, the type of masking used is determined by the object's Form_DataType (which supports both masked and non-masked types) and the object's Form_Mask. Two additional messages, set Currency_Mask and set Numeric_Mask make it particularly easy to define currency and numeric data types and fields with a single message.

Setting Entry Parameters for Columns

Previous revisions of DataFlex allowed you to set column parameters by placing special parameters on the entry_item command line. These options would be placed inside French braces (Entry_Item Table.Column {capslock, iPrompt =(myObj(Self)), iEntry =msg_MyMessage} ). Data Dictionaries all but obviate the need for these settings. Normally these settings can and should be placed inside your DataDictionary subclasses. In addition, the Studio does not support the use of these command-line options.

In the rare case where you need to set any of these options for columns within your data-entry object, a complete interface is provided for getting and setting any of them. The single-item data-entry classes (such as this class) use one set of messages for setting these parameters, while the row-based data-entry classes provide a parallel set of messages for setting these parameters on a column-by-column basis. These messages are documented in the datalist class. Below is a summary of all these messages. This list shows the single-item-based message, its equivalent row-based message, and the entry_item option it replaces. Each of these messages supports a get and a set syntax.

Form-Based Messages dbForm, dbComboForm Grid Column-Based Messages dbGrid, dbList Old Entry_Item {option} (no longer used)
Item_Options Column_Options Required, FindReq, NoEnter, NoPut, DisplayOnly, AutoFind, etc.
Item_Option Column_Option (same as above)
Enabled_State (formerly object_shadow_state) Column_Shadow_State DisplayOnly
Capslock_State Column_Capslock_State Capslock
Prompt_Object Column_Prompt_Object iPrompt=
Zoom_Object Column_Zoom_Object iZoom=
Item_Entry_msg Column_Entry_msg iEntry=
Item_Exit_msg Column_Exit_msg iExit=
Item_Validate_msg Column_Validate_msg iValidate=

Prompt Buttons

This class automatically supports prompt buttons. If a prompt object is defined for this object, a prompt button will appear automatically in it. When the button is pressed, the prompt message will be sent and a prompt object (usually a selection list) will appear. Prompt objects are usually acquired from the data-dictionary object, but may be explicitly defined by setting the Prompt_Object property.

If you do not want automatic prompt-button creation, this feature may be disabled by setting the property Prompt_Button_Mode to PB_PromptOff. A prompt button may be explicitly created by setting the prompt_button_mode property to PB_PromptAuto.


Forms often require an associated description or label. Most-often, these appear to the left of the form. Labels are supported with the label message. The default location and justification mode of labels can be controlled with the properties Label_Col_Offset, Label_Row_Offset and Label_Justification_Mode. If this object is connected to a server and its Auto_Label_State is set true, the label value, if any, will be overridden by the value of a field property in the Ddo.

The Server

All dbForm objects should always be connected to a Server (a DataDictionary object). While the server can be explicitly set within the object, it will usually be set within a parent (or other ancestor) container object.

Using Data Dictionaries

When this object's server is a data dictionary, this object will acquire a great deal of "knowledge" from the server. It will "know" data types, input masks, status-help and prompt objects, validation rules, entry rules, exit rules, display formats (capslock, noput, displayonly, etc.) and much more regarding the data file and its fields. If you use data sets, these settings may all be controlled by setting properties. While possible, this requires a great deal more work and greatly increases the chance of errors and inconsistencies.

Accelerator Keys

Name Message Sent
kbegin_of_data beginning_of_data
kbegin_of_panel beginning_of_panel
kcancel request_cancel
kclear request_clear
kclear_all request_clear_all
kdelete_record request_delete
kend_of_data end_of_data
kend_of_panel end_of_panel
kexit_function exit_function
kfind find_ge
kfind_next find_next
kfind_previous find_previous
kprompt prompt
ksave_record request_save
ksuper_find superfind
ksuper_find_next superfind_next
ksuper_find_previous superfind_previous
kswitch switch
kswitch_back switch_back
kswitch_panel switch_next_group
kswitch_panel_back switch_prior_group
kzoom zoom