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
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
|
<HTML><BODY>
<H1 ALIGN=RIGHT><A NAME=common>3 - Common Widgets and Attributes</A></H1>
This chapter describes many of the widgets that are provided with FLTK
and covers how to query and set the standard attributes.
<H2>Buttons</H2>
FLTK provides many types of buttons:
<UL>
<LI><A HREF="Fl_Button.html"><TT>Fl_Button</TT></A> - A standard push button. </LI>
<LI><A HREF="Fl_Check_Button.html"><TT>Fl_Check_Button</TT></A> - A button with a check box. </LI>
<LI><A HREF="Fl_Light_Button.html"><TT>Fl_Light_Button</TT></A> - A push button with a light. </LI>
<LI><A HREF="Fl_Repeat_Button.html"><TT>Fl_Repeat_Button</TT></A> - A push button that repeats when held. </LI>
<LI><A HREF="Fl_Return_Button.html"><TT>Fl_Return_Button</TT></A> - A push button that is activated by the
Enter key. </LI>
<LI><A HREF="Fl_Round_Button.html"><TT>Fl_Round_Button</TT></A> - A button with a check circle. </LI>
</UL>
<P ALIGN=CENTER><IMG SRC="buttons.gif" ALT="FLTK Buttons">
<P>For all of these buttons you just need to include the corresponding <TT>
<FL/Fl_xyz_Button.H></TT> header file. The constructor takes the
bounding box of the button and optionally a label string:
<UL>
<PRE>
Fl_Button *button = new Fl_Button(x, y, width, height, "label");
Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height);
Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label");
</PRE>
</UL>
Each button has an associated <A href=Fl_Button.html#Fl_Button.type><TT>
type()</TT></A> which allows it to behave as a push button, toggle
button, or radio button:
<UL>
<PRE>
button->type(0);
lbutton->type(FL_TOGGLE_BUTTON);
rbutton->type(FL_RADIO_BUTTON);
</PRE>
</UL>
For toggle and radio buttons, the <A href=Fl_Button.html#Fl_Button.value>
<TT>value()</TT></A> method returns the current button state (0 = off,
1 = on). The <A href=#Fl_Widget.set><TT>set()</TT></A> and <A href=#Fl_Widget.clear>
<TT>clear()</TT></A> methods can be used on toggle buttons to turn a
toggle button on or off, respectively. Radio buttons can be turned on
with the <A href=#Fl_Widget.setonly><TT>setonly()</TT></A> method; this
will also turn off other radio buttons in the same group.
<H2>Text</H2>
FLTK provides several text widgets for displaying and receiving text:
<UL>
<LI><A HREF="Fl_Input.html"><TT>Fl_Input</TT></A> - A standard one-line text input field. </LI>
<LI><A HREF="Fl_Output.html"><TT>Fl_Output</TT></A> - A standard one-line text output field. </LI>
<LI><A HREF="Fl_Multiline_Input.html"><TT>Fl_Multiline_Input</TT></A> - A standard multi-line text input
field. </LI>
<LI><A HREF="Fl_Multiline_Output.html"><TT>Fl_Multiline_Output</TT></A> - A standard multi-line text output
field. </LI>
</UL>
The <TT>Fl_Output</TT> and <TT>Fl_Multiline_Output</TT> widgets allow
the user to copy text from the output field but not change it.
<P>The <A href=Fl_Input.html#Fl_Input.value><TT>value()</TT></A> method
is used to get or set the string that is displayed: </P>
<UL>
<PRE>
Fl_Input *input = new Fl_Input(x, y, width, height, "label");
input->value("Now is the time for all good men...");
</PRE>
</UL>
<p>The string is copied to the widget's own storage when you set the
<tt>value()</tt> of the widget.
<H2>Valuators</H2>
Unlike text widgets, valuators keep track of numbers instead of
strings. FLTK provides the following valuators:
<UL>
<LI><A HREF="Fl_Counter.html"><TT>Fl_Counter</TT></A> - A widget with arrow buttons that shows the
current value. </LI>
<LI><A HREF="Fl_Dial.html"><TT>Fl_Dial</TT></A> - A round knob. </LI>
<LI><A HREF="Fl_Roller.html"><TT>Fl_Roller</TT></A> - An SGI-like dolly widget. </LI>
<LI><A HREF="Fl_Scrollbar.html"><TT>Fl_Scrollbar</TT></A> - A standard scrollbar widget. </LI>
<LI><A HREF="Fl_Slider.html"><TT>Fl_Slider</TT></A> - A scrollbar with a knob. </LI>
<LI><A HREF="Fl_Value_Slider.html"><TT>Fl_Value_Slider</TT></A> - A slider that shows the current value. </LI>
</UL>
<P ALIGN=CENTER><IMG SRC="valuators.gif" ALT="FLTK Valuators"></P>
The <A href=Fl_Valuator.html#Fl_Valuator.value><TT>value()</TT></A>
method gets and sets the current value of the widget. The <A href=Fl_Valuator.html#Fl_Valuator.minimum>
<TT>minimum()</TT></A> and <A href=Fl_Valuator.html#Fl_Valuator.maximum><TT>
maximum()</TT></A> methods set the range of values that are reported by
the widget.
<H2>Groups</H2>
The <TT>Fl_Group</TT> widget class is used as a general purpose
"container" widget. Besides grouping radio buttons, the groups are
used to encapsulate windows, tabs, and scrolled windows. The following
group classes are available with FLTK:
<UL>
<LI><A HREF="Fl_Double_Window.html"><TT>Fl_Double_Window</TT></A> - A double-buffered window on the screen. </LI>
<LI><A HREF="Fl_Gl_Window.html"><TT>Fl_Gl_Window</TT></A> - An OpenGL window on the screen. </LI>
<LI><A HREF="Fl_Group.html"><TT>Fl_Group</TT></A> - The base container class; can be used to group
any widgets together. </LI>
<LI><A HREF="Fl_Scroll.html"><TT>Fl_Scroll</TT></A> - A scrolled window area. </LI>
<LI><A HREF="Fl_Tabs.html"><TT>Fl_Tabs</TT></A> - Displays child widgets as tabs. </LI>
<LI><A HREF="Fl_Window.html"><TT>Fl_Window</TT></A> - A window on the screen. </LI>
</UL>
<H2>Setting the Size and Position of Widgets</H2>
The size and position of widgets is usually set when you create them.
You can access them with the <tt>x()</tt>, <tt>y()</tt>, <tt>w()</tt>,
and <tt>h()</tt> methods.
<p>You can change the size and position by using the <TT>position()</TT>, <TT>
resize()</TT>, and <TT>size()</TT> methods:
<UL>
<PRE>
button->position(x, y);
group->resize(x, y, width, height);
window->size(width, height);
</PRE>
</UL>
If you change a widget's size or position after it is displayed you
will have to call <tt>redraw()</tt> on the widget's parent.
<H2><A NAME=colors>Colors</A></H2>
FLTK stores the colors of widgets as an 8-bit number that is an index
into a color palette of 256 colors. This is <i>not</i> the X or WIN32
colormap, but instead is an internal table with fixed contents.
<p>There are symbols for naming some of the more common colors:
<UL>
<LI><TT>FL_BLACK</TT> (this is the default label color)</LI>
<LI><TT>FL_RED</TT></LI>
<LI><TT>FL_GREEN</TT></LI>
<LI><TT>FL_YELLOW</TT></LI>
<LI><TT>FL_BLUE</TT></LI>
<LI><TT>FL_MAGENTA</TT></LI>
<LI><TT>FL_CYAN</TT></LI>
<LI><TT>FL_WHITE</TT> (this is the default background color of text widgets)</LI>
<LI><TT>FL_GRAY</TT> (this is the default background color of most widgets)</LI>
</UL>
The widget color can be set using the <TT>color()</TT> method:
<UL>
<PRE>
button->color(FL_RED);
</PRE>
</UL>
Similarly, the label color can be set using the <TT>labelcolor()</TT>
method:
<UL>
<PRE>
button->labelcolor(FL_WHITE);
</PRE>
</UL>
<H2><A NAME=boxtypes>Box Types</A></H2>
<P>The type <TT>Fl_Boxtype</TT> stored and returned in <A href=Fl_Widget.html#Fl_Widget.box>
<TT>Fl_Widget::box()</TT></A> is an enumeration defined in <A href=enumerations.html#enumerations>
<TT><Enumerations.H></TT></A>:
<P ALIGN=CENTER><IMG src="boxtypes.gif" ALT="FLTK Box Types"></P>
<P><TT>FL_NO_BOX</TT> means nothing is drawn at all, so whatever is
already on the screen remains. The <TT>FL_..._FRAME</TT> types only
draw their edges, leaving the interior unchanged. In the above diagram
the blue color is the area that is not drawn by the box. </P>
<H3>Making your own Boxtypes</H3>
<i>Warning: this interface may change in future versions of fltk!</i>
<p>You can define your own boxtypes by making a small function that draws
the box and adding it to the table of boxtypes.
<H4>The Drawing Function</H4>
The drawing function is passed the bounding box and background color
for the widget:
<UL>
<PRE>
void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
...
}
</PRE>
</UL>
A simple drawing function might fill a rectangle with the given color
and then draw a black outline:
<UL>
<PRE>
void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
fl_color(c);
fl_rectf(x, y, w, h);
fl_color(FL_BLACK);
fl_rect(x, y, w, h);
}
</PRE>
</UL>
<H4>Adding Your Box Type</H4>
The <TT>Fl::set_boxtype()</TT> method adds or replaces the specified
box type:
<UL>
<PRE>
#define XYZ_BOX FL_FREE_BOXTYPE
Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
</PRE>
</UL>
The last 4 arguments to <TT>Fl::set_boxtype()</TT> are the offsets for
the bounding box that should be subtracted when drawing the label
inside the box.
<H2><A NAME=labels>Labels and Label Types</A></H2>
The <TT>label()</TT>, <TT>align()</TT>, <TT>labelfont()</TT>, <TT>
labelsize()</TT>, and <TT>labeltype()</TT> methods control the labeling
of widgets.
<H3>label()</H3>
The <TT>label()</TT> method sets the string that is displayed for the
label. For the <TT>FL_SYMBOL_LABEL</TT> and image label types the
string contains the actual symbol or image data.
<H3>align()</H3>
The <TT>align()</TT> method positions the label. The following
constants are defined (they may be OR'd together as needed):
<UL>
<LI><TT>FL_ALIGN_CENTER</TT> - center the label in the widget. </LI>
<LI><TT>FL_ALIGN_TOP</TT> - align the label at the top of the widget. </LI>
<LI><TT>FL_ALIGN_BOTTOM</TT> - align the label at the bottom of the
widget. </LI>
<LI><TT>FL_ALIGN_LEFT</TT> - align the label to the left of the widget. </LI>
<LI><TT>FL_ALIGN_RIGHT</TT> - align the label to the right of the
widget. </LI>
<LI><TT>FL_ALIGN_INSIDE</TT> - align the label inside the widget. </LI>
<LI><TT>FL_ALIGN_CLIP</TT> - clip the label to the widget's bounding
box. </LI>
<LI><TT>FL_ALIGN_WRAP</TT> - wrap the label text as needed. </LI>
</UL>
<H3>labeltype()</H3>
The <TT>labeltype()</TT> method sets the type of the label. The
following standard label types are included:
<UL>
<LI><TT>FL_NORMAL_LABEL</TT> - draws the text. </LI>
<LI><TT>FL_NO_LABEL</TT> - does nothing </LI>
<LI><TT>FL_SYMBOL_LABEL</TT> - draws "@xyz" labels, see "<A href=#symbols>
Symbol Labels</A>" </LI>
<LI><TT>FL_SHADOW_LABEL</TT> - draws a drop shadow under the text </LI>
<LI><TT>FL_ENGRAVED_LABEL</TT> - draws edges as though the text is
engraved </LI>
<LI><TT>FL_EMBOSSED_LABEL</TT> - draws edges as thought the text is
raised </LI>
</UL>
To make bitmaps or pixmaps you use a method on the <A href=drawing.html#Fl_Bitmap>
<TT>Fl_Bitmap</TT></A> or <A href=drawing.html#Fl_Pixmap><TT>Fl_Pixmap</TT>
</A> objects.
<H4>Making Your Own Label Types</H4>
<i>Warning: this interface is changing in FLTK 2.0!</i>
<p>Label types are actually indexes into a table of functions that draw
them. The primary purpose of this is to let you reuse the <TT>label()</TT>
pointer as a pointer to arbitrary data such as a bitmap or pixmap. You
can also use this to draw the labels in ways inaccessible through the <TT>
fl_font</TT> mechanisim (e.g. <TT>FL_ENGRAVED_LABEL</TT>) or with
program-generated letters or symbology.
<H5>Label Type Functions</H5>
To setup your own label type you will need to write two functions to
draw and measure the label. The draw function is called with a pointer
to a <A href=#Fl_Label><TT>Fl_Label</TT></A> structure containing the
label information, the bounding box for the label, and the label
alignment:
<UL>
<PRE>
void xyz_draw(Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
...
}
</PRE>
</UL>
The label should be drawn <I>inside</I> this bounding box, even if <TT>
FL_ALIGN_INSIDE</TT> is not enabled. The function is not called if the
label value is <TT>NULL</TT>.
<P>The measure function is called with a pointer to a <A href=#Fl_Label><TT>
Fl_Label</TT></A> structure and references to the width and height: </P>
<UL>
<PRE>
void xyz_measure(Fl_Label *label, int &w, int &h) {
...
}
</PRE>
</UL>
It should measure the size of the label and set <TT>w</TT> and <TT>h</TT>
to the size it will occupy.
<H5>Adding Your Label Type</H5>
The <TT>Fl::set_labeltype</TT> method creates a label type using your
draw and measure functions:
<UL>
<PRE>
#define XYZ_LABEL FL_FREE_LABELTYPE
Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
</PRE>
</UL>
The label type number <TT>n</TT> can be any integer value starting at
the constant <TT>FL_FREE_LABELTYPE</TT>. Once you have added the label
type you can use the <TT>labeltype()</TT> method to select your label
type.
<P>The <TT>Fl::set_labeltype</TT> method can also be used to overload
an existing label type such as <TT>FL_NORMAL_LABEL</TT>. </P>
<H4><A name=symbols>Symbol Labels</A></H4>
<P>The <TT>FL_SYMBOL_LABEL</TT> label type uses the <TT>label()</TT>
string to look up a small drawing procedure in a hash table. For
historical reasons the string always starts with '@'; if it starts with
something else (or the symbol is not found) the label is drawn
normally:
<CENTER><IMG src="symbols.gif" ALT="FLTK Symbols"></CENTER>
<P>The @ sign may be followed by the following optional "formatting"
characters, in this order:
<UL>
<LI>'#' forces square scaling, rather than distortion to the widget's
shape. </LI>
<LI>+[1-9] or -[1-9] tweaks the scaling a little bigger or smaller. </LI>
<LI>[1-9] - rotates by a multiple of 45 degrees. '6' does nothing,
the others point in the direction of that key on a numeric keypad. </LI>
</UL>
<H2>Callbacks</H2>
Callbacks are functions that are called when the value of a widget
changes. A callback function is sent a <TT>Fl_Widget</TT> pointer of
the widget that changed and optionally a pointer to data of some sort:
<UL>
<PRE>
void xyz_callback(Fl_Widget *w, void *data) {
...
}
</PRE>
</UL>
The <TT>callback()</TT> method sets the callback function for a
widget. You can optionally pass a pointer to some data needed for the
callback:
<UL>
<PRE>
int xyz_data;
button->callback(xyz_callback, data);
</PRE>
</UL>
Normally callbacks are performed only when the value of the widget
changes. You can change this using the <A href=Fl_Widget.html#Fl_Widget.when>
<TT>when()</TT></A> method:
<UL>
<PRE>
button->when(FL_WHEN_NEVER);
button->when(FL_WHEN_CHANGED);
button->when(FL_WHEN_RELEASE);
button->when(FL_WHEN_RELEASE_ALWAYS);
button->when(FL_WHEN_ENTER_KEY);
button->when(FL_WHEN_ENTER_KEY_ALWAYS);
button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED);
</PRE>
</UL>
<H2>Shortcuts</H2>
Shortcuts are key sequences that activate widgets (usually buttons or
menu items). The <TT>shortcut()</TT> method sets the shortcut for a
widget:
<UL>
<PRE>
button->shortcut(FL_Enter);
button->shortcut(FL_SHIFT + 'b');
button->shortcut(FL_CTRL + 'b');
button->shortcut(FL_ALT + 'b');
button->shortcut(FL_CTRL + FL_ALT + 'b');
button->shortcut(0); // no shortcut
</PRE>
</UL>
The shortcut value is the key event value (the ASCII value or one of
the special keys like <a
href="enumerations.html#key_values"><TT>FL_Enter</TT></a>) combined
with any modifiers (like shift, alt, and control).
</BODY></HTML>
|
