-
-
Notifications
You must be signed in to change notification settings - Fork 31
/
childwidgetorganizer.h
205 lines (174 loc) · 7.12 KB
/
childwidgetorganizer.h
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
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
/** @file childwidgetorganizer.h Organizes widgets according to a UI context.
*
* @authors Copyright (c) 2013 Jaakko Keränen <jaakko.keranen@iki.fi>
*
* @par License
* LGPL: http://www.gnu.org/licenses/lgpl.html
*
* <small>This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 3 of the License, or (at your
* option) any later version. This program is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
* General Public License for more details. You should have received a copy of
* the GNU Lesser General Public License along with this program; if not, see:
* http://www.gnu.org/licenses</small>
*/
#ifndef LIBAPPFW_CHILDWIDGETORGANIZER_H
#define LIBAPPFW_CHILDWIDGETORGANIZER_H
#include "../libappfw.h"
#include "../ui/Data"
#include "../GuiWidget"
namespace de {
/**
* Utility class that observes changes in a ui::Context and updates a parent
* widget's children to reflect the UI context's contents. This involves
* creating the corresponding widgets, updating them when the context items
* change, and reordering them when the items' order changes.
*
* The concrete task of creating widgets is done by an object that implements
* the ChildWidgetOrganizer::IWidgetFactory interface. Also, third parties
* may observe widget creation and updates and alter the widget as they choose.
*
* @todo Virtualization: it is not required that all the items of the context
* are represented by widgets on screen at the same time. In contexts with
* large numbers of items, virtualization should be applied to keep only a
* subset/range of items present as widgets.
*
* @ingroup appfw
*/
class LIBAPPFW_PUBLIC ChildWidgetOrganizer
{
public:
/**
* Constructs widgets for the organizer.
*/
class IWidgetFactory
{
public:
virtual ~IWidgetFactory() {}
/**
* Called when the organizer needs a widget for a context item. This allows
* the specialized organizers to choose the widget type and customize it
* appropriately.
*
* After construction, the widget is automatically updated with
* updateItemWidget().
*
* @param item Item that has the content.
* @param parent Future parent of the widget, if any (can be @c NULL).
*/
virtual GuiWidget *makeItemWidget(ui::Item const &item, GuiWidget const *parent) = 0;
/**
* Called whenever the item's content changes and this should be reflected
* in the widget.
*
* @param widget Widget that represents the item.
* @param item Item that has the content.
*/
virtual void updateItemWidget(GuiWidget &widget, ui::Item const &item) = 0;
};
public:
ChildWidgetOrganizer(GuiWidget &container);
/**
* Sets the object responsible for creating widgets for this organizer. The
* default factory creates labels with their default settings. The factory
* should be set before calling setContext().
*
* @param factory Widget factory.
*/
void setWidgetFactory(IWidgetFactory &factory);
IWidgetFactory &widgetFactory() const;
/**
* Sets the data context of the organizer. If there was a previous context,
* all widgets created for it are deleted from the container. The widgets
* are immediately constructed using the current factory.
*
* @param context Context with items.
*/
void setContext(ui::Data const &context);
void unsetContext();
ui::Data const &context() const;
GuiWidget *itemWidget(ui::Data::Pos pos) const;
GuiWidget *itemWidget(ui::Item const &item) const;
GuiWidget *itemWidget(String const &label) const;
ui::Item const *findItemForWidget(GuiWidget const &widget) const;
//- Child Widget Virtualization ---------------------------------------------------------
/**
* Enables or disables child widget virtualization. When enabled, widgets are
* only created for items that are potentially visible.
*
* Virtualization is necessary when the set of data items is very large.
*
* If enabled, you must also provide the top and bottom rules for the visible
* area, and the approximated average child widget height.
*
* @param enabled Enable or disable child virtualization.
*/
void setVirtualizationEnabled(bool enabled);
/**
* Enables or disables child recycling. Deleted children will be put up for
* recycling instead of being deleted, and new children will first be taken
* from the set of old recycled widgets.
*
* It is only possible to use this when all the items being managed have the
* same kind of widget representing them.
*/
void setRecyclingEnabled(bool enabled);
void setVirtualTopEdge(Rule const &topEdge);
void setVisibleArea(Rule const &minimum, Rule const &maximum);
bool virtualizationEnabled() const;
/**
* Returns the rule that defines the height of all the currently nonexistent widgets
* above the first visible child. This will be automatically updated as children are
* recycled and the top child changes.
*
* The initial value is zero.
*/
Rule const &virtualStrut() const;
/**
* The average child height is used when estimating the maximum number of widgets
* that can be created.
*
* @param height Average child height.
*/
void setAverageChildHeight(int height);
int averageChildHeight() const;
Rule const &estimatedTotalHeight() const;
/**
* After child widgets have been moved around, this must be called to update the
* potentially visible item range and to recycle any widgets that are outside the
* range. Items entering the range will be given widgets.
*/
void updateVirtualization();
public:
/**
* Notified when the organizer creates a widget for a context item. Allows
* third parties to customize the widget as needed.
*/
DENG2_DEFINE_AUDIENCE2(WidgetCreation,
void widgetCreatedForItem(GuiWidget &widget,
ui::Item const &item))
/**
* Notified when the organizer updates a widget for a changed context item.
* Allows third parties to customize the widget as needed.
*/
DENG2_DEFINE_AUDIENCE2(WidgetUpdate,
void widgetUpdatedForItem(GuiWidget &widget,
ui::Item const &item))
private:
DENG2_PRIVATE(d)
};
/**
* Simple widget factory that creates label widgets with their default
* settings, using the label from the ui::Item.
*/
class DefaultWidgetFactory : public ChildWidgetOrganizer::IWidgetFactory
{
public:
GuiWidget *makeItemWidget(ui::Item const &item, GuiWidget const *parent);
void updateItemWidget(GuiWidget &widget, ui::Item const &item);
};
} // namespace de
#endif // LIBAPPFW_CHILDWIDGETORGANIZER_H