1 files changed, 81 insertions, 0 deletions
diff --git a/fltk/fltk/WidgetAssociation.h b/fltk/fltk/WidgetAssociation.h
new file mode 100644
index 0000000..0d4d512
--- /dev/null
+++ b/fltk/fltk/WidgetAssociation.h
@@ -0,0 +1,81 @@
+#ifndef fltk_WidgetAssociation_h
+#define fltk_WidgetAssociation_h
+
+#include <fltk/FL_API.h>
+
+namespace fltk {
+
+class FL_API Widget;
+class FL_API AssociationType;
+
+/*! \brief Class used by the foreach() functions.
+ *
+ * Base class for the association functor that is used in foreach(). If you want to supply
+ * your specific actions to do with the associated data found by the foreach() functions
+ * you need to derive from this class and provide a new handle function.
+ */
+class FL_API AssociationFunctor {
+ public:
+  /*!
+   * For each
+   * found association this function is called. If the function returns true the
+   * loop is aborted and the data pointer for the current association is returned
+   */
+  virtual bool handle(const AssociationType&, const Widget*, void* data) = 0;
+};
+
+/*! \relates AssociationType
+ * This function allows traversing all associations of a certain association type, a certain widget,
+ * both, or none of the constraints.
+ * For each found widget the handle function in the associaionFunctor class is called. If that
+ * function returns true the scan is aborted and the data for the current widget is returned
+ * A NULL pointer for the AssociationType or the Widget pointer means to call the functor for all
+ * AssociationTypes and/or all Widgets.
+ *
+ * The function either returns the first associated data for which the functor returns true, or NULL.
+ * See also Widget::foreach() and AssociationType::foreach().
+ */
+FL_API void*  foreach(const AssociationType*, const Widget*, AssociationFunctor&);
+
+/*! \brief Base class for the association type.
+ *
+ * FLTK allows you to attach any kind of user data to a widget. This data is automatically freed when the
+ * widget to which it is attached is destroyed. Internally an association table is used to connect the
+ * widget pointer with the data pointer that is why all the functions concerned with this feature contain
+ * "association" in their name. The advantage of this is that no space is taken on widgets that do not
+ * contain the data (or that have the "default value"), and that the destructor code is not linked in
+ * if the association is not used.
+ *
+ * To be able to associate data and to be able to have a customized way of freeing the data you need
+ * to derive from this class and then create an instance of that class. With the pointer to that instance
+ * the type of the data is identified.
+ *
+ * possible uses:
+ * - assign key shortcuts to certain widgets
+ * - assign a tooltip to some widgets
+ * - assign a help-index to widgets
+ * - assign a unique identifier to widgets to remote controlling
+ * - assign additional layouting data for new container widgets
+ * - assign data needed by typesafe callback mechanisms
+ * - assign all kind of data not always required within a widget / each widget
+ */
+class FL_API AssociationType {
+
+ public:
+  /*! \brief This function is called when associated data is freed
+   * This function must be proveded when creating a data specific subclass. The function
+   * must do whatever is necessary to free associated data. Most of the time it will be a cast
+   * to the right datatype and a delete
+   */
+  virtual void destroy(void* data) const = 0;
+
+  /*! \brief Finds all data of this association type for a widget
+   * This function just calls fltk::foreach(this, wg, fkt). If \a wg
+   * is NULL this function will find all data for any widget.
+   */
+  void* foreach(const Widget* wg, AssociationFunctor& fkt) { return fltk::foreach(this, wg, fkt); }
+};
+
+}
+
+#endif