1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
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
|
