libyui  3.2.1
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  * Reimplemented from YSelectionWidget.
102  **/
103  virtual void addItem( YItem * item_disown );
104 
105  /**
106  * Delete all items.
107  *
108  * Reimplemented from YSelectionWidget.
109  **/
110  virtual void deleteAllItems();
111 
112  /**
113  * Resolve keyboard shortcut conflicts: Change shortcuts of menu items if
114  * there are duplicates in the respective menu level.
115  *
116  * This has to be called after all items are added, but before rebuildMenuTree()
117  * (see above). YMenuButton::addItems() calls this automatically.
118  **/
120 
121  /**
122  * Set a property.
123  * Reimplemented from YWidget.
124  *
125  * This function may throw YUIPropertyExceptions.
126  *
127  * This function returns 'true' if the value was successfully set and
128  * 'false' if that value requires special handling (not in error cases:
129  * those are covered by exceptions).
130  **/
131  virtual bool setProperty( const std::string & propertyName,
132  const YPropertyValue & val );
133 
134  /**
135  * Get a property.
136  * Reimplemented from YWidget.
137  *
138  * This method may throw YUIPropertyExceptions.
139  **/
140  virtual YPropertyValue getProperty( const std::string & propertyName );
141 
142  /**
143  * Return this class's property set.
144  * This also initializes the property upon the first call.
145  *
146  * Reimplemented from YWidget.
147  **/
148  virtual const YPropertySet & propertySet();
149 
150 protected:
151 
152  /**
153  * Recursively find the first menu item with the specified index.
154  * Returns 0 if there is no such item.
155  **/
156  YMenuItem * findMenuItem( int index );
157 
158  /**
159  * Recursively find the first menu item with the specified index
160  * from iterator 'begin' to iterator 'end'.
161  *
162  * Returns 0 if there is no such item.
163  **/
164  YMenuItem * findMenuItem( int index, YItemConstIterator begin, YItemConstIterator end );
165 
166  /**
167  * Alias for findMenuItem(). Reimplemented to ensure consistent behaviour
168  * with YSelectionWidget::itemAt().
169  **/
170  YMenuItem * itemAt( int index )
171  { return findMenuItem( index ); }
172 
173 private:
174 
175  /**
176  * Assign a unique index to all items from iterator 'begin' to iterator 'end'.
177  **/
178  void assignUniqueIndex( YItemIterator begin, YItemIterator end );
179 
180 
182 };
183 
184 
185 #endif // YMenuButton_h
YMenuItem * findMenuItem(int index)
Recursively find the first menu item with the specified index.
Definition: YMenuButton.cc:105
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:269
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YMenuButton.cc:153
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YMenuButton.h:69
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
Base class for selection widgets:
virtual ~YMenuButton()
Destructor.
Definition: YMenuButton.cc:55
A set of properties to check names and types against.
Definition: YProperty.h:184
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:71
virtual void rebuildMenuTree()=0
Rebuild the displayed menu tree from the internally stored YMenuItems.
virtual void deleteAllItems()
Delete all items.
Definition: YMenuButton.cc:97
YMenuItem * itemAt(int index)
Alias for findMenuItem().
Definition: YMenuButton.h:170
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YMenuButton.cc:62
YMenuButton(YWidget *parent, const std::string &label)
Constructor.
Definition: YMenuButton.cc:46
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YMenuButton.cc:192
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
std::string label() const
Return this widget's label (the caption above the item list).
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YMenuButton.cc:175
void resolveShortcutConflicts()
Resolve keyboard shortcut conflicts: Change shortcuts of menu items if there are duplicates in the re...
Definition: YMenuButton.cc:138
Abstract base class of all UI widgets.
Definition: YWidget.h:54