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
|
<html>
<body>
<h1> DAD: Dynamic Attribute Dialogs </h1>
<h2> History </h2>
<p>
Attribute Dialogs were originally invented around the early/mid 2000s for export
HIDs to store a static, flat list of options that are then presented both
as command line options and as the GUI dialog box for export parameters.
<h2> Intro </h2>
<p>
DAD is the dyamically allocated version, extended with new widget types for
providing tools for building more complex dialog boxes. It is not connected
with command line options in any way at the moment.
<p>
The list of widgets is still a flat, growing C array, often called the
<i>table</i>. But inside the table, widgets build as a logical tree
structure. Widgets with name that includes "BEGIN" will open a new
logical layout level that has to be closed with a PCB_DAD_END().
<h2> Calling conventions </h2>
<p>
A table is always built incrementally and sequentially. In this sense
the dialog box is static: once build and created, the number and
type of widgets can not be modified. The dynamic aspect is that the code
may create (and destroy) arbitrary DAD boxes, even with loops and
runtime conditions on what widgets end up in the box.
<p>
There are two kind of widget calls: widget creation and property set.
Property set calls always change the last created widget. This, by
convention, is often indicated by code indentation as well. For example:
<pre>
PCB_DAD_INTEGER(dlg, "foo");
PCB_DAD_MINVAL(dlg, 1);
PCB_DAD_MAXVAL(dlg, 10);
PCB_DAD_DEFAULT_NUM(dlg, 3);
widget_id_foo = PCB_DAD_CURRENT(dlg);
PCB_DAD_BUTTON(dlg, "update!");
PCB_DAD_CHANGE_CB(dlg, pcb_act_attr_chg);
</pre>
<p>
PCB_DAD_INTEGER() and PCB_DAD_BUTTON() are (macro) calls to create
new widgets (an integer entry and a button), the rest of the calls
change the last created widget's properties.
<p>
The main widget of the box, the root widget of the widget tree is
any widget. It is practical to make it a container widget (e.g. a HBOX, VBOX,
TABLE, PANE, or TABBED) so that it can host children widgets.
<p>
After each creation, the caller can query and store the integer widget
identifier using the PCB_DAD_CURRENT() macro. The widget identifier can
be used, together with the table, to query or change widget properties
and current value any time the dialog box is active.
|
