Add missing Fl_Labeltype and Fl_Boxtype definitions.

Some labeltypes and boxtypes were missing a #define for the enum
without a leading underscore and the corresponding setup function
to initialize the internal table of boxtypes and labeltypes, for
instance _FL_MULTI_LABEL. This is now fixed so (hopefully) all boxtypes
and labeltypes can and _should_ be used w/o leading underscore.

Note: if there are still boxtypes or labeltypes that can't be used w/o
leading underscore this should be considered a bug and is to be fixed ASAP.


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

6 files changed, 122 insertions, 13 deletions

diff --git a/CHANGES b/CHANGES
index 01f5569c9..e3bb6e9ff 100644
--- a/CHANGES
+++ b/CHANGES
@@ -71,6 +71,13 @@ Changes in FLTK 1.4.0					Released: ??? ?? 2017
   Other Improvements
 
   - (add new items here)
+  - The Fl_Boxtype and Fl_Labeltype definitions contained enum values
+    (names) with a leading underscore (e.g. _FL_MULTI_LABEL) that had to
+    be used in this form. Now all boxtypes and labeltypes can and should
+    be used without the leading underscore. A note was added to the enum
+    documentations to make clear that the leading underscore must not be
+    used in user code, although the enum documentation still contains
+    leading underscores for technical reasons (internal use).
   - The blocks demo program got a new keyboard shortcut (ALT+SHIFT+H) to
     reset the user's high score. It is now slower than before in higher
     levels, hence you can expect higher scores (due to a bug fix in the
diff --git a/FL/Enumerations.H b/FL/Enumerations.H
index 6902c0ee6..a959a8208 100644
--- a/FL/Enumerations.H
+++ b/FL/Enumerations.H
@@ -3,7 +3,7 @@
 //
 // Enumerations for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2016 by Bill Spitzak and others.
+// Copyright 1998-2017 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -558,7 +558,13 @@ enum Fl_When { // Fl_Widget::when():
     \brief FLTK standard box types
     
     This enum defines the standard box types included with FLTK.
-    
+
+   \note The documented \p enum \p Fl_Boxtype contains some values (names)
+      with leading underscores, e.g. \p \b _FL_SHADOW_BOX. This is due to
+      technical reasons - please use the same values (names) without the
+      leading underscore in your code! Enum values with leading underscores
+      are reserved for internal use and subject to change without notice!
+
     FL_NO_BOX means nothing is drawn at all, so whatever is already 
     on the screen remains. The FL_..._FRAME types only draw their edges, 
     leaving the interior unchanged. The blue color in Figure 1 
@@ -722,6 +728,12 @@ inline Fl_Boxtype fl_frame(Fl_Boxtype b) {
 /**
    The labeltype() method sets the type of the label.
 
+   \note The documented \p enum \p Fl_Labeltype contains some values (names)
+      with leading underscores, e.g. \p \b _FL_IMAGE_LABEL. This is due to
+      technical reasons - please use the same values (names) without the
+      leading underscore in your code! Enum values with leading underscores
+      are reserved for internal use and subject to change without notice!
+
    The following standard label types are included:
 
    \todo	The doxygen comments are incomplete, and some labeltypes
@@ -748,13 +760,78 @@ enum Fl_Labeltype {	// labeltypes:
   Sets the current label type and returns its corresponding Fl_Labeltype value.
   @{
 */
+
+/** FL_SYMBOL_LABEL is an alias for FL_NORMAL_LABEL.
+
+  '@' symbols can be drawn with normal labels as well.\n
+  This definition is for historical reasons only (forms compatibility).
+  You should use FL_NORMAL_LABEL instead.
+*/
 #define FL_SYMBOL_LABEL FL_NORMAL_LABEL
+/**
+  Initializes the internal table entry for FL_SHADOW_LABEL and returns
+  its internal value. Internal use only.
+*/
 extern Fl_Labeltype FL_EXPORT fl_define_FL_SHADOW_LABEL();
+/**
+  Draws a label with shadows behind the text.
+*/
 #define FL_SHADOW_LABEL fl_define_FL_SHADOW_LABEL()
+
+/**
+  Initializes the internal table entry for FL_ENGRAVED_LABEL and returns
+  its internal value. Internal use only.
+*/
 extern Fl_Labeltype FL_EXPORT fl_define_FL_ENGRAVED_LABEL();
+/**
+  Draws a label with engraved text.
+*/
 #define FL_ENGRAVED_LABEL fl_define_FL_ENGRAVED_LABEL()
+
+/**
+  Initializes the internal table entry for FL_EMBOSSED_LABEL and returns
+  its internal value. Internal use only.
+*/
 extern Fl_Labeltype FL_EXPORT fl_define_FL_EMBOSSED_LABEL();
+/**
+  Draws a label with embossed text.
+*/
 #define FL_EMBOSSED_LABEL fl_define_FL_EMBOSSED_LABEL()
+
+/**
+  Initializes the internal table entry for FL_MULTI_LABEL and returns
+  its internal value. Internal use only.
+*/
+extern Fl_Labeltype FL_EXPORT fl_define_FL_MULTI_LABEL();
+/**
+  Draws a label that can comprise several parts like text and images.
+  \see Fl_Multi_Label
+*/
+#define FL_MULTI_LABEL fl_define_FL_MULTI_LABEL()
+
+/**
+  Initializes the internal table entry for FL_ICON_LABEL and returns
+  its internal value. Internal use only.
+*/
+extern Fl_Labeltype FL_EXPORT fl_define_FL_ICON_LABEL();
+/**
+  Draws an icon as the label.
+*/
+#define FL_ICON_LABEL fl_define_FL_ICON_LABEL()
+
+/**
+  Initializes the internal table entry for FL_IMAGE_LABEL and returns
+  its internal value. Internal use only.
+*/
+extern Fl_Labeltype FL_EXPORT fl_define_FL_IMAGE_LABEL();
+/**
+  Draws an image (Fl_Image) as the label.
+  This is useful for one particular part of an Fl_Multi_Label.
+  Use Fl_Widget::image() and/or Fl_Widget::deimage() for normal widgets
+  with images as labels.
+*/
+#define FL_IMAGE_LABEL fl_define_FL_IMAGE_LABEL()
+
 /** @} */
 
 /** \name Alignment Flags
diff --git a/FL/Fl_Image.H b/FL/Fl_Image.H
index f338500cd..4a1b56d79 100644
--- a/FL/Fl_Image.H
+++ b/FL/Fl_Image.H
@@ -183,6 +183,9 @@ public:
   void draw(int X, int Y) {draw(X, Y, w(), h(), 0, 0);} // platform dependent
   virtual void uncache();
 
+  // used by fl_define_FL_IMAGE_LABEL() to avoid 'friend' declaration
+  static Fl_Labeltype define_FL_IMAGE_LABEL();
+
   // set RGB image scaling method
   static void RGB_scaling(Fl_RGB_Scaling);
 
diff --git a/FL/Fl_Menu_Item.H b/FL/Fl_Menu_Item.H
index 55f953db6..dbe1a80fb 100644
--- a/FL/Fl_Menu_Item.H
+++ b/FL/Fl_Menu_Item.H
@@ -348,11 +348,19 @@ struct FL_EXPORT Fl_Menu_Item {
 
   // compatibility for FLUID so it can set the image of a menu item...
 
-  /** compatibility api for FLUID, same as a->label(this) */
-  void image(Fl_Image* a) {a->label(this);}
+  /** Compatibility API for FLUID, same as image->label(this).
 
-  /** compatibility api for FLUID, same as a.label(this) */
-  void image(Fl_Image& a) {a.label(this);}
+    \note This method is intended for internal use by fluid and may
+      not do what you expect.
+  */
+  void image(Fl_Image* image) {image->label(this);}
+
+  /** Compatibility API for FLUID, same as image.label(this).
+
+    \note This method is intended for internal use by fluid and may
+      not do what you expect.
+  */
+  void image(Fl_Image& image) {image.label(this);}
 
   // used by menubar:
   int measure(int* h, const Fl_Menu_*) const;
diff --git a/src/Fl_Image.cxx b/src/Fl_Image.cxx
index efe980cb8..a43a596eb 100644
--- a/src/Fl_Image.cxx
+++ b/src/Fl_Image.cxx
@@ -113,6 +113,16 @@ void Fl_Image::color_average(Fl_Color, float) {
 void Fl_Image::desaturate() {
 }
 
+// Doxygen documentation in FL/Enumerations.H
+Fl_Labeltype fl_define_FL_IMAGE_LABEL() {
+  return Fl_Image::define_FL_IMAGE_LABEL();
+}
+
+Fl_Labeltype Fl_Image::define_FL_IMAGE_LABEL() {
+  Fl::set_labeltype(_FL_IMAGE_LABEL, Fl_Image::labeltype, Fl_Image::measure);
+  return _FL_IMAGE_LABEL;
+}
+
 /**
   The label() methods are an obsolete way to set the
   image attribute of a widget or menu item. Use the
diff --git a/src/Fl_Multi_Label.cxx b/src/Fl_Multi_Label.cxx
index 56ce602ca..1a9050494 100644
--- a/src/Fl_Multi_Label.cxx
+++ b/src/Fl_Multi_Label.cxx
@@ -3,7 +3,7 @@
 //
 // Multi-label widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2010 by Bill Spitzak and others.
+// Copyright 1998-2017 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -16,8 +16,8 @@
 //     http://www.fltk.org/str.php
 //
 
-// Allows two labels to be used on a widget (by having one of them
-// be one of these it allows an infinte number!)
+// Allows two or more labels to be used on a widget (by having one of them
+// be one of these it allows an infinite number!)
 
 #include <FL/Fl.H>
 #include <FL/Fl_Widget.H>
@@ -56,14 +56,18 @@ static void multi_measure(const Fl_Label* o, int& w, int& h) {
   w += W; if (H>h) h = H;
 }
 
-void Fl_Multi_Label::label(Fl_Widget* o) {
+// used by FL_MULTI_LABEL to set up the internal table, see FL/Enumerations.H
+Fl_Labeltype fl_define_FL_MULTI_LABEL() {
   Fl::set_labeltype(_FL_MULTI_LABEL, multi_labeltype, multi_measure);
-  o->label(_FL_MULTI_LABEL, (const char*)this);
+  return _FL_MULTI_LABEL;
+}
+
+void Fl_Multi_Label::label(Fl_Widget* o) {
+  o->label(FL_MULTI_LABEL, (const char*)this); // calls fl_define_FL_MULTI_LABEL()
 }
 
 void Fl_Multi_Label::label(Fl_Menu_Item* o) {
-  Fl::set_labeltype(_FL_MULTI_LABEL, multi_labeltype, multi_measure);
-  o->label(_FL_MULTI_LABEL, (const char*)this);
+  o->label(FL_MULTI_LABEL, (const char*)this); // calls fl_define_FL_MULTI_LABEL()
 }
 
 //