libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YSelectionBox.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:         YSelectionBox.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YSelectionBox_h
00026 #define YSelectionBox_h
00027 
00028 #include "YSelectionWidget.h"
00029 
00030 class YSelectionBoxPrivate;
00031 
00032 
00033 /**
00034  * Selection box: List box that displays a (scrollable) list of items from
00035  * which the user can select exactly one. Each item has a label text and an
00036  * optional icon (*).
00037  *
00038  * This widget displays a number of items at once (as screen space permits). If
00039  * there is little screen space, you might consider using a ComboBox instead
00040  * which (in non-editable mode which is the default) displays just one item
00041  * (the selected item) right away and the others in a pop-up dialog upon mouse
00042  * click or keypress.
00043  *
00044  * The selection box also has a caption label that is
00045  * displayed above the list. The hotkey displayed in that caption label will
00046  * move the keyboard focus into the list.
00047  *
00048  * If multiple columns are needed, use the table widget instead.
00049  * For tree-like structures, use the tree widget.
00050  *
00051  *
00052  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
00053  * so an icon should never be an exclusive means to display any kind of
00054  * information.
00055  **/
00056 class YSelectionBox : public YSelectionWidget
00057 {
00058 protected:
00059 
00060     /**
00061      * Constructor.
00062      **/
00063     YSelectionBox( YWidget * parent, const std::string & label );
00064 
00065 public:
00066     /**
00067      * Destructor.
00068      **/
00069     virtual ~YSelectionBox();
00070 
00071     /**
00072      * Returns a descriptive name of this widget class for logging,
00073      * debugging etc.
00074      **/
00075     virtual const char * widgetClass() const { return "YSelectionBox"; }
00076 
00077     /**
00078      * Return 'true' if this SelectionBox should be very small.
00079      **/
00080     bool shrinkable() const;
00081 
00082     /**
00083      * Make this SelectionBox very small. This will take effect only upon the
00084      * next geometry management run.
00085      *
00086      * Derived classes can overwrite this, but should call this base class
00087      * function in the new function.
00088      **/
00089     virtual void setShrinkable( bool shrinkable = true );
00090 
00091     /**
00092      * Deliver even more events than with notify() set.
00093      *
00094      * For YSelectionBox, this is relevant mostly for the NCurses UI:
00095      *
00096      * In graphical UIs like the Qt UI, the user can use the mouse to select an
00097      * item in a selection box. With notify() set, this will send an event
00098      * right away (i.e., it will make UserInput and related return, while
00099      * normally it would only return when the user clicks a PushButton).
00100      *
00101      * In the NCurses UI, there is no mouse, so the user has to use the cursor
00102      * keys to move to the item he wants to select. In immediateMode(), every
00103      * cursor key press will make the selection box send an event. Without
00104      * immediateMode(), the NCSelectionBox will wait until the user hits the
00105      * [Return] key until an event is sent. Depending on what the application
00106      * does upon each selection box event, immediateMode() might make the
00107      * application less responsive.
00108      **/
00109     bool immediateMode() const;
00110 
00111     /**
00112      * Set immediateMode() on or off.
00113      **/
00114     void setImmediateMode( bool on = true );
00115 
00116     /**
00117      * Set a property.
00118      * Reimplemented from YWidget.
00119      *
00120      * This function may throw YUIPropertyExceptions.
00121      *
00122      * This function returns 'true' if the value was successfully set and
00123      * 'false' if that value requires special handling (not in error cases:
00124      * those are covered by exceptions).
00125      **/
00126     virtual bool setProperty( const std::string & propertyName,
00127                               const YPropertyValue & val );
00128 
00129     /**
00130      * Get a property.
00131      * Reimplemented from YWidget.
00132      *
00133      * This method may throw YUIPropertyExceptions.
00134      **/
00135     virtual YPropertyValue getProperty( const std::string & propertyName );
00136 
00137     /**
00138      * Return this class's property set.
00139      * This also initializes the property upon the first call.
00140      *
00141      * Reimplemented from YWidget.
00142      **/
00143     virtual const YPropertySet & propertySet();
00144 
00145     /**
00146      * The name of the widget property that will return user input.
00147      * Inherited from YWidget.
00148      **/
00149     const char * userInputProperty() { return YUIProperty_CurrentItem; }
00150 
00151 
00152 private:
00153 
00154     ImplPtr<YSelectionBoxPrivate> priv;
00155 };
00156 
00157 
00158 #endif // YSelectionBox_h
 All Classes Functions Variables Enumerations Friends