cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseForm
------------------------DfBaseEntry
---------------------------Entry
------------------------------dbForm_
---------------------------------dbFormDS
------------------------------------dbForm
---------------------------------------dbFormExternalControl
---------------------------------------dbSuggestionForm
The dbForm class is used to support data entry for one table column via an Entry_Item.
Related controls are dbComboForm, dbSuggestionForm, dbCheckBox, dbSpinForm.
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"
End_Object
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
End_Object
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
End_Function
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
End_Object
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
:
End_Procedure
Procedure OnSetFocus
:
End_Procedure
Procedure OnKillFocus
:
End_Procedure
End_Object
// 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
:
End_Procedure
Procedure OnSetFocus
:
End_Procedure
Procedure OnKillFocus
:
End_Procedure
End_Object
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.
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.
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= |
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.
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.
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.
| 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 |