<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><TT>Fl_Button</TT> - A standard push button. </LI>
<LI><TT>Fl_Check_Button</TT> - A button with a check box. </LI>
<LI><TT>Fl_Light_Button</TT> - A push button with a light. </LI>
<LI><TT>Fl_Repeat_Button</TT> - A push button that repeats when held. </LI>
<LI><TT>Fl_Return_Button</TT> - A push button that is activated by the 
Enter key. </LI>
<LI><TT>Fl_Round_Button</TT> - 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>
&lt;FL/Fl_xyz_Button.H&gt;</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, &quot;label&quot;);
Fl_Light_Button *lbutton = new Fl_Light_Button(x, y, width, height);
Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, &quot;label&quot;);
</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-&gt;type(0);
lbutton-&gt;type(FL_TOGGLE_BUTTON);
rbutton-&gt;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><TT>Fl_Input</TT> - A standard one-line text input field. </LI>
<LI><TT>Fl_Output</TT> - A standard one-line text output field. </LI>
<LI><TT>Fl_Multiline_Input</TT> - A standard multi-line text input 
field. </LI>
<LI><TT>Fl_Multiline_Output</TT> - 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, &quot;label&quot;);
input-&gt;value(&quot;Now is the time for all good men...&quot;);
</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><TT>Fl_Counter</TT> - A widget with arrow buttons that shows the 
 current value. </LI>
<LI><TT>Fl_Dial</TT> - A round knob. </LI>
<LI><TT>Fl_Roller</TT> - An SGI-like dolly widget. </LI>
<LI><TT>Fl_Scrollbar</TT> - A standard scrollbar widget. </LI>
<LI><TT>Fl_Slider</TT> - A scrollbar with a knob. </LI>
<LI><TT>Fl_Value_Slider</TT> - 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 
&quot;container&quot; 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><TT>Fl_Double_Window</TT> - A double-buffered window on the screen. </LI>
<LI><TT>Fl_Gl_Window</TT> - An OpenGL window on the screen. </LI>
<LI><TT>Fl_Group</TT> - The base container class; can be used to group 
any widgets together. </LI>
<LI><TT>Fl_Scroll</TT> - A scrolled window area. </LI>
<LI><TT>Fl_Tabs</TT> - Displays child widgets as tabs. </LI>
<LI><TT>Fl_Window</TT> - 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-&gt;position(x, y);
group-&gt;resize(x, y, width, height);
window-&gt;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-&gt;color(FL_RED);
</PRE>
</UL>
 Similarly, the label color can be set using the <TT>labelcolor()</TT>
 method: 
<UL>
<PRE>
button-&gt;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>&lt;Enumerations.H&gt;</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 &quot;@xyz&quot; labels, see &quot;<A href=#symbols>
Symbol Labels</A>&quot; </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 may change in future versions of fltk!</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 &amp;w, int &amp;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 &quot;formatting&quot; 
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-&gt;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-&gt;when(FL_WHEN_NEVER);
button-&gt;when(FL_WHEN_CHANGED);
button-&gt;when(FL_WHEN_RELEASE);
button-&gt;when(FL_WHEN_RELEASE_ALWAYS);
button-&gt;when(FL_WHEN_ENTER_KEY);
button-&gt;when(FL_WHEN_ENTER_KEY_ALWAYS);
button-&gt;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-&gt;shortcut(FL_Enter);
button-&gt;shortcut(FL_SHIFT + 'b');
button-&gt;shortcut(FL_CTRL + 'b');
button-&gt;shortcut(FL_ALT + 'b');
button-&gt;shortcut(FL_CTRL + FL_ALT + 'b');
button-&gt;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>