libyui  3.3.2
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 protected:
157 
158  /**
159  * Recursively find the first menu item with the specified index.
160  * Returns 0 if there is no such item.
161  **/
162  YMenuItem * findMenuItem( int index );
163 
164  /**
165  * Recursively find the first menu item with the specified index
166  * from iterator 'begin' to iterator 'end'.
167  *
168  * Returns 0 if there is no such item.
169  **/
171 
172  /**
173  * Alias for findMenuItem(). Reimplemented to ensure consistent behaviour
174  * with YSelectionWidget::itemAt().
175  **/
176  YMenuItem * itemAt( int index )
177  { return findMenuItem( index ); }
178 
179 private:
180 
181  /**
182  * Assign a unique index to all items from iterator 'begin' to iterator 'end'.
183  **/
184  void assignUniqueIndex( YItemIterator begin, YItemIterator end );
185 
186 
188 };
189 
190 
191 #endif // YMenuButton_h
YMenuItem * findMenuItem(int index)
Recursively find the first menu item with the specified index.
Definition: YMenuButton.cc:106
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).
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YMenuButton.h:69
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
Definition: YMenuButton.cc:214
Transport class for the value of simple properties.
Definition: YProperty.h:104
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.
virtual ~YMenuButton()
Destructor.
Definition: YMenuButton.cc:56
A set of properties to check names and types against.
Definition: YProperty.h:197
MenuButton: Similar to PushButton, but with several actions: Upon clicking on a MenuButton (or activa...
Definition: YMenuButton.h:48
virtual void addItem(YItem *item_disown)
Add one item.
Definition: YMenuButton.cc:72
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
virtual void rebuildMenuTree()=0
Rebuild the displayed menu tree from the internally stored YMenuItems.
virtual void deleteAllItems()
Delete all items.
Definition: YMenuButton.cc:98
YMenuItem * itemAt(int index)
Alias for findMenuItem().
Definition: YMenuButton.h:176
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YMenuButton.cc:63
YMenuButton(YWidget *parent, const std::string &label)
Constructor.
Definition: YMenuButton.cc:47
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YMenuButton.cc:253
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49
YItemCollection::const_iterator YItemConstIterator
Const iterator over YItemCollection.
Definition: YItem.h:42
Item class for menu items.
Definition: YMenuItem.h:35
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YMenuButton.cc:236
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
void resolveShortcutConflicts()
Resolve keyboard shortcut conflicts: Change shortcuts of menu items if there are duplicates in the re...
Definition: YMenuButton.cc:207
Abstract base class of all UI widgets.
Definition: YWidget.h:54