diff options
Diffstat (limited to 'documentation/common.html')
| -rw-r--r-- | documentation/common.html | 761 |
1 files changed, 493 insertions, 268 deletions
diff --git a/documentation/common.html b/documentation/common.html index b13955da2..e05bdfbc8 100644 --- a/documentation/common.html +++ b/documentation/common.html @@ -1,326 +1,515 @@ -<HTML><BODY> +<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. + +<P>This chapter describes many of the widgets that are provided +with FLTK and covers how to query and set the standard +attributes.</P> + <H2>Buttons</H2> - FLTK provides many types of buttons: + +<P>FLTK provides many types of buttons:</P> + <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> + + <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 <KBD>Enter</KBD> key.</LI> + + <LI><A HREF="Fl_Round_Button.html"><TT>Fl_Round_Button</TT></A> - + A button with a radio 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> + +<P ALIGN="CENTER"><IMG SRC="buttons.gif" ALT="FLTK Buttons"><BR> +Figure 3-1: FLTK Button Widgets</P> + +<P>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:</P> + +<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); +</PRE></UL> + +<P>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:</P> + +<UL><PRE> +button->type(FL_NORMAL_BUTTON); 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_Button.html#Fl_Button.set"><TT>set()</TT></A> and <A href="Fl_Button.html#Fl_Button.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_Button.html#Fl_Button.setonly"><TT>setonly()</TT></A> method; this -will also turn off other radio buttons in the same group. +</PRE></UL> + +<P>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_Button.html#Fl_Button.set"><TT>set()</TT></A> and +<A href="Fl_Button.html#Fl_Button.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_Button.html#Fl_Button.setonly"><TT>setonly()</TT></A> +method; this will also turn off other radio buttons in the same +group.</P> + <H2>Text</H2> - FLTK provides several text widgets for displaying and receiving text: + +<P>FLTK provides several text widgets for displaying and receiving text:</P> + <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> + + <LI><A HREF="Fl_Input.html"><TT>Fl_Input</TT></A> - A + one-line text input field.</LI> + + <LI><A HREF="Fl_Output.html"><TT>Fl_Output</TT></A> - A + one-line text output field.</LI> + + <LI><A HREF="Fl_Multiline_Input.html"><TT>Fl_Multiline_Input</TT></A> + - A multi-line text input field. </LI> + + <LI><A HREF="Fl_Multiline_Output.html"><TT>Fl_Multiline_Output</TT></A> + - A multi-line text output field.</LI> + + <LI><A HREF="Fl_Text_Display.html"><TT>Fl_Text_Display</TT></A> + - A multi-line text display widget.</LI> + + <LI><A HREF="Fl_Text_Editor.html"><TT>Fl_Text_Editor</TT></A> - + A multi-line text editing widget. </LI> + + <LI><A HREF="Fl_Help_View.html"><TT>Fl_Help_View</TT></A> - A + HTML text display widget.</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> + +<P>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> + +<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. +</PRE></UL> + +<P>The string is copied to the widget's own storage when you set +the <tt>value()</tt> of the widget.</P> + +<P>The <TT>Fl_Text_Display</TT> and <TT>Fl_Text_Editor</TT> +widgets use an associated <TT>Fl_Text_Buffer</TT> class for the +value, instead of a simple string.</P> + <H2>Valuators</H2> - Unlike text widgets, valuators keep track of numbers instead of -strings. FLTK provides the following valuators: + +<P>Unlike text widgets, valuators keep track of numbers instead of +strings. FLTK provides the following valuators:</P> + <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> + + <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. + +<P ALIGN="CENTER"><IMG SRC="valuators.gif" ALT="FLTK Valuators"><BR> +<I>Figure 3-2: FLTK valuator widgets</I></P> + +<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.</P> + <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: + +<P>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:</P> + <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> + + <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_Packed.html"><TT>Fl_Pack</TT></A> - A collection of widgets that are packed into the group area.</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_Tile.html"><TT>Fl_Tile</TT></A> - A tiled window area.</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> + +<P>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> + +<P>You can change the size and position by using the +<TT>position()</TT>, <TT> resize()</TT>, and <TT>size()</TT> +methods:</P> + +<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: +</PRE></UL> + +<P>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.</P> + +<H2><A NAME="colors">Colors</A></H2> + +<P>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 <i>not</i> +the X or WIN32 colormap, but instead is an internal table with +fixed contents.</P> + +<P>There are symbols for naming some of the more common colors:</P> + <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> + <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> + +<P>RGB colors can be set using the <A HREF="drawing.html#fl_rgb_color"><TT>fl_rgb_color()</TT></A> +function:</P> + +<UL><PRE> +Fl_Color c = fl_rgb_color(85, 170, 255); +</PRE></UL> + +<P>The widget color is set using the <TT>color()</TT> method:</P> + +<UL><PRE> button->color(FL_RED); -</PRE> -</UL> - Similarly, the label color can be set using the <TT>labelcolor()</TT> - method: -<UL> -<PRE> +</PRE></UL> + +<P>Similarly, the label color is set using the <TT>labelcolor()</TT> +method:</P> + +<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> +</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>. +Figure 3-3 shows the standard box types included with FLTK.</P> + +<P ALIGN="CENTER"><IMG src="boxtypes.gif" ALT="FLTK Box Types"><BR> +<I>Figure 3-3: FLTK box types</I></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. +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.</P> + +<H3>Making Your Own Boxtypes</H3> + +<P>You can define your own boxtypes by making a small function that draws +the box and adding it to the table of boxtypes.</P> + +<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!</P> + </TD> +</TR> +</TABLE></CENTER> + <H4>The Drawing Function</H4> - The drawing function is passed the bounding box and background color -for the widget: -<UL> -<PRE> + +<P>The drawing function is passed the bounding box and background color +for the widget:</P> + +<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> +</PRE></UL> + +<P>A simple drawing function might fill a rectangle with the +given color and then draw a black outline:</P> + +<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> +</PRE></UL> + <H4>Adding Your Box Type</H4> - The <TT>Fl::set_boxtype()</TT> method adds or replaces the specified -box type: -<UL> -<PRE> + +<P>The <TT>Fl::set_boxtype()</TT> method adds or replaces the +specified box type:</P> + +<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. +</PRE></UL> + +<P>The last 4 arguments to <TT>Fl::set_boxtype()</TT> are the +offsets for the x, y, width, and height values that should be +subtracted when drawing the label inside the box.</P> + +<H2><A NAME="labels">Labels and Label Types</A></H2> + +<P>The <TT>label()</TT>, <TT>align()</TT>, <TT>labelfont()</TT>, +<TT>labelsize()</TT>, <TT>labeltype()</TT>, <TT>image()</TT>, and +<TT>deimage()</TT> methods control the labeling of widgets.</P> + <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. + +<P>The <TT>label()</TT> 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.</P> + +<P ALIGN="CENTER"><IMG src="symbols.gif" ALT="FLTK Symbols"><BR> +<I>Figure 3-4: FLTK label symbols</I></P> + +<P>The @ sign may also 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> + <H3>align()</H3> - The <TT>align()</TT> method positions the label. The following -constants are defined (they may be OR'd together as needed): + +<P>The <TT>align()</TT> method positions the label. The following +constants are defined and may be OR'd together as needed:</P> + <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> + + <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> + + <LI><TT>FL_TEXT_OVER_IMAGE</TT> - show the label text over the image.</LI> + + <LI><TT>FL_IMAGE_OVER_TEXT</TT> - show the label image over the text (default).</LI> + </UL> + <H3><A NAME="labeltypes">labeltype()</A></H3> - The <TT>labeltype()</TT> method sets the type of the label. The -following standard label types are included: + +<P>The <TT>labeltype()</TT> method sets the type of the label. The +following standard label types are included:</P> + <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> + + <LI><TT>FL_NORMAL_LABEL</TT> - draws the text.</LI> + + <LI><TT>FL_NO_LABEL</TT> - does nothing.</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> + + <LI><TT>FL_ICON_LABEL</TT> - draws the icon associated + with the text.</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. + +<H3>image() and deimage()</H3> + +<P>The <TT>image()</TT> and <TT>deimage()</TT> methods set an image that +will be displayed with the widget. The <TT>deimage()</TT> method sets the +image that is shown when the widget is inactive, while the <TT>image()</TT> +method sets the image that is shown when the widget is active.</P> + +<P>To make an image you use a subclass of +<A HREF="drawing.html#Fl_Image"><TT>Fl_Image</TT></A>.</P> + <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. + +<P>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 +<TT>fl_font</TT> mechanisim (e.g. <TT>FL_ENGRAVED_LABEL</TT>) or +with program-generated letters or symbology.</P> + +<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!</P> + </TD> +</TR> +</TABLE></CENTER> + <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 <TT>Fl_Label</TT> structure containing the -label information, the bounding box for the label, and the label -alignment: -<UL> -<PRE> + +<P>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 <TT>Fl_Label</TT> +structure containing the label information, the bounding box for +the label, and the label alignment:</P> + +<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 <TT>Fl_Label</TT> -structure and references to the width and height: </P> -<UL> -<PRE> +</PRE></UL> + +<P>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> + +<P>The measure function is called with a pointer to a +<TT>Fl_Label</TT> 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. +</PRE></UL> + +<P>The function should measure the size of the label and set +<TT>w</TT> and <TT>h</TT> to the size it will occupy.</P> + <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> + +<P>The <TT>Fl::set_labeltype</TT> method creates a label type +using your draw and measure functions:</P> + +<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. +</PRE></UL> + +<P>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> + <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> +an existing label type such as <TT>FL_NORMAL_LABEL</TT>.</P> + <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> + +<P>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 a pointer to data that +you provide:</P> + +<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> +</PRE></UL> + +<P>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:</P> + +<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->callback(xyz_callback, &xyz_data); +</PRE></UL> + +<P>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:</P> + +<UL><PRE> button->when(FL_WHEN_NEVER); button->when(FL_WHEN_CHANGED); button->when(FL_WHEN_RELEASE); @@ -328,24 +517,60 @@ 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> +</PRE></UL> + +<CENTER><TABLE WIDTH="80%" BORDER="1" CELLPADDING="5" CELLSPACING="0" BGCOLOR="#cccccc"> +<TR> + <TD><B>Hint:</B> + + <P>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.</P> + + <P>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 + <TT>callback()</TT> method of the widget can be a + pointer to the instance of your class.</P> + + <UL><PRE> +class foo { + void my_callback(Widget *); + static void my_static_callback(Widget *w, foo *f) { f->my_callback(w); } + ... +} + +... + +w->callback(my_static_callback, this); + </PRE></UL> + </TD> +</TR> +</TABLE></CENTER> + <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> + +<P>Shortcuts are key sequences that activate widgets such as +buttons or menu items. The <TT>shortcut()</TT> method sets the +shortcut for a widget:</P> + +<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> +</PRE></UL> + +<P>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 <KBD>Shift</KBD>, +<KBD>Alt</KBD>, and <KBD>Control</KBD>.</P> + +</BODY> +</HTML> |