libyui  3.10.0
YMenuButton.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: YMenuButton.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YMenuButton_h
26 #define YMenuButton_h
27 
28 #include "YSelectionWidget.h"
29 #include "YMenuItem.h"
30 
31 class YMenuItem;
32 class YMenuButtonPrivate;
33 
34 
35 /**
36  * MenuButton: Similar to PushButton, but with several actions: Upon clicking
37  * on a MenuButton (or activating it with the keyboard), a pop-up menu opens
38  * where the user can activate an action. Menu items in that pop-up menu can
39  * have submenus (that will pop up in separate pop-up menus).
40  *
41  * Internally, this widget is more similar to the Tree widget. The difference
42  * is that it does not keep a "selected" status, but triggers an action right
43  * away, just like a PushButton. Like PushButton, MenuButton sends an event
44  * right away when the user selects an item (clicks on a menu item or activates
45  * it with the keyboard). Items that have a submenu never send an event, they
46  * simply open their submenu when activated.
47  **/
49 {
50 protected:
51  /**
52  * Constructor.
53  *
54  * 'label' is the user-visible text on the button (not above it like all
55  * other SelectionWidgets).
56  **/
57  YMenuButton( YWidget * parent, const std::string & label );
58 
59 public:
60  /**
61  * Destructor.
62  **/
63  virtual ~YMenuButton();
64 
65  /**
66  * Returns a descriptive name of this widget class for logging,
67  * debugging etc.
68  **/
69  virtual const char * widgetClass() const { return "YMenuButton"; }
70 
71  /**
72  * Rebuild the displayed menu tree from the internally stored YMenuItems.
73  *
74  * The application should call this (once) after all items have been added
75  * with addItem(). YMenuButton::addItems() calls this automatically.
76  *
77  * Derived classes are required to implement this.
78  **/
79  virtual void rebuildMenuTree() = 0;
80 
81  /**
82  * Add multiple items. For some UIs, this can be more efficient than
83  * calling addItem() multiple times. This function also automatically calls
84  * resolveShortcutConflicts() and rebuildMenuTree() at the end.
85  *
86  * Derived classes can overwrite this function, but they should call this
87  * base class function at the end of the new implementation.
88  *
89  * Reimplemented from YSelectionWidget.
90  **/
91  virtual void addItems( const YItemCollection & itemCollection );
92 
93  /**
94  * Add one item. This widget assumes ownership of the item object and will
95  * delete it in its destructor.
96  *
97  * This reimplementation will an index to the item that is unique for all
98  * items in this MenuButton. That index can be used later with
99  * findMenuItem() to find the item by that index.
100  *
101  * @note please do not forget to call after adding all elements
102  * #resolveShortcutConflicts and #rebuildMenuTree in this order. It is
103  * important to call it after all submenus are added otherwise it won't
104  * have proper shortcuts and won't be rendered.
105  * @see examples/MenuButton.cc.
106  *
107  * Reimplemented from YSelectionWidget.
108  **/
109  virtual void addItem( YItem * item_disown );
110 
111  /**
112  * Delete all items.
113  *
114  * Reimplemented from YSelectionWidget.
115  **/
116  virtual void deleteAllItems();
117 
118  /**
119  * Resolve keyboard shortcut conflicts: Change shortcuts of menu items if
120  * there are duplicates in the respective menu level.
121  *
122  * This has to be called after all items are added, but before rebuildMenuTree()
123  * (see above). YMenuButton::addItems() calls this automatically.
124  **/
126 
127  /**
128  * Set a property.
129  * Reimplemented from YWidget.
130  *
131  * This function may throw YUIPropertyExceptions.
132  *
133  * This function returns 'true' if the value was successfully set and
134  * 'false' if that value requires special handling (not in error cases:
135  * those are covered by exceptions).
136  **/
137  virtual bool setProperty( const std::string & propertyName,
138  const YPropertyValue & val );
139 
140  /**
141  * Get a property.
142  * Reimplemented from YWidget.
143  *
144  * This method may throw YUIPropertyExceptions.
145  **/
146  virtual YPropertyValue getProperty( const std::string & propertyName );
147 
148  /**
149  * Return this class's property set.
150  * This also initializes the property upon the first call.
151  *
152  * Reimplemented from YWidget.
153  **/
154  virtual const YPropertySet & propertySet();
155 
156  /**
157  * Return item in the tree which matches path of labels or nullptr in case no
158  * item with such label was found and is a leaf, as other nodes do not trigger
159  * actions except showing children items.
160  * Accepts vector of strings which denote path to the node.
161  **/
162  YMenuItem * findItem( std::vector<std::string> & path ) const;
163 
164  /**
165  * Activate the item selected in the tree. Can be used in tests to simulate user input.
166  *
167  * Derived classes are required to implement this.
168  **/
169  virtual void activateItem( YMenuItem * item ) = 0;
170 
171  /**
172  * Recursively find the first menu item with the specified index.
173  * Returns 0 if there is no such item.
174  **/
175  YMenuItem * findMenuItem( int index );
176 
177 protected:
178 
179  /**
180  * Recursively find the first menu item with the specified index
181  * from iterator 'begin' to iterator 'end'.
182  *
183  * Returns 0 if there is no such item.
184  **/
186 
187  /**
188  * Recursively looks for the first item in the tree of the menu items
189  * using depth first search.
190  * Return nullptr if item which matches full path is not found.
191  * Path is a vector of strings, where next element is a child item, so
192  * in case one needs to select File->Export->As PDF, for instance,
193  * Vector will look like [ "File", "Export", "As PDF" ].
194  */
195  YMenuItem * findItem( std::vector<std::string>::iterator path_begin,
196  std::vector<std::string>::iterator path_end,
198  YItemConstIterator end ) const;
199 
200  /**
201  * Alias for findMenuItem(). Reimplemented to ensure consistent behaviour
202  * with YSelectionWidget::itemAt().
203  **/
204  YMenuItem * itemAt( int index )
205  { return findMenuItem( index ); }
206 
207 private:
208 
209  /**
210  * Assign a unique index to all items from iterator 'begin' to iterator 'end'.
211  **/
212  void assignUniqueIndex( YItemIterator begin, YItemIterator end );
213 
214 
216 };
217 
218 
219 #endif // YMenuButton_h
YWidget::parent
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271
YWidget
Abstract base class of all UI widgets.
Definition: YWidget.h:55
YMenuButton::resolveShortcutConflicts
void resolveShortcutConflicts()
Resolve keyboard shortcut conflicts: Change shortcuts of menu items if there are duplicates in the re...
Definition: YMenuButton.cc:209
YSelectionWidget
Base class for various kinds of multi-value widgets.
Definition: YSelectionWidget.h:43
YMenuButton::widgetClass
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YMenuButton.h:69
YWidget::end
YWidgetListIterator end()
A helper for the range-based "for" loop.
Definition: YWidget.h:245
YMenuButton::propertySet
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YMenuButton.cc:216
YItemIterator
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
YItemCollection
std::vector< YItem * > YItemCollection
Collection of pointers to YItem.
Definition: YItem.h:38
YMenuButton::findItem
YMenuItem * findItem(std::vector< std::string > &path) const
Return item in the tree which matches path of labels or nullptr in case no item with such label was f...
Definition: YMenuButton.cc:270
YMenuButton::~YMenuButton
virtual ~YMenuButton()
Destructor.
Definition: YMenuButton.cc:58
YPropertySet
A set of properties to check names and types against.
Definition: YProperty.h:198
YWidget::begin
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
YMenuButton
MenuButton: Similar to PushButton, but with several actions: Upon clicking on a MenuButton (or activa...
Definition: YMenuButton.h:49
YSelectionWidget::label
std::string label() const
Return this widget's label (the caption above the item list).
Definition: YSelectionWidget.cc:99
YMenuButton::rebuildMenuTree
virtual void rebuildMenuTree()=0
Rebuild the displayed menu tree from the internally stored YMenuItems.
YMenuButton::addItem
virtual void addItem(YItem *item_disown)
Add one item.
Definition: YMenuButton.cc:74
ImplPtr< YMenuButtonPrivate >
YMenuButton::itemAt
YMenuItem * itemAt(int index)
Alias for findMenuItem().
Definition: YMenuButton.h:204
YMenuButton::setProperty
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YMenuButton.cc:238
YMenuButton::deleteAllItems
virtual void deleteAllItems()
Delete all items.
Definition: YMenuButton.cc:100
YMenuButton::addItems
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YMenuButton.cc:65
YMenuButton::YMenuButton
YMenuButton(YWidget *parent, const std::string &label)
Constructor.
Definition: YMenuButton.cc:49
YPropertyValue
Transport class for the value of simple properties.
Definition: YProperty.h:105
YMenuItem
Item class for menu items.
Definition: YMenuItem.h:36
YMenuButton::activateItem
virtual void activateItem(YMenuItem *item)=0
Activate the item selected in the tree.
YMenuButton::getProperty
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YMenuButton.cc:255
YMenuButton::findMenuItem
YMenuItem * findMenuItem(int index)
Recursively find the first menu item with the specified index.
Definition: YMenuButton.cc:108
YMenuButtonPrivate
Definition: YMenuButton.cc:38
YItemConstIterator
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
YItem
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:50