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. + + +
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.
+ + +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. + +
If finditem is specified, name will contain the 'menu pathname' for that item. + +
Returns: + +
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. +
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.
+\image html src=
+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.
+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.
+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.
+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. +
The constructor sets menu() to NULL. See + Fl_Menu_ for the methods to set or change the menu.
+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.
+label() is ignored unless you change align() to + put it outside the menubar. +
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. +
\image html src=
+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.
+The menu will also pop up in response to shortcuts indicated by + putting a '&' character in the label().
+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.
+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. +
+ 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
+ };
+
+
+ Typically menu items are statically defined; for example:
+
+ 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}};
+
+ produces:
+ \image html menu.gif
+ + 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. +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 not 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. +
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.
+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 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. This does not do the
+ callbacks or change the state of check or radio items.
+ 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). title is a character string title for the menu. If
+ non-zero a small box appears above the menu with the title in it. 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. 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 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.
+ 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.
+
+ 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. 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". 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. 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. 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: The return value is the index into the array that the entry was put. No items must be added to a menu during a callback to the same menu. 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() 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.
+
+ 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).
+ 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.
+ 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:
+
+ [#+^]<ascii_value> eg. "97", "^97", "+97", "#97"
+ [#+^]<ascii_char> eg. "a", "^a", "+a", "#a"
+
+ ..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.
+
+ # - Alt
+ + - Shift
+ ^ - Control
+
+ Text shortcuts are converted to integer shortcut by calling
+ int fl_old_shortcut(const char*).
+
+ int Fl_Menu_::add(const char *)
+
+
+
+*/
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;