diff options
| -rw-r--r-- | FL/Fl_Menu_.H | 75 | ||||
| -rw-r--r-- | FL/Fl_Menu_Bar.H | 39 | ||||
| -rw-r--r-- | FL/Fl_Menu_Button.H | 20 | ||||
| -rw-r--r-- | FL/Fl_Menu_Item.H | 222 | ||||
| -rw-r--r-- | FL/Fl_Menu_Window.H | 12 | ||||
| -rw-r--r-- | FL/Fl_Progress.H | 10 | ||||
| -rw-r--r-- | FL/Fl_Timer.H | 19 | ||||
| -rw-r--r-- | documentation/todo_filelist_doc.txt | 19 | ||||
| -rw-r--r-- | src/Fl_Menu.cxx | 64 | ||||
| -rw-r--r-- | src/Fl_Menu_.cxx | 78 | ||||
| -rw-r--r-- | src/Fl_Menu_Button.cxx | 13 | ||||
| -rw-r--r-- | src/Fl_Menu_Window.cxx | 2 | ||||
| -rw-r--r-- | src/Fl_Menu_add.cxx | 91 | ||||
| -rw-r--r-- | src/Fl_Menu_global.cxx | 10 | ||||
| -rw-r--r-- | src/Fl_Progress.cxx | 14 | ||||
| -rw-r--r-- | src/forms_timer.cxx | 20 |
16 files changed, 636 insertions, 72 deletions
diff --git a/FL/Fl_Menu_.H b/FL/Fl_Menu_.H index 04cd4519b..583f44440 100644 --- a/FL/Fl_Menu_.H +++ b/FL/Fl_Menu_.H @@ -33,6 +33,15 @@ #endif #include "Fl_Menu_Item.H" +/** + Base class of all widgets that have a menu in FLTK. + Currently FLTK provides you with + Fl_Menu_Button, Fl_Menu_Bar, and Fl_Choice. + + <P>The class contains a pointer to an array of structures of type Fl_Menu_Item. The + array may either be supplied directly by the user program, or it may + be "private": a dynamically allocated array managed by the Fl_Menu_. +*/ class FL_EXPORT Fl_Menu_ : public Fl_Widget { Fl_Menu_Item *menu_; @@ -57,41 +66,99 @@ public: const Fl_Menu_Item* test_shortcut() {return picked(menu()->test_shortcut());} void global(); + /** + Returns a pointer to the array of Fl_Menu_Items. This will either be + the value passed to menu(value) or the private copy. + */ const Fl_Menu_Item *menu() const {return menu_;} void menu(const Fl_Menu_Item *m); void copy(const Fl_Menu_Item *m, void* user_data = 0); int add(const char*, int shortcut, Fl_Callback*, void* = 0, int = 0); - int add(const char* a, const char* b, Fl_Callback* c, - void* d = 0, int e = 0) {return add(a,fl_old_shortcut(b),c,d,e);} + /** See int Fl_Menu_::add(const char* label, int shortcut, Fl_Callback*, void *user_data=0, int flags=0)*/ + int add(const char* a, const char* b, Fl_Callback* c, void* d = 0, int e = 0) { + return add(a,fl_old_shortcut(b),c,d,e);} + int add(const char *); int size() const ; void size(int W, int H) { Fl_Widget::size(W, H); } void clear(); - int add(const char *); void replace(int,const char *); void remove(int); + /** Changes the shortcut of item i to n. */ void shortcut(int i, int s) {menu_[i].shortcut(s);} + /** Sets the flags of item i. For a list of the flags, see Fl_Menu_Item. */ void mode(int i,int fl) {menu_[i].flags = fl;} + /** Gets the flags of item i. For a list of the flags, see Fl_Menu_Item. */ int mode(int i) const {return menu_[i].flags;} + /** Returns a pointer to the last menu item that was picked. */ const Fl_Menu_Item *mvalue() const {return value_;} + /** Returns the index into menu() of the last item chosen by the user. It is zero initially. */ int value() const {return value_ ? (int)(value_-menu_) : -1;} int value(const Fl_Menu_Item*); + /** + The value is the index into menu() of the last item chosen by + the user. It is zero initially. You can set it as an integer, or set + it with a pointer to a menu item. The set routines return non-zero if + the new value is different than the old one. + */ int value(int i) {return value(menu_+i);} + /** Returns the title of the last item chosen, or of item i. */ const char *text() const {return value_ ? value_->text : 0;} + /** Returns the title of the last item chosen, or of item i. */ const char *text(int i) const {return menu_[i].text;} + /** Gets the current font of menu item labels. */ Fl_Font textfont() const {return textfont_;} + /** Sets the current font of menu item labels. */ void textfont(Fl_Font c) {textfont_=c;} + /** Gets the font size of menu item labels. */ Fl_Fontsize textsize() const {return textsize_;} + /** Sets the font size of menu item labels. */ void textsize(Fl_Fontsize c) {textsize_=c;} + /** Get the current color of menu item labels. */ Fl_Color textcolor() const {return (Fl_Color)textcolor_;} + /** Sets the current color of menu item labels. */ void textcolor(unsigned c) {textcolor_=c;} + /** + This box type is used to surround the currently-selected items in the + menus. If this is FL_NO_BOX then it acts like + FL_THIN_UP_BOX and selection_color() acts like + FL_WHITE, for back compatability. + + + <h4>const Fl_Menu_Item *Fl_Menu_::find_item(const char *name);</h4> + + <p>Returns a pointer to the menu item with the given (full) + pathname. If no matching menu item can be found, a NULL pointer + is returned. This function does not search submenus that are linked + via FL_SUBMENU_POINTER.</p> + + + <h4>int Fl_Menu_::item_pathname(char *name, int namelen ) const;<br> + int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *finditem) const;</h4> + + <p>Returns the 'menu pathname' (eg. "File/Quit") for the recently picked item in user supplied string 'name'. Useful in the callback function for a menu item, to determine the last picked item's 'menu pathname' string. + + <p>If finditem is specified, name will contain the 'menu pathname' for that item. + + <p>Returns: + + <ul> + <li>0 - OK: 'name' has the pathname, guaranteed not longer than namelen + <li>-1 - Failed: 'finditem' was not found in the menu + <li>-2 - Failed: 'name' is not large enough to handle the menu names + </ul> + + <p>In the case of errors (-1 or -2), 'name' will be an empty string. + */ Fl_Boxtype down_box() const {return (Fl_Boxtype)down_box_;} + /** See Fl_Boxtype Fl_Menu_::down_box() const */ void down_box(Fl_Boxtype b) {down_box_ = b;} - // back compatability: + /** For back compatability, same as selection_color() */ Fl_Color down_color() const {return selection_color();} + /** For back compatability, same as selection_color() */ void down_color(unsigned c) {selection_color(c);} }; diff --git a/FL/Fl_Menu_Bar.H b/FL/Fl_Menu_Bar.H index 42c7d2949..074821838 100644 --- a/FL/Fl_Menu_Bar.H +++ b/FL/Fl_Menu_Bar.H @@ -30,11 +30,50 @@ #include "Fl_Menu_.H" +/** + This widget provides a standard menubar interface. Usually you will + put this widget along the top edge of your window. The height of the + widget should be 30 for the menu titles to draw correctly with the + default font. + <P>The items on the bar and the menus they bring up are defined by a + single Fl_Menu_Item + array. Because a Fl_Menu_Item array defines a hierarchy, the + top level menu defines the items in the menubar, while the submenus + define the pull-down menus. Sub-sub menus and lower pop up to the right + of the submenus. </P> + <P ALIGN=CENTER>\image html src=</P> + <P>If there is an item in the top menu that is not a title of a + submenu, then it acts like a "button" in the menubar. Clicking on it + will pick it. </P> + <P>When the user picks an item off the menu, the item's callback is + done with the menubar as the Fl_Widget* argument. If the item + does not have a callback the menubar's callback is done instead. </P> + <P>Submenus will also pop up in response to shortcuts indicated by + putting a '&' character in the name field of the menu item. If you put a + '&' character in a top-level "button" then the shortcut picks it. The + '&' character in submenus is ignored until the menu is popped up. </P> + <P>Typing the shortcut() of any of the menu items will cause + callbacks exactly the same as when you pick the item with the mouse. +*/ class FL_EXPORT Fl_Menu_Bar : public Fl_Menu_ { protected: void draw(); public: int handle(int); + /** + Creates a new Fl_Menu_Bar widget using the given position, + size, and label string. The default boxtype is FL_UP_BOX. + <P>The constructor sets menu() to NULL. See + Fl_Menu_ for the methods to set or change the menu. </P> + <P>labelsize(), labelfont(), and labelcolor() + are used to control how the menubar items are drawn. They are + initialized from the Fl_Menu static variables, but you can + change them if desired. </P> + <P>label() is ignored unless you change align() to + put it outside the menubar. + <P>The destructor removes the Fl_Menu_Bar widget and all of its + menu items. + */ Fl_Menu_Bar(int X, int Y, int W, int H,const char *l=0) : Fl_Menu_(X,Y,W,H,l) {} }; diff --git a/FL/Fl_Menu_Button.H b/FL/Fl_Menu_Button.H index b0d669a05..7acebcef0 100644 --- a/FL/Fl_Menu_Button.H +++ b/FL/Fl_Menu_Button.H @@ -30,6 +30,26 @@ #include "Fl_Menu_.H" +/** + This is a button that when pushed pops up a menu (or hierarchy of + menus) defined by an array of + Fl_Menu_Item objects. + <P ALIGN=CENTER>\image html src=</P> + <P>Normally any mouse button will pop up a menu and it is lined up + below the button as shown in the picture. However an Fl_Menu_Button + may also control a pop-up menu. This is done by setting the type() + , see below. </P> + <P>The menu will also pop up in response to shortcuts indicated by + putting a '&' character in the label(). </P> + <P>Typing the shortcut() of any of the menu items will cause + callbacks exactly the same as when you pick the item with the mouse. + The '&' character in menu item names are only looked at when the menu is + popped up, however. </P> + <P>When the user picks an item off the menu, the item's callback is + done with the menu_button as the Fl_Widget* argument. If the + item does not have a callback the menu_button's callback is done + instead. +*/ class FL_EXPORT Fl_Menu_Button : public Fl_Menu_ { protected: void draw(); diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H index a302a5446..6e4908951 100644 --- a/FL/Fl_Menu_Item.H +++ b/FL/Fl_Menu_Item.H @@ -51,6 +51,70 @@ extern FL_EXPORT int fl_old_shortcut(const char*); class Fl_Menu_; +/** + The Fl_Menu_Item structure defines a single menu item that + is used by the Fl_Menu_ class. + <UL> + <PRE> + struct Fl_Menu_Item { + const char* text; // label() + ulong shortcut_; + Fl_Callback* callback_; + void* user_data_; + int flags; + uchar labeltype_; + uchar labelfont_; + uchar labelsize_; + uchar labelcolor_; + }; + + enum { // values for flags: + FL_MENU_INACTIVE = 1, + FL_MENU_TOGGLE = 2, + FL_MENU_VALUE = 4, + FL_MENU_RADIO = 8, + FL_MENU_INVISIBLE = 0x10, + FL_SUBMENU_POINTER = 0x20, + FL_SUBMENU = 0x40, + FL_MENU_DIVIDER = 0x80, + FL_MENU_HORIZONTAL = 0x100 + }; + </PRE> + </UL> + Typically menu items are statically defined; for example: + <UL><PRE> + Fl_Menu_Item popup[] = { + {"&alpha", FL_ALT+'a', the_cb, (void*)1}, + {"&beta", FL_ALT+'b', the_cb, (void*)2}, + {"gamma", FL_ALT+'c', the_cb, (void*)3, FL_MENU_DIVIDER}, + {"&strange", 0, strange_cb}, + {"&charm", 0, charm_cb}, + {"&truth", 0, truth_cb}, + {"b&eauty", 0, beauty_cb}, + {"sub&menu", 0, 0, 0, FL_SUBMENU}, + {"one"}, + {"two"}, + {"three"}, + {0}, + {"inactive", FL_ALT+'i', 0, 0, FL_MENU_INACTIVE|FL_MENU_DIVIDER}, + {"invisible",FL_ALT+'i', 0, 0, FL_MENU_INVISIBLE}, + {"check", FL_ALT+'i', 0, 0, FL_MENU_TOGGLE|FL_MENU_VALUE}, + {"box", FL_ALT+'i', 0, 0, FL_MENU_TOGGLE}, + {0}}; + </PRE></UL> + produces: + <P ALIGN=CENTER>\image html menu.gif </P> + + A submenu title is identified by the bit FL_SUBMENU in the + flags field, and ends with a label() that is NULL. + You can nest menus to any depth. A pointer to the first item in the + submenu can be treated as an Fl_Menu array itself. It is also + possible to make seperate submenu arrays with FL_SUBMENU_POINTER + flags. + <P>You should use the method functions to access structure members and + not access them directly to avoid compatibility problems with future + releases of FLTK. +*/ struct FL_EXPORT Fl_Menu_Item { const char *text; // label() int shortcut_; @@ -64,51 +128,185 @@ struct FL_EXPORT Fl_Menu_Item { // advance N items, skipping submenus: const Fl_Menu_Item *next(int=1) const; + /** + Advance a pointer by n items through a menu array, skipping + the contents of submenus and invisible items. There are two calls so + that you can advance through const and non-const data. + */ Fl_Menu_Item *next(int i=1) { return (Fl_Menu_Item*)(((const Fl_Menu_Item*)this)->next(i));} + /** Returns the first menu item, same as next(0). */ const Fl_Menu_Item *first() const { return next(0); } + /** Returns the first menu item, same as next(0). */ Fl_Menu_Item *first() { return next(0); } // methods on menu items: + /** + This is the title of the item. A NULL here indicates the end + of the menu (or of a submenu). A '&' in the item will print an + underscore under the next letter, and if the menu is popped up that + letter will be a "shortcut" to pick that item. To get a + real '&' put two + in a row. + */ const char* label() const {return text;} + /** See const char* Fl_Menu_Item::label() const */ void label(const char* a) {text=a;} + /** See const char* Fl_Menu_Item::label() const */ void label(Fl_Labeltype a,const char* b) {labeltype_ = a; text = b;} + /** + A labeltype identifies a routine that draws the label of the + widget. This can be used for special effects such as emboss, or to use + the label() pointer as another form of data such as a bitmap. + The value FL_NORMAL_LABEL prints the label as text. + */ Fl_Labeltype labeltype() const {return (Fl_Labeltype)labeltype_;} + /** + A labeltype identifies a routine that draws the label of the + widget. This can be used for special effects such as emboss, or to use + the label() pointer as another form of data such as a bitmap. + The value FL_NORMAL_LABEL prints the label as text. + */ void labeltype(Fl_Labeltype a) {labeltype_ = a;} + /** + This color is passed to the labeltype routine, and is typically the + color of the label text. This defaults to FL_BLACK. If this + color is not black fltk will <I>not</I> use overlay bitplanes to draw + the menu - this is so that images put in the menu draw correctly. + */ Fl_Color labelcolor() const {return (Fl_Color)labelcolor_;} + /** See Fl_Color Fl_Menu_Item::labelcolor() const */ void labelcolor(unsigned a) {labelcolor_ = a;} + /** + Fonts are identified by small 8-bit indexes into a table. See the + enumeration list for predefined fonts. The default value is a + Helvetica font. The function + Fl::set_font() can define new fonts. + */ Fl_Font labelfont() const {return labelfont_;} + /** + Fonts are identified by small 8-bit indexes into a table. See the + enumeration list for predefined fonts. The default value is a + Helvetica font. The function + Fl::set_font() can define new fonts. + */ void labelfont(Fl_Font a) {labelfont_ = a;} + /** Gets or sets the label font pixel size/height. */ + /** Gets the label font pixel size/height.*/ Fl_Fontsize labelsize() const {return labelsize_;} + /** Sets the label font pixel size/height.*/ void labelsize(Fl_Fontsize a) {labelsize_ = a;} + + /** + Each item has space for a callback function and an argument for that + function. Due to back compatability, the Fl_Menu_Item itself + is not passed to the callback, instead you have to get it by calling + ((Fl_Menu_*)w)->mvalue() where w is the widget argument. + */ Fl_Callback_p callback() const {return callback_;} + /** See Fl_Callback_p Fl_MenuItem::callback() const */ void callback(Fl_Callback* c, void* p) {callback_=c; user_data_=p;} + /** See Fl_Callback_p Fl_MenuItem::callback() const */ void callback(Fl_Callback* c) {callback_=c;} + /** See Fl_Callback_p Fl_MenuItem::callback() const */ void callback(Fl_Callback0*c) {callback_=(Fl_Callback*)c;} + /** See Fl_Callback_p Fl_MenuItem::callback() const */ void callback(Fl_Callback1*c, long p=0) {callback_=(Fl_Callback*)c; user_data_=(void*)p;} + /** + Get or set the user_data argument that is sent to the + callback function. + */ void* user_data() const {return user_data_;} + /** + Get or set the user_data argument that is sent to the + callback function. + */ void user_data(void* v) {user_data_ = v;} + /** + For convenience you can also define the callback as taking a long + argument. This is implemented by casting this to a Fl_Callback + and casting the long to a void* and may not be + portable to some machines. + */ long argument() const {return (long)user_data_;} + /** + For convenience you can also define the callback as taking a long + argument. This is implemented by casting this to a Fl_Callback + and casting the long to a void* and may not be + portable to some machines. + */ void argument(long v) {user_data_ = (void*)v;} + /** Gets what key combination shortcut will trigger the menu item. */ int shortcut() const {return shortcut_;} + /** + Sets exactly what key combination will trigger the menu item. The + value is a logical 'or' of a key and a set of shift flags, for instance + FL_ALT+'a' or FL_ALT+FL_F+10 or just 'a'. A value of + zero disables the shortcut. + <P>The key can be any value returned by + Fl::event_key(), but will usually be an ASCII letter. Use + a lower-case letter unless you require the shift key to be held down. </P> + <P>The shift flags can be any set of values accepted by + Fl::event_state(). If the bit is on that shift key must + be pushed. Meta, Alt, Ctrl, and Shift must be off if they are not in + the shift flags (zero for the other bits indicates a "don't care" + setting). + */ void shortcut(int s) {shortcut_ = s;} + /** + Returns true if either FL_SUBMENU or FL_SUBMENU_POINTER + is on in the flags. FL_SUBMENU indicates an embedded submenu + that goes from the next item through the next one with a NULL + label(). FL_SUBMENU_POINTER indicates that user_data() + is a pointer to another menu array. + */ int submenu() const {return flags&(FL_SUBMENU|FL_SUBMENU_POINTER);} + /** + Returns true if a checkbox will be drawn next to this item. This is + true if FL_MENU_TOGGLE or FL_MENU_RADIO is set in the + flags. + */ int checkbox() const {return flags&FL_MENU_TOGGLE;} + /** + Returns true if this item is a radio item. When a radio button is + selected all "adjacent" radio buttons are turned off. A set of radio + items is delimited by an item that has radio() false, or by an + item with FL_MENU_DIVIDER turned on. + */ int radio() const {return flags&FL_MENU_RADIO;} + /** Returns the current value of the check or radio item. */ int value() const {return flags&FL_MENU_VALUE;} + /** + Turns the check or radio item "on" for the menu item. Note that this + does not turn off any adjacent radio items like set_only() + does. + */ void set() {flags |= FL_MENU_VALUE;} + /** Turns the check or radio item "off" for the menu item. */ void clear() {flags &= ~FL_MENU_VALUE;} void setonly(); + /** Gets the visibility of an item. */ int visible() const {return !(flags&FL_MENU_INVISIBLE);} + /** Makes an item visible in the menu. */ void show() {flags &= ~FL_MENU_INVISIBLE;} + /** Hides an item in the menu. */ void hide() {flags |= FL_MENU_INVISIBLE;} + /** Get whether or not the item can be picked. */ int active() const {return !(flags&FL_MENU_INACTIVE);} + /** Allows a menu item to be picked. */ void activate() {flags &= ~FL_MENU_INACTIVE;} + /** + Prevents a menu item from being picked. Note that this will also cause + the menu item to appear grayed-out. + */ void deactivate() {flags |= FL_MENU_INACTIVE;} - int activevisible() const {return !(flags&0x11);} + /** Returns non 0 if FL_INACTIVE and FL_INVISIBLE are cleared, 0 otherwise. */ + int activevisible() const {return !(flags & (FL_MENU_INACTIVE|FL_MENU_INVISIBLE));} // compatibility for FLUID so it can set the image of a menu item... + /** compatibility api for FLUID, same as a->label(this) */ void image(Fl_Image* a) {a->label(this);} + /** compatibility api for FLUID, same as a.label(this) */ void image(Fl_Image& a) {a.label(this);} // used by menubar: @@ -130,15 +328,37 @@ struct FL_EXPORT Fl_Menu_Item { const Fl_Menu_Item* test_shortcut() const; const Fl_Menu_Item* find_shortcut(int *ip=0) const; + /** + Call the Fl_Menu_Item item's callback, and provide the + Fl_Widget argument (and optionally override the user_data() + argument). You must first check that callback() is non-zero + before calling this. + */ void do_callback(Fl_Widget* o) const {callback_(o, user_data_);} + /** + Call the Fl_Menu_Item item's callback, and provide the + Fl_Widget argument (and optionally override the user_data() + argument). You must first check that callback() is non-zero + before calling this. + */ void do_callback(Fl_Widget* o,void* arg) const {callback_(o, arg);} + /** + Call the Fl_Menu_Item item's callback, and provide the + Fl_Widget argument (and optionally override the user_data() + argument). You must first check that callback() is non-zero + before calling this. + */ void do_callback(Fl_Widget* o,long arg) const {callback_(o, (void*)arg);} // back-compatability, do not use: + /** back compatibility only \deprecated. */ int checked() const {return flags&FL_MENU_VALUE;} + /** back compatibility only \deprecated. */ void check() {flags |= FL_MENU_VALUE;} + /** back compatibility only \deprecated. */ void uncheck() {flags &= ~FL_MENU_VALUE;} int add(const char*, int shortcut, Fl_Callback*, void* =0, int = 0); + /** See int add(const char*, int shortcut, Fl_Callback*, void*, int) */ int add(const char*a, const char* b, Fl_Callback* c, void* d = 0, int e = 0) { return add(a,fl_old_shortcut(b),c,d,e);} diff --git a/FL/Fl_Menu_Window.H b/FL/Fl_Menu_Window.H index b2fea05d0..7337ac1d2 100644 --- a/FL/Fl_Menu_Window.H +++ b/FL/Fl_Menu_Window.H @@ -30,6 +30,12 @@ #include "Fl_Single_Window.H" +/** + The Fl_Menu_Window widget is a window type used for menus. By + default the window is drawn in the hardware overlay planes if they are + available so that the menu don't force the rest of the window to + redraw. +*/ class FL_EXPORT Fl_Menu_Window : public Fl_Single_Window { enum {NO_OVERLAY = 128}; public: @@ -37,12 +43,18 @@ public: void erase(); void flush(); void hide(); + /** Tells if hardware overlay mode is set */ int overlay() {return !(flags()&NO_OVERLAY);} + /** Tells FLTK to use hardware overlay planes if they are available. */ void set_overlay() {clear_flag(NO_OVERLAY);} + /** Tells FLTK to use normal drawing planes instead of overlay planes. + This is usually necessary if your menu contains multi-color pixmaps. */ void clear_overlay() {set_flag(NO_OVERLAY);} ~Fl_Menu_Window(); + /** Creates a new Fl_Menu_Window widget using the given size, and label string. */ Fl_Menu_Window(int W, int H, const char *l = 0) : Fl_Single_Window(W,H,l) { image(0); } + /** Creates a new Fl_Menu_Window widget using the given position, size, and label string. */ Fl_Menu_Window(int X, int Y, int W, int H, const char *l = 0) : Fl_Single_Window(X,Y,W,H,l) { image(0); } }; diff --git a/FL/Fl_Progress.H b/FL/Fl_Progress.H index 6f5819a2b..12ccf09c6 100644 --- a/FL/Fl_Progress.H +++ b/FL/Fl_Progress.H @@ -38,7 +38,9 @@ // // Progress class... // - +/** + Displays a progress bar for the user. +*/ class FL_EXPORT Fl_Progress : public Fl_Widget { float value_, @@ -53,13 +55,19 @@ class FL_EXPORT Fl_Progress : public Fl_Widget Fl_Progress(int x, int y, int w, int h, const char *l = 0); + /** Sets the maximum value in the progress widget. */ void maximum(float v) { maximum_ = v; redraw(); } + /** Gets the maximum value in the progress widget. */ float maximum() const { return (maximum_); } + /** Sets the minimum value in the progress widget. */ void minimum(float v) { minimum_ = v; redraw(); } + /** Gets the minimum value in the progress widget. */ float minimum() const { return (minimum_); } + /** Sets the current value in the progress widget. */ void value(float v) { value_ = v; redraw(); } + /** Gets the current value in the progress widget. */ float value() const { return (value_); } }; diff --git a/FL/Fl_Timer.H b/FL/Fl_Timer.H index 6c9e28067..4f3dada40 100644 --- a/FL/Fl_Timer.H +++ b/FL/Fl_Timer.H @@ -37,6 +37,13 @@ #define FL_VALUE_TIMER 1 #define FL_HIDDEN_TIMER 2 +/** + This is provided only to emulate the Forms Timer widget. It works by + making a timeout callback every 1/5 second. This is wasteful and + inaccurate if you just want something to happen a fixed time in the + future. You should directly call + Fl::add_timeout() instead. +*/ class FL_EXPORT Fl_Timer : public Fl_Widget { static void stepcb(void *); void step(); @@ -50,9 +57,21 @@ public: Fl_Timer(uchar t,int x,int y,int w,int h, const char *l); ~Fl_Timer(); void value(double); + /** See void Fl_Timer::value(double) */ double value() const {return delay>0.0?delay:0.0;} + /** + Gets or sets the direction of the timer. If the direction is zero + then the timer will count up, otherwise it will count down from the + initial value(). + */ char direction() const {return direction_;} + /** + Gets or sets the direction of the timer. If the direction is zero + then the timer will count up, otherwise it will count down from the + initial value(). + */ void direction(char d) {direction_ = d;} + /** Gets or sets whether the timer is suspended. */ char suspended() const {return !on;} void suspended(char d); }; diff --git a/documentation/todo_filelist_doc.txt b/documentation/todo_filelist_doc.txt index 6db2db872..74c65362c 100644 --- a/documentation/todo_filelist_doc.txt +++ b/documentation/todo_filelist_doc.txt @@ -15,7 +15,7 @@ In Progress Work List (add your WP and name here): - WP4 (Fabien) DONE - WP5 (Fabien) DONE - WP6 (Fabien) DONE - - WP7 (Fabien) + - WP7 (Fabien) DONE - WP8 (Fabien) - WP9 - WP10 @@ -194,19 +194,6 @@ Fl_Input_.cxx Fl_Input_Choice.H Fl_Int_Input.H Fl_Line_Dial.H -Fl_Menu.H -Fl_Menu.cxx -Fl_Menu_.H -Fl_Menu_.cxx -Fl_Menu_Bar.H -Fl_Menu_Bar.cxx -Fl_Menu_Button.H -Fl_Menu_Button.cxx -Fl_Menu_Item.H -Fl_Menu_Window.H -Fl_Menu_Window.cxx -Fl_Menu_add.cxx -Fl_Menu_global.cxx Fl_Multi_Browser.H Fl_Multi_Label.H Fl_Multi_Label.cxx @@ -215,8 +202,6 @@ Fl_Multiline_Output.H Fl_Nice_Slider.H Fl_Object.H Fl_Output.H -Fl_Progress.H -Fl_Progress.cxx Fl_Radio_Button.H Fl_Radio_Light_Button.H Fl_Radio_Round_Button.H @@ -251,7 +236,6 @@ Fl_Text_Editor.H Fl_Text_Editor.cxx Fl_Tiled_Image.H Fl_Tiled_Image.cxx -Fl_Timer.H Fl_Toggle_Button.H Fl_Toggle_Light_Button.H Fl_Toggle_Round_Button.H @@ -354,7 +338,6 @@ forms_bitmap.cxx forms_compatability.cxx forms_fselect.cxx forms_pixmap.cxx -forms_timer.cxx freeglut_geometry.cxx freeglut_stroke_mono_roman.cxx freeglut_stroke_roman.cxx diff --git a/src/Fl_Menu.cxx b/src/Fl_Menu.cxx index eeda1bcc2..a7af493df 100644 --- a/src/Fl_Menu.cxx +++ b/src/Fl_Menu.cxx @@ -41,7 +41,7 @@ #ifdef __APPLE__ # include <Carbon/Carbon.h> #endif - +/** Size of the menu starting from this menu item */ int Fl_Menu_Item::size() const { const Fl_Menu_Item* m = this; int nest = 0; @@ -56,6 +56,11 @@ int Fl_Menu_Item::size() const { } } +/** + Advance a pointer by n items through a menu array, skipping + the contents of submenus and invisible items. There are two calls so + that you can advance through const and non-const data. +*/ const Fl_Menu_Item* Fl_Menu_Item::next(int n) const { if (n < 0) return 0; // this is so selected==-1 returns NULL const Fl_Menu_Item* m = this; @@ -118,7 +123,10 @@ public: extern char fl_draw_shortcut; -// width of label, including effect of & characters: +/** + Measures width of label, including effect of & characters. + Optionally, can get height if hp is not NULL. +*/ int Fl_Menu_Item::measure(int* hp, const Fl_Menu_* m) const { Fl_Label l; l.value = text; @@ -136,6 +144,7 @@ int Fl_Menu_Item::measure(int* hp, const Fl_Menu_* m) const { return w; } +/** Draws the menu item in bounding box x,y,w,h, optionally selects the item. */ void Fl_Menu_Item::draw(int x, int y, int w, int h, const Fl_Menu_* m, int selected) const { Fl_Label l; @@ -745,13 +754,22 @@ int menuwindow::early_hide_handle(int e) { return Fl_Window::handle(e); } +/** + Pulldown() is similar to popup(), but a rectangle is + provided to position the menu. The menu is made at least W + wide, and the picked item is centered over the rectangle + (like Fl_Choice uses). If picked is zero or not + found, the menu is aligned just below the rectangle (like a pulldown + menu). + <P>The title and menubar arguments are used + internally by the Fl_Menu_Bar widget. +*/ const Fl_Menu_Item* Fl_Menu_Item::pulldown( int X, int Y, int W, int H, const Fl_Menu_Item* initial_item, const Fl_Menu_* pbutton, const Fl_Menu_Item* t, - int menubar) const -{ + int menubar) const { Fl_Group::current(0); // fix possible user error... button = pbutton; @@ -894,21 +912,39 @@ const Fl_Menu_Item* Fl_Menu_Item::pulldown( return m; } -const Fl_Menu_Item* -Fl_Menu_Item::popup( +/** + This method is called by widgets that want to display menus. The menu + stays up until the user picks an item or dismisses it. The selected + item (or NULL if none) is returned. <I>This does not do the + callbacks or change the state of check or radio items.</I> + <P>X,Y is the position of the mouse cursor, relative to the + window that got the most recent event (usually you can pass + Fl::event_x() and Fl::event_y() unchanged here). </P> + <P>title is a character string title for the menu. If + non-zero a small box appears above the menu with the title in it. </P> + <P>The menu is positioned so the cursor is centered over the item + picked. This will work even if picked is in a submenu. + If picked is zero or not in the menu item table the menu is + positioned with the cursor in the top-left corner. </P> + <P>button is a pointer to an + Fl_Menu_ from which the color and boxtypes for the menu are + pulled. If NULL then defaults are used. +*/ +const Fl_Menu_Item* Fl_Menu_Item::popup( int X, int Y, const char* title, const Fl_Menu_Item* picked, const Fl_Menu_* but - ) const -{ + ) const { static Fl_Menu_Item dummy; // static so it is all zeros dummy.text = title; return pulldown(X, Y, 0, 0, picked, but, title ? &dummy : 0); } -// Search only the top level menu for a shortcut. Either &x in the -// label or the shortcut fields are used: +/** + Search only the top level menu for a shortcut. + Either &x in the label or the shortcut fields are used. +*/ const Fl_Menu_Item* Fl_Menu_Item::find_shortcut(int* ip) const { const Fl_Menu_Item* m = first(); if (m) for (int ii = 0; m->text; m = m->next(), ii++) { @@ -925,6 +961,14 @@ const Fl_Menu_Item* Fl_Menu_Item::find_shortcut(int* ip) const { // Recursive search of all submenus for anything with this key as a // shortcut. Only uses the shortcut field, ignores &x in the labels: +/** + This is designed to be called by a widgets handle() method in + response to a FL_SHORTCUT event. If the current event matches + one of the items shortcut, that item is returned. If the keystroke + does not match any shortcuts then NULL is returned. This only + matches the shortcut() fields, not the letters in the title + preceeded by ' +*/ const Fl_Menu_Item* Fl_Menu_Item::test_shortcut() const { const Fl_Menu_Item* m = first(); const Fl_Menu_Item* ret = 0; diff --git a/src/Fl_Menu_.cxx b/src/Fl_Menu_.cxx index 1a8e12691..c875a6688 100644 --- a/src/Fl_Menu_.cxx +++ b/src/Fl_Menu_.cxx @@ -24,7 +24,6 @@ // // http://www.fltk.org/str.php // - // This is a base class for all items that have a menu: // Fl_Menu_Bar, Fl_Menu_Button, Fl_Choice // This provides storage for a menu item, functions to add/modify/delete @@ -38,15 +37,15 @@ #include <stdio.h> #include <stdlib.h> -// Set 'pathname' of specified menuitem -// If finditem==NULL, mvalue() is used (the most recently picked menuitem) -// Returns: -// 0 : OK -// -1 : item not found (name="") -// -2 : 'name' not large enough (name="") -// -#define SAFE_STRCAT(s) \ - { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); } +#define SAFE_STRCAT(s) { len += strlen(s); if ( len >= namelen ) { *name='\0'; return(-2); } else strcat(name,(s)); } + +/** Set 'pathname' of specified menuitem + If finditem==NULL, mvalue() is used (the most recently picked menuitem) + Returns: + - 0 : OK + - -1 : item not found (name="") + - -2 : 'name' not large enough (name="") +*/ int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *finditem) const { int len = 0; finditem = finditem ? finditem : mvalue(); @@ -75,14 +74,13 @@ int Fl_Menu_::item_pathname(char *name, int namelen, const Fl_Menu_Item *findite return(-1); // item not found } -// FIND MENU ITEM INDEX, GIVEN MENU PATHNAME -// eg. "Edit/Copy" -// Will also return submenus, eg. "Edit" -// Returns NULL if not found. -// -const Fl_Menu_Item * -Fl_Menu_::find_item(const char *name) -{ +/** + Find menu item index, given menu pathname + eg. "Edit/Copy" + Will also return submenus, eg. "Edit" + Returns NULL if not found. +*/ +const Fl_Menu_Item * Fl_Menu_::find_item(const char *name) { char menupath[1024] = ""; // File/Export for ( int t=0; t < size(); t++ ) { @@ -115,15 +113,23 @@ Fl_Menu_::find_item(const char *name) return (const Fl_Menu_Item *)0; } +/** + The value is the index into menu() of the last item chosen by + the user. It is zero initially. You can set it as an integer, or set + it with a pointer to a menu item. The set routines return non-zero if + the new value is different than the old one. +*/ int Fl_Menu_::value(const Fl_Menu_Item* m) { clear_changed(); if (value_ != m) {value_ = m; return 1;} return 0; } -// When user picks a menu item, call this. It will do the callback. -// Unfortunatly this also casts away const for the checkboxes, but this -// was necessary so non-checkbox menus can really be declared const... +/** + When user picks a menu item, call this. It will do the callback. + Unfortunatly this also casts away const for the checkboxes, but this + was necessary so non-checkbox menus can really be declared const... +*/ const Fl_Menu_Item* Fl_Menu_::picked(const Fl_Menu_Item* v) { if (v) { if (v->radio()) { @@ -150,7 +156,7 @@ const Fl_Menu_Item* Fl_Menu_::picked(const Fl_Menu_Item* v) { return v; } -// turn on one of a set of radio buttons +/** Turns the radio item "on" for the menu item and turns off adjacent radio items set. */ void Fl_Menu_Item::setonly() { flags |= FL_MENU_RADIO | FL_MENU_VALUE; Fl_Menu_Item* j; @@ -167,6 +173,10 @@ void Fl_Menu_Item::setonly() { } Fl_Menu_::Fl_Menu_(int X,int Y,int W,int H,const char* l) +/** + Creates a new Fl_Menu_ widget using the given position, size, + and label string. menu() is initialized to null. +*/ : Fl_Widget(X,Y,W,H,l) { set_flag(SHORTCUT_LABEL); box(FL_UP_BOX); @@ -180,11 +190,24 @@ Fl_Menu_::Fl_Menu_(int X,int Y,int W,int H,const char* l) down_box(FL_NO_BOX); } +/** + This returns the number of Fl_Menu_Item structures that make up the + menu, correctly counting submenus. This includes the "terminator" + item at the end. To copy a menu array you need to copy + size()*sizeof(Fl_Menu_Item) bytes. If the menu is + NULL this returns zero (an empty menu will return 1). +*/ int Fl_Menu_::size() const { if (!menu_) return 0; return menu_->size(); } +/** + Sets the menu array pointer directly. If the old menu is private it is + deleted. NULL is allowed and acts the same as a zero-length + menu. If you try to modify the array (with add(), replace(), or + delete()) a private copy is automatically done. +*/ void Fl_Menu_::menu(const Fl_Menu_Item* m) { clear(); value_ = menu_ = (Fl_Menu_Item*)m; @@ -192,6 +215,11 @@ void Fl_Menu_::menu(const Fl_Menu_Item* m) { // this version is ok with new Fl_Menu_add code with fl_menu_array_owner: +/** + Sets the menu array pointer with a copy of m that will be automatically deleted. + If ud is not NULL, then all user data pointers are changed in the menus as well. + See void Fl_Menu_::menu(const Fl_Menu_Item* m). +*/ void Fl_Menu_::copy(const Fl_Menu_Item* m, void* ud) { int n = m->size(); Fl_Menu_Item* newMenu = new Fl_Menu_Item[n]; @@ -213,6 +241,12 @@ Fl_Menu_::~Fl_Menu_() { // expanding array. We must not free this array: Fl_Menu_* fl_menu_array_owner = 0; +/** + Same as menu(NULL), set the array pointer to null, indicating + a zero-length menu. + + <P>Menus must no be cleared during a callback to the same menu. +*/ void Fl_Menu_::clear() { if (alloc) { if (alloc>1) for (int i = size(); i--;) diff --git a/src/Fl_Menu_Button.cxx b/src/Fl_Menu_Button.cxx index a3c13a829..5474cbaaf 100644 --- a/src/Fl_Menu_Button.cxx +++ b/src/Fl_Menu_Button.cxx @@ -47,6 +47,13 @@ void Fl_Menu_Button::draw() { fl_line(X+H, Y, X+H/2, Y+H); } +/** + Act exactly as though the user clicked the button or typed the + shortcut key. The menu appears, it waits for the user to pick an item, + and if they pick one it sets value() and does the callback or + sets changed() as described above. The menu item is returned + or NULL if the user dismisses the menu. +*/ const Fl_Menu_Item* Fl_Menu_Button::popup() { const Fl_Menu_Item* m; pressed_menu_button_ = this; @@ -101,6 +108,12 @@ int Fl_Menu_Button::handle(int e) { } } +/** + Creates a new Fl_Menu_Button widget using the given position, + size, and label string. The default boxtype is FL_UP_BOX. + <P>The constructor sets menu() to NULL. See + Fl_Menu_ for the methods to set or change the menu. +*/ Fl_Menu_Button::Fl_Menu_Button(int X,int Y,int W,int H,const char *l) : Fl_Menu_(X,Y,W,H,l) { down_box(FL_NO_BOX); diff --git a/src/Fl_Menu_Window.cxx b/src/Fl_Menu_Window.cxx index ece82ce30..2b463f3bc 100644 --- a/src/Fl_Menu_Window.cxx +++ b/src/Fl_Menu_Window.cxx @@ -78,6 +78,7 @@ void Fl_Menu_Window::flush() { #endif } +/** Erases the window, does nothing if HAVE_OVERLAY is not defined config.h */ void Fl_Menu_Window::erase() { #if HAVE_OVERLAY if (!gc || !shown()) return; @@ -94,6 +95,7 @@ void Fl_Menu_Window::hide() { Fl_Single_Window::hide(); } +/** Destroys the window and all of its children.*/ Fl_Menu_Window::~Fl_Menu_Window() { hide(); } diff --git a/src/Fl_Menu_add.cxx b/src/Fl_Menu_add.cxx index ba5d0931d..7bc766948 100644 --- a/src/Fl_Menu_add.cxx +++ b/src/Fl_Menu_add.cxx @@ -24,7 +24,6 @@ // // http://www.fltk.org/str.php // - // Methods to alter the menu in an Fl_Menu_ widget. // These are for Forms emulation and for dynamically changing the @@ -97,9 +96,10 @@ static int compare(const char* a, const char* b) { } } -// Add an item. The text is split at '/' characters to automatically -// produce submenus (actually a totally unnecessary feature as you can -// now add submenu titles directly by setting SUBMENU in the flags): +/** Adds an item. The text is split at '/' characters to automatically + produce submenus (actually a totally unnecessary feature as you can + now add submenu titles directly by setting SUBMENU in the flags): +*/ int Fl_Menu_Item::add( const char *mytext, int sc, @@ -175,7 +175,68 @@ int Fl_Menu_Item::add( if (array == local_array) local_array_size = msize; return m-array; } - +/** + Adds a new menu item, with a title string, shortcut int (or string), + callback, argument to the callback, and flags. + If the menu array was directly set with menu(x) then copy() is done + to make a private array. + + <p>The characters "&", "/", "\", and "_" are treated as + special characters in the label string. The "&" character + specifies that the following character is an accelerator and + will be underlined. The "\" character is used to escape the next + character in the string. Labels starting with the "_" character + cause a divider to be placed after that menu item.</p> + + <p>A label of the form "foo/bar/baz" will create a + submenus called "foo" and "bar" with an + entry called "baz". The "/" character is ignored if it + appears as the first character of the label string, e.g. + "/foo/bar/baz".</p> + + <p>The label string is copied to new memory and can be freed. + The other arguments (including the shortcut) are copied into the + menu item unchanged. </P> + + <P>If an item exists already with that name then it is replaced with + this new one. Otherwise this new one is added to the end of the + correct menu or submenu. The return value is the offset into the array + that the new entry was placed at.</P> + + <P>Shortcut can be 0L, or either a modifier/key combination (for example + FL_CTRL+'A') or a string describing the shortcut in one of two ways:</p> + + <pre> + [#+^]<ascii_value> eg. "97", "^97", "+97", "#97" + [#+^]<ascii_char> eg. "a", "^a", "+a", "#a" + </pre> + ..where <ascii_value> is a decimal value representing an + ascii character (eg. 97 is the ascii for 'a'), and the optional + prefixes enhance the value that follows. Multiple prefixes must + appear in the above order. + <pre> + # - Alt + + - Shift + ^ - Control + </pre> + Text shortcuts are converted to integer shortcut by calling + int fl_old_shortcut(const char*). + + <P>The return value is the index into the array that the entry was put. </P> + + <P>No items must be added to a menu during a callback to the same menu.</P> + + + <h4>int Fl_Menu_::add(const char *)</H4> + + <P>The passed string is split at any '|' characters and then + add(s,0,0,0,0) is done with each section. This is + often useful if you are just using the value, and is compatible + with Forms and other GL programs. The section strings use the + same special characters as described for the long version of add()</p> + + <P>No items must be added to a menu during a callback to the same menu. +*/ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { // make this widget own the local array: if (this != fl_menu_array_owner) { @@ -218,9 +279,11 @@ int Fl_Menu_::add(const char *t, int s, Fl_Callback *c,void *v,int f) { return r; } -// This is a Forms (and SGI GL library) compatable add function, it -// adds many menu items, with '|' seperating the menu items, and tab -// seperating the menu item names from an optional shortcut string. +/** + This is a Forms (and SGI GL library) compatible add function, it + adds many menu items, with '|' seperating the menu items, and tab + separating the menu item names from an optional shortcut string. +*/ int Fl_Menu_::add(const char *str) { char buf[1024]; int r = 0; @@ -238,6 +301,11 @@ int Fl_Menu_::add(const char *str) { return r; } +/** + Changes the text of item n. This is the only way to get + slash into an add()'ed menu item. If the menu array was directly set + with menu(x) then copy() is done to make a private array. +*/ void Fl_Menu_::replace(int i, const char *str) { if (i<0 || i>=size()) return; if (!alloc) copy(menu_); @@ -247,7 +315,12 @@ void Fl_Menu_::replace(int i, const char *str) { } menu_[i].text = str; } - +/** + Deletes item n from the menu. If the menu array was directly + set with menu(x) then copy() is done to make a private array. + + <P>No items must be removed from a menu during a callback to the same menu. +*/ void Fl_Menu_::remove(int i) { int n = size(); if (i<0 || i>=n) return; diff --git a/src/Fl_Menu_global.cxx b/src/Fl_Menu_global.cxx index b7cba6faf..ebfb7965e 100644 --- a/src/Fl_Menu_global.cxx +++ b/src/Fl_Menu_global.cxx @@ -40,6 +40,16 @@ static int handler(int e) { return the_widget->handle(e); } +/** + Make the shortcuts for this menu work no matter what window has the + focus when you type it. This is done by using + Fl::add_handler(). This Fl_Menu_ widget does not + have to be visible (ie the window it is in can be hidden, or it does + not have to be put in a window at all). + <P>Currently there can be only one global()menu. Setting a new + one will replace the old one. There is no way to remove the + global() setting (so don't destroy the widget!) +*/ void Fl_Menu_::global() { if (!the_widget) Fl::add_handler(handler); the_widget = this; diff --git a/src/Fl_Progress.cxx b/src/Fl_Progress.cxx index 69e76492c..ee311a326 100644 --- a/src/Fl_Progress.cxx +++ b/src/Fl_Progress.cxx @@ -25,6 +25,7 @@ // http://www.fltk.org/str.php // // Contents: + // // Fl_Progress::draw() - Draw the check button. // Fl_Progress::Fl_Progress() - Construct a Fl_Progress widget. @@ -49,6 +50,7 @@ // 'Fl_Progress::draw()' - Draw the check button. // +/** Draws the check button. */ void Fl_Progress::draw() { int progress; // Size of progress bar... @@ -96,13 +98,13 @@ void Fl_Progress::draw() } -// -// 'Fl_Progress::Fl_Progress()' - Construct a Fl_Progress widget. -// - +/** + The constructor creates the progress bar using the position, + size, and label. + <P> The inherited destructor removes the progress bar. +*/ Fl_Progress::Fl_Progress(int X, int Y, int W, int H, const char* l) -: Fl_Widget(X, Y, W, H, l) -{ +: Fl_Widget(X, Y, W, H, l) { align(FL_ALIGN_INSIDE); box(FL_DOWN_BOX); color(FL_BACKGROUND2_COLOR, FL_YELLOW); diff --git a/src/forms_timer.cxx b/src/forms_timer.cxx index 031d67f27..33627761d 100644 --- a/src/forms_timer.cxx +++ b/src/forms_timer.cxx @@ -126,11 +126,28 @@ int Fl_Timer::handle(int event) { return 0; } +/** + Destroys the timer and removes the timeout. +*/ Fl_Timer::~Fl_Timer() { Fl::remove_timeout(stepcb, this); } +/** + Creates a new Fl_Timer widget using the given type, position, + size, and label string. The type parameter can be any of the + following symbolic constants: + <UL> + <LI>FL_NORMAL_TIMER - The timer just does the callback and + displays the string "Timer" in the widget. </LI> + <LI>FL_VALUE_TIMER - The timer does the callback and displays + the current timer value in the widget. </LI> + <LI>FL_HIDDEN_TIMER - The timer just does the callback and + does not display anything. </LI> + </UL> +*/ Fl_Timer::Fl_Timer(uchar t, int X, int Y, int W, int H, const char* l) + : Fl_Widget(X, Y, W, H, l) { box(FL_DOWN_BOX); selection_color(FL_RED); @@ -141,7 +158,7 @@ Fl_Timer::Fl_Timer(uchar t, int X, int Y, int W, int H, const char* l) if (t == FL_HIDDEN_TIMER) clear_visible(); if (t == FL_VALUE_TIMER) align(FL_ALIGN_LEFT); } - +/** Sets the current timer value */ void Fl_Timer::value(double d) { delay = total = d; on = (d > 0.0); @@ -151,6 +168,7 @@ void Fl_Timer::value(double d) { if (on) Fl::add_timeout(FL_TIMER_BLINKRATE, stepcb, this); } +/** Gets or sets whether the timer is suspended.*/ void Fl_Timer::suspended(char d) { if (!d) { if (on) return; |