libyui  3.3.1
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  * 'singleSelectionMode' indicates if this base class should enforce single
50  * selection when items are added or when items are selected from the
51  * application. Note that single selection can also mean that no item is
52  * selected.
53  **/
55  const std::string & label,
57  bool recurisveSelection = 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  * Deselect all items.
206  *
207  * Derived classes can overwrite this function, but they should call this
208  * base class function in the new implementation.
209  **/
210  virtual void deselectAllItems();
211 
212  /**
213  * Set this widget's base path where to look up icons.
214  * If this is a relative path, YUI::qApp()->iconBasePath() is prepended.
215  **/
216  void setIconBasePath( const std::string & basePath );
217 
218  /**
219  * Return this widget's base path where to look up icons
220  * as set with setIconBasePath().
221  **/
222  std::string iconBasePath() const;
223 
224  /**
225  * Return the full path + file name for the specified icon name.
226  * If iconBasePath is non-empty, it is prepended to the icon name.
227  * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
228  * is used find the icon in one of them
229  *
230  * If 'iconName' is empty, this will return an empty string.
231  **/
232  std::string iconFullPath( const std::string & iconName ) const;
233 
234  /**
235  * Return the full path + file name for the icon of the specified item.
236  * If iconBasePath is non-empty, it is prepended to the item's iconName.
237  * Otherwise, YUI::yApp()->iconLoader() and its icon search paths
238  * is used find the icon in one of them
239  *
240  * If 'item' does not have an iconName specified, this will return an empty
241  * string.
242  **/
243  std::string iconFullPath( YItem * item ) const;
244 
245  /**
246  * Return 'true' if this widget's items contain the specified item.
247  **/
248  bool itemsContain( YItem * item ) const;
249 
250  /**
251  * Find the (first) item with the specified label.
252  * Return 0 if there is no item with that label.
253  **/
254  YItem * findItem( const std::string & itemLabel ) const;
255 
256  /**
257  * Get the string of this widget that holds the keyboard shortcut.
258  *
259  * Reimplemented from YWidget.
260  **/
261  virtual std::string shortcutString() const { return label(); }
262 
263  /**
264  * Set the string of this widget that holds the keyboard shortcut.
265  *
266  * Reimplemented from YWidget.
267  **/
268  virtual void setShortcutString( const std::string & str )
269  { setLabel( str ); }
270 
271 protected:
272 
273  /**
274  * Set single selection mode on or off. In single selection mode, only one
275  * item can be selected at any time.
276  *
277  * If set, this base class enforces this when items are added or when items
278  * are selected from the application. Note that single selection can also
279  * mean that no item is selected.
280  **/
281  void setEnforceSingleSelection( bool on );
282 
283  /**
284  * Return 'true' if this base class should enforce single selection.
285  **/
286  bool enforceSingleSelection() const;
287 
288  /**
289  * Return 'true' if this base class should select children recursively.
290  **/
291  bool recursiveSelection() const;
292 
293  /**
294  * Recursively try to find the first selected item between iterators
295  * 'begin' and 'end'. Return that item or 0 if there is none.
296  **/
299 
300  /**
301  * Recursively find all selected items between iterators 'begin' and 'end'
302  * and add each of them to the 'selectedItems' YItemCollection.
303  **/
304  void findSelectedItems( YItemCollection & selectedItems,
305  YItemConstIterator begin,
306  YItemConstIterator end );
307 
308  /**
309  * Recursively deselect all items between iterators 'begin' and 'end'.
310  **/
311  void deselectAllItems( YItemIterator begin,
312  YItemIterator end );
313  /**
314  * Recursively try to find an item with label 'wantedItemLabel' between
315  * iterators 'begin' and 'end'. Return that item or 0 if there is none.
316  **/
317  YItem * findItem ( const std::string & wantedItemLabel,
318  YItemConstIterator begin,
319  YItemConstIterator end ) const;
320 
321  /**
322  * Recursively check if 'wantedItem' is between iterators 'begin' and
323  * 'end'.
324  **/
325  bool itemsContain ( YItem * wantedItem,
326  YItemConstIterator begin,
327  YItemConstIterator end ) const;
328  /**
329  * Return the item at index 'index' (from 0)
330  * or 0 if there is no such item.
331  **/
332  YItem * itemAt( int index ) const;
333 
334 
335 private:
336 
338 };
339 
340 
341 #endif // YSelectionWidget_h
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
std::string label() const
Return this widget&#39;s label (the caption above the item list).
void setItems(const YItemCollection &itemCollection)
Delete all items and add new items.
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.
YSelectionWidget(YWidget *parent, const std::string &label, bool enforceSingleSelection, bool recurisveSelection=false)
Constructor.
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:269
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.
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
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
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
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 iconBasePath() const
Return this widget&#39;s base path where to look up icons as set with setIconBasePath().
std::string iconFullPath(const std::string &iconName) const
Return the full path + file name for the specified icon name.