Class: dbComboForm

Properties  Events  Methods    Index of Classes

Provides general-purpose comboform DEOs

Hierarchy

cObject
---cUIObject
------DfBaseObject
---------DfBaseWindow
------------DfBaseUIWindow
---------------DfBaseControl
------------------DfBaseList
---------------------DfBaseForm
------------------------DfBaseEntry
---------------------------DfBaseComboBoxEntry
------------------------------ComboEntry
---------------------------------dbBasicComboForm_
------------------------------------dbBasicComboForm
---------------------------------------dbDataComboForm
------------------------------------------dbComboFormDS
---------------------------------------------dbComboFormDD_
------------------------------------------------dbComboForm
---------------------------------------------------dbParentCombo

Library: Windows Application Class Library

Package: Dfcentry.pkg

Mixins: Extended_Deo_dfCombo_mixin

Description

dbComboForm is used to provide general-purpose comboform data entry objects (DEOs). This class optionally supports separate values for display and database storage. When used with a DataDictionary (the typical use), the list of combo data and display values is loaded automatically. When Entry_State is True, the list is a dropdown edit list (data entry is permitted in the form). When Entry_State is False, the list is a dropdown list (the form can only be filled with an item selected from the list).

A dbComboForm really consists of two components, a form and a list. The form behaves similarly to a dbForm. It is single-item and supports the standard single-item interface. When a dbForm-class object has the focus, it will accept data from the keyboard directly into the value of the item. The value can also be directly changed and retrieved with the get and set value messages (get/set value 0 to val).

One way in which this class is not like a dbForm is that it does not support masking. In addition, entry validation support is limited. The intent of this class is mostly to allow a user to select from a predefined list of values. For more complicated uses, you should probably look at alternative classes, such as dbForm, cDbCJGridPromptList and dbRadioGroup,

Sample

Object Orderhea_VIA is a dbComboForm
    Entry_Item Orderhea.Via 
    set Entry_State to True
    Set Location to 64 146
    Set Size to 13 95
    Set Label to 'Ship Via:'
End_Object



Syntax

Object oObjectName is a dbComboForm 
    Set Location to vertical horizontal
    Set Size to height width
    Entry_Item table.column
    Set Label to text
    Set Entry_State to true|false
    Set Enabled_State to true|false
    Set Code_Display_Mode to DisplayMode
    Set Combo_Sort_State to true|false
 
// when used with a server, the following may be used
    Set Auto_Label_State to true
 
// when used with no server, the following may be used
    Set Status_Help to StatusHelpText
    Set Allow_Blank_State to true|false
 
    Procedure Combo_Fill_List
        Send Combo_Add_Item [DisplayValue] DataBaseValue
        :
    End_Procedure
or:
    Set Combo_Data_File to table_number
    Set Code_Field to column_number
    Set Combo_Index to index_number
    Set Description_Field to field_number
End_Object



Of Special Note

A dbComboForm object is associated with a single data element which is assigned with the Entry_Item command. Each value in the dropdown list is a valid value for the entry item. The current value is displayed in the form. This class supports the separation of display value and database value. Each valid choice is defined with a data value (the value that is read and written to the database) and a description (the text value that is displayed in the form and the list). This separation is optional; the data value and description value may be the same. When using a data-dictionary these value are supplied automatically. When not using the data dictonary, the list must be filled within the object with the Combo_Fill_List procedure.

ComboForm Height and Vertical Label Location

The height of a ComboForm (or dbComboForm) is more or less fixed by Windows, so you could technically set the height to be anything and the combo form itself would look the same. e.g.

Set Size to 13 95
Set Size to 60 95

The two lines of code above would produce a combo form that looks identical.

However, the Label (Label_Object) of a combo form is positioned to be centered with the height, so we recommend keeping the height always at 13 for consistent label height centering.

If you must set a different height, you can set the Label_Row_Offset to determine the label's vertical location.

Set Label_Row_Offset to 1


Sorting the Combo List

By default the combo list is displayed in sorted order. This can be disabled by setting the Combo_Sort_State property to False.

Navigating with Arrow Keys

By default, the up and down arrow keys navigate within the dropdown list. This can be changed to navigate between rows in the grid by setting the pbComboNavigation property to False.

Combo Lists vs. Selection Lists

Combo lists (dbComboForm) should not be used in place of selection lists (cDbCJGridPromptList). Normally, selection lists should be used to look up records from a database (both main files and parent files) and combo lists should be used to find static choices provided from validation tables. Popup selection lists are used to look up data that is potentially large and potentially dynamic. In addition, selection lists support a number of flexible multi-index search capabilities that make it easy to find data. For example, a customer lookup should use a dbList.

A combo list is designed to be used with static data. The list is loaded once and does not change. When using data dictionaries, this distinction is very clear. Selection lists are used to find data from data files. Combo forms should be used to find data from validation tables.

Display Value and Database Value

A combo list may display the database values, the description values, or both. The property Code_Display_Mode determines what is displayed. Valid modes are CB_Code_Display_Description (the default-displays the description), CB_Code_Display_Code (displays the code), and CB_Code_Display_Both (displays the code followed by the description). A list may contain only codes, in which case the code is displayed regardless of the code_display_mode. The default display-description mode is the most-flexible setting. It supports a complete separation of display and data.

Entry State of Forms

The Entry_State (Item 0) of the form determines how keyboard interaction is handled. When true (the default), normal entry is allowed into the form. This is referred to as a dropdown-edit list. When set to false, the value in the form must match a value from the list and keyboard input performs an incremental search. This is referred to as a dropdown list.

The Size of a dbComboForm

The height of the form component is determined by Windows and is 13 dialog units. This cannot be changed. The maximum height of the list is determined by the ListRowCount property and defaults to 10. Therefore the actual height you enter when setting the size property does usually not matter because it will be set by the by the object using ListRowCount. It is normally set to 13 making it easy to convert dbForms into dbCombForms without having to remember to change the size property.

Shadowing

This class supports object shadowing. Objects of this class can either be explicitly shadowed (set enabled_state) or shadowed implicitly when an ancestor object is shadowed. When shadowed, access to the form and the dropdown list is disabled.

Labels

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. If this object is connected to a data dictionary, you can use field-property values in the DDO by setting the Auto_Label_State property true. These will override any label values you may have set in this object. The default location and justification mode of labels can be controlled with the properties Label_Col_Offset, Label_Row_Offset, and Label_Justification_Mode.

Validation of Entries

When used with data dictionaries, the combo form is not used for data validation. The data dictionary handles all validation. When used without data dictionaries, a message is provided for validating the value against the combo list. The item-validation function Validate_Combo_Item may be used to report an error if the form value does not match a value in the list. It will respect the Allow_Blank_State property, which allows a blank entry. This is only required when entry_state is false. When entry_state is true, the value in the form will always match a value from the combo list.

Entry_Item Orderhea.Via {iValidate =get_Validate_Combo_item}
Set Entry_State to False
Set Allow_Blank_State to True // empty is OK



Again, note that this type of validation should never be used with data dictionaries. Data dictionaries do this for you (another good reason to use them).