libyui  3.9.3
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::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
void setItems(const YItemCollection &itemCollection)
Delete all items and add new items.
bool enforceInitialSelection() const
Return &#39;true&#39; if this class enforces an initial selection.
virtual void selectItem(YItem *item, bool selected=true)
Select or deselect an item.
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
YItemIterator itemsEnd()
Return an iterator that points behind the last item.
virtual void setLabel(const std::string &newLabel)
Change this widget&#39;s label (the caption above the item list).
YItem * firstItem() const
Return the first item or 0 if there is none.
YWidgetListIterator end()
A helper for the range-based "for" loop.
Definition: YWidget.h:245
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
Base class for various kinds of multi-value widgets.
void setEnforceSingleSelection(bool on)
Set single selection mode on or off.
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:271
YSelectionWidget(YWidget *parent, const std::string &label, bool enforceSingleSelection, bool recursiveSelection=false)
Constructor.
virtual YItemCollection selectedItems()
Return all selected items.
void findSelectedItems(YItemCollection &selectedItems, YItemConstIterator begin, YItemConstIterator end)
Recursively find all selected items between iterators &#39;begin&#39; and &#39;end&#39; and add each of them to the &#39;...
YItemIterator itemsBegin()
Return an iterator that points to the first item.
virtual void deleteAllItems()
Delete all items.
virtual std::string shortcutString() const
Get the string of this widget that holds the keyboard shortcut.
int itemsCount() const
Return the number of items.
bool itemsContain(YItem *item) const
Return &#39;true&#39; if this widget&#39;s items contain the specified item.
virtual YItem * selectedItem()
Return the (first) selected item or 0 if none is selected.
std::string label() const
Return this widget&#39;s label (the caption above the item list).
virtual void setItemStatus(YItem *item, int status)
Set the status of an item.
virtual void setShortcutString(const std::string &str)
Set the string of this widget that holds the keyboard shortcut.
bool hasSelectedItem()
Return &#39;true&#39; if any item is selected.
virtual void addItem(YItem *item_disown)
Add one item.
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49
std::string iconBasePath() const
Return this widget&#39;s base path where to look up icons as set with setIconBasePath().
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
virtual void deselectAllItems()
Deselect all items.
void setIconBasePath(const std::string &basePath)
Set this widget&#39;s base path where to look up icons.
virtual ~YSelectionWidget()
Destructor.
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
void setEnforceInitialSelection(bool on)
In single selection mode, enforce selecting an initial item (&#39;true&#39; by default).
bool recursiveSelection() const
Return &#39;true&#39; if this base class should select children recursively.
YItem * findSelectedItem(YItemConstIterator begin, YItemConstIterator end)
Recursively try to find the first selected item between iterators &#39;begin&#39; and &#39;end&#39;.
YItem * itemAt(int index) const
Return the item at index &#39;index&#39; (from 0) or 0 if there is no such item.
Abstract base class of all UI widgets.
Definition: YWidget.h:54
void dumpItems() const
Dump all items and their selection state to the log.
bool hasItems() const
Return &#39;true&#39; if this widget has any items.
bool enforceSingleSelection() const
Return &#39;true&#39; if this base class should enforce single selection.
YItem * findItem(const std::string &itemLabel) const
Find the (first) item with the specified label.
std::string iconFullPath(const std::string &iconName) const
Return the full path + file name for the specified icon name.