libyui  3.3.1
YContextMenu.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: YContextMenu.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YContextMenu_h
26 #define YContextMenu_h
27 
28 #include "YSelectionWidget.h"
29 #include "YMenuItem.h"
30 
31 class YMenuItem;
33 
34 
35 /**
36  * ContextMenu: Similar to PushButton, but with several actions: Upon clicking
37  * on a ContextMenu (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, ContextMenu 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  *
48  * Note: unlike other widgets, this one is not created via YWidgetFactory
49  * or YOptionalWidgetFactory but with YApplication::openContextMenu()
50  **/
52 {
53 protected:
54  /**
55  * Constructor.
56  *
57  * 'label' is the user-visible text on the button (not above it like all
58  * other SelectionWidgets).
59  **/
60  YContextMenu();
61 
62 public:
63  /**
64  * Destructor.
65  **/
66  virtual ~YContextMenu();
67 
68  /**
69  * Returns a descriptive name of this widget class for logging,
70  * debugging etc.
71  **/
72  virtual const char * widgetClass() const { return "YContextMenu"; }
73 
74  /**
75  * Rebuild the displayed menu tree from the internally stored YMenuItems.
76  *
77  * The application should call this (once) after all items have been added
78  * with addItem(). YContextMenu::addItems() calls this automatically.
79  *
80  * Derived classes are required to implement this.
81  **/
82  virtual void rebuildMenuTree() = 0;
83 
84  /**
85  * Add multiple items. For some UIs, this can be more efficient than
86  * calling addItem() multiple times. This function also automatically calls
87  * resolveShortcutConflicts() and rebuildMenuTree() at the end.
88  *
89  * Derived classes can overwrite this function, but they should call this
90  * base class function at the end of the new implementation.
91  *
92  * Reimplemented from YSelectionWidget.
93  **/
94  virtual void addItems( const YItemCollection & itemCollection );
95 
96  /**
97  * Add one item. This widget assumes ownership of the item object and will
98  * delete it in its destructor.
99  *
100  * This reimplementation will an index to the item that is unique for all
101  * items in this ContextMenu. That index can be used later with
102  * findMenuItem() to find the item by that index.
103  *
104  * Reimplemented from YSelectionWidget.
105  **/
106  virtual void addItem( YItem * item_disown );
107 
108  /**
109  * Delete all items.
110  *
111  * Reimplemented from YSelectionWidget.
112  **/
113  virtual void deleteAllItems();
114 
115  /**
116  * Resolve keyboard shortcut conflicts: Change shortcuts of menu items if
117  * there are duplicates in the respective menu level.
118  *
119  * This has to be called after all items are added, but before rebuildMenuTree()
120  * (see above). YContextMenu::addItems() calls this automatically.
121  **/
123 
124  /**
125  * Set a property.
126  * Reimplemented from YWidget.
127  *
128  * This function may throw YUIPropertyExceptions.
129  *
130  * This function returns 'true' if the value was successfully set and
131  * 'false' if that value requires special handling (not in error cases:
132  * those are covered by exceptions).
133  **/
134  virtual bool setProperty( const std::string & propertyName,
135  const YPropertyValue & val );
136 
137  /**
138  * Get a property.
139  * Reimplemented from YWidget.
140  *
141  * This method may throw YUIPropertyExceptions.
142  **/
143  virtual YPropertyValue getProperty( const std::string & propertyName );
144 
145  /**
146  * Return this class's property set.
147  * This also initializes the property upon the first call.
148  *
149  * Reimplemented from YWidget.
150  **/
151  virtual const YPropertySet & propertySet();
152 
153 protected:
154 
155  /**
156  * Recursively find the first menu item with the specified index.
157  * Returns 0 if there is no such item.
158  **/
159  YMenuItem * findMenuItem( int index );
160 
161  /**
162  * Recursively find the first menu item with the specified index
163  * from iterator 'begin' to iterator 'end'.
164  *
165  * Returns 0 if there is no such item.
166  **/
168 
169  /**
170  * Alias for findMenuItem(). Reimplemented to ensure consistent behaviour
171  * with YSelectionWidget::itemAt().
172  **/
173  YMenuItem * itemAt( int index )
174  { return findMenuItem( index ); }
175 
176 private:
177 
178  /**
179  * Assign a unique index to all items from iterator 'begin' to iterator 'end'.
180  **/
181  void assignUniqueIndex( YItemIterator begin, YItemIterator end );
182 
183 
185 };
186 
187 
188 #endif // YContextMenu_h
YItemCollection::iterator YItemIterator
Mutable iterator over YItemCollection.
Definition: YItem.h:40
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.
A set of properties to check names and types against.
Definition: YProperty.h:197
virtual void addItems(const YItemCollection &itemCollection)
Add multiple items.
Definition: YContextMenu.cc:62
void resolveShortcutConflicts()
Resolve keyboard shortcut conflicts: Change shortcuts of menu items if there are duplicates in the re...
virtual ~YContextMenu()
Destructor.
Definition: YContextMenu.cc:55
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
YMenuItem * itemAt(int index)
Alias for findMenuItem().
Definition: YContextMenu.h:173
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YContextMenu.h:72
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
YMenuItem * findMenuItem(int index)
Recursively find the first menu item with the specified index.
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 void deleteAllItems()
Delete all items.
Definition: YContextMenu.cc:97
YWidgetListIterator begin()
A helper for the range-based "for" loop.
Definition: YWidget.h:238
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
virtual void rebuildMenuTree()=0
Rebuild the displayed menu tree from the internally stored YMenuItems.
ContextMenu: Similar to PushButton, but with several actions: Upon clicking on a ContextMenu (or acti...
Definition: YContextMenu.h:51
virtual void addItem(YItem *item_disown)
Add one item.
Definition: YContextMenu.cc:71
YContextMenu()
Constructor.
Definition: YContextMenu.cc:46