diff options
| author | Albrecht Schlosser <albrechts.fltk@online.de> | 2008-09-14 21:58:12 +0000 |
|---|---|---|
| committer | Albrecht Schlosser <albrechts.fltk@online.de> | 2008-09-14 21:58:12 +0000 |
| commit | de6f468b5121df32566bbaa3b250d35eae8e1178 (patch) | |
| tree | 0f4b8e5b0fdccb9bb7ba3f07a49c4ebed11ca77f /documentation/common.dox | |
| parent | 7f544a0cf941eeaf7760700839d8a2b143a540e2 (diff) | |
Edited basic chapters to be more doxygen-friendly, added \image html
statements.
git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6245 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
Diffstat (limited to 'documentation/common.dox')
| -rw-r--r-- | documentation/common.dox | 290 |
1 files changed, 133 insertions, 157 deletions
diff --git a/documentation/common.dox b/documentation/common.dox index 20553873e..6dc452010 100644 --- a/documentation/common.dox +++ b/documentation/common.dox @@ -11,61 +11,49 @@ attributes.</P> <P>FLTK provides many types of buttons:</P> <UL> + <LI>Fl_Button - A standard push button.</LI> - <LI><A HREF="Fl_Button.html"><TT>Fl_Button</TT></A> - A - standard push button.</LI> + <LI>Fl_Check_Button - A button with a check box.</LI> - <LI><A HREF="Fl_Check_Button.html"><TT>Fl_Check_Button</TT></A> - - A button with a check box.</LI> + <LI>Fl_Light_Button - A push button with a light.</LI> - <LI><A HREF="Fl_Light_Button.html"><TT>Fl_Light_Button</TT></A> - - A push button with a light.</LI> + <LI>Fl_Repeat_Button - A push button that repeats + when held.</LI> - <LI><A HREF="Fl_Repeat_Button.html"><TT>Fl_Repeat_Button</TT></A> - - A push button that repeats when held.</LI> + <LI>Fl_Return_Button - A push button that is activated + by the <KBD>Enter</KBD> key.</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> + <LI>Fl_Round_Button - A button with a radio circle.</LI> </UL> -<P ALIGN="CENTER"><IMG SRC="buttons.gif" ALT="FLTK Buttons"><BR> -Figure 3-1: FLTK Button Widgets</P> +\image html buttons.gif "Figure 3-1: FLTK Button Widgets" <P>All of these buttons just need the corresponding -<TT><FL/Fl_xyz_Button.H></TT> header file. The constructor +<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"); +\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"); -</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> - -<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> +Fl_Round_Button *rbutton = new Fl_Round_Button(x, y, width, height, "label"); +\endcode + +<P>Each button has an associated <TT>type()</TT> which allows +it to behave as a push button, toggle button, or radio button:</P> + +\code +button->type(FL_NORMAL_BUTTON); +lbutton->type(FL_TOGGLE_BUTTON); +rbutton->type(FL_RADIO_BUTTON); +\endcode + +<P>For toggle and radio buttons, the value() method returns +the current button state (0 = off, 1 = on). The set() and +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 setonly() method; this will also turn off other radio buttons in the same group.</P> @@ -74,41 +62,32 @@ group.</P> <P>FLTK provides several text widgets for displaying and receiving text:</P> <UL> + <LI>Fl_Input - A one-line text input 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>Fl_Output - A one-line text output field.</LI> - <LI><A HREF="Fl_Multiline_Output.html"><TT>Fl_Multiline_Output</TT></A> - - A multi-line text output field.</LI> + <LI>Fl_Multiline_Input - A multi-line text input field.</LI> - <LI><A HREF="Fl_Text_Display.html"><TT>Fl_Text_Display</TT></A> - - A multi-line text display widget.</LI> + <LI>Fl_Multiline_Output - A multi-line text output field.</LI> - <LI><A HREF="Fl_Text_Editor.html"><TT>Fl_Text_Editor</TT></A> - - A multi-line text editing widget. </LI> + <LI>Fl_Text_Display - A multi-line text display widget.</LI> - <LI><A HREF="Fl_Help_View.html"><TT>Fl_Help_View</TT></A> - A - HTML text display widget.</LI> + <LI>Fl_Text_Editor - A multi-line text editing widget.</LI> + <LI>Fl_Help_View - A HTML text display widget.</LI> </UL> <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> +<P>The <TT>value()</TT> 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> +\code +Fl_Input *input = new Fl_Input(x, y, width, height, "label"); +input->value("Now is the time for all good men..."); +\endcode <P>The string is copied to the widget's own storage when you set the <tt>value()</tt> of the widget.</P> @@ -126,28 +105,25 @@ 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>Fl_Counter - 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>Fl_Dial - A round knob.</LI> - <LI><A HREF="Fl_Roller.html"><TT>Fl_Roller</TT></A> - An SGI-like dolly widget. </LI> + <LI>Fl_Roller - An SGI-like dolly widget.</LI> - <LI><A HREF="Fl_Scrollbar.html"><TT>Fl_Scrollbar</TT></A> - A standard scrollbar widget. </LI> + <LI>Fl_Scrollbar - A standard scrollbar widget.</LI> - <LI><A HREF="Fl_Slider.html"><TT>Fl_Slider</TT></A> - A scrollbar with a knob. </LI> + <LI>Fl_Slider - 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>Fl_Value_Slider - A slider that shows the current value.</LI> </UL> -<P ALIGN="CENTER"><IMG SRC="valuators.gif" ALT="FLTK Valuators"><BR> -<I>Figure 3-2: FLTK valuator widgets</I></P> +\image html valuators.gif "Figure 3-2: FLTK valuator widgets" -<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> +<P>The <TT>value()</TT> method gets and sets the current value +of the widget. The <TT>minimum()</TT> and <TT>maximum()</TT> methods set the range of values that are reported by the widget.</P> @@ -156,29 +132,31 @@ widget.</P> <H2>Groups</H2> <P>The <TT>Fl_Group</TT> widget class is used as a general -purpose "container" widget. Besides grouping radio +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>Fl_Double_Window - 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>Fl_Gl_Window - 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>Fl_Group - The base container class; can be used to group + any widgets together.</LI> - <LI><A HREF="Fl_Pack.html"><TT>Fl_Pack</TT></A> - A collection of widgets that are packed into the group area.</LI> + <LI>Fl_Pack - 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>Fl_Scroll - A scrolled window area.</LI> - <LI><A HREF="Fl_Tabs.html"><TT>Fl_Tabs</TT></A> - Displays child widgets as tabs. </LI> + <LI>Fl_Tabs - Displays child widgets as tabs.</LI> - <LI><A HREF="Fl_Tile.html"><TT>Fl_Tile</TT></A> - A tiled window area.</LI> + <LI>Fl_Tile - A tiled window area.</LI> - <LI><A HREF="Fl_Window.html"><TT>Fl_Window</TT></A> - A window on the screen. </LI> + <LI>Fl_Window - A window on the screen.</LI> + + <LI>Fl_Wizard - Displays one group of widgets at a time.</LI> </UL> @@ -192,11 +170,11 @@ create them. You can access them with the <tt>x()</tt>, <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> +\code +button->position(x, y); +group->resize(x, y, width, height); +window->size(width, height); +\endcode <P>If you change a widget's size or position after it is displayed you will have to call <tt>redraw()</tt> on the @@ -228,6 +206,8 @@ fixed contents.</P> <LI><TT>FL_CYAN</TT></LI> <LI><TT>FL_WHITE</TT></LI> + + <LI>FL_WHITE</LI> </UL> <P>These symbols are the default colors for all FLTK widgets. They are @@ -244,35 +224,34 @@ explained in more detail in the chapter <LI><TT>FL_SELECTION_COLOR</TT> </LI> </UL> -<P>RGB colors can be set using the <A HREF="functions.html#fl_rgb_color"><TT>fl_rgb_color()</TT></A> +<P>RGB colors can be set using the <TT>fl_rgb_color()</TT> function:</P> -<UL><PRE> +\code Fl_Color c = fl_rgb_color(85, 170, 255); -</PRE></UL> +\endcode <P>The widget color is set using the <TT>color()</TT> method:</P> -<UL><PRE> -button->color(FL_RED); -</PRE></UL> +\code +button->color(FL_RED); +\endcode <P>Similarly, the label color is set using the <TT>labelcolor()</TT> method:</P> -<UL><PRE> -button->labelcolor(FL_WHITE); -</PRE></UL> +\code +button->labelcolor(FL_WHITE); +\endcode <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>. +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> +\image html boxtypes.gif "Figure 3-3: FLTK box types" <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 @@ -297,25 +276,25 @@ the box and adding it to the table of boxtypes.</P> <P>The drawing function is passed the bounding box and background color for the widget:</P> -<UL><PRE> +\code void xyz_draw(int x, int y, int w, int h, Fl_Color c) { ... } -</PRE></UL> +\endcode <!-- NEED 3in --> <P>A simple drawing function might fill a rectangle with the given color and then draw a black outline:</P> -<UL><PRE> +\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); } -</PRE></UL> +\endcode <H4><A name="fl_down">Fl_Boxtype fl_down(Fl_Boxtype)</A></H4> @@ -343,11 +322,11 @@ See also: <TT><A HREF="#fl_frame">fl_frame</A></TT>. <P>The <TT>Fl::set_boxtype()</TT> method adds or replaces the specified box type:</P> -<UL><PRE> +\code #define XYZ_BOX FL_FREE_BOXTYPE Fl::set_boxtype(XYZ_BOX, xyz_draw, 1, 1, 2, 2); -</PRE></UL> +\endcode <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 @@ -376,13 +355,12 @@ 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"><A name="symbols"><IMG src="symbols.gif" ALT="FLTK Symbols"><BR> -<I>Figure 3-4: FLTK label symbols</I></A></P> +\image html symbols.gif "Figure 3-4: FLTK label symbols" <!-- NEED 2in --> <P>The @ sign may also be followed by the following optional -"formatting" characters, in this order:</P> +"formatting" characters, in this order:</P> <UL> @@ -402,7 +380,7 @@ sign. Figure 3-4 shows the available symbols.</P> </UL> <P>Thus, to show a very large arrow pointing downward you would use the -label string "@+92->". +label string "@+92->". <H3>align()</H3> @@ -495,11 +473,11 @@ 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> +\code void xyz_draw(const Fl_Label *label, int x, int y, int w, int h, Fl_Align align) { ... } -</PRE></UL> +\endcode <P>The label should be drawn <I>inside</I> this bounding box, even if <TT>FL_ALIGN_INSIDE</TT> is not enabled. The function @@ -509,11 +487,11 @@ is not called if the label value is <TT>NULL</TT>.</P> <TT>Fl_Label</TT> structure and references to the width and height:</P> -<UL><PRE> -void xyz_measure(const Fl_Label *label, int &w, int &h) { +\code +void xyz_measure(const Fl_Label *label, int &w, int &h) { ... } -</PRE></UL> +\endcode <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> @@ -523,11 +501,11 @@ void xyz_measure(const Fl_Label *label, int &w, int &h) { <P>The <TT>Fl::set_labeltype</TT> method creates a label type using your draw and measure functions:</P> -<UL><PRE> +\code #define XYZ_LABEL FL_FREE_LABELTYPE Fl::set_labeltype(XYZ_LABEL, xyz_draw, xyz_measure); -</PRE></UL> +\endcode <P>The label type number <TT>n</TT> can be any integer value starting at the constant <TT>FL_FREE_LABELTYPE</TT>. Once you @@ -550,19 +528,19 @@ 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 <tt>fl_add_symbol</tt>:</P> -<UL><PRE> -<A NAME="fl_add_symbol">int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable)</A> -</PRE></UL> +\code +int fl_add_symbol(const char *name, void (*drawit)(Fl_Color), int scalable) +\endcode <P><i>name</i> is the name of the symbol without the "@"; <i>scalable</I> must be set to 1 if the symbol is generated using scalable vector drawing functions.</P> -<UL><PRE> -<A NAME="fl_draw_symbol">int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col)</A> -</PRE></UL> +\code +int fl_draw_symbol(const char *name,int x,int y,int w,int h,Fl_Color col) +\endcode -<P>This function draw a named symbol fitting the given rectangle. +<P>This function draws a named symbol fitting the given rectangle. <H2>Callbacks</H2> @@ -571,36 +549,35 @@ 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> +\code void xyz_callback(Fl_Widget *w, void *data) { ... } -</PRE></UL> +\endcode <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> +\code int xyz_data; -button->callback(xyz_callback, &xyz_data); -</PRE></UL> +button->callback(xyz_callback, &xyz_data); +\endcode <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> +widget changes. You can change this using the Fl_Widget::when() method:</P> -<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> +\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> @@ -608,8 +585,7 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); <P>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 <a - href='Fl.html#Fl.delete_widget'><tt>Fl::delete_widget()</tt></a> + is completed. Instead, use the Fl::delete_widget() method to mark your widget for deletion when it is safe to do so.</p> @@ -628,17 +604,17 @@ button->when(FL_WHEN_CHANGED | FL_WHEN_NOT_CHANGED); <TT>callback()</TT> method of the widget can be a pointer to the instance of your class.</P> -<PRE> +\code class Foo { void my_callback(Fl_Widget *w); - static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); } + static void my_static_callback(Fl_Widget *w, void *f) { ((Foo *)f)->my_callback(w); } ... } ... -w->callback(my_static_callback, (void *)this); -</PRE> +w->callback(my_static_callback, (void *)this); +\endcode </TD> </TR> </TABLE></CENTER> @@ -649,14 +625,14 @@ w->callback(my_static_callback, (void *)this); 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> +\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 <P>The shortcut value is the key event value - the ASCII value or one of the special keys like |