libyui  3.4.2
YSelectionBox.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: YSelectionBox.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YSelectionBox_h
26 #define YSelectionBox_h
27 
28 #include "YSelectionWidget.h"
29 
31 
32 
33 /**
34  * Selection box: List box that displays a (scrollable) list of items from
35  * which the user can select exactly one. Each item has a label text and an
36  * optional icon (*).
37  *
38  * This widget displays a number of items at once (as screen space permits). If
39  * there is little screen space, you might consider using a ComboBox instead
40  * which (in non-editable mode which is the default) displays just one item
41  * (the selected item) right away and the others in a pop-up dialog upon mouse
42  * click or keypress.
43  *
44  * The selection box also has a caption label that is
45  * displayed above the list. The hotkey displayed in that caption label will
46  * move the keyboard focus into the list.
47  *
48  * If multiple columns are needed, use the YTable widget instead.
49  * For tree-like structures, use the YTree widget.
50  * Use YMultiSelectionBox if more than one item can be selected.
51  *
52  * (*) Not all UIs (in particular not text-based UIs) support displaying icons,
53  * so an icon should never be an exclusive means to display any kind of
54  * information.
55  **/
57 {
58 protected:
59 
60  /**
61  * Constructor.
62  **/
63  YSelectionBox( YWidget * parent, const std::string & label );
64 
65 public:
66  /**
67  * Destructor.
68  **/
69  virtual ~YSelectionBox();
70 
71  /**
72  * Returns a descriptive name of this widget class for logging,
73  * debugging etc.
74  **/
75  virtual const char * widgetClass() const { return "YSelectionBox"; }
76 
77  /**
78  * Return 'true' if this SelectionBox should be very small.
79  **/
80  bool shrinkable() const;
81 
82  /**
83  * Make this SelectionBox very small. This will take effect only upon the
84  * next geometry management run.
85  *
86  * Derived classes can overwrite this, but should call this base class
87  * function in the new function.
88  **/
89  virtual void setShrinkable( bool shrinkable = true );
90 
91  /**
92  * Deliver even more events than with notify() set.
93  *
94  * For YSelectionBox, this is relevant mostly for the NCurses UI:
95  *
96  * In graphical UIs like the Qt UI, the user can use the mouse to select an
97  * item in a selection box. With notify() set, this will send an event
98  * right away (i.e., it will make UserInput and related return, while
99  * normally it would only return when the user clicks a PushButton).
100  *
101  * In the NCurses UI, there is no mouse, so the user has to use the cursor
102  * keys to move to the item he wants to select. In immediateMode(), every
103  * cursor key press will make the selection box send an event. Without
104  * immediateMode(), the NCSelectionBox will wait until the user hits the
105  * [Return] key until an event is sent. Depending on what the application
106  * does upon each selection box event, immediateMode() might make the
107  * application less responsive.
108  **/
109  bool immediateMode() const;
110 
111  /**
112  * Set immediateMode() on or off.
113  **/
114  void setImmediateMode( bool on = true );
115 
116  /**
117  * Set a property.
118  * Reimplemented from YWidget.
119  *
120  * This function may throw YUIPropertyExceptions.
121  *
122  * This function returns 'true' if the value was successfully set and
123  * 'false' if that value requires special handling (not in error cases:
124  * those are covered by exceptions).
125  **/
126  virtual bool setProperty( const std::string & propertyName,
127  const YPropertyValue & val );
128 
129  /**
130  * Get a property.
131  * Reimplemented from YWidget.
132  *
133  * This method may throw YUIPropertyExceptions.
134  **/
135  virtual YPropertyValue getProperty( const std::string & propertyName );
136 
137  /**
138  * Return this class's property set.
139  * This also initializes the property upon the first call.
140  *
141  * Reimplemented from YWidget.
142  **/
143  virtual const YPropertySet & propertySet();
144 
145  /**
146  * The name of the widget property that will return user input.
147  * Inherited from YWidget.
148  **/
149  const char * userInputProperty() { return YUIProperty_CurrentItem; }
150 
151 
152 private:
153 
155 };
156 
157 
158 #endif // YSelectionBox_h
Selection box: List box that displays a (scrollable) list of items from which the user can select exa...
Definition: YSelectionBox.h:56
std::string label() const
Return this widget&#39;s label (the caption above the item list).
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
const char * userInputProperty()
The name of the widget property that will return user input.
bool immediateMode() const
Deliver even more events than with notify() set.
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
virtual ~YSelectionBox()
Destructor.
bool shrinkable() const
Return &#39;true&#39; if this SelectionBox should be very small.
Transport class for the value of simple properties.
Definition: YProperty.h:104
Base class for various kinds of multi-value widgets.
A set of properties to check names and types against.
Definition: YProperty.h:197
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
void setImmediateMode(bool on=true)
Set immediateMode() on or off.
virtual void setShrinkable(bool shrinkable=true)
Make this SelectionBox very small.
YSelectionBox(YWidget *parent, const std::string &label)
Constructor.
Abstract base class of all UI widgets.
Definition: YWidget.h:54
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YSelectionBox.h:75