1 /** @file item.h  Data context item.
2  *
3  * @authors Copyright (c) 2013-2017 Jaakko Keränen <jaakko.keranen@iki.fi>
4  *
5  * @par License
6  * LGPL: http://www.gnu.org/licenses/lgpl.html
7  *
8  * <small>This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License as published by
10  * the Free Software Foundation; either version 3 of the License, or (at your
11  * option) any later version. This program is distributed in the hope that it
12  * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
13  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
14  * General Public License for more details. You should have received a copy of
15  * the GNU Lesser General Public License along with this program; if not, see:
16  * http://www.gnu.org/licenses</small>
17  */
18 
19 #ifndef LIBAPPFW_UI_DATAITEM_H
20 #define LIBAPPFW_UI_DATAITEM_H
21 
22 #include "../libappfw.h"
23 #include <de/Observers>
24 #include <de/String>
25 
26 #include <QVariant>
27 
28 namespace de {
29 namespace ui {
30 
31 class Data;
32 
33 /**
34  * Data item.
35  *
36  * Items are pure content -- the exact presentation parameters (widget type,
37  * alignment, scaling, etc.)ares determined by the container widget and/or
38  * responsible organizer, not by an Item. This allows one item to be presented
39  * in different ways by different widgets/contexts.
40  *
41  * @see ui::Data
42  *
43  * @ingroup uidata
44  */
45 class LIBAPPFW_PUBLIC Item
46 {
47 public:
48     /**
49      * Determines the item's behavior and look'n'feel. This acts as a hint for
50      * the containing widget (and the responsible organizer) so it can adjust
51      * its behavior accordingly.
52      */
53     enum SemanticFlag {
54         ShownAsLabel          = 0x1,
55         ShownAsButton         = 0x2,
56         ShownAsToggle         = 0x4,
57         ShownAsPopupButton    = 0x8 | ShownAsButton,
58 
59         ActivationClosesPopup = 0x100,
60         Separator             = 0x200,
61         Annotation            = 0x400 | Separator,
62         ClosesParentPopup     = 0x800,
63 
64         DefaultSemantics      = ShownAsLabel
65     };
66     Q_DECLARE_FLAGS(Semantics, SemanticFlag)
67 
68     DENG2_DEFINE_AUDIENCE2(Change, void itemChanged(Item const &item))
69 
70 public:
71     Item(Semantics semantics = DefaultSemantics);
72 
73     Item(Semantics semantics, String const &label);
74 
75     virtual ~Item();
76 
77     Semantics semantics() const;
78 
79     bool isSeparator() const;
80 
81     void setLabel(String const &label);
82 
83     String label() const;
84 
85     void setDataContext(Data &context);
86 
87     bool hasDataContext() const;
88 
89     Data &dataContext() const;
90 
91     /**
92      * Returns a text string that should be used for sorting the item inside a
93      * context.
94      */
95     virtual String sortKey() const;
96 
97     /**
98      * Sets the custom user data of the item.
99      *
100      * @param d  Variant data to be associated with the item.
101      */
102     void setData(QVariant const &d);
103 
104     QVariant const &data() const;
105 
106     DENG2_CAST_METHODS()
107 
108     /**
109      * Notifies the Change audience of a changed property.
110      */
111     void notifyChange() const;
112 
113 private:
114     DENG2_PRIVATE(d)
115 };
116 
117 Q_DECLARE_OPERATORS_FOR_FLAGS(Item::Semantics)
118 
119 } // namespace ui
120 } // namespace de
121 
122 #endif // LIBAPPFW_UI_DATAITEM_H
123