+Attribute Dialogs are coming from geda/PCB. They were invented 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. + +
+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. +
+The list of widgets is still a flat, growing C array, often called the +table. But inside the table, widgets build a a logical tree +structure. Widgets with name that includes "BEGIN" will open a new +logical layout level that has to be closed with an PCB_DAD_END(). + +
+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. +
+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 exaple: +
+ PCB_DAD_INTEGER(dlg, "foo"); + PCB_DAD_MINVAL(dlg, 1); + PCB_DAD_MAXVAL(dlg, 10); + PCB_DAD_DEFAULT(dlg, 3); + widget_id_foo = PCB_DAD_CURRENT(dlg); + PCB_DAD_BUTTON(dlg, "update!"); + PCB_DAD_CHANGE_CB(dlg, pcb_act_attr_chg); ++
+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. +
+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. +
+After each creaton, 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. + Index: doc/developer/dad/widgets.html =================================================================== --- doc/developer/dad/widgets.html (nonexistent) +++ doc/developer/dad/widgets.html (revision 20992) @@ -0,0 +1,67 @@ + +
+ ++Input widgets are leaf widgets in the widget tree that typically +implement a field where user input takes place. Available +input widgets are: +
| creation call | screenshot (gtk2) | description + |
|---|---|---|
| PCB_DAD_LABEL | | single line or multi line of plain text, from a string + |
| PCB_DAD_LABELF | | single line or multi line of plain text, using printf formatting + |
| PCB_DAD_ENUM | | select one value from a fixed set (typical implementation is a combo box) + |
| PCB_DAD_BOOL | | checkbox + |
| PCB_DAD_INTEGER | | set an integer value + |
| PCB_DAD_REAL | | set a real (floating point) value + |
| PCB_DAD_COORD | | set a coordinate value + |
| PCB_DAD_STRING | | input single line string value (plain text) + |
| PCB_DAD_BUTTON | | clicable push button + |
| PCB_DAD_PROGRESS | | progress bad + |
| PCB_DAD_TREE | | a list, table or tree of text data + |
| PCB_DAD_PREVIEW | | drawing area + |
| creation call | screenshot (gtk2) | description + |
|---|---|---|
| PCB_DAD_BEGIN_HBOX |  | arrange children widgets in a horizontal list + |
| PCB_DAD_BEGIN_VBOX |  | arrange children widgets in a vertical list + |
| PCB_DAD_BEGIN_HPANE |  | split the parent box horizontally into two sections; the split ratio is adjustable + |
| PCB_DAD_BEGIN_VPANE |  | split the parent box vertically into two sections; the split ratio is adjustable + |
| PCB_DAD_BEGIN_TABLE |  | arrange children widgets into a n*m matrix, allocate each cell the same size + |
| PCB_DAD_BEGIN_TABBED |  | create a "tabbed notebook" view, each children is a new tab + |