From 98811098a928fc69c2aa0b4cb0f7665a5d1d78c9 Mon Sep 17 00:00:00 2001
From: Albrecht Schlosser <albrechts.fltk@online.de>
Date: Wed, 17 Nov 2010 11:03:51 +0000
Subject: 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
---
 src/Fl_Window.cxx | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 55 insertions(+), 5 deletions(-)

(limited to 'src')

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_) {
-- 
cgit v1.2.3