libyui  3.10.0
YSelectionWidget.h
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: YSelectionWidget.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YSelectionWidget_h
26 #define YSelectionWidget_h
27 
28 #include "YWidget.h"
29 #include "YItem.h"
30 #include "ImplPtr.h"
31 
33 
34 /**
35  * Base class for various kinds of multi-value widgets.
36  * - YSelectionBox, YMultiSelectionBox, YComboBox
37  * - YContextMenu, YMenuButton
38  * - YTable
39  * - YTree
40  * - YDumbTab
41  **/
42 class YSelectionWidget : public YWidget
43 {
44 protected:
45 
46  /**
47  * Constructor.
48  *
49  * 'enforceSingleSelection' indicates if this base class should enforce
50  * single selection when items are added or when items are selected from
51  * the application. Note that single selection can also mean that no item
52  * is selected.
53  **/
55  const std::string & label,
57  bool recursiveSelection = false );
58 
59 public:
60  /**
61  * Destructor.
62  **/
63  virtual ~YSelectionWidget();
64 
65  /**
66  * Returns a descriptive name of this widget class for logging,
67  * debugging etc.
68  **/
69  virtual const char * widgetClass() const { return "YSelectionWidget"; }
70 
71  /**
72  * Return this widget's label (the caption above the item list).
73  **/
74  std::string label() const;
75 
76  /**
77  * Change this widget's label (the caption above the item list).
78  *
79  * Derived classes should overwrite this function, but they should call
80  * this base class function in the new implementation.
81  **/
82  virtual void setLabel( const std::string & newLabel );
83 
84  /**
85  * Add one item. This widget assumes ownership of the item object and will
86  * delete it in its destructor.
87  *
88  * NOTE: For tree items, call this only for the toplevel items; all
89  * non-toplevel items are already owned by their respective parent
90  * items. Adding them to the parent widget will clash with this ownership.
91  *
92  * Derived classes can overwrite this function, but they should call this
93  * base class function in the new implementation.
94  **/
95  virtual void addItem( YItem * item_disown );
96 
97  /**
98  * Overloaded for convenience: Add an item by string.
99  **/
100  void addItem( const std::string & itemLabel, bool selected = false );
101 
102  /**
103  * Overloaded for convenience: Add an item with a text and an icon.
104  * Note that not all UIs can display icons.
105  **/
106  void addItem( const std::string & itemLabel,
107  const std::string & iconName,
108  bool selected = false );
109 
110  /**
111  * Add multiple items. For some UIs, this can be more efficient than
112  * calling addItem() multiple times.
113  **/
114  virtual void addItems( const YItemCollection & itemCollection );
115 
116  /**
117  * Delete all items.
118  *
119  * Derived classes can overwrite this function, but they should call this
120  * base class function in the new implementation.
121  **/
122  virtual void deleteAllItems();
123 
124  /**
125  * Delete all items and add new items.
126  **/
127  void setItems( const YItemCollection & itemCollection )
128  { deleteAllItems(); addItems( itemCollection ); }
129 
130  /**
131  * Return an iterator that points to the first item.
132  *
133  * For YSelectionWidgets that can have tree structures, this iterator will
134  * iterate over the toplevel items.
135  *
136  * Important: Don't use this iterator to iterate over all items and check
137  * their "selected" state; that information might not always be up to
138  * date. Use the dedicated functions for that.
139  **/
142 
143  /**
144  * Return an iterator that points behind the last item.
145  **/
148 
149  /**
150  * Return 'true' if this widget has any items.
151  **/
152  bool hasItems() const;
153 
154  /**
155  * Return the number of items.
156  *
157  * For YSelectionWidgets that can have tree structures, this returns the
158  * number of toplevel items.
159  **/
160  int itemsCount() const;
161 
162  /**
163  * Return the first item or 0 if there is none.
164  **/
165  YItem * firstItem() const;
166 
167  /**
168  * Return the (first) selected item or 0 if none is selected.
169  **/
170  virtual YItem * selectedItem();
171 
172  /**
173  * Return all selected items. This is mostly useful for derived classes
174  * that allow selecting multiple items.
175  *
176  * This function does not transfer ownership of those items to the caller,
177  * so don't try to delete them!
178  **/
179  virtual YItemCollection selectedItems();
180 
181  /**
182  * Return 'true' if any item is selected.
183  **/
184  bool hasSelectedItem();
185 
186  /**
187  * Select or deselect an item.
188  *
189  * Notice that this is different from YItem::setSelected() because unlike
190  * the latter function, this function informs the parent widget of the
191  * selection change.
192  *
193  * If only one item can be selected at any time (single selection), the
194  * derived class will make sure to deselect any previous selection, if
195  * applicable.
196  *
197  * Derived classes should overwrite this function, but they should call
198  * this base class function at the new function's start (this will also
199  * check if the item really belongs to this widget and throw an exception
200  * if not).
201  **/
202  virtual void selectItem( YItem * item, bool selected = true );
203 
204  /**
205  * Set the status of an item.
206  *
207  * This is similar to selectItem(), but with numeric values.
208  *
209  * This default implementation just calls selectItem() with 'status'
210  * converted to boolean. Derived classes can choose to make more detailed
211  * use of the numeric value.
212  **/
213  virtual void setItemStatus( YItem * item, int status );
214 
215  /**
216  * Deselect all items.
217  *
218  * Derived classes can overwrite this function, but they should call this
219  * base class function in the new implementation.
220  **/
221  virtual void deselectAllItems();
222 
223  /**
224  * Set this widget's base path where to look up icons.
225  * If this is a relative path, YUI::qApp()->iconBasePath() is prepended.
226  **/
227  void setIconBasePath( const std::string & basePath );
228 
229  /**
230  * Return this widget's base path where to look up icons
231  * as set with setIconBasePath().
232  **/
233  std::string iconBasePath() const;
234 
235  /**
236  * Return the full path + file name for the specified icon name.
237  * If iconBasePath is non-empty, it is prepended to the icon name.
238  * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
239  * is used find the icon in one of them
240  *
241  * If 'iconName' is empty, this will return an empty string.
242  **/
243  std::string iconFullPath( const std::string & iconName ) const;
244 
245  /**
246  * Return the full path + file name for the icon of the specified item.
247  * If iconBasePath is non-empty, it is prepended to the item's iconName.
248  * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
249  * is used find the icon in one of them
250  *
251  * If 'item' does not have an iconName specified, this will return an empty
252  * string.
253  **/
254  std::string iconFullPath( YItem * item ) const;
255 
256  /**
257  * Return 'true' if this widget's items contain the specified item.
258  **/
259  bool itemsContain( YItem * item ) const;
260 
261  /**
262  * Find the (first) item with the specified label.
263  * Return 0 if there is no item with that label.
264  **/
265  YItem * findItem( const std::string & itemLabel ) const;
266 
267  /**
268  * Get the string of this widget that holds the keyboard shortcut.
269  *
270  * Reimplemented from YWidget.
271  **/
272  virtual std::string shortcutString() const { return label(); }
273 
274  /**
275  * Set the string of this widget that holds the keyboard shortcut.
276  *
277  * Reimplemented from YWidget.
278  **/
279  virtual void setShortcutString( const std::string & str )
280  { setLabel( str ); }
281 
282  /**
283  * Dump all items and their selection state to the log.
284  **/
285  void dumpItems() const;
286 
287  /**
288  * Return 'true' if this base class should enforce single selection.
289  **/
290  bool enforceSingleSelection() const;
291 
292 protected:
293 
294  /**
295  * Set single selection mode on or off. In single selection mode, only one
296  * item can be selected at any time.
297  *
298  * If set, this base class enforces this when items are added or when items
299  * are selected from the application. Note that single selection can also
300  * mean that no item is selected.
301  **/
302  void setEnforceSingleSelection( bool on );
303 
304  /**
305  * In single selection mode, enforce selecting an initial item
306  * ('true' by default). This is ignored in multi selection mode.
307  **/
308  void setEnforceInitialSelection( bool on );
309 
310  /**
311  * Return 'true' if this class enforces an initial selection.
312  **/
313  bool enforceInitialSelection() const;
314 
315  /**
316  * Return 'true' if this base class should select children recursively.
317  **/
318  bool recursiveSelection() const;
319 
320  /**
321  * Recursively try to find the first selected item between iterators
322  * 'begin' and 'end'. Return that item or 0 if there is none.
323  **/
326 
327  /**
328  * Recursively find all selected items between iterators 'begin' and 'end'
329  * and add each of them to the 'selectedItems' YItemCollection.
330  **/
334 
335  /**
336  * Recursively deselect all items between iterators 'begin' and 'end'.
337  **/
339  YItemIterator end );
340  /**
341  * Recursively try to find an item with label 'wantedItemLabel' between
342  * iterators 'begin' and 'end'. Return that item or 0 if there is none.
343  **/
344  YItem * findItem ( const std::string & wantedItemLabel,
346  YItemConstIterator end ) const;
347 
348  /**
349  * Recursively check if 'wantedItem' is between iterators 'begin' and
350  * 'end'.
351  **/
352  bool itemsContain ( YItem * wantedItem,
354  YItemConstIterator end ) const;
355  /**
356  * Return the item at index 'index' (from 0)
357  * or 0 if there is no such item.
358  **/
359  YItem * itemAt( int index ) const;
360 
361 
362 private:
363 
365 };
366 
367 
368 #endif // YSelectionWidget_h
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:50
Base class for various kinds of multi-value widgets.
bool enforceSingleSelection() const
Return 'true' if this base class should enforce single selection.
std::string iconFullPath(const std::string &iconName) const
Return the full path + file name for the specified icon name.
YItem * findSelectedItem(YItemConstIterator begin, YItemConstIterator end)
Recursively try to find the first selected item between iterators 'begin' and 'end'.
virtual void deleteAllItems()
Delete all items.
virtual void deselectAllItems()
Deselect all items.
void setItems(const YItemCollection &itemCollection)
Delete all items and add new items.
void findSelectedItems(YItemCollection &selectedItems, YItemConstIterator begin, YItemConstIterator end)
Recursively find all selected items between iterators 'begin' and 'end' and add each of them to the '...
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
YItemIterator itemsEnd()
Return an iterator that points behind the last item.
bool recursiveSelection() const
Return 'true' if this base class should select children recursively.
std::string iconBasePath() const
Return this widget's base path where to look up icons as set with setIconBasePath().
YItem * firstItem() const
Return the first item or 0 if there is none.
YItemIterator itemsBegin()
Return an iterator that points to the first item.
YItem * findItem(const std::string &itemLabel) const
Find the (first) item with the specified label.
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
bool hasItems() const
Return 'true' if this widget has any items.
bool enforceInitialSelection() const
Return 'true' if this class enforces an initial selection.
virtual void addItem(YItem *item_disown)
Add one item.
void setEnforceSingleSelection(bool on)
Set single selection mode on or off.
YSelectionWidget(YWidget *parent, const std::string &label, bool enforceSingleSelection, bool recursiveSelection=false)
Constructor.
virtual std::string shortcutString() const
Get the string of this widget that holds the keyboard shortcut.
void dumpItems() const
Dump all items and their selection state to the log.
virtual void setItemStatus(YItem *item, int status)
Set the status of an item.
std::string label() const
Return this widget's label (the caption above the item list).
virtual ~YSelectionWidget()
Destructor.
virtual YItem * selectedItem()
Return the (first) selected item or 0 if none is selected.
virtual void setLabel(const std::string &newLabel)
Change this widget's label (the caption above the item list).
void setEnforceInitialSelection(bool on)
In single selection mode, enforce selecting an initial item ('true' by default).
virtual void selectItem(YItem *item, bool selected=true)
Select or deselect an item.
virtual YItemCollection selectedItems()
Return all selected items.
bool hasSelectedItem()
Return 'true' if any item is selected.
virtual void setShortcutString(const std::string &str)
Set the string of this widget that holds the keyboard shortcut.
int itemsCount() const
Return the number of items.
YItem * itemAt(int index) const
Return the item at index 'index' (from 0) or 0 if there is no such item.
void setIconBasePath(const std::string &basePath)
Set this widget's base path where to look up icons.
bool itemsContain(YItem *item) const
Return 'true' if this widget's items contain the specified item.
Abstract base class of all UI widgets.
Definition: YWidget.h:55
YWidgetListIterator end()
A helper for the range-based "for" loop.
Definition: YWidget.h:245
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271