From 2bded55947262987210542842a89a1093a9c4e7f Mon Sep 17 00:00:00 2001 From: Matthias Melcher Date: Mon, 11 Aug 2008 08:35:34 +0000 Subject: [PATCH] Moving more documentation into doxygen format git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6155 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Enumerations.H | 20 +++ FL/Fl_Widget.H | 423 +++++++++++++++++++++++++++++++++++++++++++--- src/Fl_Widget.cxx | 2 +- 3 files changed, 421 insertions(+), 24 deletions(-) diff --git a/FL/Enumerations.H b/FL/Enumerations.H index 2f7331fac..a50fb0131 100644 --- a/FL/Enumerations.H +++ b/FL/Enumerations.H @@ -472,16 +472,36 @@ extern Fl_Labeltype FL_EXPORT fl_define_FL_ENGRAVED_LABEL(); extern Fl_Labeltype FL_EXPORT fl_define_FL_EMBOSSED_LABEL(); #define FL_EMBOSSED_LABEL fl_define_FL_EMBOSSED_LABEL() +/** Flags to control the label alignment. + * This controls how the label is displayed next to or inside the widget. + * The default value is FL_ALIGN_CENTER for most widgets, which centers the label + * inside the widget. + * + * Flags can be or'd to achieve a combination of alignments. + */ enum Fl_Align { // align() values + /** Align the label horizontally in the middle. */ FL_ALIGN_CENTER = 0, + /** Align the label at the top of the widget. Inside labels appear below the top, + * outside labels are drawn on top of the widget. */ FL_ALIGN_TOP = 1, + /** Align the label at the bottom of the widget. */ FL_ALIGN_BOTTOM = 2, + /** Align the label at the left of the widget. Inside labels appear left-justified + * starting at the left side of the widget, outside labels are right-justified and + * drawn to the left of the widget. */ FL_ALIGN_LEFT = 4, + /** Align the label to the right of the widget. */ FL_ALIGN_RIGHT = 8, + /** Draw the label inside of the widget. */ FL_ALIGN_INSIDE = 16, + /** If the label contains an image, draw the text on top of the image. */ FL_ALIGN_TEXT_OVER_IMAGE = 32, + /** If the label contains an image, draw the text below the image. */ FL_ALIGN_IMAGE_OVER_TEXT = 0, + /** All parts of the label that are lager than the widget will not be drawn . */ FL_ALIGN_CLIP = 64, + /** Wrap text that does not fit the width of the widget. */ FL_ALIGN_WRAP = 128, FL_ALIGN_TOP_LEFT = FL_ALIGN_TOP | FL_ALIGN_LEFT, FL_ALIGN_TOP_RIGHT = FL_ALIGN_TOP | FL_ALIGN_RIGHT, diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H index 5df8d0e16..bedfb6936 100644 --- a/FL/Fl_Widget.H +++ b/FL/Fl_Widget.H @@ -25,6 +25,10 @@ // http://www.fltk.org/str.php // +/** \file + * This file describes the Fl_Widget and Fl_Label classes. + */ + #ifndef Fl_Widget_H #define Fl_Widget_H @@ -40,6 +44,13 @@ typedef Fl_Callback* Fl_Callback_p; // needed for BORLAND typedef void (Fl_Callback0)(Fl_Widget*); typedef void (Fl_Callback1)(Fl_Widget*, long); +/** This struct stores all information for a text or mixed graphics label. + * + * \todo For FLTK1.3, the Fl_Label type eill become a widget by itself. That way + * we will be avoiding a lot of code duplication by handling labels in + * a similar fashion to widgets containing text. We also provide an easy + * interface for very complex labels, containing html or vector graphics. + */ struct FL_EXPORT Fl_Label { const char* value; Fl_Image* image; @@ -52,6 +63,19 @@ struct FL_EXPORT Fl_Label { 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 +101,16 @@ class FL_EXPORT Fl_Widget { 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 the position of the widget relative to the enclosing window + * \param[in] w, h size of the widget in pixels + * \param[in] label optional text for the widget label + */ + Fl_Widget(int x, int y, int w, int h, Fl_CString label=0L); void x(int v) {x_ = v;} void y(int v) {y_ = v;} @@ -100,10 +133,31 @@ protected: 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 + * \em immediately 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; - virtual int handle(int); + + /** 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. + * + * \param[in] event the kind of event received + * \retval 0 if the event was not used or understood + * \retval 1 if the event was used and can be deleted + * \see Fl_Event + */ + virtual int handle(int event); + Fl_Group* parent() const {return parent_;} void parent(Fl_Group* p) {parent_ = p;} // for hacks only, Fl_Group::add() @@ -119,44 +173,233 @@ public: void position(int X,int Y) {resize(X,Y,w_,h_);} void size(int W,int H) {resize(x_,y_,W,H);} + /** Gets the label alignment. + * \return label alignment + * \see label(), align(uchar), Fl_Align + * \todo This function should not take ucahr as an argument. Apart from the fact that ucahr is too short + * with only 8 bits, it does not provide type safety (in which case we don't need to declare Fl_Type + * an enum to begin with). + */ Fl_Align align() const {return (Fl_Align)align_;} - void align(uchar a) {align_ = a;} + + /** Sets the label alignment. + * This 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. + * \param[in] alignment new label alignment + * \see align(), Fl_Align + */ + void align(uchar alignment) {align_ = a;} + + /** Gets the box type for the widget. + * \return the current box type + * \see box(Fl_Boxtype), Fl_Boxtype + */ Fl_Boxtype box() const {return (Fl_Boxtype)box_;} - void box(Fl_Boxtype a) {box_ = a;} + + /** Sets the box type for the widget. + * This identifies a routine that draws the background of the widget. + * See Fl_Boxtype for the available types. The default depends on the widget, + * but is usually FL_NO_BOX or FL_UP_BOX. + * \param[in] new_box the new box type + * \see box(), Fl_Boxtype + */ + void box(Fl_Boxtype new_box) {box_ = new_box;} + + /** Gets the background color of the widget. + * \return current background color + * \see color(unsigned), color(unsigned, unsigned) + */ Fl_Color color() const {return (Fl_Color)color_;} - void color(unsigned a) {color_ = a;} + + /** 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. Use Fl::set_color() to + * redefine colors in the color map. + * \param[in] bg background color + * \see color(), color(unsigned, unsigned), selection_color(unsigned) + */ + void color(unsigned bg) {color_ = a;} + Fl_Color selection_color() const {return (Fl_Color)color2_;} void selection_color(unsigned a) {color2_ = a;} - void color(unsigned a, unsigned b) {color_=a; color2_=b;} + + /** Sets the background and selection color of the widget. + * The two color form sets both the background and selection colors. + * \param[in] bg background color + * \param[in] sel selection color + * \see color(unsigned), selection_color(unsigned) + */ + void color(unsigned bg, unsigned sel) {color_=a; color2_=b;} + + /** Get the current label text. + * \return a pointer to the current label text + * \see label(Fl_CString), copy_label(Fl_CString) + */ const char* label() const {return label_.value;} - void label(const char* a); - void copy_label(const char* a); + + /** Get or 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 \em not copied), so if + * you need to set the label to a formatted value, make sure the buffer is + * \code static, global, or allocated. The copy_label() method can be used + * to make a copy of the label string automatically. + * \param[in] text pointer to new label text + * \see copy_label() + */ + void label(const char* text); + + /** Sets the current label. + * Unlike label(), this method allocates a copy of the label + * string instead of using the original string pointer. + * \param[in] new_label the new label text + * \see label() + */ + void copy_label(Fl_CString new_label); + void label(Fl_Labeltype a,const char* b) {label_.type = a; label_.value = b;} + + /** Gets the label type. + * \return the current label type. + * \see Fl_Labeltype + */ Fl_Labeltype labeltype() const {return (Fl_Labeltype)label_.type;} + + /** Sets the label type. + * The label type 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 a new label type + * \see Fl_Labeltype + */ void labeltype(Fl_Labeltype a) {label_.type = a;} + + /** Gets the label color. + * The default color is FL_FOREGROUND_COLOR. + * \return the current label color + */ Fl_Color labelcolor() const {return (Fl_Color)label_.color;} - void labelcolor(unsigned a) {label_.color=a;} + + /** Sets the label color. + * The default color is FL_FOREGROUND_COLOR. + * \param[in] c the new label color + */ + void labelcolor(unsigned c) {label_.color=c;} + + /** Gets the font to use. + * Fonts are identified by indexes into a table. The default value uses a + * Helvetica typeface (Arial for Microsoft® Windows®). The function + * Fl::set_font() can define new typefaces. + * \return current font used by the label + * \see Fl_Font + */ Fl_Font labelfont() const {return label_.font;} - void labelfont(Fl_Font a) {label_.font=a;} + + /** Sets the font to use. + * Fonts are identified by indexes into a table. The default value uses a + * Helvetica typeface (Arial for Microsoft® Windows®). The function + * Fl::set_font() can define new typefaces. + * \param[in] f the new font for the label + * \see Fl_Font + */ + void labelfont(Fl_Font f) {label_.font=f;} + + /** Gets the font size in pixels. + * The default size is 14 pixels. + * \return the current font size + */ Fl_Font_Size labelsize() const {return label_.size;} - void labelsize(Fl_Font_Size a) {label_.size=a;} + + /** Gets or sets the font size in pixels. + * The default size is 14 pixels. + * \param[in] pix the new font size + */ + void labelsize(Fl_Font_Size pix) {label_.size=pix;} + + /** Gets or sets the image to use as part of the widget label. + * This image is used when drawing the widget in the active state. + * \return the current image + */ Fl_Image* image() {return label_.image;} - void image(Fl_Image* a) {label_.image=a;} - void image(Fl_Image& a) {label_.image=&a;} + + /** Gets or 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] img the new image for the label + */ + void image(Fl_Image* img) {label_.image=img;} + + /** Gets or 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] img the new image for the label + */ + void image(Fl_Image& img) {label_.image=&img;} + + /** Gets the image to use as part of the widget label. + * This image is used when drawing the widget in the inactive state. + * \return the current deactivated image for this widget + */ Fl_Image* deimage() {return label_.deimage;} - void deimage(Fl_Image* a) {label_.deimage=a;} - 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. + * \param[in] img the new image for the deactivated widget + */ + void deimage(Fl_Image* img) {label_.deimage=img;} + + /** Sets the image to use as part of the widget label. + * This image is used when drawing the widget in the inactive state. + * \param[in] img the new image for the deactivated widget + */ + void deimage(Fl_Image& img) {label_.deimage=&img;} + const char *tooltip() const {return tooltip_;} void tooltip(const char *t); + + /** Gets the current callback function for the widget. + * Each widget has a single callback. + * \return current callback + */ Fl_Callback_p callback() const {return callback_;} - void callback(Fl_Callback* c, void* p) {callback_=c; user_data_=p;} - void callback(Fl_Callback* c) {callback_=c;} - void callback(Fl_Callback0*c) {callback_=(Fl_Callback*)c;} - void callback(Fl_Callback1*c, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;} + + /** Sets the current callback function for the widget. + * Each widget has a single callback. + * \param[in] cb new callback + * \param[in] p user data + */ + void callback(Fl_Callback* cb, void* p) {callback_=c; user_data_=p;} + + /** Sets the current callback function for the widget. + * Each widget has a single callback. + * \param[in] cb new callback + */ + void callback(Fl_Callback* cb) {callback_=c;} + + /** Sets the current callback function for the widget. + * Each widget has a single callback. + * \param[in] cb new callback + */ + void callback(Fl_Callback0*cb) {callback_=(Fl_Callback*)c;} + + /** Sets the current callback function for the widget. + * Each widget has a single callback. + * \param[in] cb new callback + * \param[in] p user data + */ + void callback(Fl_Callback1*cb, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;} + void* user_data() const {return user_data_;} void user_data(void* v) {user_data_ = v;} + + /** Gets the current user data (long) argument that is passed to the callback function. + */ long argument() const {return (long)user_data_;} + + /** Sets the current user data (long) argument that is passed to the callback function. + * \todo The user data value must be implemented using a \em union to avoid 64 bit machine incompatibilities. + */ void argument(long v) {user_data_ = (void*)v;} + Fl_When when() const {return (Fl_When)when_;} void when(uchar i) {when_ = i;} @@ -165,40 +408,174 @@ public: void show(); void hide(); 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;} + + /** Returns whether the widget is active. + * \retval 0 if the widget is inactive + * \see active_r(), activate(), deactivate() + */ int active() const {return !(flags_&INACTIVE);} + + /** active_r() returns whether the widget and all of its + * parents are active. + * \retval 0 if this or any of the parent widgets are inactive + * \see active(), activate(), deactivate() + */ int active_r() const; + + /** Activate a widget. + * Changing this value will send FL_ACTIVATE to the widget if + * active_r() is true. + * \see active(), active_r(), deactivate() + */ void activate(); + + /** Deactivate a widget. + * 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 and all of its parents. + * + * Changing this value will send FL_DEACTIVATE to the widget if + * active_r() is true. + * + * Currently you cannot deactivate Fl_Window widgets. + * + * \see activate(), active(), active_r() + */ void deactivate(); + int output() const {return (flags_&OUTPUT);} void set_output() {flags_ |= OUTPUT;} void clear_output() {flags_ &= ~OUTPUT;} int takesevents() const {return !(flags_&(INACTIVE|INVISIBLE|OUTPUT));} + + /** Check if the widget value changed since the last callback. + * "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. + * + * \retval 0 if the value did not change + * \see set_changed(), clear_changed()` + */ int changed() const {return flags_&CHANGED;} + + /** Mark the value of the widget as changed. + * \see changed(), clear_changed() + */ void set_changed() {flags_ |= CHANGED;} + + /** Mark the value of the widget as unchanged. + * \see changed(), set_changed() + */ void clear_changed() {flags_ &= ~CHANGED;} + int take_focus(); 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; } void visible_focus(int v) { if (v) set_visible_focus(); else clear_visible_focus(); } int visible_focus() { return flags_ & VISIBLE_FOCUS; } - static void default_callback(Fl_Widget*, void*); + /** Sets the default callback for all widgets.. + * Sets 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. + * \param cb the new callback + * \param d user data associated with that callback + * \see callback(), do_callback(), Fl::readqueu() + */ + static void default_callback(Fl_Widget *cb, void *d); + + /** Call the widget callback. + * Causes a widget to invoke its callback function, optionally + * with arbitrary arguments. + * \see callback() + */ void do_callback() {callback_(this,user_data_); if (callback_ != default_callback) clear_changed();} + + /** Call the widget callback. + * Causes a widget to invoke its callback function, optionally + * with arbitrary arguments. + * \param o call the callback with \em o as the widget argument + * \param arg call the callback with \em arg as the user data argument + * \see callback() + */ void do_callback(Fl_Widget* o,void* arg=0) {callback_(o,arg); if (callback_ != default_callback) clear_changed();} + + /** Call the widget callback. + * Causes a widget to invoke its callback function, optionally + * with arbitrary arguments. + * \param o call the callback with \em o as the widget argument + * \param arg call the callback with \em arg as the user data argument + * \see callback() + */ void do_callback(Fl_Widget* o,long arg) {callback_(o,(void*)arg); if (callback_ != default_callback) clear_changed();} + int test_shortcut(); static char label_shortcut(const char *t); static int test_shortcut(const char*); - int contains(const Fl_Widget*) const ; - int inside(const Fl_Widget* o) const {return o ? o->contains(this) : 0;} + + /** Checks if w is a child of this widget. + * \param[in] w potential child widget + * \return Returns 1 if \em w is a child of this widget, or is + * equal to this widget. Returns 0 if \en w is NULL. + */ + int contains(const Fl_Widget *w) const ; + + /** Check if this widget is a child of w. + * Returns 1 if this widget is a child of \em w, or is + * equal to \em w. Returns 0 if \em w is NULL. + * \param[in] w the possible parent widget. + * \see contains() + */ + int inside(const Fl_Widget* w) const {return w ? w->contains(this) : 0;} void redraw(); void redraw_label(); + + /** 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. + * \return a bitmap of flags describing the kind of damage to the widget + * \see damage(uchar), clear_damage(uchar) + */ uchar damage() const {return damage_;} + + /** Clear damage flags. + * Damage flags are cleared when parts of the widget drawing is repaired. + * \param[in] c bitmask of flags to clear + * \see damage(uchar), damage() + */ void clear_damage(uchar c = 0) {damage_ = c;} + + /** Set the damage bits for the widget. + * Setting damage bits will schedule the widget for the next redraw. + * \param[in] c bitmask of flags to set + * \see damage(), clear_damage(uchar) + */ void damage(uchar c); - void damage(uchar c,int,int,int,int); + + /** Set the damage bits for an area inside the widget. + * Setting damage bits will schedule the widget for the next redraw. + * \param[in] c bitmask of flags to set + * \param x, y, w, h size of damaged area + * \see damage(), clear_damage(uchar) + */ + 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);} diff --git a/src/Fl_Widget.cxx b/src/Fl_Widget.cxx index 9b4c6415c..019a5dd73 100644 --- a/src/Fl_Widget.cxx +++ b/src/Fl_Widget.cxx @@ -78,7 +78,7 @@ int Fl_Widget::handle(int) { Fl_Font_Size FL_NORMAL_SIZE = 14; -Fl_Widget::Fl_Widget(int X, int Y, int W, int H, const char* L) { +Fl_Widget::Fl_Widget(int X, int Y, int W, int H, Fl_CString L) { x_ = X; y_ = Y; w_ = W; h_ = H;