Documentation updates for Fl_Window::xclass(), default_xclass(),

and show().


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

2 files changed, 81 insertions, 24 deletions

diff --git a/FL/Fl_Window.H b/FL/Fl_Window.H
index 721d10289..1f12ff8d4 100644
--- a/FL/Fl_Window.H
+++ b/FL/Fl_Window.H
@@ -329,20 +329,6 @@ public:
   static void default_xclass(const char*);
   static const char *default_xclass();
   const char* xclass() const;
-  /**
-    A string used to tell the system what type of window this is. Mostly
-    this identifies the picture to draw in the icon. <I>Under X, this is
-    turned into a XA_WM_CLASS pair by truncating at the first
-    non-alphanumeric character and capitalizing the first character, and
-    the second one if the first is 'x'.  Thus "foo" turns into "foo, Foo",
-    and "xprog.1" turns into "xprog, XProg".</I> This only works if called <I>
-    before</I> calling show().
-
-    Under Microsoft Windows this string is used as the name of the
-    WNDCLASS structure, though it is not clear if this can have any
-    visible effect. The passed pointer is stored unchanged. The string 
-    is not copied.
-  */
   void xclass(const char* c);
   /** Gets the current icon window target dependent data. */
   const void* icon() const	{return icon_;}
@@ -357,14 +343,18 @@ public:
   int shown() {return i != 0;}
   /**
     Puts the window on the screen. Usually (on X) this has the side
-    effect of opening the display. The second form is used for top-level
-    windows and allows standard arguments to be parsed from the
-    command-line.
+    effect of opening the display. 
 
     If the window is already shown then it is restored and raised to the
     top.  This is really convenient because your program can call show()
     at any time, even if the window is already up.  It also means that 
     show() serves the purpose of raise() in other toolkits.
+    
+    Fl_Window::show(int argc, char **argv) is used for top-level
+    windows and allows standard arguments to be parsed from the
+    command-line.
+    
+    \see Fl_Window::show(int argc, char **argv)
   */
   virtual void show();
   /**
@@ -373,9 +363,26 @@ public:
   */
   virtual void hide();
   /**
-    See virtual void Fl_Window::show() 
+    Puts the window on the screen and parses command-line arguments.
+
+    Usually (on X) this has the side effect of opening the display.
+
+    This form should be used for top-level windows, at least for the
+    first (main) window. It allows standard arguments to be parsed
+    from the command-line. You can use \p argc and \p argv from
+    main(int argc, char **argv) for this call.
+
+    The first call also sets up some system-specific internal
+    variables like the system colors.
+
+    \todo explain which system parameters are set up.
+
+    \param argc command-line argument count, usually from main()
+    \param argv command-line argument vector, usually from main()
+
+    \see virtual void Fl_Window::show()
   */
-  void show(int, char**);
+  void show(int argc, char **argv);
   /**
     Makes the window completely fill the screen, without any window
     manager border visible.  You must use fullscreen_off() to undo
diff --git a/src/Fl_Window.cxx b/src/Fl_Window.cxx
index 0c641fe32..aa6dcff70 100644
--- a/src/Fl_Window.cxx
+++ b/src/Fl_Window.cxx
@@ -180,8 +180,12 @@ Fl_Window *Fl_Window::current() {
   return current_;
 }
 
-/** Returns the default xclass */
-const char *Fl_Window::default_xclass() 
+/** Returns the default xclass.
+
+  \see Fl_Window::default_xclass(const char *)
+
+ */
+const char *Fl_Window::default_xclass()
 {
   if (default_xclass_) {
     return default_xclass_;
@@ -190,7 +194,26 @@ const char *Fl_Window::default_xclass()
   }
 }
 
-/** Sets the defaul xclass */
+/** Sets the default window xclass.
+
+  The default xclass is used for all windows that don't have their
+  own xclass set before show() is called. You can change the default
+  xclass whenever you want, but this only affects windows that are
+  created (and shown) after this call.
+
+  The given string \p xc is copied. You can use a local variable or
+  free the string immediately after this call.
+
+  If you don't call this, the default xclass for all windows will be "FLTK".
+  You can reset the default xclass by specifying NULL for \p xc.
+
+  If you call Fl_Window::xclass(const char *) for any window, then
+  this also sets the default xclass, unless it has been set before.
+
+  \param[in] xc default xclass for all windows subsequently created
+
+  \see Fl_Window::xclass(const char *)
+*/
 void Fl_Window::default_xclass(const char *xc)
 {
   if (default_xclass_) {
@@ -202,7 +225,30 @@ void Fl_Window::default_xclass(const char *xc)
   }
 }
 
-/** Set the xclass for this window */
+/** Sets the xclass for this window.
+
+  A string used to tell the system what type of window this is. Mostly
+  this identifies the picture to draw in the icon. This only works if
+  called \e before calling show().
+
+  <I>Under X</I>, this is turned into a XA_WM_CLASS pair by truncating at
+  the first non-alphanumeric character and capitalizing the first character,
+  and the second one if the first is 'x'.  Thus "foo" turns into "foo, Foo",
+  and "xprog.1" turns into "xprog, XProg".
+
+  <I>Under Microsoft Windows</I>, this string is used as the name of the
+  WNDCLASS structure, though it is not clear if this can have any
+  visible effect.
+
+  \since FLTK 1.3 the passed string is copied. You can use a local
+  variable or free the string immediately after this call. Note that
+  FLTK 1.1 stores the \e pointer without copying the string.
+
+  If the default xclass has not yet been set, this also sets the
+  default xclass for all windows created subsequently.
+
+  \see Fl_Window::default_xclass(const char *)
+*/
 void Fl_Window::xclass(const char *xc) 
 {
   if (xclass_) {
@@ -217,7 +263,11 @@ void Fl_Window::xclass(const char *xc)
   }
 }
 
-/** Return the XClass for this window, or a default. */
+/** Returns the xclass for this window, or a default.
+
+  \see Fl_Window::default_xclass(const char *)
+  \see Fl_Window::xclass(const char *)
+*/
 const char *Fl_Window::xclass() const
 {
   if (xclass_) {