libyui  3.3.2
YTree.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: YTree.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YTree_h
26 #define YTree_h
27 
28 #include "YSelectionWidget.h"
29 
30 class YTreeItem;
31 class YTreePrivate;
32 
33 
34 /**
35  * Tree: List box that displays a (scrollable) list of hierarchical items from
36  * which the user can select exactly one. Each item has a label text and an
37  * optional icon (*).
38  *
39  * This is very similar to SelectionBox, but each item can have subitems that
40  * can be open (expanded) or closed (collapsed).
41  *
42  * The tree widget also has a caption label that is displayed above the
43  * tree. The hotkey displayed in that caption label will move the keyboard
44  * focus into the tree item list.
45  *
46  *
47  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
48  * so an icon should never be an exclusive means to display any kind of
49  * information.
50 
51  * 'multiSelection' indicates whether or not the user can select multiple
52  * items at the same time. This can only be set in the constructor.
53  **/
54 
55 
56 class YTree : public YSelectionWidget
57 {
58 protected:
59  /**
60  * Constructor.
61  **/
62  YTree( YWidget * parent, const std::string & label, bool multiSelection, bool recursiveSelection);
63 
64 public:
65  /**
66  * Destructor.
67  **/
68  virtual ~YTree();
69 
70  /**
71  * Returns a descriptive name of this widget class for logging,
72  * debugging etc.
73  **/
74  virtual const char * widgetClass() const { return "YTree"; }
75 
76  /**
77  * Rebuild the displayed tree from the internally stored YTreeItems.
78  *
79  * The application should call this (once) after all items have been added
80  * with addItem(). YTree::addItems() calls this automatically.
81  *
82  * Derived classes are required to implement this.
83  **/
84  virtual void rebuildTree() = 0;
85 
86  /**
87  * Add multiple items. For some UIs, this can be more efficient than
88  * calling addItem() multiple times. This function also automatically calls
89  * rebuildTree() at the end.
90  *
91  * Derived classes can overwrite this function, but they should call this
92  * base class function at the end of the new implementation.
93  *
94  * Reimplemented from YSelectionWidget.
95  **/
96  virtual void addItems( const YItemCollection & itemCollection );
97 
98  /**
99  * Deliver even more events than with notify() set.
100  *
101  * For YTree, this is relevant mostly for the NCurses UI:
102  *
103  * In graphical UIs like the Qt UI, the user can use the mouse to select an
104  * item in a tree. With notify() set, this will send an event right away
105  * (i.e., it will make UserInput and related return, while normally it
106  * would only return when the user clicks a PushButton).
107  *
108  * In the NCurses UI, there is no mouse, so the user has to use the cursor
109  * keys to move to the item he wants to select. In immediateMode(), every
110  * cursor key press will make the tree send an event. Without
111  * immediateMode(), the NCTree will wait until the user hits the [Return]
112  * key until an event is sent. Depending on what the application does upon
113  * each selection box event, immediateMode() might make the application
114  * less responsive.
115  **/
116  bool immediateMode() const;
117 
118  /**
119  * Set immediateMode() on or off.
120  **/
121  void setImmediateMode( bool on = true );
122 
123  /**
124  * Set a property.
125  * Reimplemented from YWidget.
126  *
127  * This function may throw YUIPropertyExceptions.
128  *
129  * This function returns 'true' if the value was successfully set and
130  * 'false' if that value requires special handling (not in error cases:
131  * those are covered by exceptions).
132  **/
133  virtual bool setProperty( const std::string & propertyName,
134  const YPropertyValue & val );
135 
136  /**
137  * Get a property.
138  * Reimplemented from YWidget.
139  *
140  * This method may throw YUIPropertyExceptions.
141  **/
142  virtual YPropertyValue getProperty( const std::string & propertyName );
143 
144  /**
145  * Return this class's property set.
146  * This also initializes the property upon the first call.
147  *
148  * Reimplemented from YWidget.
149  **/
150  virtual const YPropertySet & propertySet();
151 
152  /**
153  * The name of the widget property that will return user input.
154  * Inherited from YWidget.
155  **/
156  const char * userInputProperty() { return YUIProperty_CurrentItem; }
157 
158 
159  /**
160  * Return 'true' if the user can select multiple items at the same time
161  **/
162  bool hasMultiSelection() const;
163 
164  /**
165  * Return the the item that currently has the keyboard focus
166  * or 0 if no item currently has the keyboard focus.
167  *
168  * Notice that for a MultiSelectionBox the current item is not necessarily
169  * selected, i.e., its check box may or may not be checked.
170  *
171  * Derived classes are required to implement this function.
172  **/
173  virtual YTreeItem * currentItem() = 0;
174 
175 
176 private:
177 
179 };
180 
181 
182 #endif // YTree_h
std::string label() const
Return this widget&#39;s label (the caption above the item list).
bool immediateMode() const
Deliver even more events than with notify() set.
Definition: YTree.cc:64
Transport class for the value of simple properties.
Definition: YProperty.h:104
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
void setImmediateMode(bool on=true)
Set immediateMode() on or off.
Definition: YTree.cc:71
Base class for various kinds of multi-value widgets.
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YTree.cc:146
A set of properties to check names and types against.
Definition: YProperty.h:197
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
YTree(YWidget *parent, const std::string &label, bool multiSelection, bool recursiveSelection)
Constructor.
Definition: YTree.cc:44
virtual YTreeItem * currentItem()=0
Return the the item that currently has the keyboard focus or 0 if no item currently has the keyboard ...
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YTree.h:74
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YTree.cc:81
virtual ~YTree()
Destructor.
Definition: YTree.cc:57
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YTree.cc:123
Tree: List box that displays a (scrollable) list of hierarchical items from which the user can select...
Definition: YTree.h:56
virtual void rebuildTree()=0
Rebuild the displayed tree from the internally stored YTreeItems.
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
Definition: YTree.cc:89
bool hasMultiSelection() const
Return &#39;true&#39; if the user can select multiple items at the same time.
Definition: YTree.cc:165
bool recursiveSelection() const
Return &#39;true&#39; if this base class should select children recursively.
Abstract base class of all UI widgets.
Definition: YWidget.h:54
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YTree.h:156
Item class for tree items.
Definition: YTreeItem.h:37