From 8dd0abe3f20d4de3034428c541ef3f25ce7cc4e2 Mon Sep 17 00:00:00 2001 From: engelsman Date: Thu, 9 Apr 2009 19:00:16 +0000 Subject: [PATCH] converted more html tags to doxygen commands in subclassing.dox removed a lot of old html name anchors (unused, or superseded by \ref) added draw_childred() text corrected signatures for draw_child(), draw_outside_label(), update_child() git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@6748 ea41ed52-d2ee-0310-a9c1-e6b18d33e121 --- documentation/src/subclassing.dox | 50 ++++++++++++++----------------- 1 file changed, 23 insertions(+), 27 deletions(-) diff --git a/documentation/src/subclassing.dox b/documentation/src/subclassing.dox index 7bf75d228..cb5480dfc 100644 --- a/documentation/src/subclassing.dox +++ b/documentation/src/subclassing.dox @@ -41,7 +41,7 @@ MyClass(int x, int y, int w, int h, const char *label = 0); \endcode This will allow the class to be used in -FLUID +\ref fluid "FLUID" without problems. The constructor must call the constructor for the base class and @@ -88,7 +88,6 @@ The following methods are provided for subclasses to use: \li \ref subclassing_test_shortcut "test_shortcut()" \li \ref subclassing_type "type()" - \anchor subclassing_damage void Fl_Widget::damage(uchar mask)
void Fl_Widget::damage(uchar mask, int x, int y, int w, int h)
@@ -108,7 +107,7 @@ but the implementation of your widget can call the public The second form indicates that a region is damaged. If only these calls are done in a window (no calls to \p damage(n)) then FLTK will clip to the union of all these calls before drawing anything. - This can greatly speed up incremental displays. The mask bits are +This can greatly speed up incremental displays. The mask bits are OR'd into \p damage() unless this is a Fl_Window widget. \par @@ -142,7 +141,6 @@ MyClass::draw() { \todo Clarify Fl_Window::damage(n) handling - seems confused/wrong? ORing value doesn't match setting behaviour in FL_Widget.H! - \anchor subclassing_draw_box void Fl_Widget::draw_box() const
void Fl_Widget::draw_box(Fl_Boxtype t, Fl_Color c) const @@ -152,7 +150,6 @@ The first form draws this widget's \p box(), using the dimensions of the widget. The second form uses \p t as the box type and \p c as the color for the box. - \anchor subclassing_draw_focus void Fl_Widget::draw_focus()
void Fl_Widget::draw_focus(Fl_Boxtype t, int x, int y, int w, int h) const @@ -161,7 +158,6 @@ void Fl_Widget::draw_focus(Fl_Boxtype t, int x, int y, int w, int h) const Draws a focus box inside the widget's bounding box. The second form allows you to specify a different bounding box. - \anchor subclassing_draw_label void Fl_Widget::draw_label() const
void Fl_Widget::draw_label(int x, int y, int w, int h) const
@@ -184,7 +180,6 @@ The third form draws the label anywhere. It acts as though the passed bounding box. This is designed for parent groups to draw labels with. - \anchor subclassing_set_flag void Fl_Widget::set_flag(int c)
@@ -193,7 +188,6 @@ Calling \p set_flag(SHORTCUT_LABEL) modifies the behavior of \ref subclassing_draw_label "draw_label()" so that '\&' characters cause an underscore to be printed under the next letter. - \anchor subclassing_clear_visible \anchor subclassing_set_visible @@ -204,7 +198,6 @@ void Fl_Widget::clear_visible() Fast inline versions of Fl_Widget::hide() and Fl_Widget::show(). These do not send the \p FL_HIDE and \p FL_SHOW events to the widget. - \anchor subclassing_test_shortcut int Fl_Widget::test_shortcut()
static int Fl_Widget::test_shortcut(const char *s) @@ -223,14 +216,13 @@ The second version lets you do this test against an arbitrary string. \todo Clarify Fl_Widget::test_shortcut() explanations. Fl_Widget.h says Internal Use only, but subclassing chapter gives details! - \anchor subclassing_type uchar Fl_Widget::type() const
void Fl_Widget::type(uchar t) \par The property Fl_Widget::type() can return an arbitrary 8-bit -identifier, and can be set with the protected method \p type(uchar t). +identifier, and can be set with the protected method type(uchar t). This value had to be provided for Forms compatibility, but you can use it for any purpose you want. Try to keep the value less than 100 to not interfere with reserved values. @@ -247,9 +239,8 @@ be greater than the symbol \p FL_RESERVED_TYPE (which is 100) and less than \p FL_WINDOW (unless you make a subclass of Fl_Window). Look through the header files for \p FL_RESERVED_TYPE to find an unused number. If you make a subclass of Fl_Window you must use -\p FL_WINDOW+n (where \p n must be in the range 1 to 7). +FL_WINDOW + n (where \p n must be in the range 1 to 7). - \section subclassing_events Handling Events The virtual method Fl_Widget::handle(int event) is called @@ -265,13 +256,13 @@ to handle each event passed to the widget. It can: \li Call Fl_Widget::handle() on child widgets. Events are identified by the integer argument. Other information -about the most recent event is stored in static locations and aquired +about the most recent event is stored in static locations and acquired by calling the \ref events_event_xxx. This information remains valid until another event is handled. Here is a sample \p handle() method for a widget that acts as -a pushbutton and also accepts the keystroke 'x' to cause the callback: +a pushbutton and also accepts the keystroke \p 'x' to cause the callback: \code int MyClass::handle(int event) { @@ -333,14 +324,14 @@ be redrawn, e.g. for an expose event. Expose events (and the \ref subclassing_damage "damage(mask,x,y,w,h)" function described above) will cause \p draw() to be called with FLTK's - clipping +\ref ssect_Clipping "clipping" turned on. You can greatly speed up redrawing in some -cases by testing \p fl_not_clipped(x,y,w,h) or \p fl_clip_box(...) +cases by testing \p fl_not_clipped(x,y,w,h) or \p %fl_clip_box() and skipping invisible parts. Besides the protected methods described above, FLTK provides a large -number of basic drawing functions, which are described in the -\ref drawing chapter. +number of basic drawing functions, which are described in the chapter +\ref drawing. \section subclassing_resizing Resizing the Widget @@ -438,15 +429,13 @@ int MyClass::draw() { } \endcode -\todo The new method draw_children should be documented below. - Fl_Group provides some protected methods to make drawing easier: \li \ref subclassing_draw_child "draw_child()" +\li \ref subclassing_draw_children "draw_children()" \li \ref subclassing_draw_outside_label "draw_outside_label()" \li \ref subclassing_update_child "update_child()" - \anchor subclassing_draw_child void Fl_Group::draw_child(Fl_Widget &widget) const @@ -458,9 +447,17 @@ if you draw something (like a background box) that damages the child. Nothing is done if the child is not \p visible() or if it is clipped. - +\anchor subclassing_draw_children +void Fl_Group::draw_children() + +\par +A convenience function that draws all children of the group. +This is useful if you derived a widget from Fl_Group and want to draw +a special border or background. You can call \p draw_children() from the +derived \p draw() method after drawing the box, border, or background. + \anchor subclassing_draw_outside_label -void Fl_Group::draw_outside_label(Fl_Widget &widget) const +void Fl_Group::draw_outside_label(const Fl_Widget &widget) const \par Draw the labels that are \e not drawn by @@ -468,9 +465,8 @@ Draw the labels that are \e not drawn by If you want more control over the label positions you might want to call child->draw_label(x,y,w,h,a). - \anchor subclassing_update_child -void Fl_Group::update_child(Fl_Widget &widget) +void Fl_Group::update_child(Fl_Widget& widget) const \par Draws the child only if its \p damage() is non-zero. You @@ -521,7 +517,7 @@ switch a subclass back and forth. Watch out for the following differences: -# Fl_Window is a subclass of Fl_Group so - make sure your constructor calls \p end() + make sure your constructor calls \p end() unless you actually want children added to your window. -# When handling events and drawing, the upper-left corner is at