libyui  3.3.2
YComboBox.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: YComboBox.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YComboBox_h
26 #define YComboBox_h
27 
28 #include "YSelectionWidget.h"
29 
30 class YComboBoxPrivate;
31 
32 
33 /**
34  * ComboBox (or "drop down box", "drop down selection"); may be editable.
35  *
36  * A widget with a drop-down list of predefined values to select from.
37  * Optionally, this widget can be created in "editable" mode which means that
38  * the user can freely enter any text.
39  *
40  * In non-editable mode, a ComboBox works very much like a SelectionBox that
41  * uses fewer screen space. In that mode, it is recommended to use
42  * selectedItem() to retrieve its current value and selectItem() to set it.
43  *
44  * In editable mode, a ComboBox is more like an InputField with a list to pick
45  * predefined values from (for less typing). In that mode, it is recommended to
46  * use value() and setValue().
47  *
48  * In either mode, it might be dangerous to use the iterators the
49  * (itemsBegin(), itemsEnd()) the base class (YSelectionWidget) provides to
50  * find the currently selected item: The items' "selected" flag may or may not
51  * be up to date. YComboBox::selectedItem() makes sure they are up to date.
52  **/
54 {
55 protected:
56  /**
57  * Constructor.
58  *
59  * 'editable' means the user can freely enter any value without being
60  * restricted to the items of the ComboBox's list.
61  **/
62  YComboBox( YWidget * parent, const std::string & label, bool editable );
63 
64 public:
65  /**
66  * Destructor.
67  **/
68  virtual ~YComboBox();
69 
70  /**
71  * Returns a descriptive name of this widget class for logging,
72  * debugging etc.
73  **/
74  virtual const char * widgetClass() const { return "YComboBox"; }
75 
76  /**
77  * Return 'true' if this ComboBox is editable, i.e. if the user can freely
78  * enter any value without being restricted to the items of the ComboBox's
79  * list.
80  *
81  * Notice that this can only be set in the constructor.
82  **/
83  bool editable() const;
84 
85  /**
86  * Return the value of this ComboBox:
87  *
88  * The text of a list item if the user (or the appplication) selected a
89  * list item or the content of the ComboBox's input field if the ComboBox
90  * is editable and the user (or the application) entered text there.
91  *
92  * See also YComboBox::selectedItem().
93  **/
94  std::string value();
95 
96  /**
97  * Set the value of this ComboBox by string: Try to find a list item with
98  * that label and select it.
99  *
100  * If there is no matching list item, editable ComboBoxes will set their
101  * input field to that text. Non-editable ComboBoxes will throw an
102  * exception.
103  *
104  * See also selectItem().
105  **/
106  void setValue( const std::string & newText );
107 
108  /**
109  * Return the (first) selected item or 0 if none is selected or if this
110  * ComboBox is editable and the user entered something that does not match
111  * any of the ComboBox's list items (in that case, use value() instead).
112  *
113  * Reimplemented from YSelectionWidget for better reliability: This will
114  * compare an editable ComboBox's user input against the text labels of
115  * all items and try to return an item if there is any match.
116  **/
117  virtual YItem * selectedItem();
118 
119  /**
120  * Return all selected items.
121  *
122  * This is not particularly useful for ComboBoxes since there can be no
123  * more than one selected item anyway; * better use selectedItem() or
124  * value() instead.
125  *
126  * This function does not transfer ownership of those items to the caller,
127  * so don't try to delete them!
128  *
129  * Reimplemented from YSelectionWidget for better reliability.
130  **/
131  virtual YItemCollection selectedItems();
132 
133  /**
134  * Select or deselect an item. See also setValue().
135  *
136  * Reimplemented from YSelectionWidget.
137  **/
138  virtual void selectItem( YItem * item, bool selected = true );
139 
140  /**
141  * Get the valid input characters. No input validation is performed (i.e.,
142  * the user can enter anything) if this is empty.
143  *
144  * This is only meaningful for if the ComboBox is editable.
145  **/
146  std::string validChars();
147 
148  /**
149  * Set the valid input characters. No input validation is performed (i.e.,
150  * the user can enter anything) if this is empty.
151  *
152  * This is only meaningful for if the ComboBox is editable.
153  *
154  * Derived classes are free to reimplement this, but they should call this
155  * base class method at the end of the overloaded function.
156  **/
157  virtual void setValidChars( const std::string & validChars );
158 
159  /**
160  * The maximum input length, i.e., the maximum number of characters the
161  * user can enter. -1 means no limit.
162  *
163  * This is only meaningful for if the ComboBox is editable.
164  **/
165  int inputMaxLength() const;
166 
167  /**
168  * Set the maximum input length, i.e., the maximum number of characters the
169  * user can enter. -1 means no limit.
170  *
171  * This is only meaningful for if the ComboBox is editable.
172  *
173  * Derived classes are free to reimplement this, but they should call this
174  * base class method at the end of the overloaded function.
175  **/
176  virtual void setInputMaxLength( int numberOfChars );
177 
178  /**
179  * Set a property.
180  * Reimplemented from YWidget.
181  *
182  * This function may throw YUIPropertyExceptions.
183  *
184  * This function returns 'true' if the value was successfully set and
185  * 'false' if that value requires special handling (not in error cases:
186  * those are covered by exceptions).
187  **/
188  virtual bool setProperty( const std::string & propertyName,
189  const YPropertyValue & val );
190 
191  /**
192  * Get a property.
193  * Reimplemented from YWidget.
194  *
195  * This method may throw YUIPropertyExceptions.
196  **/
197  virtual YPropertyValue getProperty( const std::string & propertyName );
198 
199  /**
200  * Return this class's property set.
201  * This also initializes the property upon the first call.
202  *
203  * Reimplemented from YWidget.
204  **/
205  virtual const YPropertySet & propertySet();
206 
207  /**
208  * The name of the widget property that will return user input.
209  * Inherited from YWidget.
210  **/
211  const char * userInputProperty() { return YUIProperty_Value; }
212 
213 
214 protected:
215 
216  /**
217  * Return this ComboBox's current value as text.
218  *
219  * Called internally from value(), selectedItem() and related.
220  *
221  * Derived classes are required to implement this function.
222  **/
223  virtual std::string text() = 0;
224 
225  /**
226  *
227  * Set this ComboBox's current value as text.
228  *
229  * Called internally whenever the content is to change
230  * programmatically. Don't call setValue() or selectItem() from here.
231  *
232  * Derived classes are required to implement this function.
233  **/
234  virtual void setText( const std::string & newText ) = 0;
235 
236 
237 private:
238 
240 };
241 
242 
243 #endif // YComboBox_h
std::string label() const
Return this widget&#39;s label (the caption above the item list).
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YComboBox.cc:220
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YComboBox.h:211
bool editable() const
Return &#39;true&#39; if this ComboBox is editable, i.e.
Definition: YComboBox.cc:64
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 various kinds of multi-value widgets.
virtual void setInputMaxLength(int numberOfChars)
Set the maximum input length, i.e., the maximum number of characters the user can enter...
Definition: YComboBox.cc:88
A set of properties to check names and types against.
Definition: YProperty.h:197
void setValue(const std::string &newText)
Set the value of this ComboBox by string: Try to find a list item with that label and select it...
Definition: YComboBox.cc:100
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
std::string validChars()
Get the valid input characters.
Definition: YComboBox.cc:70
YComboBox(YWidget *parent, const std::string &label, bool editable)
Constructor.
Definition: YComboBox.cc:49
ComboBox (or "drop down box", "drop down selection"); may be editable.
Definition: YComboBox.h:53
virtual void selectItem(YItem *item, bool selected=true)
Select or deselect an item.
Definition: YComboBox.cc:122
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YComboBox.cc:200
virtual std::string text()=0
Return this ComboBox&#39;s current value as text.
virtual const char * widgetClass() const
Returns a descriptive name of this widget class for logging, debugging etc.
Definition: YComboBox.h:74
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:49
virtual ~YComboBox()
Destructor.
Definition: YComboBox.cc:58
virtual YItem * selectedItem()
Return the (first) selected item or 0 if none is selected or if this ComboBox is editable and the use...
Definition: YComboBox.cc:136
int inputMaxLength() const
The maximum input length, i.e., the maximum number of characters the user can enter.
Definition: YComboBox.cc:82
std::string value()
Return the value of this ComboBox:
Definition: YComboBox.cc:94
virtual void setText(const std::string &newText)=0
Set this ComboBox&#39;s current value as text.
Abstract base class of all UI widgets.
Definition: YWidget.h:54
virtual YItemCollection selectedItems()
Return all selected items.
Definition: YComboBox.cc:157
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
Definition: YComboBox.cc:172
virtual void setValidChars(const std::string &validChars)
Set the valid input characters.
Definition: YComboBox.cc:76