libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YMenuButton.h
00001 /*
00002   Copyright (C) 2000-2012 Novell, Inc
00003   This library is free software; you can redistribute it and/or modify
00004   it under the terms of the GNU Lesser General Public License as
00005   published by the Free Software Foundation; either version 2.1 of the
00006   License, or (at your option) version 3.0 of the License. This library
00007   is distributed in the hope that it will be useful, but WITHOUT ANY
00008   WARRANTY; without even the implied warranty of MERCHANTABILITY or 
00009   FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public
00010   License for more details. You should have received a copy of the GNU
00011   Lesser General Public License along with this library; if not, write
00012   to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
00013   Floor, Boston, MA 02110-1301 USA
00014 */
00015 
00016 
00017 /*-/
00018 
00019   File:         YMenuButton.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YMenuButton_h
00026 #define YMenuButton_h
00027 
00028 #include "YSelectionWidget.h"
00029 #include "YMenuItem.h"
00030 
00031 class YMenuItem;
00032 class YMenuButtonPrivate;
00033 
00034 
00035 /**
00036  * MenuButton: Similar to PushButton, but with several actions: Upon clicking
00037  * on a MenuButton (or activating it with the keyboard), a pop-up menu opens
00038  * where the user can activate an action. Menu items in that pop-up menu can
00039  * have submenus (that will pop up in separate pop-up menus).
00040  *
00041  * Internally, this widget is more similar to the Tree widget. The difference
00042  * is that it does not keep a "selected" status, but triggers an action right
00043  * away, just like a PushButton. Like PushButton, MenuButton sends an event
00044  * right away when the user selects an item (clicks on a menu item or activates
00045  * it with the keyboard). Items that have a submenu never send an event, they
00046  * simply open their submenu when activated.
00047  **/
00048 class YMenuButton : public YSelectionWidget
00049 {
00050 protected:
00051     /**
00052      * Constructor.
00053      *
00054      * 'label' is the user-visible text on the button (not above it like all
00055      * other SelectionWidgets).
00056      **/
00057     YMenuButton( YWidget * parent, const std::string & label );
00058 
00059 public:
00060     /**
00061      * Destructor.
00062      **/
00063     virtual ~YMenuButton();
00064 
00065     /**
00066      * Returns a descriptive name of this widget class for logging,
00067      * debugging etc.
00068      **/
00069     virtual const char * widgetClass() const { return "YMenuButton"; }
00070 
00071     /**
00072      * Rebuild the displayed menu tree from the internally stored YMenuItems.
00073      *
00074      * The application should call this (once) after all items have been added
00075      * with addItem(). YMenuButton::addItems() calls this automatically.
00076      *
00077      * Derived classes are required to implement this.
00078      **/
00079     virtual void rebuildMenuTree() = 0;
00080 
00081     /**
00082      * Add multiple items. For some UIs, this can be more efficient than
00083      * calling addItem() multiple times. This function also automatically calls
00084      * resolveShortcutConflicts() and rebuildMenuTree() at the end.
00085      *
00086      * Derived classes can overwrite this function, but they should call this
00087      * base class function at the end of the new implementation.
00088      *
00089      * Reimplemented from YSelectionWidget.
00090      **/
00091     virtual void addItems( const YItemCollection & itemCollection );
00092 
00093     /**
00094      * Add one item. This widget assumes ownership of the item object and will
00095      * delete it in its destructor.
00096      *
00097      * This reimplementation will an index to the item that is unique for all
00098      * items in this MenuButton. That index can be used later with
00099      * findMenuItem() to find the item by that index.
00100      *
00101      * Reimplemented from YSelectionWidget.
00102      **/
00103     virtual void addItem( YItem * item_disown );
00104 
00105     /**
00106      * Delete all items.
00107      *
00108      * Reimplemented from YSelectionWidget.
00109      **/
00110     virtual void deleteAllItems();
00111 
00112     /**
00113      * Resolve keyboard shortcut conflicts: Change shortcuts of menu items if
00114      * there are duplicates in the respective menu level.
00115      *
00116      * This has to be called after all items are added, but before rebuildMenuTree()
00117      * (see above). YMenuButton::addItems() calls this automatically.
00118      **/
00119     void resolveShortcutConflicts();
00120 
00121     /**
00122      * Set a property.
00123      * Reimplemented from YWidget.
00124      *
00125      * This function may throw YUIPropertyExceptions.
00126      *
00127      * This function returns 'true' if the value was successfully set and
00128      * 'false' if that value requires special handling (not in error cases:
00129      * those are covered by exceptions).
00130      **/
00131     virtual bool setProperty( const std::string & propertyName,
00132                               const YPropertyValue & val );
00133 
00134     /**
00135      * Get a property.
00136      * Reimplemented from YWidget.
00137      *
00138      * This method may throw YUIPropertyExceptions.
00139      **/
00140     virtual YPropertyValue getProperty( const std::string & propertyName );
00141 
00142     /**
00143      * Return this class's property set.
00144      * This also initializes the property upon the first call.
00145      *
00146      * Reimplemented from YWidget.
00147      **/
00148     virtual const YPropertySet & propertySet();
00149 
00150 protected:
00151 
00152     /**
00153      * Recursively find the first menu item with the specified index.
00154      * Returns 0 if there is no such item.
00155      **/
00156     YMenuItem * findMenuItem( int index );
00157 
00158     /**
00159      * Recursively find the first menu item with the specified index
00160      * from iterator 'begin' to iterator 'end'.
00161      *
00162      * Returns 0 if there is no such item.
00163      **/
00164     YMenuItem * findMenuItem( int index, YItemConstIterator begin, YItemConstIterator end );
00165 
00166     /**
00167      * Alias for findMenuItem(). Reimplemented to ensure consistent behaviour
00168      * with YSelectionWidget::itemAt().
00169      **/
00170     YMenuItem * itemAt( int index )
00171         { return findMenuItem( index ); }
00172 
00173 private:
00174 
00175     /**
00176      * Assign a unique index to all items from iterator 'begin' to iterator 'end'.
00177      **/
00178     void assignUniqueIndex( YItemIterator begin, YItemIterator end );
00179 
00180 
00181     ImplPtr<YMenuButtonPrivate> priv;
00182 };
00183 
00184 
00185 #endif // YMenuButton_h
 All Classes Functions Variables Enumerations Friends