1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
|
<html>
<body>
<h1> DAD: Dynamic Attribute Dialogs </h1>
<h2> Input widgets </h2>
<p>
Input widgets are leaf widgets in the widget tree that typically
implement a field where user input takes place. Available
input widgets are:
<table border=1 cellspacing=0 cellpadding=5>
<tr><th>creation call <th> screenshot (gtk2) <th> description
<tr><td>PCB_DAD_LABEL <td> <img src="wlabel.png"> <td> single line or multi line of plain text, from a string
<tr><td>PCB_DAD_LABELF <td> <img src="wlabel.png"> <td> single line or multi line of plain text, using printf formatting
<tr><td>PCB_DAD_ENUM <td> <img src="wenum.png"> <td> select one value from a fixed set (typical implementation is a combo box)
<tr><td>PCB_DAD_BOOL <td> <img src="wbool.png"> <td> checkbox
<tr><td>PCB_DAD_INTEGER <td> <img src="winteger.png"> <td> set an integer value
<tr><td>PCB_DAD_REAL <td> <img src="wreal.png"> <td> set a real (floating point) value
<tr><td>PCB_DAD_COORD <td> <img src="wcoord.png"> <td> set a coordinate value
<tr><td>PCB_DAD_STRING <td> <img src="wstring.png"> <td> input single line string value (plain text)
<tr><td>PCB_DAD_BUTTON <td> <img src="wbutton.png"> <td> clickable push button
<tr><td>PCB_DAD_PROGRESS <td> <img src="wprogress.png"> <td> progress bar
<tr><td>PCB_DAD_TREE <td> <img src="wtree.png"> <td> a list, table or tree of text data
<tr><td>PCB_DAD_PREVIEW <td> <img src="wpreview.png"> <td> drawing area
<tr><td>PCB_DAD_PICTURE <td> <img src="wpicture.png"> <td> static bitmap image
<tr><td>PCB_DAD_PICBUTTON<td> <img src="wpicbtn.png"> <td> static bitmap button
<tr><td>PCB_DAD_COLOR <td> <img src="wcolor.png"> <td> color button and selector
<tr><td>PCB_DAD_TEXT <td> <img src="wtext.png"> <td> text box (text editor)
</table>
<h3>PCB_DAD_LABEL(table, text)</h3>
<p>
Draw a label, which is not an input field (unmodifiable by the user).
<i>text</i> is copied by the call into a new allocation. The only
control <i>text</i> accepts is '\n', which is line break.
<h3>PCB_DAD_LABELF(table, (printf_args))</h3>
<p>
Same as PCB_DAD_LABEL() but the text is rendered using printf. Note:
printf args, including the format string, shall be in parenthesis, e.g.
<pre>
PCB_DAD_LABELF(dlg, ("Cats: %d", num_cats))
</pre>
<h3>PCB_DAD_ENUM(table, choices)</h3>
<p>
The user can choose one value out of an ordered list of strings. The list
is passed as a NULL terminalte char * array. The <i>value</i>
of the enum is an integer index into that array, 0 being the first string.
<p>
Typical GUI implementation is a combo box, without text editing.
<h3>PCB_DAD_BOOL(table, label)</h3>
<p>
Ask the user about a boolean value, typically using a checkbox. The <i>value</i>
of the bool is an integer which is either 0 or 1.
<h3>PCB_DAD_INTEGER(table, label)</h3>
<p>
Ask for an integer value, between a <i>minval</i> and a <i>maxval</i>.
The <i>value</i> is an int, which is not guaranteed to be wider than a
16 bit signed value.
<p>
Typical GUI implementation is a text entry, often upgraded with small buttons
to increase or decrease the value ("spinbox").
<h3>PCB_DAD_REAL(table, label)</h3>
<p>
Ask for a REAL (double precision floating point value), between a <i>minval</i>
and a <i>maxval</i>.
<p>
Typical GUI implementation is a text entry, often upgraded with small buttons
to increase or decrease the value ("spinbox").
<h3>PCB_DAD_COORD(table, label)</h3>
<p>
Ask for a coordinate value, between a <i>minval</i> and a <i>maxval</i>.
The <i>value</i> is pcb_coord_t.
<p>
Typical GUI implementation is a text entry that understands unit suffix,
often upgraded with small buttons to increase or decrease the value ("spinbox").
<h3>PCB_DAD_STRING(table)</h3>
<p>
Ask for a single line of plain text input.
<p>
The <i>value</i> is a dynamically allocated string.
<h3>PCB_DAD_BUTTON(table, text)</h3>
<p>
A push button the user can click on. <i>text</i> is not allocated or copied
(shall be a static const string or allocated/free'd by the user).
<p>
There is no <i>value</i>, the only interface is the <i>change callback</i>.
<h3>PCB_DAD_PROGRESS(table)</h3>
<p>
Present a progress bar which is not an user input. <i>value</i> is a
REAL value between 0.0 and 1.0. When the code changes the value, the
GUI makes sure the dialog box is drawn and flushed, because typical use
is in a busy loop calculation.
<h3>PCB_DAD_TREE(table, cols, first_col_is_tree, opt_header)</h3>
<p>
Present a tree-table with <i>cols</i> columns of text objects. When
<i>first_col_is_tree</i> is 1, the first column works as a tree, with
indentation and/or tree graphics and logics for collapsing/expanding subtrees.
If <i>opt_header</i> is not NULL, it is a NULL terminated static const
array of header strings describing the table header to be displayed, in as
many strings as <i>cols</i> specified.
<p>
A special cases:
<p>
<table border=1 cellspacing=0>
<tr><th> case <th> parameters
<tr><td> plain flat list <td> <i>cols</i>=1, <i>first_col_is_tree</i>=0
<tr><td> tree-only <td> <i>cols</i>=1, <i>first_col_is_tree</i>=1
<tr><td> table-only <td> <i>cols</i>>1, <i>first_col_is_tree</i>=0
</table>
<p>
Manipulating the data and the view are both done using
<a href="tree.html"> special tree-table macros</a>.
<h3>PCB_DAD_PREVIEW(table, expose_cb, mouse_cb, free_cb, initial_view_box, user_ctx)</h3>
<p>
Present a drawing area with callbacks to the host code to handle drawing:
<table border=1 cellspacing=0>
<tr><th> argument <th> meaning
<tr><td> expose_cb <td> called when (parts of) the preview needs to be redrawn
<tr><td> mouse_cb <td> called on mouse events
<tr><td> free_cb <td> called before the widget is destroyed
<tr><td> initial_view_box <td> set the initial zoom/pan to match the view box specified in drawing units
<tr><td> min_sizex_px <td> widget minimum size in x direction (width), in pixels
<tr><td> min_sizey_px <td> widget minimum size in y direction (height), in pixels
<tr><td> user_ctx <td> opaque pointer that is passed to every callback
</table>
<h3>PCB_DAD_PICTURE(table, xpm)</h3>
<p>
The pointer to a static xpm image is stored in the enumerations field. The image
is displayed in a widget without any other decoration.
<h3>PCB_DAD_PICBUTTON(table, xpm)</h3>
<p>
The pointer to a static xpm image is stored in the enumerations field. The image
is displayed in a button tat behaves exaclty as a normal BUTTON in all other
regards.
<h3>PCB_DAD_COLOR(table)</h3>
<p>
A button that has a solid region of the color specified in value. Unless
read-only (PCB_HATF_CLR_STATIC), when the user clicks the button a
HID-specific color selector dialog is popped up where the user can
specify a new color.
<h3>PCB_DAD_TEXT(table, cols, first_col_is_tree, opt_header)</h3>
<p>
Free form multiline text string, edited using a HID-builtin text editor. Line
terminator is \n.
<p>
TODO: accessor macros
<h2> Layout widgets </h2>
<table border=1 cellspacing=0 cellpadding=5>
<tr><th>creation call <th> screenshot (gtk2) <th> description
<tr><td>PCB_DAD_BEGIN_HBOX <td> <img src="whbox.png"> <td> arrange children widgets in a horizontal list
<tr><td>PCB_DAD_BEGIN_VBOX <td> <img src="wvbox.png"> <td> arrange children widgets in a vertical list
<tr><td>PCB_DAD_BEGIN_HPANE <td> <img src="whpane.png"> <td> split the parent box horizontally into two sections; the split ratio is adjustable <br> Note: "left" and "right" are the first and second children (left and right sibling) of the widget tree
<tr><td>PCB_DAD_BEGIN_VPANE <td> <img src="wvpane.png"> <td> split the parent box vertically into two sections; the split ratio is adjustable <br> Note: on the screenshot "left" and "right" are the first and second children (left and right sibling) of the widget tree
<tr><td>PCB_DAD_BEGIN_TABLE <td> <img src="wtable.png"> <td> arrange children widgets into a n*m matrix, allocate each cell the same size <br> Note: on the screenshot the table is set up to have 3 columns
<tr><td>PCB_DAD_BEGIN_TABBED <td> <img src="wtabbed.png"> <td> create a "tabbed notebook" view, each children is a new tab
</table>
<h3>Box common flags</h3>
<p>
hbox, vbox and table share a few common compflags, that are defined in
hid_attrib.h, pcb_hatt_compflags_t. The explanation of what each flag does
can be found there. The most commonly used ones are PCB_HATF_FRAME,
PCB_HATF_SCROLL, PCB_HATF_EXPFILL.
<p>
If PCB_HATF_EXPFILL is set, the given box tries to expannd and fill, using
up all available space in its parent widget. If multiple sibling boxes
have this flag set the behaviour is unspecified; some HIDs may prefer
to grow only one box, others may evenly distribute the avaialble space
among boxes. If this flag is not set, the box uses only as much space
as its children widgets require.
<h3>PCB_DAD_BEGIN_HBOX(table) and PCB_DAD_BEGIN_VBOX(table)</h3>
<p>
Arrange children widgets in a horizontal or vertical row.
<h3>PCB_DAD_BEGIN_HPANE(table)</h3>
<p>
Expect exactly two child widgets. Arrange them horizontally, with
a widget in between them that allows the user to change the space allocation
between the sides.
<h3>PCB_DAD_BEGIN_VPANE(table)</h3>
<p>
Expect exactly two child widgets. Arrange them vertically, with
a widget in between them that allows the user to change the space allocation
between the sides.
<h3>PCB_DAD_BEGIN_TABLE(table, cols)</h3>
<p>
Place children widgets in a table with <i>cols</i> columns. Widgets are
placed by filling up rows first. If there are not enough widget to finish
the last row, rightmost columns are left empty.
<p>
The table is homogenous, which means the cell size is the same for all cells
and is either determined by the size of the smallest cell content or if
the table fills in a larger widget space than its minimal size, then cell
space is evenly distributed.
<h3>PCB_DAD_BEGIN_TABBED(table, tabs)</h3>
<p>
Creates a "tabbed notebook": each child widget ends up on a new
page, there is only one page shown at a time and there is a GUI way
to switch page (the tab). The list of tab names is passed as <i>tabs</i>,
as a NULL terminalte char * array. The number of tab names must match
the number of children widgets. The <i>value</i>
of is an integer index into that array, 0 being the first tab.
<p>
If compflag includes PCB_HATF_HIDE_TABLAB, the tab graphics are hidden -
no tab labels printed and the user can not click to switch tab. This is
useful for dialog boxes where the code needs to present different tabs
using the same screen estate.
<p>
If compflag PCB_HATF_LEFT_TAB is set, tab labels are presented in a vertical
row on the left side of the widget. This is useful if there are a lot of
tabs with short names.
<h3>PCB_DAD_DUP_ATTR(table, attr)</h3>
<p>
Create a new widget by duplicating an existing one. <i>attr</i> is the
widget ID of the existing widget. If the widget being duplicated is a
BEGIN*, it will need a corresponding PCB_DAD_END.
<h2> Property sets </h2>
<p>
The raw macro call is PCB_DAD_SET_VALUE, which can change (overwrite) a named
field of the current (last created) widget. The following table lists high
level macros that usually call PCB_DAD_SET_VALUE on a specific field.
<p>
<table border=1 cellspacing=0>
<tr><th> name <th> description
<tr><td>PCB_DAD_COMPFLAG(table, val) <td> set all compflags
<tr><td>PCB_DAD_MINVAL(table, val) <td> change the minimal value for numeric input
<tr><td>PCB_DAD_MAXVAL(table, val) <td> change the maximal value for numeric input
<tr><td>PCB_DAD_DEFAULT_NUM(table, val) <td> set the default (initial) value for numeric fields (integers, coords, bools, floats)
<tr><td>PCB_DAD_DEFAULT_PTR(table, val) <td> set the default (initial) value for pointer fields (e.g. strings)
<tr><td>PCB_DAD_MINMAX(table, min, max) <td> hange both the minimal and the maximal value for numeric input
<tr><td>PCB_DAD_CHANGE_CB(table, cb) <td> <i>cb</i> is a function that shall be called upon any change to the widget value
<tr><td>PCB_DAD_HELP(table, val) <td> set the help text (typically presented as a tooltip)
</table>
<h2> Actions and scripting </h2>
<p>
There is a dad() action in the dialogd plugin that exposes all the above macros.
The dialog table ID is am arbitrary unique string and commands are the macro
names without PCB_DAD, written in lowercase.
<p>
Please refer to <a href="../../user/06_feature/scripting/rosetta/">scripting rosetta</a>
project for examples. An example of a typical small dialog box is the
<a href="../../user/06_feature/scripting/rosetta/72_dad_unitconv">unit conveter</a>
script.
|
