New method Fl::scheme_is(const char *name).

This is a convenience method to support easier implementation of
scheme-specific code in draw() methods and elsewhere.

Also improved Fl::scheme(const char *name) documentation.


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

3 files changed, 49 insertions, 11 deletions

diff --git a/CHANGES b/CHANGES
index a4b0dc419..24461aa88 100644
--- a/CHANGES
+++ b/CHANGES
@@ -1,5 +1,6 @@
 CHANGES IN FLTK 1.3.3                                              RELEASED: MMM DD YYYY
 
+	- new method Fl::scheme_is(const char *name) returns 1 if current scheme is name.
 	- Fixed recent MinGW build WRT configure not finding strcasecmp() (STR #2994).
 	  Note: This fix is temporary and should be revisited later.
 	- Fixed missing libdl dependency in CMake builds (STR #2977).
diff --git a/FL/Fl.H b/FL/Fl.H
index 5fd5c7fbd..614e01826 100644
--- a/FL/Fl.H
+++ b/FL/Fl.H
@@ -275,10 +275,41 @@ public:
   static void background2(uchar, uchar, uchar);
 
   // schemes:
-  static int scheme(const char*);
+  static int scheme(const char *name);
   /** See void scheme(const char *name) */
   static const char* scheme() {return scheme_;}
-  /** 
+
+  /** Returns whether the current scheme is the given name.
+
+    This is a fast inline convenience function to support scheme-specific
+    code in widgets, e.g. in their draw() methods, if required.
+
+    Use a valid scheme name, not \p NULL (although \p NULL is allowed,
+    this is not a useful argument - see below).
+
+    If Fl::scheme() has not been set or has been set to the default
+    scheme ("none" or "base"), then this will always return 0 regardless
+    of the argument, because Fl::scheme() is \p NULL in this case.
+
+    \note The stored scheme name is always lowercase, and this method will
+    do a case-sensitive compare, so you \b must use a lowercase string to
+    return the correct value. This is intentional for performance reasons.
+
+    Example:
+    \code
+      if (Fl::scheme_is("gtk+")) { your_code_here(); }
+    \endcode
+
+    \param[in] name \b lowercase string of requested scheme name.
+
+    \return 1 if the given scheme is active, 0 otherwise.
+
+    \see Fl::scheme(const char *name)
+  */
+  static int scheme_is(const char *name) {
+    return (scheme_ && name && !strcmp(name,scheme_));
+  }
+  /**
     Called by scheme according to scheme name. 
     Loads or reloads the current scheme selection. 
     See void scheme(const char *name) 
diff --git a/src/Fl_get_system_colors.cxx b/src/Fl_get_system_colors.cxx
index bf158e0bc..76beda545 100644
--- a/src/Fl_get_system_colors.cxx
+++ b/src/Fl_get_system_colors.cxx
@@ -258,19 +258,25 @@ Fl_Image	*Fl::scheme_bg_ = (Fl_Image *)0;    // current background image for the
 static Fl_Pixmap	tile(tile_xpm);
 
 /**
-    Gets or sets the current widget scheme. NULL will use
-    the scheme defined in the FLTK_SCHEME environment
-    variable or the scheme resource under X11. Otherwise,
-    any of the following schemes can be used:
-      
+    Sets the current widget scheme. NULL will use the scheme defined
+    in the FLTK_SCHEME environment variable or the scheme resource
+    under X11. Otherwise, any of the following schemes can be used:
+
     	- "none" - This is the default look-n-feel which resembles old
     	Windows (95/98/Me/NT/2000) and old GTK/KDE
-    
+
+    	- "base" - This is an alias for "none"
+
     	- "plastic" - This scheme is inspired by the Aqua user interface
     	on Mac OS X
-    
-    	- "gtk+" - This scheme is inspired by the Red Hat Bluecurve
-    	theme
+
+    	- "gtk+" - This scheme is inspired by the Red Hat Bluecurve theme
+
+    Uppercase scheme names are equivalent, but the stored scheme name will
+    always be lowercase and Fl::scheme() will return this lowercase name.
+
+    If the resulting scheme name is not defined, the default scheme will
+    be used and Fl::scheme() will return NULL.
 */
 int Fl::scheme(const char *s) {
   if (!s) {