0e6e2393bf
Fl_Browser_ docos finished. Added Fl_Group::init_sizes() description. Added links for common widgets in chapter 3 (?) Fixed formatting problems in subclassing and FLUID chapters. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.0@1100 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
352 lines
14 KiB
HTML
352 lines
14 KiB
HTML
<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">
|
|
<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"></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"></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>
|
|
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></CENTER>
|
|
The @ sign may be followed by the following optional "formatting"
|
|
characters, in this order: </P>
|
|
<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>
|