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

3 files changed, 94 insertions, 6 deletions

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;