Author: matt Date: 2008-01-31 15:16:26 -0800 (Thu, 31 Jan 2008) New Revision: 6023 Log: After a long long time there is a little update to the doxygen version of FLTK1
Removed: branches/branch-1.1-doxygen/documentation/Fl_Clock_Output.html branches/branch-1.1-doxygen/documentation/Fl_Dial.html branches/branch-1.1-doxygen/documentation/Fl_Toggle_Button.html branches/branch-1.1-doxygen/documentation/Fl_Valuator.html Modified: branches/branch-1.1-doxygen/FL/Fl_Clock.H branches/branch-1.1-doxygen/FL/Fl_Dial.H branches/branch-1.1-doxygen/FL/Fl_Toggle_Button.H branches/branch-1.1-doxygen/FL/Fl_Valuator.H branches/branch-1.1-doxygen/FL/Fl_Widget.H Modified: branches/branch-1.1-doxygen/FL/Fl_Clock.H =================================================================== --- branches/branch-1.1-doxygen/FL/Fl_Clock.H 2008-01-30 09:43:49 UTC (rev 6022) +++ branches/branch-1.1-doxygen/FL/Fl_Clock.H 2008-01-31 23:16:26 UTC (rev 6023) @@ -25,6 +25,10 @@ // http://www.fltk.org/str.php // +/** \file + * Fl_Clock widget definitions for the Fast Light Tool Kit (FLTK). + */ + #ifndef Fl_Clock_H #define Fl_Clock_H @@ -40,6 +44,15 @@ // a Fl_Clock_Output can be used to display a program-supplied time: +/** + * This widget can be used to display a program-supplied time. + * The time shown on the clock is not updated. + * To display the current time, use <TT>Fl_Clock</A></TT> instead. + * + * \image html clock.gif + * + * \image html round_clock.gif + */ class FL_EXPORT Fl_Clock_Output : public Fl_Widget { int hour_, minute_, second_; ulong value_; @@ -48,23 +61,101 @@ void draw(int, int, int, int); void draw(); public: + + /** + * Creates a new <tt>Fl_Clock_Output</tt> widget. + * Create an <tt>Fl_Clock_Output</tt> widget using the given position, + * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>. + * + * \param[in] x, y, w, h position and size of the widget + * \param[in] label widget label, default is no label + */ Fl_Clock_Output(int x,int y,int w,int h, const char *l = 0); + + /** + * Set the displayed time. + * Set the time in seconds since the UNIX epoch (January 1, 1970). + * \see value() + */ void value(ulong v); // set to this Unix time - void value(int,int,int); // set hour, minute, second + + /** + * Set the displayed time. + * Set the time in hours, minutes, and seconds. + * \param[in] hour, minute, second displayed time + * \see hour(), minute(), second() + */ + void value(int hour, int minute, int second); + + /** + * Returns the displayed time. + * Returns the time in seconds since the UNIX epoch (January 1, 1970). + * \see value(ulong) + */ ulong value() const {return value_;} + + /** + * Returns the displayed time. + * Returns the displayed hour (0 to 23). + * \see value(), minute(), second() + */ int hour() const {return hour_;} + + /** + * Returns the displayed time. + * Returns the displayed minute (0 to 59). + * \see value(), hour(), second() + */ int minute() const {return minute_;} + + /** + * Returns the displayed time. + * Returns the displayed second (0 to 60, 60=leap second). + * \see value(), hour(), minute() + */ int second() const {return second_;} }; // a Fl_Clock displays the current time always by using a timeout: +/** + * This widget provides a round analog clock display. + * <tt>Fl_Clock</tt> is provided for Forms compatibility. + * It installs a 1-second timeout callback using <tt>Fl::add_timeout()</tt>. + * + * \image html clock.gif + * + * \image html round_clock.gif + */ class FL_EXPORT Fl_Clock : public Fl_Clock_Output { public: int handle(int); void update(); + + /** + * Creates a new <tt>Fl_Clock</tt> widget. + * Create an <tt>Fl_Clock</tt> widget using the given position, + * size, and label string. The default boxtype is <tt>FL_NO_BOX</tt>. + * + * \param[in] x, y, w, h position and size of the widget + * \param[in] label widget label, default is no label + */ Fl_Clock(int x,int y,int w,int h, const char *l = 0); + + /** + * Creates a new <tt>Fl_Clock</tt> widget. + * Create an <tt>Fl_Clock</tt> widget using the given position, + * size, and label string. + * + * \param[in] t boxtype + * \param[in] x, y, w, h position and size of the widget + * \param[in] label widget label, default is no label + */ Fl_Clock(uchar t,int x,int y,int w,int h, const char *l); + + /** + * The destructor removes the clock. + */ ~Fl_Clock(); }; Modified: branches/branch-1.1-doxygen/FL/Fl_Dial.H =================================================================== --- branches/branch-1.1-doxygen/FL/Fl_Dial.H 2008-01-30 09:43:49 UTC (rev 6022) +++ branches/branch-1.1-doxygen/FL/Fl_Dial.H 2008-01-31 23:16:26 UTC (rev 6023) @@ -25,6 +25,10 @@ // http://www.fltk.org/str.php // +/** \file + * Fl_Dial widget definitions for the Fast Light Tool Kit (FLTK). + */ + #ifndef Fl_Dial_H #define Fl_Dial_H @@ -33,10 +37,18 @@ #endif // values for type(): +/// Draws a normal dial with a knob. #define FL_NORMAL_DIAL 0 +/// Draws a dial with a line. #define FL_LINE_DIAL 1 +/// Draws a dial with a filled arc. #define FL_FILL_DIAL 2 +/** + * The <TT>Fl_Dial</TT> widget provides a circular dial to control a + * single floating point value. + * \image html "dial.gif" + */ class FL_EXPORT Fl_Dial : public Fl_Valuator { short a1,a2; @@ -51,11 +63,72 @@ public: int handle(int); - Fl_Dial(int x,int y,int w,int h, const char *l = 0); + + /** + * Creates a new <TT>Fl_Dial</TT> widget. + * + * Creates a <TT>Fl_Dial</TT> widget using the given position, size, + * and label string. The default type is <TT>FL_NORMAL_DIAL</TT>. + * + * \param[in] x, y, w, h position and size of the Dial + * \param[in] label widget label, default is no label + */ + Fl_Dial(int x,int y,int w,int h, const char *label = 0); + + /** + * Get the angle used for the minimum value. + * The default minimum value is 45 degrees. + * + * \see angle1(short) + */ short angle1() const {return a1;} + + /** + * Set the angle used for the minimum value. + * The default minimum value is 45 degrees. + * 0 degrees is straight down and the angles progress clockwise. + * Normally angle1 is less than angle2, but if you reverse them the + * dial moves counter-clockwise. + * + * \param[in] a minimum angle in degrees + * + * \see angle2(short), angle1(), angles(short, short) + */ void angle1(short a) {a1 = a;} + + /** + * Get the angle used for the maximum value. + * The default maximum value is 45 degrees. + * + * \see angle2(short) + */ short angle2() const {return a2;} + + /** + * Set the angle used for the maximum value. + * The default maximum value is 315 degrees. + * 0 degrees is straight down and the angles progress clockwise. + * Normally angle1 is less than angle2, but if you reverse them the + * dial moves counter-clockwise. + * + * \param[in] a maximum angle in degrees + * + * \see angle1(short), angle2(), angles(short, short) + */ void angle2(short a) {a2 = a;} + + /** + * Set the minimum and maximum angle. + * The default values are 45 and 315 degrees. + * 0 degrees is straight down and the angles progress clockwise. + * Normally angle1 is less than angle2, but if you reverse them the + * dial moves counter-clockwise. + * + * \param[in] a minimum angle in degrees + * \param[in] b maximum angle in degrees + * + * \see angle1(short), angle2(short) + */ void angles(short a, short b) {a1 = a; a2 = b;} }; Modified: branches/branch-1.1-doxygen/FL/Fl_Toggle_Button.H =================================================================== --- branches/branch-1.1-doxygen/FL/Fl_Toggle_Button.H 2008-01-30 09:43:49 UTC (rev 6022) +++ branches/branch-1.1-doxygen/FL/Fl_Toggle_Button.H 2008-01-31 23:16:26 UTC (rev 6023) @@ -25,14 +25,38 @@ // http://www.fltk.org/str.php // +/** \file + * Fl_Toggle_Button widget definitions for the Fast Light Tool Kit (FLTK). + */ + #ifndef Fl_Toggle_Button_H #define Fl_Toggle_Button_H #include "Fl_Button.H" +/** + * The toggle button is a push button that needs to be clicked once + * to toggle on, and one more time to toggle off. + * + * The <TT>Fl_Toggle_Button</TT> subclass displays the "on" state by + * drawing a pushed-in button. + * + * Buttons generate callbacks when they are clicked by the user. You + * control exactly when and how by changing the values for <TT>type()</TT> + * and <TT>when()</TT>. + */ class Fl_Toggle_Button : public Fl_Button { public: - Fl_Toggle_Button(int X,int Y,int W,int H,const char *l=0) + /** + * Creates a new <TT>Fl_Toggle_Button</TT> widget. + * + * The constructor creates a new widget using the given position, + * size, and label string. The default boxtype is <TT>FL_UP_BOX</TT>. + * + * \param[in] x, y, w, h position and size of the Widget + * \param[in] label widget label, default is no label + */ + Fl_Toggle_Button(int X,int Y,int W,int H,const char *l=0) : Fl_Button(X,Y,W,H,l) {type(FL_TOGGLE_BUTTON);} }; Modified: branches/branch-1.1-doxygen/FL/Fl_Valuator.H =================================================================== --- branches/branch-1.1-doxygen/FL/Fl_Valuator.H 2008-01-30 09:43:49 UTC (rev 6022) +++ branches/branch-1.1-doxygen/FL/Fl_Valuator.H 2008-01-31 23:16:26 UTC (rev 6023) @@ -25,6 +25,10 @@ // http://www.fltk.org/str.php // +/** \file + * Fl_Valuator widget definitions for the Fast Light Tool Kit (FLTK). + */ + #ifndef Fl_Valuator_H #define Fl_Valuator_H @@ -36,6 +40,24 @@ #define FL_VERTICAL 0 #define FL_HORIZONTAL 1 +/** + * The <TT>Fl_Valuator</TT> class controls a single floating-point value. + * + * This class controls a single floating-point value + * and provides a consistent interface to set the value, range, and step, + * and insures that callbacks are done the same for every object. + * + * There are probably more of these classes in FLTK than any others: + * + * \image html valuators.gif + * + * In the above diagram each box surrounds an actual subclass. These + * are further differentiated by setting the <TT> type()</TT></A> + * of the widget to the symbolic value labeling the + * widget. The ones labelled "0" are the default versions with a <TT> + * type(0)</TT>. For consistency the symbol <TT>FL_VERTICAL</TT> is + * defined as zero. + */ class FL_EXPORT Fl_Valuator : public Fl_Widget { double value_; @@ -46,6 +68,16 @@ protected: int horizontal() const {return type()&1;} + + /** + * Creates a new <TT>Fl_Valuator</TT> widget. + * + * The constructor creates a new widget using the given position, + * size, and label string. The default boxtype is <TT>FL_NO_BOX</TT>. + * + * \param[in] x, y, w, h position and size of the Widget + * \param[in] label widget label, default is no label + */ Fl_Valuator(int X, int Y, int W, int H, const char* L); double previous_value() const {return previous_value_;} @@ -58,25 +90,204 @@ public: + /** + * Sets the minimum and maximum values for the valuator widget. + * + * <tt>bounds(double, double)</tt> is the same as <tt>range(double, double)</tt>. + * + * \param[in] a minimum value + * \param[in] b maximum value + * \see minimum(), maximum(), minimum(double), maximum(double) + * \see range(double, double) + */ void bounds(double a, double b) {min=a; max=b;} + + /** + * Gets the minimum value for the valuator. + * + * \return minimum value + * \see minimum(double), maximum() + */ double minimum() const {return min;} + + /** + * Sets the minimum value for the valuator. + * + * \param[in] a minimum value + * \see minimum(), maximum(double) + */ void minimum(double a) {min = a;} + + /** + * Gets the maximum value for the valuator. + * + * \return maximum value + * \see maximum(double), minimum() + */ double maximum() const {return max;} + + /** + * Sets the maximum value for the valuator. + * + * \param[in] a maximum value + * \see maximum(), minimum(double) + */ void maximum(double a) {max = a;} + + /** + * Sets the minimum and maximum values for the valuator. + * + * When the user manipulates the widget, the value is limited to this + * range. This clamping is done <I>after</I> rounding to the step + * value (this makes a difference if the range is not a multiple of + * the step). + * + * The minimum may be greater than the maximum. This has the + * effect of "reversing" the object so the larger values + * are in the opposite direction. This also switches which end of + * the filled sliders is filled. + * + * Some widgets consider this a "soft" range. This + * means they will stop at the range, but if the user releases and + * grabs the control again and tries to move it further, it is + * allowed. + * + * The range may affect the display. You must <TT>redraw()</TT> + * the widget after changing the range. + * + * \param[in] min minimum value + * \param[in] max maximum value + * \see minimum(), maximum(), minimum(double), maximum(double) + * \see bounds(double, double) + */ void range(double a, double b) {min = a; max = b;} + + /** + * Sets the step value. + * + * \param[in] a ratio as an integer + * \see step(double), step(double, int) + */ void step(int a) {A = a; B = 1;} + + /** + * Sets the step value. + * + * As the user moves the mouse the + * value is rounded to the nearest multiple of the step value. This + * is done <I>before</I> clamping it to the range. For most widgets + * the default step is zero. + * + * For precision the step is stored as the ratio of two + * integers, <i>a/b</i>. You can set these integers directly. Currently + * setting a floating point value sets the nearest <i>a/1</i> or <i>1/b</i> value + * possible. + * + * \param[in] a, b ratio as a fraction + * \see step(double), step(int) + */ void step(double a, int b) {A = a; B = b;} + + /** + * Sets the step value. + * + * \param[in] a ratio as a floating point number + * \see step(int), step(double, int) + */ void step(double s); + + /** + * Gets the step value. + * + * \return step value as a floating point number + */ double step() const {return A/B;} - void precision(int); + /** + * Sets the step value to 1/10<SUP>digits</SUP>. + * + * \param[in] digits new precision + */ + void precision(int digits); + + /** + * Gets the current value. + * + * \return current value + */ double value() const {return value_;} - int value(double); + + /** + * Gets or sets the current value. + * + * The new value is <I>not</I> + * clamped or otherwise changed before storing it. Use + * <TT>clamp()</TT> or <TT>round()</TT> to modify the value before + * calling <TT>value()</TT>. The widget is redrawn if the new value + * is different than the current one. The initial value is zero. + * + * \param[in] v new value + * \return 1 if the value changed, 0 otherwise + */ + int value(double v); - virtual int format(char*); + /** + * Format the fields numerical value into a string. + * + * Uses internal rules to format the fields numerical value into + * the character array pointed to by the passed parameter. + * + * The actual format used depends on the current step value. If + * the step value has been set to zero then a %g format is used. + * If the step value is non-zero, then a %.*f format is used, + * where the precision is calculated to show sufficient digits + * for the current step value. An integer step value, such as 1 + * or 1.0, gives a precision of 0, so the formatted value will + * appear as an integer. + * + * This method is used by the <TT>Fl_Value_...</TT> group of widgets to + * format the current value into a text string. + * The return value is the length of the formatted text. + * The formatted value is written into in <i>buffer</i>. + * <i>buffer</i> should have space for at least 128 bytes. + * + * You may override this function to create your own text formatting. + * + * \param[out] buffer pointer to a 128 byte buffer that will + * contain the formatted value + * \return length of the formatted text + */ + virtual int format(char *buffer); + + /** + * Round the passed value to the nearest step increment. + * + * Does nothing if step is zero. + * + * \param[in] v value + * \return rounded value + */ double round(double); // round to nearest multiple of step - double clamp(double); // keep in range - double increment(double, int); // add n*step to value + + /** + * Clamps the passed value to the valuator range. + * + * \param[in] v value + * \return clamped value + */ + double clamp(double v); // keep in range + + /** + * Adds <i>n</i> times the step value to the passed value. + * + * If step was set to zero it uses <TT>fabs(maximum() - minimum()) / + * 100</TT>. + * + * \param[in] value this value will be incremented + * \param[in] n increment value <i>n</i> times + * \return the incremented value + */ + double increment(double value, int n); // add n*step to value }; #endif Modified: branches/branch-1.1-doxygen/FL/Fl_Widget.H =================================================================== --- branches/branch-1.1-doxygen/FL/Fl_Widget.H 2008-01-30 09:43:49 UTC (rev 6022) +++ branches/branch-1.1-doxygen/FL/Fl_Widget.H 2008-01-31 23:16:26 UTC (rev 6023) @@ -52,6 +52,20 @@ void measure(int&, int&) const ; }; + +/** + * Fl_Widget is the base class for all widgets in FLTK. You can't + * create one of these because the constructor is not public. However you + * can subclass it. + * + * All "property" accessing methods, such as color(), + * parent(), or argument() are implemented as trivial inline + * functions and thus are as fast and small as accessing fields in a + * structure. Unless otherwise noted, the property setting methods such as + * color(n) or label(s) are also trivial inline functions, + * even if they change the widget's appearance. It is up to the user code + * to call redraw() after these. + */ class FL_EXPORT Fl_Widget { friend class Fl_Group; @@ -77,7 +91,17 @@ protected: - Fl_Widget(int,int,int,int,const char* =0); + /** + * Creates a widget at the given position and size. The + * Fl_Widget is a protected constructor, but all derived + * widgets have a matching public constructor. It takes a value for + * x(), y(), w(), h(), and an + * optional value for label(). + * + * \param[in] x, y, w, h position and size of the widget + * \param[in] label pointer to the label text (will not be copied) + */ + Fl_Widget(int x, int y, int w, int h, const char* label=0); void x(int v) {x_ = (short)v;} void y(int v) {y_ = (short)v;} @@ -100,107 +124,660 @@ public: + /** + * Destroys the widget. Destroying single widgets is not very + * common, and it is your responsibility to either + * remove() them from any enclosing group or destroy that + * group <I>immediately</I> after destroying the children. You + * almost always want to destroy the parent group instead which + * will destroy all of the child widgets and groups in that group. + */ virtual ~Fl_Widget(); virtual void draw() = 0; + + /** + * Handles the specified event. You normally don't call this + * method directly, but instead let FLTK do it when the user + * interacts with the widget + * + * When implemented in a new widget, this function must return 0 + * if the widget does not use the event or 1 if it uses the + * event. + */ virtual int handle(int); + + /** + * Returns a pointer to the parent widget. Usually this is a + * Fl_Group or Fl_Window. Returns + * <tt>NULL</tt> if the widget has no parent. + */ Fl_Group* parent() const {return parent_;} + + /** + * This function manipulates a pointer. Please use Fl_Group::add() + * to set the parent od a widget. + */ void parent(Fl_Group* p) {parent_ = p;} // for hacks only, Fl_Group::add() + /** + * Returns the widget type value, which is used for Forms + * compatability and to simulate RTTI. + */ uchar type() const {return type_;} void type(uchar t) {type_ = t;} + /** + * Returns the position of the upper-left corner of the widget + * in its enclosing Fl_Window (<I>not</I> its parent if that is not + * an Fl_Window). + */ int x() const {return x_;} + + /** + * Returns the position of the upper-left corner of the widget + * in its enclosing Fl_Window (<I>not</I> its parent if that is not + * an Fl_Window). + */ int y() const {return y_;} + + /** + * Returns the width of the widget. + */ int w() const {return w_;} + + /** + * Returns the height of the widget. + */ int h() const {return h_;} + + /** + * Change the size and position of the widget. This is a virtual + * function so that the widget may implement its own handling of + * resizing. The default version does <I>not</I> call the + * <TT>redraw()</TT> method, but instead relies on the parent + * widget to do so because the parent may know a faster way to + * update the display, such as scrolling from the old position. + * + * Some window managers under X11 call resize() a lot more + * often than needed. Please verify that the position or size of + * a widget did actually change before doing any extensiive calculations. + */ virtual void resize(int,int,int,int); + int damage_resize(int,int,int,int); + + /** + * position(x,y) is a shortcut for resize(x,y,w(),h()). + */ void position(int X,int Y) {resize(X,Y,w_,h_);} + + /** + * size(w,h) is a shortcut for resize(x(),y(),w,h). + */ void size(int W,int H) {resize(x_,y_,W,H);} + + /** + * Gets the label alignment, which controls how the + * label is displayed next to or inside the widget. + */ Fl_Align align() const {return (Fl_Align)align_;} + + /** + * Sets the label alignment, which controls how the + * label is displayed next to or inside the widget. The default + * value is FL_ALIGN_CENTER, which centers the label + * inside the widget. The value can be any of these constants + * bitwise-OR'd together: + * * FL_ALIGN_BOTTOM + * * FL_ALIGN_CENTER + * * FL_ALIGN_CLIP + * * FL_ALIGN_INSIDE + * * FL_ALIGN_LEFT + * * FL_ALIGN_RIGHT + * * FL_ALIGN_TEXT_OVER_IMAGE + * * FL_ALIGN_TOP + * * FL_ALIGN_WRAP + * + * \param[in] a alignment + */ void align(uchar a) {align_ = a;} + + /** + * Gets the box type for the widget. + */ Fl_Boxtype box() const {return (Fl_Boxtype)box_;} + + /** + * <P>Sets the box type for the widget, which identifies a + * routine that draws the background of the widget. See + * Box Types for the available + * types. The default depends on the widget, but is usually + * FL_NO_BOX or FL_UP_BOX. + * + * \param[in] a box type identifier + */ void box(Fl_Boxtype a) {box_ = a;} + + /** + * Gets the background color of the widget. + */ Fl_Color color() const {return (Fl_Color)color_;} + + /** + * Sets the background color of the widget. The color is + * passed to the box routine. The color is either an index into an + * internal table of RGB colors or an RGB color value generated + * using fl_rgb_color(). The default for most widgets is + * FL_BACKGROUND_COLOR. See the enumeration list for + * predefined colors. Use Fl::set_color() to + * redefine colors. + * + * \param[in] a new background color + */ void color(unsigned a) {color_ = a;} + + /** + * Gets the selection color. + */ Fl_Color selection_color() const {return (Fl_Color)color2_;} + + /** + * Sets the selection color, which is defined for Forms + * compatibility and is usually used to color the widget when it is + * selected, although some widgets use this color for other + * purposes. You can set both colors at once with + * color(a,b). + */ void selection_color(unsigned a) {color2_ = a;} + + /** + * Sets both the background and selection + * colors. See the description of the selection_color() + * method for more information. + * + * \param[in] a new background color + * \param[in] b new selection color + */ void color(unsigned a, unsigned b) {color_=a; color2_=b;} + + /** + * Get the current label pointer. + */ const char* label() const {return label_.value;} + + /** + * Set the current label pointer. The label is shown + * somewhere on or next to the widget. The passed pointer is stored + * unchanged in the widget (the string is <I>not</I> copied), so if + * you need to set the label to a formatted value, make sure the + * buffer is <TT>static</TT>, global, or allocated. The + * copy_label() method * can be used to make a copy of the label string + * automatically. + * + * \param[in] a new label as static ASCII text + */ void label(const char* a); + + /** + * Sets the current label. Unlike Fl_Widget::label(), this method + * allocates a copy of the label string instead of using the + * original string pointer. + * + * \param[in] a new text for label + */ void copy_label(const char* a); void label(Fl_Labeltype a,const char* b) {label_.type = a; label_.value = b;} + + /** + * Gets the labeltype which + * identifies the function that draws the label of the widget. + */ Fl_Labeltype labeltype() const {return (Fl_Labeltype)label_.type;} + + /** + * Sets the labeltype which + * identifies the function that draws the label of the widget. This + * is generally used for special effects such as embossing or for + * using the label() pointer as another form of data such + * as an icon. The value FL_NORMAL_LABEL prints the label + * as plain text. + * + * \param[in] a the new label type + */ void labeltype(Fl_Labeltype a) {label_.type = a;} + + /** + * Gets the label color. + */ Fl_Color labelcolor() const {return (Fl_Color)label_.color;} + + /** + * Sets the label color. The default color is FL_FOREGROUND_COLOR. + */ void labelcolor(unsigned a) {label_.color=a;} + + /** + * Gets the font to use. + */ Fl_Font labelfont() const {return (Fl_Font)label_.font;} + + /** + * Sets the font to use. Fonts are identified by small + * 8-bit indexes into a table. See the + * enumeration list for predefined typefaces. The default value uses a Helvetica + * typeface (Arial for Microsoft® Windows®). The function Fl::set_font() can + * define new typefaces. + * + * \param[in] a font identifier + */ void labelfont(uchar a) {label_.font=a;} + + /** + * Gets the font size in pixels. + */ uchar labelsize() const {return label_.size;} + + /** + * Sets the font size in pixels. The default size is 14 pixels. + */ void labelsize(uchar a) {label_.size=a;} + + /** + * Gets the image to use as part of the widget label. + * This image is used when drawing the widget in the active state. + */ Fl_Image* image() {return label_.image;} + + /** + * Sets the image to use as part of the widget label. + * This image is used when drawing the widget in the active state. + * + * \param[in] a the image + */ void image(Fl_Image* a) {label_.image=a;} + + /** + * Sets the image to use as part of the widget label. + * This image is used when drawing the widget in the active state. + * + * \param[in] a the image + */ void image(Fl_Image& a) {label_.image=&a;} + + /** + * Gets the image to use as part of the widget label. + * This image is used when drawing the widget in the inactive + * state. + */ Fl_Image* deimage() {return label_.deimage;} + + /** + * Sets the image to use as part of the widget label. + * This image is used when drawing the widget in the inactive + * state. + */ void deimage(Fl_Image* a) {label_.deimage=a;} + + /** + * Sets the image to use as part of the widget label. + * This image is used when drawing the widget in the inactive + * state. + */ void deimage(Fl_Image& a) {label_.deimage=&a;} + + /** + * Gets a string of text to display in a popup tooltip + * window when the user hovers the mouse over the widget. + */ const char *tooltip() const {return tooltip_;} + + /** + * Sets a string of text to display in a popup tooltip + * window when the user hovers the mouse over the widget. The + * string is <I>not</I> copied, so make sure any formatted string + * is stored in a <TT>static</TT>, global, or allocated buffer. + * + * If no tooltip is set, the tooltip of the parent is inherited. + * Setting a tooltip for a group and setting no tooltip for a child + * will show the group's tooltip instead. To avoid this behavior, + * you can set the child's tooltip to an empty string + * (""). + */ void tooltip(const char *t); + + /** + * Gets the current callback function for the widget. + */ Fl_Callback_p callback() const {return callback_;} + + /** + * Sets the current callback function for the widget. + * Each widget has a single callback. + * + * \param[in] c pointer to callback function + * \param[in] p user data pointer + */ void callback(Fl_Callback* c, void* p) {callback_=c; user_data_=p;} + + /** + * Sets the current callback function for the widget. + * Each widget has a single callback. + * + * \param[in] c pointer to callback function + */ void callback(Fl_Callback* c) {callback_=c;} + + /** + * Sets the current callback function for the widget. + * Each widget has a single callback. + * + * \param[in] c pointer to callback function + */ void callback(Fl_Callback0*c) {callback_=(Fl_Callback*)c;} + + /** + * Gets or sets the current callback function for the widget. + * Each widget has a single callback. + * + * \param[in] c pointer to callback function + * \param[in] p user data integer + */ void callback(Fl_Callback1*c, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;} + + /** + * Gets the current user data argument that is passed to the callback function. + */ void* user_data() const {return user_data_;} + + /** + * Sets the current user data (<TT>void *</TT>) argument + * that is passed to the callback function. + */ void user_data(void* v) {user_data_ = v;} + + /** + * Gets the current user data (<TT>long</TT>) argument + * that is passed to the callback function. + */ long argument() const {return (long)user_data_;} + + /** + * Sets the current user data (<TT>long</TT>) argument + * that is passed to the callback function. + * + * <B>Note:</B> + * + * This is implemented by casting the <TT>long</TT> + * value to a <TT>void *</TT> and may not be portable on + * some machines. + * + * \param[in] v arbitrary user data + */ void argument(long v) {user_data_ = (void*)v;} + + /** + * Return a combination of flags which determine when the callback + * is called. + */ Fl_When when() const {return (Fl_When)when_;} + + /** + * Fl_Widget::when() is a set of bitflags used by + * subclasses of Fl_Widget to decide when to do the + * callback. If the value is zero then the callback is never + * done. Other values are described in the individual widgets. + * This field is in the base class so that you can scan a panel and + * do_callback() on all the ones that don't do their own + * callbacks in response to an "OK" button. + */ void when(uchar i) {when_ = i;} + /** + * The visible() method returns true if the + * widget is set to be visible. + */ int visible() const {return !(flags_&INVISIBLE);} + + /** + * The visible_r() method + * returns true if the widget and all of its parents are visible. A + * widget is only visible if visible() is true on it + * <I>and all of its parents</I>. + */ int visible_r() const; + + /** + * Show the widget. + * + * Changing it will send FL_SHOW + * events to the widget. Do not change it if the parent is not + * visible, as this will send false FL_SHOW + * events to the widget. <TT>redraw()</TT> is called if necessary on + * this or the parent. + */ void show(); + + /** + * Changing it will send FL_HIDE + * events to the widget. Do not change it if the parent is not + * visible, as this will send false FL_HIDE + * events to the widget. redraw() is called if necessary on + * this or the parent. + */ void hide(); + + /** + * Makes the widget visible; you must still redraw the parent + * widget to see a change in the window. Normally you want to use + * the show() method instead. + */ void set_visible() {flags_ &= ~INVISIBLE;} + + /** + * Hides the widget; you must still redraw the parent to see a + * change in the window. Normally you want to use the + * hide() method instead. + */ void clear_visible() {flags_ |= INVISIBLE;} + + /** + * Fl_Widget::active() returns whether the widget is + * active. + */ int active() const {return !(flags_&INACTIVE);} + + /** + * Fl_Widget::active_r() returns whether the + * widget and all of its parents are active. + */ int active_r() const; + + /** + * Changing this value will send + * FL_ACTIVATE to the widget if active_r() is false. + * + * Inactive widgets + * will be drawn "grayed out", e.g. with less contrast than the + * active widget. Inactive widgets will not receive any keyboard or + * mouse button events. Other events (including FL_ENTER, + * FL_MOVE, FL_LEAVE, FL_SHORTCUT, and + * others) will still be sent. A widget is only active if + * active() is true on it <I>and all of its parents</I>. + */ void activate(); + + /** + * Changing this value will send + * FL_DEACTIVATE to the widget if active_r() is true. + * + * Currently you cannot deactivate Fl_Window widgets. + */ void deactivate(); + + /** + * Returns non-zero if this widget is used for output only. + */ int output() const {return (flags_&OUTPUT);} + + /** + * output() means the same as !active() except + * it does not change how the widget is drawn. The widget will not + * receive any events. This is useful for making scrollbars or + * buttons that work as displays rather than input devices. + */ void set_output() {flags_ |= OUTPUT;} + + /** + * output() means the same as !active() except + * it does not change how the widget is drawn. The widget will not + * receive any events. This is useful for making scrollbars or + * buttons that work as displays rather than input devices. + */ void clear_output() {flags_ &= ~OUTPUT;} + + /** + * This is the same as <TT>(active() && !output() + * && visible())</TT> but is faster. + */ int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));} + + /** + * Fl_Widget::changed() is a flag that is turned on + * when the user changes the value stored in the widget. This is + * only used by subclasses of Fl_Widget that store values, + * but is in the base class so it is easier to scan all the widgets + * in a panel and do_callback() on the changed ones in + * response to an "OK" button. + * + * Most widgets turn this flag off when they do the callback, and when + * the program sets the stored value. + */ int changed() const {return flags_&CHANGED;} void set_changed() {flags_ |= CHANGED;} void clear_changed() {flags_ &= ~CHANGED;} + + /** + * Tries to make this widget be the Fl::focus() widget, by first + * sending it an FL_FOCUS event, and if it returns non-zero, + * setting Fl::focus() to this widget. You should use this + * method to assign the focus to an widget. Returns true if the widget + * accepted the focus. + */ int take_focus(); + + /** + * Enables keyboard focus navigation with this widget; note, + * however, that this will not necessarily mean that the widget + * will accept focus, but for widgets that can accept focus, this + * method enables it if it has been disabled. + */ void set_visible_focus() { flags_ |= VISIBLE_FOCUS; } + + /** + * Disables keyboard focus navigation with this widget; + * normally, all widgets participate in keyboard focus navigation. + */ void clear_visible_focus() { flags_ &= ~VISIBLE_FOCUS; } + + /** + * Modifies keyboard focus navigation. + * \see set_visible_focus() and clear_visible_focus(). + */ void visible_focus(int v) { if (v) set_visible_focus(); else clear_visible_focus(); } + + /** + * This returns non-zero if this widget will participate in keyboard focus navigation. + */ int visible_focus() { return flags_ & VISIBLE_FOCUS; } + /** + * The default callback, which puts a pointer to the widget on + * the queue returned by Fl::readqueue(). You + * may want to call this from your own callback. + */ static void default_callback(Fl_Widget*, void*); + + /** + * Causes a widget to invoke its callback function. + */ void do_callback() {callback_(this,user_data_); if (callback_ != default_callback) clear_changed();} - void do_callback(Fl_Widget* o,void* arg=0) {callback_(o,arg); if (callback_ != default_callback) clear_changed();} - void do_callback(Fl_Widget* o,long arg) {callback_(o,(void*)arg); if (callback_ != default_callback) clear_changed();} + + /** + * Causes a widget to invoke its callback function with arbitrary arguments. + */ + void do_callback(Fl_Widget* o,void* arg=0) { + callback_(o,arg); if (callback_ != default_callback) clear_changed();} + + /** + * Causes a widget to invoke its callback function with arbitrary arguments. + */ + void do_callback(Fl_Widget* o,long arg) { + callback_(o,(void*)arg); if (callback_ != default_callback) clear_changed();} + int test_shortcut(); static int test_shortcut(const char*); + + /** + * Returns 1 if <TT>b</TT> is a child of this widget, or is + * equal to this widget. Returns 0 if <TT>b</TT> is <TT>NULL</TT>. + */ int contains(const Fl_Widget*) const ; + + /** + * Returns 1 if this widget is a child of <TT>a</TT>, or is + * equal to <TT>a</TT>. Returns 0 if <TT>a</TT> is <TT>NULL</TT>. + * + * \param[in] o a widget which may be the parent + */ int inside(const Fl_Widget* o) const {return o ? o->contains(this) : 0;} + /** + * Marks the widget as needing its draw() routine called. + */ void redraw(); + + /** + * Marks the widget or the parent as needing a redraw for the + * label area of a widget. + */ void redraw_label(); + + /** + * This returns non-zero if draw() needs to be + * called. The damage value is actually a bit field that the widget + * subclass can use to figure out what parts to draw. + */ uchar damage() const {return damage_;} + void clear_damage(uchar c = 0) {damage_ = c;} + + /** + * Set the damage bits for the widget. + * + * \param[in] c damage flags or'd + */ void damage(uchar c); - void damage(uchar c,int,int,int,int); + + /** + * Set the damage bits for the widget and damages the widget within the + * specified bounding box. + * + * \param[in] c damage flags + * \param[in] x, y, w, h damaged area + */ + void damage(uchar c, int x, int y, int w, int h); + void draw_label(int, int, int, int, Fl_Align) const; void measure_label(int& xx, int& yy) {label_.measure(xx,yy);} + /** + * Returns a pointer to the primary Fl_Window widget. + * Returns <TT>NULL</TT> if no window is associated with this + * widget. Note: for an Fl_Window widget, this returns + * its <I>parent</I> window (if any), not <I>this</I> window. + */ Fl_Window* window() const ; // back compatability only: Deleted: branches/branch-1.1-doxygen/documentation/Fl_Clock_Output.html Deleted: branches/branch-1.1-doxygen/documentation/Fl_Dial.html Deleted: branches/branch-1.1-doxygen/documentation/Fl_Toggle_Button.html Deleted: branches/branch-1.1-doxygen/documentation/Fl_Valuator.html _______________________________________________ fltk-commit mailing list [email protected] http://lists.easysw.com/mailman/listinfo/fltk-commit
