libyui  3.2.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 selection widgets:
36  * - YSelectionBox
37  * - MultiselectionBox
38  * - YCombobox
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  **/
298  YItemConstIterator end );
299 
300  /**
301  * Recursively find all selected items between iterators 'begin' and 'end'
302  * and add each of them to the 'selectedItems' YItemCollection.
303  **/
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
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.
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:269
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
bool recursiveSelection() const
Return 'true' if this base class should select children recursively.
YItemIterator itemsEnd()
Return an iterator that points behind the last item.
virtual void setLabel(const std::string &newLabel)
Change this widget's label (the caption above the item list).
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
Base class for selection widgets:
YSelectionWidget(YWidget *parent, const std::string &label, bool enforceSingleSelection, bool recurisveSelection=false)
Constructor.
std::string iconFullPath(const std::string &iconName) const
Return the full path + file name for the specified icon name.
std::string iconBasePath() const
Return this widget's base path where to look up icons as set with setIconBasePath().
virtual std::string shortcutString() const
Get the string of this widget that holds the keyboard shortcut.
void setEnforceSingleSelection(bool on)
Set single selection mode on or off.
YItem * firstItem() const
Return the first item or 0 if there is none.
virtual YItemCollection selectedItems()
Return all selected 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 '...
YItemIterator itemsBegin()
Return an iterator that points to the first item.
YItem * itemAt(int index) const
Return the item at index 'index' (from 0) or 0 if there is no such item.
virtual void deleteAllItems()
Delete all items.
int itemsCount() const
Return the number of items.
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 'true' 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
bool itemsContain(YItem *item) const
Return 'true' if this widget's items contain the specified item.
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
std::string label() const
Return this widget's label (the caption above the item list).
bool enforceSingleSelection() const
Return 'true' if this base class should enforce single selection.
virtual void deselectAllItems()
Deselect all items.
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
void setIconBasePath(const std::string &basePath)
Set this widget's base path where to look up icons.
virtual ~YSelectionWidget()
Destructor.
bool hasItems() const
Return 'true' if this widget has any items.
YItem * findItem(const std::string &itemLabel) const
Find the (first) item with the specified label.
YItem * findSelectedItem(YItemConstIterator begin, YItemConstIterator end)
Recursively try to find the first selected item between iterators 'begin' and 'end'.
Abstract base class of all UI widgets.
Definition: YWidget.h:54