libyui  3.10.0
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  /**
65  * Recursively looks for the first item in the tree of the menu items
66  * using depth first search.
67  * Return nullptr if item which matches full path is not found.
68  */
69  YTreeItem * findItem( std::vector<std::string>::iterator path_begin,
70  std::vector<std::string>::iterator path_end,
72  YItemConstIterator end ) const;
73 public:
74  /**
75  * Destructor.
76  **/
77  virtual ~YTree();
78 
79  /**
80  * Returns a descriptive name of this widget class for logging,
81  * debugging etc.
82  **/
83  virtual const char * widgetClass() const { return "YTree"; }
84 
85  /**
86  * Rebuild the displayed tree from the internally stored YTreeItems.
87  *
88  * The application should call this (once) after all items have been added
89  * with addItem(). YTree::addItems() calls this automatically.
90  *
91  * Derived classes are required to implement this.
92  **/
93  virtual void rebuildTree() = 0;
94 
95  /**
96  * Add multiple items. For some UIs, this can be more efficient than
97  * calling addItem() multiple times. This function also automatically calls
98  * rebuildTree() at the end.
99  *
100  * Derived classes can overwrite this function, but they should call this
101  * base class function at the end of the new implementation.
102  *
103  * Reimplemented from YSelectionWidget.
104  **/
105  virtual void addItems( const YItemCollection & itemCollection );
106 
107  /**
108  * Deliver even more events than with notify() set.
109  *
110  * For YTree, this is relevant mostly for the NCurses UI:
111  *
112  * In graphical UIs like the Qt UI, the user can use the mouse to select an
113  * item in a tree. With notify() set, this will send an event right away
114  * (i.e., it will make UserInput and related return, while normally it
115  * would only return when the user clicks a PushButton).
116  *
117  * In the NCurses UI, there is no mouse, so the user has to use the cursor
118  * keys to move to the item he wants to select. In immediateMode(), every
119  * cursor key press will make the tree send an event. Without
120  * immediateMode(), the NCTree will wait until the user hits the [Return]
121  * key until an event is sent. Depending on what the application does upon
122  * each selection box event, immediateMode() might make the application
123  * less responsive.
124  **/
125  bool immediateMode() const;
126 
127  /**
128  * Set immediateMode() on or off.
129  **/
130  void setImmediateMode( bool on = true );
131 
132  /**
133  * Set a property.
134  * Reimplemented from YWidget.
135  *
136  * This function may throw YUIPropertyExceptions.
137  *
138  * This function returns 'true' if the value was successfully set and
139  * 'false' if that value requires special handling (not in error cases:
140  * those are covered by exceptions).
141  **/
142  virtual bool setProperty( const std::string & propertyName,
143  const YPropertyValue & val );
144 
145  /**
146  * Get a property.
147  * Reimplemented from YWidget.
148  *
149  * This method may throw YUIPropertyExceptions.
150  **/
151  virtual YPropertyValue getProperty( const std::string & propertyName );
152 
153  /**
154  * Return this class's property set.
155  * This also initializes the property upon the first call.
156  *
157  * Reimplemented from YWidget.
158  **/
159  virtual const YPropertySet & propertySet();
160 
161  /**
162  * The name of the widget property that will return user input.
163  * Inherited from YWidget.
164  **/
165  const char * userInputProperty() { return YUIProperty_CurrentItem; }
166 
167 
168  /**
169  * Return 'true' if the user can select multiple items at the same time
170  **/
171  bool hasMultiSelection() const;
172 
173  /**
174  * Return the the item that currently has the keyboard focus
175  * or 0 if no item currently has the keyboard focus.
176  *
177  * Notice that for a MultiSelectionBox the current item is not necessarily
178  * selected, i.e., its check box may or may not be checked.
179  *
180  * Derived classes are required to implement this function.
181  **/
182  virtual YTreeItem * currentItem() = 0;
183 
184  /**
185  * Return item in the tree which matches path of labels or nullptr in case no
186  * item with such label was found.
187  * Accepts vector of strings which denote path to the node.
188  **/
189  YTreeItem * findItem( std::vector<std::string> & path ) const;
190 
191  /**
192  * Activate the item selected in the tree. Can be used in tests to simulate user input.
193  *
194  * Derived classes are required to implement this.
195  **/
196  virtual void activate() = 0;
197 
198 
199 private:
200 
202 };
203 
204 
205 #endif // YTree_h
YWidget::parent
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271
YTree::userInputProperty
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YTree.h:165
YTreeItem
Item class for tree items.
Definition: YTreeItem.h:35
YWidget
Abstract base class of all UI widgets.
Definition: YWidget.h:54
YSelectionWidget
Base class for various kinds of multi-value widgets.
Definition: YSelectionWidget.h:42
YTree::setImmediateMode
void setImmediateMode(bool on=true)
Set immediateMode() on or off.
Definition: YTree.cc:74
YWidget::end
YWidgetListIterator end()
A helper for the range-based "for" loop.
Definition: YWidget.h:245
YItemCollection
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
YTree::immediateMode
bool immediateMode() const
Deliver even more events than with notify() set.
Definition: YTree.cc:67
YTree
Tree: List box that displays a (scrollable) list of hierarchical items from which the user can select...
Definition: YTree.h:56
YPropertySet
A set of properties to check names and types against.
Definition: YProperty.h:197
YTree::YTree
YTree(YWidget *parent, const std::string &label, bool multiSelection, bool recursiveSelection)
Constructor.
Definition: YTree.cc:47
YTree::getProperty
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YTree.cc:149
YWidget::begin
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
YSelectionWidget::label
std::string label() const
Return this widget's label (the caption above the item list).
Definition: YSelectionWidget.cc:99
YTree::currentItem
virtual YTreeItem * currentItem()=0
Return the the item that currently has the keyboard focus or 0 if no item currently has the keyboard ...
YTree::findItem
YTreeItem * findItem(std::vector< std::string >::iterator path_begin, std::vector< std::string >::iterator path_end, YItemConstIterator begin, YItemConstIterator end) const
Recursively looks for the first item in the tree of the menu items using depth first search.
Definition: YTree.cc:182
ImplPtr< YTreePrivate >
YSelectionWidget::recursiveSelection
bool recursiveSelection() const
Return 'true' if this base class should select children recursively.
Definition: YSelectionWidget.cc:130
YTreePrivate
Definition: YTree.cc:37
YTree::activate
virtual void activate()=0
Activate the item selected in the tree.
YTree::widgetClass
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YTree.h:83
YTree::~YTree
virtual ~YTree()
Destructor.
Definition: YTree.cc:60
YTree::addItems
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YTree.cc:84
YTree::hasMultiSelection
bool hasMultiSelection() const
Return 'true' if the user can select multiple items at the same time.
Definition: YTree.cc:168
YTree::rebuildTree
virtual void rebuildTree()=0
Rebuild the displayed tree from the internally stored YTreeItems.
YPropertyValue
Transport class for the value of simple properties.
Definition: YProperty.h:104
YTree::setProperty
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YTree.cc:126
YTree::propertySet
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YTree.cc:92
YItemConstIterator
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42