7f18e1002f
removed "old html link" section from development.dox git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6799 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
609 lines
17 KiB
Plaintext
609 lines
17 KiB
Plaintext
/**
|
|
|
|
\page common Common Widgets and Attributes
|
|
|
|
This chapter describes many of the widgets that are provided
|
|
with FLTK and covers how to query and set the standard
|
|
attributes.
|
|
|
|
\section common_buttons Buttons
|
|
|
|
FLTK provides many types of buttons:
|
|
|
|
\li Fl_Button - A standard push button.
|
|
|
|
\li Fl_Check_Button - A button with a check box.
|
|
|
|
\li Fl_Light_Button - A push button with a light.
|
|
|
|
\li Fl_Repeat_Button - A push button that repeats when held.
|
|
|
|
\li Fl_Return_Button - A push button that is activated by the
|
|
\p Enter key.
|
|
|
|
\li Fl_Round_Button - A button with a radio circle.
|
|
|
|
\image html buttons.gif "Figure 3-1: FLTK Button Widgets"
|
|
\image latex buttons.eps "FLTK Button Widgets" width=10cm
|
|
|
|
All of these buttons just need 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:
|
|
|
|
\code
|
|
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");
|
|
\endcode
|
|
|
|
Each button has an associated \p type() which allows
|
|
it to behave as a push button, toggle button, or radio button:
|
|
|
|
\code
|
|
button->type(FL_NORMAL_BUTTON);
|
|
lbutton->type(FL_TOGGLE_BUTTON);
|
|
rbutton->type(FL_RADIO_BUTTON);
|
|
\endcode
|
|
|
|
For toggle and radio buttons, the \p value() method returns
|
|
the current button state (0 = off, 1 = on). The \p set() and
|
|
\p clear() methods can be used on toggle buttons to turn a
|
|
toggle button on or off, respectively.
|
|
Radio buttons can be turned on with the \p setonly()
|
|
method; this will also turn off other radio buttons in the same
|
|
group.
|
|
|
|
\section common_text Text
|
|
|
|
FLTK provides several text widgets for displaying and receiving text:
|
|
|
|
\li Fl_Input - A one-line text input field.
|
|
|
|
\li Fl_Output - A one-line text output field.
|
|
|
|
\li Fl_Multiline_Input - A multi-line text input field.
|
|
|
|
\li Fl_Multiline_Output - A multi-line text output field.
|
|
|
|
\li Fl_Text_Display - A multi-line text display widget.
|
|
|
|
\li Fl_Text_Editor - A multi-line text editing widget.
|
|
|
|
\li Fl_Help_View - A HTML text display widget.
|
|
|
|
The Fl_Output and Fl_Multiline_Output
|
|
widgets allow the user to copy text from the output field but
|
|
not change it.
|
|
|
|
The \p value() method is used to get or set the
|
|
string that is displayed:
|
|
|
|
\code
|
|
Fl_Input *input = new Fl_Input(x, y, width, height, "label");
|
|
input->value("Now is the time for all good men...");
|
|
\endcode
|
|
|
|
The string is copied to the widget's own storage when you set
|
|
the \p value() of the widget.
|
|
|
|
The Fl_Text_Display and Fl_Text_Editor
|
|
widgets use an associated Fl_Text_Buffer class for the
|
|
value, instead of a simple string.
|
|
|
|
<!-- NEED 4in -->
|
|
|
|
\section common_valuators Valuators
|
|
|
|
Unlike text widgets, valuators keep track of numbers instead of
|
|
strings. FLTK provides the following valuators:
|
|
|
|
\li Fl_Counter - A widget with arrow buttons that shows the current value.
|
|
|
|
\li Fl_Dial - A round knob.
|
|
|
|
\li Fl_Roller - An SGI-like dolly widget.
|
|
|
|
\li Fl_Scrollbar - A standard scrollbar widget.
|
|
|
|
\li Fl_Slider - A scrollbar with a knob.
|
|
|
|
\li Fl_Value_Slider - A slider that shows the current value.
|
|
|
|
\image html valuators.gif "Figure 3-2: FLTK valuator widgets"
|
|
\image latex valuators.eps "FLTK valuator widgets" width=10cm
|
|
|
|
The \p value() method gets and sets the current value
|
|
of the widget. The \p minimum() and \p maximum()
|
|
methods set the range of values that are reported by the
|
|
widget.
|
|
|
|
<!-- NEED 5in -->
|
|
|
|
\section common_groups Groups
|
|
|
|
The Fl_Group 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:
|
|
|
|
\li Fl_Double_Window - A double-buffered window on the screen.
|
|
|
|
\li Fl_Gl_Window - An OpenGL window on the screen.
|
|
|
|
\li Fl_Group - The base container class; can be used to group
|
|
any widgets together.
|
|
|
|
\li Fl_Pack - A collection of widgets that are packed into the group area.
|
|
|
|
\li Fl_Scroll - A scrolled window area.
|
|
|
|
\li Fl_Tabs - Displays child widgets as tabs.
|
|
|
|
\li Fl_Tile - A tiled window area.
|
|
|
|
\li Fl_Window - A window on the screen.
|
|
|
|
\li Fl_Wizard - Displays one group of widgets at a time.
|
|
|
|
\section common_sizeposition Setting the Size and Position of Widgets
|
|
|
|
The size and position of widgets is usually set when you create them.
|
|
You can access them with the \p x(), \p y(), \p w(), and \p h()
|
|
methods.
|
|
|
|
You can change the size and position by using the \p position(),
|
|
\p resize(), and \p size() methods:
|
|
|
|
\code
|
|
button->position(x, y);
|
|
group->resize(x, y, width, height);
|
|
window->size(width, height);
|
|
\endcode
|
|
|
|
If you change a widget's size or position after it is
|
|
displayed you will have to call \p redraw() on the
|
|
widget's parent.
|
|
|
|
\section common_colors Colors
|
|
|
|
FLTK stores the colors of widgets as an 32-bit unsigned
|
|
number that is either an index into a color palette of 256
|
|
colors or a 24-bit RGB color. The color palette is \e not
|
|
the X or WIN32 colormap, but instead is an internal table with
|
|
fixed contents.
|
|
|
|
There are symbols for naming some of the more common colors:
|
|
|
|
\li \p FL_BLACK
|
|
\li \p FL_RED
|
|
\li \p FL_GREEN
|
|
\li \p FL_YELLOW
|
|
\li \p FL_BLUE
|
|
\li \p FL_MAGENTA
|
|
\li \p FL_CYAN
|
|
\li \p FL_WHITE
|
|
\li \p FL_WHITE
|
|
|
|
These symbols are the default colors for all FLTK widgets. They are
|
|
explained in more detail under
|
|
\ref enumerations_colors in
|
|
\ref enumerations.
|
|
|
|
\li \p FL_FOREGROUND_COLOR
|
|
\li \p FL_BACKGROUND_COLOR
|
|
\li \p FL_INACTIVE_COLOR
|
|
\li \p FL_SELECTION_COLOR
|
|
|
|
RGB colors can be set using the \p fl_rgb_color() function:
|
|
|
|
\code
|
|
Fl_Color c = fl_rgb_color(85, 170, 255);
|
|
\endcode
|
|
|
|
The widget color is set using the \p color() method:
|
|
|
|
\code
|
|
button->color(FL_RED);
|
|
\endcode
|
|
|
|
Similarly, the label color is set using the \p labelcolor() method:
|
|
|
|
\code
|
|
button->labelcolor(FL_WHITE);
|
|
\endcode
|
|
|
|
\section common_boxtypes Box Types
|
|
|
|
The type Fl_Boxtype stored and returned in Fl_Widget::box()
|
|
is an enumeration defined in Enumerations.H.
|
|
|
|
Figure 3-3 shows the standard box types included with FLTK.
|
|
|
|
\image html boxtypes.gif "Figure 3-3: FLTK box types"
|
|
\image latex boxtypes.eps "FLTK box types" width=12cm
|
|
|
|
\p FL_NO_BOX 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. The blue color in
|
|
Figure 3-3 is the area that is not drawn by the frame types.
|
|
|
|
\subsection common_custom_boxtypes Making Your Own Boxtypes
|
|
|
|
You can define your own boxtypes by making a small function that draws
|
|
the box and adding it to the table of boxtypes.
|
|
|
|
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
|
|
<TR>
|
|
<TD><B>Note:</B>
|
|
<P>This interface has changed in FLTK 2.0!
|
|
</TD>
|
|
</TR>
|
|
</TABLE></CENTER>
|
|
|
|
\par The Drawing Function
|
|
|
|
The drawing function is passed the bounding box and background color
|
|
for the widget:
|
|
|
|
\code
|
|
void xyz_draw(int x, int y, int w, int h, Fl_Color c) {
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
<!-- NEED 3in -->
|
|
|
|
A simple drawing function might fill a rectangle with the
|
|
given color and then draw a black outline:
|
|
|
|
\code
|
|
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);
|
|
}
|
|
\endcode
|
|
|
|
\anchor common_fl_down
|
|
Fl_Boxtype fl_down(Fl_Boxtype b)
|
|
|
|
\par
|
|
fl_down() returns the "pressed" or "down" version of a box.
|
|
If no "down" version of a given box exists, the behavior of this function
|
|
is undefined and some random box or frame is returned.
|
|
See \ref drawing_fl_frame "Drawing Functions" for more details.
|
|
|
|
\anchor common_fl_frame
|
|
Fl_Boxtype fl_frame(Fl_Boxtype b)
|
|
|
|
\par
|
|
fl_frame() returns the unfilled, frame-only version of a box.
|
|
If no frame version of a given box exists, the behavior of this function
|
|
is undefined and some random box or frame is returned.
|
|
See \ref drawing_fl_frame "Drawing Functions" for more details.
|
|
|
|
Fl_Boxtype fl_box(Fl_Boxtype b)
|
|
|
|
\par
|
|
fl_box() returns the filled version of a frame.
|
|
If no filled version of a given frame exists, the behavior of this function
|
|
is undefined and some random box or frame is returned.
|
|
See \ref drawing_fl_frame "Drawing Functions" for more details.
|
|
|
|
\par Adding Your Box Type
|
|
|
|
The Fl::set_boxtype() method adds or replaces the specified box type:
|
|
|
|
\code
|
|
#define XYZ_BOX FL_FREE_BOXTYPE
|
|
|
|
Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2);
|
|
\endcode
|
|
The last 4 arguments to Fl::set_boxtype() are the
|
|
offsets for the \p x, \p y, \p width, and \p height values that should be
|
|
subtracted when drawing the label inside the box.
|
|
|
|
A complete box design contains four box types in this order:
|
|
a filled, neutral box (<tt>UP_BOX</tt>),
|
|
a filled, depressed box (<tt>DOWN_BOX</tt>),
|
|
and the same as outlines only (<tt>UP_FRAME</tt> and <tt>DOWN_FRAME</tt>).
|
|
The function
|
|
\ref common_fl_down "fl_down(Fl_Boxtype)"
|
|
expects the neutral design on a boxtype with a numerical
|
|
value evenly divideable by two.
|
|
\ref common_fl_frame "fl_frame(Fl_Boxtype)"
|
|
expects the \p UP_BOX design at a value divideable by four.
|
|
|
|
\section common_labels Labels and Label Types
|
|
|
|
The \p label(), \p align(), \p labelfont(), \p labelsize(),
|
|
\p labeltype(), \p image(), and \p deimage() methods control the
|
|
labeling of widgets.
|
|
|
|
\par label()
|
|
|
|
The \p label() method sets the string that is displayed
|
|
for the label. Symbols can be included with the label string by
|
|
escaping them using the "@" symbol - "@@" displays a single at
|
|
sign. Figure 3-4 shows the available symbols.
|
|
|
|
\image html symbols.gif "Figure 3-4: FLTK label symbols"
|
|
\image latex symbols.eps "FLTK label symbols" width=10cm
|
|
|
|
<!-- NEED 2in -->
|
|
|
|
The @ sign may also be followed by the following optional
|
|
"formatting" characters, in this order:
|
|
|
|
\li '#' forces square scaling, rather than distortion to the widget's shape.
|
|
|
|
\li +[1-9] or -[1-9] tweaks the scaling a little bigger or smaller.
|
|
|
|
\li '$' flips the symbol horizontaly, '%' flips it verticaly.
|
|
|
|
\li [0-9] - rotates by a multiple of 45 degrees. '5' and '6' do no rotation
|
|
while the others point in the direction of that key on a numeric keypad.
|
|
'0', followed by four more digits rotates the symbol by that amount in
|
|
degrees.
|
|
|
|
Thus, to show a very large arrow pointing downward you would use the
|
|
label string "@+92->".
|
|
|
|
\par align()
|
|
|
|
The \p align() method positions the label. The following
|
|
constants are defined and may be OR'd together as needed:
|
|
|
|
\li \p FL_ALIGN_CENTER - center the label in the widget.
|
|
\li \p FL_ALIGN_TOP - align the label at the top of the widget.
|
|
\li \p FL_ALIGN_BOTTOM - align the label at the bottom of the widget.
|
|
\li \p FL_ALIGN_LEFT - align the label to the left of the widget.
|
|
\li \p FL_ALIGN_RIGHT - align the label to the right of the widget.
|
|
\li \p FL_ALIGN_INSIDE - align the label inside the widget.
|
|
\li \p FL_ALIGN_CLIP - clip the label to the widget's bounding box.
|
|
\li \p FL_ALIGN_WRAP - wrap the label text as needed.
|
|
\li \p FL_TEXT_OVER_IMAGE - show the label text over the image.
|
|
\li \p FL_IMAGE_OVER_TEXT - show the label image over the text (default).
|
|
|
|
\anchor common_labeltype
|
|
\par labeltype()
|
|
|
|
The \p labeltype() method sets the type of the label. The
|
|
following standard label types are included:
|
|
|
|
\li \p FL_NORMAL_LABEL - draws the text.
|
|
\li \p FL_NO_LABEL - does nothing.
|
|
\li \p FL_SHADOW_LABEL - draws a drop shadow under the text.
|
|
\li \p FL_ENGRAVED_LABEL - draws edges as though the text is engraved.
|
|
\li \p FL_EMBOSSED_LABEL - draws edges as thought the text is raised.
|
|
\li \p FL_ICON_LABEL - draws the icon associated with the text.
|
|
|
|
\par image() and deimage()
|
|
|
|
The \p image() and \p deimage() methods set an image that
|
|
will be displayed with the widget. The \p deimage() method sets the
|
|
image that is shown when the widget is inactive, while the \p image()
|
|
method sets the image that is shown when the widget is active.
|
|
|
|
To make an image you use a subclass of
|
|
\ref ssect_Fl_Image "Fl_Image".
|
|
|
|
\par Making Your Own Label Types
|
|
|
|
Label types are actually indexes into a table of functions
|
|
that draw them. The primary purpose of this is to use this to
|
|
draw the labels in ways inaccessible through the
|
|
fl_font() mechanisim (e.g. <tt>FL_ENGRAVED_LABEL</tt>) or
|
|
with program-generated letters or symbology.
|
|
|
|
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
|
|
<TR>
|
|
<TD><B>Note:</B>
|
|
<P>This interface has changed in FLTK 2.0!
|
|
</TD>
|
|
</TR>
|
|
</TABLE></CENTER>
|
|
|
|
\par Label Type Functions
|
|
|
|
To setup your own label type you will need to write two
|
|
functions: one to draw and one to measure the label. The draw
|
|
function is called with a pointer to a Fl_Label
|
|
structure containing the label information, the bounding box for
|
|
the label, and the label alignment:
|
|
|
|
\code
|
|
void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) {
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
The label should be drawn \e inside this bounding box,
|
|
even if \p FL_ALIGN_INSIDE is not enabled. The function
|
|
is not called if the label value is \p NULL.
|
|
|
|
The measure function is called with a pointer to a
|
|
Fl_Label structure and references to the width and
|
|
height:
|
|
|
|
\code
|
|
void xyz_measure(const Fl_Label *label, int &w, int &h) {
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
The function should measure the size of the label and set
|
|
\p w and \p h to the size it will occupy.
|
|
|
|
\par Adding Your Label Type
|
|
|
|
The Fl::set_labeltype() method creates a label type
|
|
using your draw and measure functions:
|
|
|
|
\code
|
|
#define XYZ_LABEL FL_FREE_LABELTYPE
|
|
|
|
Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure);
|
|
\endcode
|
|
|
|
The label type number \p n can be any integer value
|
|
starting at the constant \p FL_FREE_LABELTYPE. Once you
|
|
have added the label type you can use the \p labeltype()
|
|
method to select your label type.
|
|
|
|
The Fl::set_labeltype() method can also be used to overload
|
|
an existing label type such as \p FL_NORMAL_LABEL.
|
|
|
|
\par Making your own symbols
|
|
|
|
It is also possible to define your own drawings and add
|
|
them to the symbol list, so they can be rendered as part of
|
|
any label.
|
|
|
|
To create a new symbol, you implement a drawing function
|
|
<tt>void drawit(Fl_Color c)</tt> which typically uses the
|
|
functions described in \ref ssect_Complex
|
|
to generate a vector shape inside a two-by-two units sized box
|
|
around the origin. This function is then linked into the symbols
|
|
table using fl_add_symbol():
|
|
|
|
\code
|
|
int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)
|
|
\endcode
|
|
|
|
\p name is the name of the symbol without the "@"; \p scalable
|
|
must be set to 1 if the symbol is generated using scalable vector drawing
|
|
functions.
|
|
|
|
\code
|
|
int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)
|
|
\endcode
|
|
|
|
This function draws a named symbol fitting the given rectangle.
|
|
|
|
\section common_callbacks Callbacks
|
|
|
|
Callbacks are functions that are called when the value of a
|
|
widget changes. A callback function is sent a Fl_Widget
|
|
pointer of the widget that changed and a pointer to data that
|
|
you provide:
|
|
|
|
\code
|
|
void xyz_callback(Fl_Widget *w, void *data) {
|
|
...
|
|
}
|
|
\endcode
|
|
|
|
The \p callback() method sets the callback function for a
|
|
widget. You can optionally pass a pointer to some data needed for the
|
|
callback:
|
|
|
|
\code
|
|
int xyz_data;
|
|
|
|
button->callback(xyz_callback, &xyz_data);
|
|
\endcode
|
|
|
|
Normally callbacks are performed only when the value of the
|
|
widget changes. You can change this using the Fl_Widget::when()
|
|
method:
|
|
|
|
\code
|
|
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);
|
|
\endcode
|
|
|
|
<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc">
|
|
<TR>
|
|
<TD><B>Note:</B>
|
|
|
|
You cannot delete a widget inside a callback, as the
|
|
widget may still be accessed by FLTK after your callback
|
|
is completed. Instead, use the Fl::delete_widget()
|
|
method to mark your widget for deletion when it is safe
|
|
to do so.
|
|
|
|
<B>Hint:</B>
|
|
|
|
Many programmers new to FLTK or C++ try to use a
|
|
non-static class method instead of a static class method
|
|
or function for their callback. Since callbacks are done
|
|
outside a C++ class, the <tt>this</tt> pointer is not
|
|
initialized for class methods.
|
|
|
|
To work around this problem, define a static method
|
|
in your class that accepts a pointer to the class, and
|
|
then have the static method call the class method(s) as
|
|
needed. The data pointer you provide to the
|
|
\p callback() method of the widget can be a
|
|
pointer to the instance of your class.
|
|
|
|
\code
|
|
class Foo {
|
|
void my_callback(Fl_Widget *w);
|
|
static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); }
|
|
...
|
|
}
|
|
|
|
...
|
|
|
|
w->callback(my_static_callback, (void *)this);
|
|
\endcode
|
|
</TD>
|
|
</TR>
|
|
</TABLE></CENTER>
|
|
|
|
\section common_shortcuts Shortcuts
|
|
|
|
Shortcuts are key sequences that activate widgets such as
|
|
buttons or menu items. The \p shortcut() method sets the
|
|
shortcut for a widget:
|
|
|
|
\code
|
|
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
|
|
\endcode
|
|
|
|
The shortcut value is the key event value - the ASCII value
|
|
or one of the special keys described in
|
|
\ref enumerations_event_key
|
|
combined with any modifiers like \p Shift , \p Alt , and \p Control.
|
|
|
|
|
|
\htmlonly
|
|
<hr>
|
|
<table summary="navigation bar" width="100%" border="0">
|
|
<tr>
|
|
<td width="45%" align="LEFT">
|
|
<a class="el" href="basics.html">
|
|
[Prev]
|
|
FLTK Basics
|
|
</a>
|
|
</td>
|
|
<td width="10%" align="CENTER">
|
|
<a class="el" href="main.html">[Index]</a>
|
|
</td>
|
|
<td width="45%" align="RIGHT">
|
|
<a class="el" href="editor.html">
|
|
Designing a Simple Text Editor
|
|
[Next]
|
|
</a>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
\endhtmlonly
|
|
|
|
*/
|