libyui  3.10.0
YItem.h
Go to the documentation of this file.
1 /*
2  Copyright (C) 2000-2012 Novell, Inc
3  This library is free software; you can redistribute it and/or modify
4  it under the terms of the GNU Lesser General Public License as
5  published by the Free Software Foundation; either version 2.1 of the
6  License, or (at your option) version 3.0 of the License. This library
7  is distributed in the hope that it will be useful, but WITHOUT ANY
8  WARRANTY; without even the implied warranty of MERCHANTABILITY or
9  FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
10  License for more details. You should have received a copy of the GNU
11  Lesser General Public License along with this library; if not, write
12  to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
13  Floor, Boston, MA 02110-1301 USA
14 */
15 
16 
17 /*-/
18 
19  File: YItem.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YItem_h
26 #define YItem_h
27 
28 #include <string>
29 #include <vector>
30 
31 
32 class YItem;
33 
34 // without "documenting" the file, typedefs will be dropped
35 //! @file
36 
37 //! Collection of pointers to YItem.
38 typedef std::vector<YItem *> YItemCollection;
39 //! Mutable iterator over @ref YItemCollection.
40 typedef YItemCollection::iterator YItemIterator;
41 //! Const iterator over @ref YItemCollection.
42 typedef YItemCollection::const_iterator YItemConstIterator;
43 
44 
45 /**
46  * Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc. items.
47  * This class provides stubs for children management.
48  **/
49 class YItem
50 {
51 public:
52  /**
53  * Constructor with just the label and optionally the selected state.
54  **/
55  YItem( const std::string & label, bool selected = false )
56  : _label( label )
57  , _status( selected ? 1 : 0 )
58  , _index( -1 )
59  , _data( 0 )
60  {}
61 
62  /**
63  * Constructor with label and icon name and optionally the selected state.
64  **/
65  YItem( const std::string & label, const std::string & iconName, bool selected = false )
66  : _label( label )
67  , _iconName( iconName )
68  , _status( selected ? 1 : 0 )
69  , _index( -1 )
70  , _data( 0 )
71  {}
72 
73  /**
74  * Destructor.
75  **/
76  virtual ~YItem() {}
77 
78  /**
79  * Return this item's label. This is what the user sees in a dialog, so
80  * this will usually be a translated text.
81  **/
82  std::string label() const { return _label; }
83 
84  /**
85  * Set this item's label.
86  **/
87  void setLabel( const std::string & newLabel ) { _label = newLabel; }
88 
89  /**
90  * Return this item's icon name.
91  **/
92  std::string iconName() const { return _iconName; }
93 
94  /**
95  * Return 'true' if this item has an icon name.
96  **/
97  bool hasIconName() const { return ! _iconName.empty(); }
98 
99  /**
100  * Set this item's icon name.
101  **/
102  void setIconName( const std::string & newIconName ) { _iconName = newIconName; }
103 
104  /**
105  * Return 'true' if this item is currently selected.
106  **/
107  bool selected() const { return _status != 0; }
108 
109  /**
110  * Select or unselect this item. This does not have any effect on any other
111  * item; if it is desired that only one item is selected at any time, the
112  * caller has to take care of that.
113  **/
114  void setSelected( bool sel = true ) { _status = sel ? 1 : 0; }
115 
116  /**
117  * Return the status of this item. This is a bit more generalized than
118  * 'selected'. Values other than 0 or 1 can mean different things to the
119  * application or to the specific widget.
120  **/
121  int status() const { return _status; }
122 
123  /**
124  * Set the status of this item. Most widgets only use 0 for "not selected"
125  * or nonzero for "selected". Some widgets may make use of other values as
126  * well.
127  **/
128  void setStatus( int newStatus ) { _status = newStatus; }
129 
130  /**
131  * Set this item's index.
132  **/
133  void setIndex( int index ) { _index = index; }
134 
135  /**
136  * Return the index of this item (as set with setIndex() ).
137  **/
138  int index() const { return _index; }
139 
140  /**
141  * Set the opaque data pointer for application use.
142  *
143  * Applications can use this to store the pointer to a counterpart of this
144  * tree item. It is the application's responsibility to watch for dangling
145  * pointers and possibliy deleting the data. All this class ever does with
146  * this pointer is to store it.
147  **/
148  void setData( void * newData ) { _data = newData; }
149 
150  /**
151  * Return the opaque data pointer.
152  **/
153  void * data() const { return _data; }
154 
155  //
156  // Children management stubs.
157  //
158  // Derived classes that can handle child items should reimplement those
159  // functions.
160  // The following default implementations don't do anything with children;
161  // they act as if this item didn't have any children.
162  //
163 
164  /**
165  * Return 'true' if this item has any child items.
166  **/
167  virtual bool hasChildren() const { return false; }
168 
169  /**
170  * Return an iterator that points to the first child item of this item.
171  *
172  * This default implementation returns the 'end' iterator of the
173  * class-static always empty _noChildren YItemCollection.
174  * It is safe to use this iterator in classic iterator loops:
175  *
176  * for ( YItemIterator it = myItem->childrenBegin();
177  * it != myItem->childrenEnd();
178  * ++it )
179  * {
180  * ...
181  * }
182  *
183  * The loop body will only ever be executed if this item is a derived class
184  * that actually manages child items.
185  **/
186  virtual YItemIterator childrenBegin() { return _noChildren.end(); }
187  virtual YItemConstIterator childrenBegin() const { return _noChildren.end(); }
188 
189  /**
190  * Return an iterator that points after the last child item of this item.
191  *
192  * This default implementation returns the 'end' iterator of the
193  * class-static always empty _noChildren YItemCollection.
194  **/
195  virtual YItemIterator childrenEnd() { return _noChildren.end(); }
196  virtual YItemConstIterator childrenEnd() const { return _noChildren.end(); }
197 
198  /**
199  * Returns this item's parent item or 0 if it is a toplevel item.
200  * This default implementation always returns 0.
201  * Derived classes that handle children should reimplement this.
202  **/
203  virtual YItem * parent() const { return 0; }
204 
205 
206 private:
207 
208  std::string _label;
209  std::string _iconName;
210  int _status;
211  int _index;
212  void * _data;
213 
214  /**
215  * Static children collection that is always empty so the children
216  * iterators of this base class have something valid to return.
217  **/
218  static YItemCollection _noChildren;
219 };
220 
221 
222 
223 #endif // YItem_h
YItem::label
std::string label() const
Return this item's label.
Definition: YItem.h:82
YItem::setData
void setData(void *newData)
Set the opaque data pointer for application use.
Definition: YItem.h:148
YItem::setIndex
void setIndex(int index)
Set this item's index.
Definition: YItem.h:133
YItemIterator
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
YItemCollection
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
YItem::index
int index() const
Return the index of this item (as set with setIndex() ).
Definition: YItem.h:138
YItem::childrenBegin
virtual YItemIterator childrenBegin()
Return an iterator that points to the first child item of this item.
Definition: YItem.h:186
YItem::selected
bool selected() const
Return 'true' if this item is currently selected.
Definition: YItem.h:107
YItem::iconName
std::string iconName() const
Return this item's icon name.
Definition: YItem.h:92
YItem::hasIconName
bool hasIconName() const
Return 'true' if this item has an icon name.
Definition: YItem.h:97
YItem::setIconName
void setIconName(const std::string &newIconName)
Set this item's icon name.
Definition: YItem.h:102
YItem::parent
virtual YItem * parent() const
Returns this item's parent item or 0 if it is a toplevel item.
Definition: YItem.h:203
YItem::data
void * data() const
Return the opaque data pointer.
Definition: YItem.h:153
YItem::hasChildren
virtual bool hasChildren() const
Return 'true' if this item has any child items.
Definition: YItem.h:167
YItem::YItem
YItem(const std::string &label, bool selected=false)
Constructor with just the label and optionally the selected state.
Definition: YItem.h:55
YItem::status
int status() const
Return the status of this item.
Definition: YItem.h:121
YItem::setSelected
void setSelected(bool sel=true)
Select or unselect this item.
Definition: YItem.h:114
YItem::setLabel
void setLabel(const std::string &newLabel)
Set this item's label.
Definition: YItem.h:87
YItem::childrenEnd
virtual YItemIterator childrenEnd()
Return an iterator that points after the last child item of this item.
Definition: YItem.h:195
YItem::YItem
YItem(const std::string &label, const std::string &iconName, bool selected=false)
Constructor with label and icon name and optionally the selected state.
Definition: YItem.h:65
YItem::setStatus
void setStatus(int newStatus)
Set the status of this item.
Definition: YItem.h:128
YItem::~YItem
virtual ~YItem()
Destructor.
Definition: YItem.h:76
YItemConstIterator
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
YItem
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49