Table of Contents
22.5.4 Class DataCombo (gb.db.form)
You can use this control to edit the value of a field via another table whose primary key is this field. The use of a DataCombo only makes sense if at least two DB tables are used in the project.
The use of a DataCombo ensures that only correct field values (from table A) can be entered in table B. For this to work, you must ensure that you declare and observe suitable conditions for the corresponding field when defining the table: You can use this control to edit the value of a field via another table whose primary key is this field.
Schema table A:
CREATE TABLE "color" ( "color" INTEGER PRIMARY KEY AUTOINCREMENT, "name" VARCHAR(32), ... )
Schema table B:
CREATE TABLE "test" (
"id" BIGINT NOT NULL ,
"color" INT4 NOT NULL DEFAULT 1,
"firstname" VARCHAR(16),
"name" VARCHAR(32),
"birth" DATETIME,
"active" BOOL,
"salary" FLOAT8,
"comment" TEXT,
"image" BLOB ,
PRIMARY KEY ("id")
)
The class can be created. To create a new DataCombo:
Dim hDataCombo As DataCombo hDataCombo = New DataCombo ( Parent As Container ) As "event name"
22.5.4.1 Properties
The DataCombo class has the following properties:
| Property | Data type | Description |
|---|---|---|
| Action | String | Returns or sets the action string assigned to the control → Chapter 12.3.3 Action. |
| All | String | Defines an additional element that is displayed as the first entry in the DataCombo list. You can also read the value of the property. |
| Background | Integer | Returns or sets the background colour used by the control. |
| Table | String | Returns or sets the name of the table used to display the DataCombo and populate the popup list. This table must have a primary key whose name matches the content of the field property. The table content can be filtered using the Filter property. |
| Value | Variant | Sets the primary index of the table that was defined via the DataCombo.Table property and has nothing to do with what is displayed in the DataCombo! You can also read the value of the property. |
| Display | String | Supplies or sets the name of the field in the table defined by the `Table` property that is used to display the data. |
| Field | String | Supplies or sets the field used by the DataCombo. The data comes from the first parent DataSource. |
| Filter | String | Supplies or sets an SQL WHERE clause that filters the content of the combo list. |
| Modified | Boolean | Returns True if the content in the DataCombo has changed. |
| ReadOnly | Boolean | Sets the mode of the DataCombo to 'ReadOnly' with True. You can also read out the value. |
| Valid | Boolean | Returns True if the content of the control is valid. |
Table 22.5.4.1.1 : Properties of the DataCombo class
22.5.4.2 Methods
The DataCombo class only has two relevant methods:
- GetFilter( ): Returns the SQL WHERE clause used in the DataCombo filter as the string “FieldName = 'Filter' ”.
- Update( ): Reloads the (current) content of the DataCombo list.
22.5.4.3 Events
The DataCombo class only has these two significant events:
- Click (): The event is triggered when an entry in the DataCombo is selected.
- Validate ( Value As Variant ): The event is triggered when the content of the DataCombo needs to be validated before saving. `Value` is the value to be checked from the DataCombo list. This event allows the user to define specific validation requirements. To invalidate the data, simply stop the event with STOP EVENT.
22.5.4.4 Example
The example demonstrates the selection of a colour from a DataCombo. The upper table contains the selectable colours (“Black”, “White”, “Red”, “Green”, “Blue”, “Yellow” and “Transparent”). This colour table does not have to be displayed - this is only for demonstration purposes. All values of the `color` field of the colour table form the content of the DataCombo list:
Figure 22.5.4.4.1: DataCombo control element
If you want to generate and output your own error messages, you should use the Validate event:
Public aColor As String[] = ["Black", "White", "Red", "Green", "Blue", "Yellow", "Transparent"] ... Public Sub DataCombo1_Validate(Value As Variant) If Not aColor.Exist(Value) Then Message.Error("Die Farbe ist nicht zulässig!") Stop Event Endif End
The 'Stop Event' instruction ensures that, for example, NULL is entered as the value for the update for the invalid colour orange:
UPDATE "test" SET "id" = 3, "color" = NULL, "firstname" = 'Frédéric', ... , WHERE "id" = 3
However, this results in an error for the example during the update because at least one field condition for the “colour” field is not fulfilled (→ NOT NULL):
CREATE TABLE "test" ( "id" BIGINT NOT NULL , "color" INT4 NOT NULL DEFAULT 1, "firstname" VARCHAR(16), "name" VARCHAR(32), "birth" DATETIME, "active" BOOL, "salary" FLOAT8, "comment" TEXT, "image" BLOB , PRIMARY KEY ("id") )
Without the use of the Validate event for the DataCombo, internal error handling also takes effect because when the data record is updated, the system obviously checks whether the entered field value - in the above example in the (colour) table - is contained or a field condition is violated. A general, correctly formulated error message is displayed in English:
Figure 22.5.4.4.2: The data set cannot be changed: Cancellation due to violation of restrictions