From 3ebc315ad21eb626b3e2d7eccd46c0cb76031246 Mon Sep 17 00:00:00 2001 From: Albrecht Schlosser Date: Sun, 8 Feb 2009 17:26:02 +0000 Subject: [PATCH] Documentation updates, in parts concerning changes done for STR #1894. git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6652 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- FL/Fl_Group.H | 38 +++++++++++++++++++++----------------- FL/Fl_Widget.H | 19 ++++++++++--------- src/Fl_Group.cxx | 16 +++++++++++----- 3 files changed, 42 insertions(+), 31 deletions(-) diff --git a/FL/Fl_Group.H b/FL/Fl_Group.H index 219039fba..21d8c8d46 100644 --- a/FL/Fl_Group.H +++ b/FL/Fl_Group.H @@ -39,9 +39,8 @@ The Fl_Group class is the FLTK container widget. It maintains an array of child widgets. These children can themselves be any widget including Fl_Group. The most important subclass of Fl_Group - is Fl_Window, however - groups can also be used to control radio buttons or to enforce resize - behavior. + is Fl_Window, however groups can also be used to control radio buttons + or to enforce resize behavior. */ class FL_EXPORT Fl_Group : public Fl_Widget { @@ -105,8 +104,8 @@ public: void add(Fl_Widget* o) {add(*o);} void insert(Fl_Widget&, int i); /** - This does insert(w, find(beforethis)). This will append the - widget if beforethis is not in the group. + This does insert(w, find(before)). This will append the + widget if \a before is not in the group. */ void insert(Fl_Widget& o, Fl_Widget* before) {insert(o,find(before));} void remove(Fl_Widget&); @@ -127,19 +126,22 @@ public: children. Widgets that are horizontally or vertically inside the dimensions of the box are scaled to the new size. Widgets outside the box are moved. -

In these examples the gray area is the resizable: -

-

\image html resizebox1.gif   - \image html resizebox2.gif

- \image latex resizebox1.eps "before resize" width=4cm - \image latex resizebox2.eps "after resize" width=4cm -

The resizable may be set to the group itself (this is the default - value for an Fl_Group, although NULL is the default - for Fl_Window and Fl_Pack), in which case all the - contents are resized. + + In these examples the gray area is the resizable: + + \image html resizebox1.gif + \image html resizebox2.gif + \image latex resizebox1.eps "before resize" width=4cm + \image latex resizebox2.eps "after resize" width=4cm + + The resizable may be set to the group itself, in which case all the + contents are resized. This is the default value for Fl_Group, + although NULL is the default for Fl_Window and Fl_Pack. + If the resizable is NULL then all widgets remain a fixed size - and distance from the top-left corner.

-

It is possible to achieve any type of resize behavior by using an + and distance from the top-left corner. + + It is possible to achieve any type of resize behavior by using an invisible Fl_Box as the resizable and/or by using a hierarchy of child Fl_Group's. */ @@ -181,8 +183,10 @@ public: \sa Fl_Widget::take_focus(); */ void focus(Fl_Widget* W) {W->take_focus();} + /** This is for forms compatibility only */ Fl_Widget* & _ddfdesign_kludge() {return resizable_;} + /** This is for forms compatibility only */ void forms_end(); }; diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H index 7fe67ce11..46e457833 100644 --- a/FL/Fl_Widget.H +++ b/FL/Fl_Widget.H @@ -164,11 +164,12 @@ 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 + Destroying single widgets is not very common. You almost always want to + destroy the parent group instead, which will destroy all of the child widgets and groups in that group. + + \since FLTK 1.3, the widget's destructor removes the widget from its parent + group, if it is member of a group. */ virtual ~Fl_Widget(); @@ -185,7 +186,7 @@ public: 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 + When implemented in a widget, this function must return 0 if the widget does not use the event or 1 otherwise. Most of the time, you want to call the inherited handle() method in @@ -208,7 +209,7 @@ public: /** Internal use only - "for hacks only". - It is \em STRONGLY recommended not to use this method, because it + It is \em \b STRONGLY recommended not to use this method, because it short-circuits Fl_Group's normal widget adding and removing methods, if the widget is already a child widget of another Fl_Group. @@ -371,7 +372,7 @@ public: */ void color(unsigned bg, unsigned sel) {color_=bg; color2_=sel;} - /** Get the current label text. + /** Gets the current label text. \return a pointer to the current label text \see label(Fl_CString), copy_label(Fl_CString) */ @@ -600,7 +601,7 @@ public: \li FL_WHEN_ENTER_KEY: If the user types the Enter key, the entire text is selected, and the callback is done if the text has changed. Normally the Enter key will navigate to the next field (or insert - a newline for a Fl_Mulitline_Input) - this changes the behavior. + a newline for a Fl_Multiline_Input) - this changes the behavior. \li FL_WHEN_ENTER_KEY|FL_WHEN_NOT_CHANGED: The Enter key will do the callback even if the text has not changed. Useful for command fields. Fl_Widget::when() is a set of bitflags used by subclasses of @@ -898,7 +899,7 @@ public: /** Reserved type numbers (necessary for my cheapo RTTI) start here. - grep the header files for "RESERVED_TYPE" to find the next available + Grep the header files for "RESERVED_TYPE" to find the next available number. */ #define FL_RESERVED_TYPE 100 diff --git a/src/Fl_Group.cxx b/src/Fl_Group.cxx index 891e0cce8..8eaa81b93 100644 --- a/src/Fl_Group.cxx +++ b/src/Fl_Group.cxx @@ -405,10 +405,16 @@ void Fl_Group::clear() { /** The destructor also deletes all the children. This allows a whole tree to be deleted at once, without having to keep a pointer to - all the children in the user code. A kludge has been done so the - Fl_Group and all of it's children can be automatic (local) - variables, but you must declare the Fl_Group first, so - that it is destroyed last. + all the children in the user code. + + It is allowed that the Fl_Group and all of its children are automatic + (local) variables, but you must declare the Fl_Group \e first, so that + it is destroyed last. + + If you add static or automatic (local) variables to an Fl_Group, then it + is your responsibility to remove (or delete) all such static or automatic + child widgets \e \b before destroying the group - otherwise the child + widgets' destructors would be called twice! */ Fl_Group::~Fl_Group() { clear(); @@ -416,7 +422,7 @@ Fl_Group::~Fl_Group() { /** The widget is removed from its current group (if any) and then - inserted into this group. It is put at index n (or at the end + inserted into this group. It is put at index n - or at the end, if n >= children(). This can also be used to rearrange the widgets inside a group. */