Skip to content

Commit 1ac17f3

Browse files
vdelachauxvdelachaux
committed
update class comboBox - add documentation
1 parent 3361212 commit 1ac17f3

File tree

9 files changed

+394
-80
lines changed

9 files changed

+394
-80
lines changed

‎UI/Documentation/Classes/comboBox.md

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
# comboBox
2+
3+
The`comboBox` class provides an interface to manage properties and actions of [Combo Box](https://developer.4d.com/docs/20/FormObjects/comboBoxOverview) widgets using an `Object` as data source.
4+
5+
The `comboBox` class is available via the [`form`](form.md#objects) class through the `ComboBox` interface.
6+
7+
```4d
8+
This.form:=cs.form.new(This)
9+
...
10+
This.myCombo:=This.form.DropDown("Combo Box"; {\ {values: ["apples"; "nuts"; "pears"; "oranges"; "carrots"]; \ ordered: True; \ automaticExpand: True; \ automaticInsertion: True})
11+
```
12+
13+
In the form editor, you set the *Variable or expression* property of the drop-down list to `formGetInstance.myCombo.data` and you can later do:
14+
15+
```4d
16+
// Get user selection
17+
var $value : Text:This.myCombo.value
18+
```
19+
20+
This class is, more generally, available from the `cs` class store, or `cs.ui` class store if you use the `UI` component:
21+
22+
```4d
23+
Form.Cities:=cs.ui.comboBox.new("Combo Box"; {\ values: ["Philadelphia"; "Pittsburg"; "Grand Blanc"; "Bad Axe"; "Frostbite Falls"; "Green Bay"]; \ ordered: True; \ automaticExpand: True; \ automaticInsertion: True})
24+
```
25+
26+
In the form editor, you set the *Variable or expression* property of the drop-down list to `Form.Cities.data` and you can later retrieve the user's selection like this:
27+
```4d
28+
// Get user selection
29+
var $value : Text:=Form.Cities.value
30+
```
31+
<br>
32+
<hr>
33+
34+
📌 <b>Important</b>
35+
36+
1. This class inherit from the [`dropDown`](dropDown.md) class
37+
2. To simplify the distinction between form objects and object type, this documentation uses the term `widget` for all form objects, whether static (a line, a rectangle…) or not (a button, a subform…).
38+
3. All functions that return `This` return the current *widget* object and can include one call after another.
39+
40+
41+
## <a name="Constructor">cs.comboBox.new()</a>
42+
43+
**cs.comboBox.new** ( ) : `cs.comboBox`
44+
<br>**cs.comboBox.new** ( *name* : Text ) : `cs.comboBox`
45+
<br>**cs.comboBox.new** ( *name* : Text ; *data* : Object ) : `cs.comboBox`
46+
<br>**cs.comboBox.new** ( *name* : Text ; *data* : Object ; *parent* : Object ) : `cs.comboBox`
47+
48+
|Parameter|Type||Description|
49+
|---|---|---|---|
50+
| name | Text | →| Widget name |
51+
| data | `Object` | → | Parameters to be used for the Combo Box management |
52+
| parent | **cs**.form | → | `form` object containing the *widget* |
53+
| result | **cs**.dropDown | ← | New `cs.dropDown`
54+
55+
### Description
56+
57+
`cs.comboBox.new()` creates & returns a new instance of the class.
58+
59+
* The optional `data` parameter is the object to be used as the data source of the drop-down list. The object contain the following properties:
60+
61+
|Parameter|Type| Mandatory |Description|
62+
|---|---|:---:|---|
63+
`automaticExpand` | Boolean | No | Enable list to be displayed on getting focus \*.<br>Default is **False**
64+
`automaticInsertion` | Boolean | No | Enable automatic insertion into the list in memory \*\*.<br>Default is **False**
65+
`currentValue` | same as `values` | No | Currently selected item (used as placeholder value if set by code)
66+
`index` | Integer | No | Index of the currently selected item (value from 0 to `values.length-1`).
67+
`ordered` | Boolean | No | Keep the list ordered.<br>Default is **False**
68+
`placeholder` | same as `values` | No | Default is `currentValue`
69+
`values` | Collection | Yes | Collection of scalar values. All values must be of the same type. <br>Supported types:<br>  • strings<br>  • numbers<br>  • dates<br>  • times<br>If empty or not defined, the drop-down list is empty.
70+
71+
* The optional `parent` parameter is the [`cs.form`](form.md) object containing the *widget*. This parameter is automatically set if instantiation is performed via a [form widget instantiation function](form.md#objects) of the `cs.form` class.
72+
* If the `name` parameter is ommited, the constructor use the result of **[OBJECT Get name](https://doc.4d.com/4Dv19/4D/19/OBJECT-Get-name.301-5392401.en.html)** (_Object current_ )
73+
74+
> ⚠️ Omitting the widget name can only be used if the constructor is called from the object method.
75+
76+
📌 The constructor checks that all values are of the same type. If this is not the case, an error is raised.
77+
78+
# Summary
79+
80+
## <a name="Inherited">Inherited Properties & Functions</a>
81+
82+
Inherited properties and functions are described in the parent classes:
83+
84+
* [`static` class](static.md)
85+
* [`widget` class](widget.md)
86+
* [`dropDown` class](dropDown.md)
87+
88+
## <a name="Properties">Properties</a>
89+
90+
|Properties|Description|Type|default|Writable|
91+
|:----------|:-----------|:-----------|:-----------|:-----------:|
92+
|**.automaticExpand** | Enable list to be displayed on getting focus\* | `Boolean` | **False** | <font color="green">✓</font>
93+
|**.automaticInsertion** | Enable automatic insertion into the list in memory\*\* | `Boolean` | **False** | <font color="green">✓</font>
94+
|**.filter** | Modify the entry filter | `Integer`\*\*\* \| `Text` | Depending on the type of values | <font color="green">✓</font>
95+
|**.ordered** | Does the values list always need to be sorted? | `Boolean` | **False** | <font color="green">✓</font>
96+
97+
<br>\*\*\* Use [4D constants](https://developer.4d.com/docs/commands/value-type) (possible values: _Is longint_, _Is real_, _Is time_ or _Is date_. Default is _Is text_) for default predefined formats or pass the filter definition as text.
98+
99+
## <a name="Functions">Functions</a>
100+
101+
| Functions | |
102+
|:-------- |:------ |
103+
|[.**expand**](#expand) ( { *expand* }) → `This`| Display the values list - to use in the On getting focus event
104+
|[.**insert**](#insert) ( { *item* }{; *order* }) → `This` | Insert an item (or the current value).<br>Sortes the list, if *order* is **True**, even if `ordered` property is **False**. <br>If *order* is omitted, the property `ordered` is used.
105+
|.**listModified** ( ) → `Boolean` | Returns **True** if the values list was modified by a call to the function `insert()`.
106+
107+
<hr>
108+
\* If **True**, the _On getting focus_ event is automatically activated for the widget, and you must call the [`.expand()`](#expand) function when this event is triggered.
109+
<br>\*\* If **True** you must call the [`.insert()`](#insert) function (without parameter) when the event _On data change_ is triggered.
110+
111+
# <a name="expand">.expand()</a>
112+
113+
.**expand** ( ) → `This`
114+
<br>.**expand** ( *force* ) → `This`
115+
116+
|Parameter|Type||Description|
117+
|---|---|---|---|
118+
| force | Boolean | → | Force expansion |
119+
| result | `This`| ← | Current widget object |
120+
121+
### Description
122+
123+
This function expands the list of values.
124+
125+
* If *force* is omitted, the `automaticExpand` property is used to allow or disallow expansion.
126+
* Must be call during the wiget's _On getting focus_ event like this, if the `automaticExpand` property is **True**:
127+
128+
```4D
129+
If (FORM Event.code=On Getting Focus) myCombo.expand() End if
130+
```
131+
# <a name="insert">.insert()</a>
132+
133+
.**insert** ( ) → `This`
134+
<br>.**insert** ( *item* ) → `This`
135+
<br>.**insert** ( *order* ) → `This`
136+
<br>.**insert** ( *item* ; *order*) → `This`
137+
138+
|Parameter|Type||Description|
139+
|---|---|---|---|
140+
| item | same as `values` | → | Item to be added to the list of values in memory|
141+
| order | same as `values` | → | Item to be added to the list of values in memory|
142+
| result | `This`| ← | Current widget object |
143+
144+
### Description
145+
146+
This function add an item to the list of values in memory & keep the list ordered if any.
147+
148+
* If *item* is omitted, the current `value` is used.
149+
* If *order* is omitted, the `ordered` property is used.
150+
* Could be call during the wiget's _On Data Change_ event like this:
151+
152+
```4D
153+
If (FORM Event.code=On Data Change) myCombo.insert() End if
154+
```
155+
* The widget's function can be called anywhere in the code to add one or more elements to the list of values:
156+
157+
```4D
158+
myCombo.insert("New Item")
159+
```
160+
161+
* In any case, when the widget is unloaded, the list of values is lost. If you wish, you can retrieve the collection of values in the `values` property and save it.
162+
163+
164+
165+

‎UI/Documentation/Classes/dropDown.md

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# dropDown
22

3-
The`dropDown` class provides an interface to manage properties and actions of [Drop-down List](https://developer.4d.com/docs/20/FormObjects/dropdownListOverview) widgets using an Object.
3+
The`dropDown` class provides an interface to manage properties and actions of [Drop-down List](https://developer.4d.com/docs/20/FormObjects/dropdownListOverview) widgets using an `Object` as data source.
44

55
The `dropDown` class is available via the [`form`](form.md#objects) class through the `DropDown` interface.
66

@@ -43,8 +43,8 @@ var $selected : Text:=Form.myDropDown. currentValue
4343

4444
**cs.dropDown.new** ( ) : `cs.dropDown`
4545
<br>**cs.dropDown.new** ( *name* : Text ) : `cs.dropDown`
46-
<br>**cs.dropDown.new** ( *name* : Text ; data : Object ) : `cs.dropDown`
47-
<br>**cs.dropDown.new** ( *name* : Text ; data : Object ; *parent* : Object ) : `cs.dropDown`
46+
<br>**cs.dropDown.new** ( *name* : Text ; *data* : Object ) : `cs.dropDown`
47+
<br>**cs.dropDown.new** ( *name* : Text ; *data* : Object ; *parent* : Object ) : `cs.dropDown`
4848

4949
|Parameter|Type||Description|
5050
|---|---|---|---|
@@ -61,10 +61,10 @@ var $selected : Text:=Form.myDropDown. currentValue
6161

6262
|Parameter|Type| Mandatory |Description|
6363
|---|---|:---:|---|
64-
`values` | Collection | Yes | Collection of scalar values. All values must be of the same type. Supported types:<br>• strings<br>• numbers<br>• dates<br>• times<br>If empty or not defined, the drop-down list is empty
65-
`index` | number | No | Index of the currently selected item (value between 0 and collection.length-1). If you set -1, currentValue is displayed as a placeholder string
66-
`currentValue` | same as Collection | No | Currently selected item (used as placeholder value if set by code)
67-
`placeholder` | same as Collection | No | Default is `currentValue` if exists
64+
`values` | Collection | Yes | Collection of scalar values. All values must be of the same type. <br>Supported types:<br>  • strings<br>  • numbers<br>  • dates<br>  • times<br>If empty or not defined, the drop-down list is empty.
65+
`index` | number | No | Index of the currently selected item (value from 0 to `values.length-1`). <br>If you set -1, `currentValue` is displayed as a placeholder string
66+
`currentValue` | same as `values` | No | Currently selected item (used as placeholder value if set by code)
67+
`placeholder` | same as `values` | No | Default is `currentValue`
6868

6969
* The optional `parent` parameter is the [`cs.form`](form.md) object containing the *widget*. This parameter is automatically set if instantiation is performed via a [form widget instantiation function](form.md#objects) of the `cs.form` class.
7070
* If the `name` parameter is ommited, the constructor use the result of **[OBJECT Get name](https://doc.4d.com/4Dv19/4D/19/OBJECT-Get-name.301-5392401.en.html)** (_Object current_ )
@@ -84,14 +84,16 @@ Inherited properties and functions are described in the parent classes:
8484

8585
|Properties|Description|Type|default|Writable|
8686
|:----------|:-----------|:-----------|:-----------|:-----------:|
87-
|**.value** | Currently selected item | same as Collection | | <font color="green">✓</font>
8887
|**.index** | Currently selected index | `Integer` | -1 | <font color="green">✓</font>
89-
|**.placeholder** | The placeholder to use if no item selected | same as Collection | `currentValue` | <font color="green">✓</font>
88+
|**.placeholder** | The placeholder to use if no item selected | same as `values` | `currentValue` | <font color="green">✓</font>
89+
|**.value** | Currently selected item | same as `values` | | <font color="green">✓</font>
90+
|**.valueType** | The type of the `values` ([4D constants](https://developer.4d.com/docs/commands/value-type))| `Integer` | | <font color="red">x</font>
9091
|**.values** | The collection of scalar values used as datasource| `Collection` | [ ] | <font color="green">✓</font>
9192

9293
## <a name="Functions">Functions</a>
9394

9495
| Functions | |
9596
|:-------- |:------ |
96-
|.**clear** () | Unselect item & restore the placeholder
97-
|.**reinit** ( *data* ) | Uses the passed object to redefine the datasource of the dropdown.
97+
|.**clear** ( ) | Unselect item & restore the placeholder if any.
98+
|.**reset** ( *data* ) | Uses the *data* object to reset the widget.
99+
|.**restore** ( ) | Restores the last definition\* of the widget data.<br>\*automatically saved at instantiation or by calling the `.reset( )` function.

‎UI/Project/Sources/Classes/comboBox.4dm

Lines changed: 80 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,6 @@ Class constructor($name : Text; $data : Object; $parent : Object)
44

55
Super:C1705($name; $data; $parent)
66

7-
// TODO: Check that values is a scalar collection of text
8-
97
If (Bool:C1537($data.ordered))
108

119
This:C1470.order()
@@ -18,6 +16,8 @@ Class constructor($name : Text; $data : Object; $parent : Object)
1816

1917
End if
2018

19+
This:C1470.filter:=Num:C11(This:C1470.data.type)
20+
2121
// <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <== <==
2222
Function get automaticExpand() : Boolean
2323

@@ -108,6 +108,55 @@ Function set filter($filter)
108108

109109
End if
110110

111+
// === === === === === === === === === === === === === === === === === === === === === === === === === ===
112+
Function setFilter($filter)
113+
114+
var $separator : Text
115+
116+
If (Value type:C1509($filter)=Is longint:K8:6)\
117+
| (Value type:C1509($filter)=Is real:K8:4) // Predefined formats
118+
119+
Case of
120+
121+
//………………………………………………………………………
122+
: ($filter=Is integer:K8:5)\
123+
| ($filter=Is longint:K8:6)\
124+
| ($filter=Is integer 64 bits:K8:25)
125+
126+
OBJECT SET FILTER:C235(*; This:C1470.name; "&\"0-9;-;+\"")
127+
128+
//………………………………………………………………………
129+
: ($filter=Is real:K8:4)
130+
131+
GET SYSTEM FORMAT:C994(Decimal separator:K60:1; $separator)
132+
OBJECT SET FILTER:C235(*; This:C1470.name; "&\"0-9;"+$separator+";.;-;+\"")
133+
134+
//………………………………………………………………………
135+
: ($filter=Is time:K8:8)
136+
137+
GET SYSTEM FORMAT:C994(Time separator:K60:11; $separator)
138+
OBJECT SET FILTER:C235(*; This:C1470.name; "&\"0-9;"+$separator+";:\"")
139+
140+
//………………………………………………………………………
141+
: ($filter=Is date:K8:7)
142+
143+
GET SYSTEM FORMAT:C994(Date separator:K60:10; $separator)
144+
OBJECT SET FILTER:C235(*; This:C1470.name; "&\"0-9;"+$separator+";/\"")
145+
146+
//………………………………………………………………………
147+
Else
148+
149+
OBJECT SET FILTER:C235(*; This:C1470.name; "") // Text as default
150+
151+
//………………………………………………………………………
152+
End case
153+
154+
Else
155+
156+
OBJECT SET FILTER:C235(*; This:C1470.name; String:C10($filter))
157+
158+
End if
159+
111160
// === === === === === === === === === === === === === === === === === === === === === === === === === ===
112161
Function order() : cs:C1710.comboBox
113162

@@ -117,9 +166,9 @@ Function order() : cs:C1710.comboBox
117166

118167
// === === === === === === === === === === === === === === === === === === === === === === === === === ===
119168
// Display the selection list (to use in the On getting focus event)
120-
Function expand() : cs:C1710.comboBox
169+
Function expand($force : Boolean) : cs:C1710.comboBox
121170

122-
If (This:C1470.data.automaticExpand)
171+
If (This:C1470.data.automaticExpand | $force)
123172

124173
POST KEY:C465(Down arrow key:K12:19; 0 ?+ Command key bit:K16:2)
125174

@@ -130,32 +179,42 @@ Function expand() : cs:C1710.comboBox
130179
// === === === === === === === === === === === === === === === === === === === === === === === === === ===
131180
// Insert an item or the current value.
132181
// Keep the list ordered if any
133-
Function insert($item; $ordered : Boolean) : cs:C1710.comboBox
182+
Function insert($item; $sort : Boolean) : cs:C1710.comboBox
134183

135-
If (Value type:C1509($1)=Is text:K8:3)
184+
If (Count parameters:C259=0)\
185+
|| (Value type:C1509($1)=Is boolean:K8:9)
136186

137-
var $value : Text:=$item
187+
var $value : Variant:=This:C1470.value
188+
$sort:=Count parameters:C259=1 ? $1 : Bool:C1537(This:C1470.ordered)
138189

139190
Else
140191

141-
$value:=This:C1470.data.currentValue
192+
$value:=$item
193+
194+
End if
195+
196+
If (Length:C16($value)=0)
197+
198+
return
142199

143200
End if
144201

145-
var $index : Integer:=This:C1470.data.values.indexOf($value)
202+
var $values:=This:C1470.values
203+
var $index : Integer:=$values.indexOf($value)
146204

147205
If ($index=-1)
148206

149-
This:C1470.data.values.push($value)
207+
$values.push($value)
150208

151-
If ($ordered || This:C1470.data.ordered)
209+
If ($sort)
152210

153-
This:C1470.data.values:=This:C1470.data.values.orderBy()
154-
$index:=This:C1470.data.values.indexOf($value)
211+
$values:=$values.orderBy()
212+
$index:=$values.indexOf($value)
155213

156214
End if
157215
End if
158216

217+
This:C1470.data.values:=$values
159218
This:C1470.data.index:=$index
160219

161220
return This:C1470
@@ -165,6 +224,14 @@ Function listModified() : Boolean
165224

166225
return Not:C34(This:C1470.data.values.equal(This:C1470._backup.values))
167226

227+
// === === === === === === === === === === === === === === === === === === === === === === === === === ===
228+
/// ⚠️ Overrides the parent class function
229+
Function reset($data : Object)
230+
231+
Super:C1706.reset($data)
232+
233+
This:C1470.filter:=Num:C11(This:C1470.data.type)
234+
168235
// MARK:-
169236
// *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** *** ***
170237
// Set On Getting focus event, if any

0 commit comments

Comments
 (0)