Documentation updates (FL/Fl_Widget.H): removed some \todo's.

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3@8155 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

1 files changed, 41 insertions, 20 deletions

diff --git a/FL/Fl_Widget.H b/FL/Fl_Widget.H
index ea86abe9c..3f227dafc 100644
--- a/FL/Fl_Widget.H
+++ b/FL/Fl_Widget.H
@@ -340,13 +340,6 @@ public:
 
       \return label alignment
       \see label(), align(Fl_Align), Fl_Align
-      \todo This function should not take uchar as an argument. 
-            Apart from the fact that uchar is too short with only 8 bits, 
-	    it does not provide type safety (in which case we don't need 
-	    to declare Fl_Align an enum to begin with).
-	    *NOTE* The current (FLTK 1.3) implementation (Dec 2008) is such that
-	    Fl_Align is (typedef'd to be) "unsigned" (int), but Fl_Widget's
-	    "align_" member variable is a bit field of 8 bits only !
    */
   Fl_Align align() const {return label_.align_;}
 
@@ -606,8 +599,8 @@ public:
   long argument() const {return (long)(fl_intptr_t)user_data_;}
 
   /** Sets the current user data (long) argument that is passed to the callback function.
-      \todo The user data value must be implemented using a \em union to avoid 
-      64 bit machine incompatibilities.
+      \todo The user data value must be implemented using \em intptr_t or similar
+      to avoid 64-bit machine incompatibilities.
    */
   void argument(long v) {user_data_ = (void*)v;}
 
@@ -937,25 +930,53 @@ public:
   Fl_Window* window() const ;
 
   /** Returns an Fl_Group pointer if this widget is an Fl_Group.
-  
+
+      Use this method if you have a widget (pointer) and need to
+      know whether this widget is derived from Fl_Group. If it returns
+      non-NULL, then the widget in question is derived from Fl_Group,
+      and you can use the returned pointer to access its children
+      or other Fl_Group-specific methods.
+      
+      Example:
+      \code
+      void my_callback (Fl_Widget *w, void *) {
+        Fl_Group *g = w->as_group();
+	if (g)
+	  printf ("This group has %d children\n",g->children());
+	else
+	  printf ("This widget is not a group!\n");
+      }
+      \endcode
+
       \retval NULL if this widget is not derived from Fl_Group.
       \note This method is provided to avoid dynamic_cast.
-      \todo More documentation ...
+      \see Fl_Widget::as_window(), Fl_Widget::as_gl_window()
    */
   virtual Fl_Group* as_group() {return 0;}
 
   /** Returns an Fl_Window pointer if this widget is an Fl_Window.
-   
-   \retval NULL if this widget is not derived from Fl_Window.
-   \note This method is provided to avoid dynamic_cast.
-   \todo More documentation ...
+
+      Use this method if you have a widget (pointer) and need to
+      know whether this widget is derived from Fl_Window. If it returns
+      non-NULL, then the widget in question is derived from Fl_Window,
+      and you can use the returned pointer to access its children
+      or other Fl_Window-specific methods.
+
+      \retval NULL if this widget is not derived from Fl_Window.
+      \note This method is provided to avoid dynamic_cast.
+      \see Fl_Widget::as_group(), Fl_Widget::as_gl_window()
    */
   virtual Fl_Window* as_window() {return 0;}
-  
-  /** Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window.   
-   \retval NULL if this widget is not derived from Fl_Gl_Window.
-   \note This method is provided to avoid dynamic_cast.
-   \todo More documentation ...
+
+  /** Returns an Fl_Gl_Window pointer if this widget is an Fl_Gl_Window.
+
+      Use this method if you have a widget (pointer) and need to
+      know whether this widget is derived from Fl_Gl_Window. If it returns
+      non-NULL, then the widget in question is derived from Fl_Gl_Window.
+
+      \retval NULL if this widget is not derived from Fl_Gl_Window.
+      \note This method is provided to avoid dynamic_cast.
+      \see Fl_Widget::as_group(), Fl_Widget::as_window()
    */
   virtual class Fl_Gl_Window* as_gl_window() {return 0;}