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
|
gui.tcl has gone through a few major changes
Migrating from version 1 to version 2:
If you overloaded any of the following you will need to make changes. See their descriptions below.
add_buttons
module_description
Also if you overloaded begin_dialog or end_dialog (which may have been necessary but messy) you should now refactor your code.
Fonts:
Fonts are currently unmanaged, using TCL defaults. Fonts listed here will change the appearance of the created dialog.
balloon-help
Font to be displayed for balloon help
Globals:
dlg
This is the key to refer to a created dialog. It starts at 0. When begin_dialog is called this goes up by one, become the key for the created dialog. A program using gui.tcl needs to get this value for a created dialog in order to refer to it again in the future. In version 2 begin_dialog returns the new value of dlg for convenience.
path
This specifies the tk object path in which the dialog will be created. Before version 2 this was always the path to a toplevel, such as {} when run from G_gui() or something like .moduleX when running from d.m or gis.m. This must be set before calling begin_dialog.
imagepath
Version 1 only, the folder to find bwidgets 1.2.1 images in. $env(GISBASE)/bwidget/images/
iconpath
Introduced in version 2, the path to search for icons. $env(GISBASE)/etc/gui/icons/
opt
An associative array used for dialogs to store their attributes, options, current answers, etc. Starts off unset.
opt parts:
$dlg,layout_* Reserved for use fo the layout system (V2)
Procedures:
Miscellaneous:
icon {class member}
Searches icons for an icon, returns either a photo command or 0 on failure. See gui/icons/README for more information
handle_scroll
Callback that makes mouse wheel scrolling work for frames
Command and selection dialog:
mkcmd
Makes the argv style list command from the current options.
mkcmd_string
Late version 1 and version 2: Makes a string verion of the current command.
show_cmd
Late version 1 and version 2: Updates the current command label
prnout
Version 1, early version 2: File callback that prints output to the text widget in opt($dlg,outtext). Could be overloaded to capture command output, probably a better idea not to. Removed now, this is handled by the gronsole made in make_output.
get_file
Opens a file selection dialog
get_map
Opens a database element selection dialog using $env(GISBASE)/etc/gtcltk/select.tcl
run_cmd
Runs the current command. Could be overloaded to get the event from clicking the run button. It's probably a better idea to overload add_buttons in version 1 or make_dialog_end or make_buttons in version 2 and later
help_cmd, close_cmd, clear_cmd
Could be overloaded to get the events from clicking the help, clear, and close buttons. See note above about run_cmd.
progress {dlg percent}
Used to set the filledness of the progress bar. -1 empties it.
Layout rules:
All of these exist only in version 2.
Layout rules are prime candidates for overloading, and can drastically change the appearance of the dialog.
layout_* Reserved for layout rules.
layout_make_frame is part of the default strategy, not the interface
layout_get_frame {dlg guisection optn}
Must return text for a frame that option widgets can be packed into
layout_get_special_frame {dlg guisection optn}
Must return text for a frame that some special widget can be packed into. Used for, for example, output.
layout_raise_frame {dlg guisection optn}
The named option or guisection should be displayed on the screen
layout_raise_special_frame {dlg guisection optn}
The named option or guisection should be displayed on the screen
make_layout {dlg path root}
The default make_dialog calls this to make the layout. A layout should overload it.
Stuff that makes the gui:
All of make_* are good candidated for overloading. Appearance and behaviour can be greatly changed just by overloading make_dialog and make_dialog_end
make_module_description:
Version 2 only, should make a description of the module. It could be overloaded to turn off the description or to provide a different one. Overloading make_dialog could also turn offf the description. Related to module_description (version 1 only).
make_command_label:
Version 2 only, makes a little command label withtextvar opt($dlg,cmd_string). See also show_cmd. Packs against the bottom side.
make_output:
Version 2 only, Makes a text box for displaying output. Required for make_buttons unless run_cmd is overloaded, since they contain a run button.
make_progress:
Version 2 only, makes a progress bar, see also progress. No longer used as progress is displayed by the gronsole.
make_buttons:
Version 2 only, adds buttons to the dialog. Replaces version 1's add_buttons. Packs against the bottom.
make_dialog
In version 2 this sets up everything that gets set up before the program is run. By default it does make_module_description, make_command_label, make_layout, and make_buttons and is a prime candidate for overloading.
In version one this set up the windows for options, output, progress, and their associated opt variables opt($dlg, outtext), opt($dlg, progress). It also initialized opt($dlg, path), opt($dlg, root), and opt($dlg, suf). It would have been difficult to overload.
A user interface wanting a special to be displayed before options should put a layout_get_special_frame here to get its frame at the top of the order.
make_dialog_end
Version 2 only, like make_dialog but run from end_dialog instead of from begin_dialog.
module_description
Version 1 only. In version 1 this added labels to the dialog for the description of the module. It was called from begin_dialog. If you overloaded it you should move those changes to an overloaded version of make_module_description
add_buttons
Only in version 1, adds the buttons to the window. Migrating: change proc definition from
proc add_buttons {dlg} {
to
proc make_buttons {dlg path root} {
do_*
Make various widgets
Decent candidates for overloading. Most layouts will want to overload do_label.
Cleanup Procedures:
These are shared between add_option and add_flag for polishing their input into a normal form. Notfor overriding:
normalize_guisection
choose_help_text
Command interface:
Gets and sets the command in tcl argv style list for exec:
dialog_get_command {dlg}
dialog_set_command {dlg cmd}
Interface for making the dialog:
Calling convention changed in late version 1. These are terrible candidates for overloading. parser.c is the only agent that should be using these.
begin_dialog
Must be called before add_option or add_flag.
Must not be called again until after end_dialog is called
In version 2 this does some of the things that version 1 did in make_dialog.
add_option
Must be called between begin_dialog and end_dialog to add an option
add_flag
Like option, but for flags
end_dialog
In version 1 this called add_buttons. Now it calls make_dialog_end to add more to the ui and layout_raise_frame to bring up the first option section.
|
