libyui
3.0.10
|
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: YComboBox.h 00020 00021 Author: Stefan Hundhammer <sh@suse.de> 00022 00023 /-*/ 00024 00025 #ifndef YComboBox_h 00026 #define YComboBox_h 00027 00028 #include "YSelectionWidget.h" 00029 00030 class YComboBoxPrivate; 00031 00032 00033 /** 00034 * ComboBox (a.k.a. "drop down box", "drop down selection"): 00035 * 00036 * A widget with a drop-down list of predefined values to select from. 00037 * Optionally, this widget can be created in "editable" mode which means that 00038 * the user can freely enter any text. 00039 * 00040 * In non-editable mode, a ComboBox works very much like a SelectionBox that 00041 * uses fewer screen space. In that mode, it is recommended to use 00042 * selectedItem() to retrieve its current value and selectItem() to set it. 00043 * 00044 * In editable mode, a ComboBox is more like an InputField with a list to pick 00045 * predefined values from (for less typing). In that mode, it is recommended to 00046 * use value() and setValue(). 00047 * 00048 * In either mode, it might be dangerous to use the iterators the 00049 * (itemsBegin(), itemsEnd()) the base class (YSelectionWidget) provides to 00050 * find the currently selected item: The items' "selected" flag may or may not 00051 * be up to date. YComboBox::selectedItem() makes sure they are up to date. 00052 **/ 00053 class YComboBox : public YSelectionWidget 00054 { 00055 protected: 00056 /** 00057 * Constructor. 00058 * 00059 * 'editable' means the user can freely enter any value without being 00060 * restricted to the items of the ComboBox's list. 00061 **/ 00062 YComboBox( YWidget * parent, const std::string & label, bool editable ); 00063 00064 public: 00065 /** 00066 * Destructor. 00067 **/ 00068 virtual ~YComboBox(); 00069 00070 /** 00071 * Returns a descriptive name of this widget class for logging, 00072 * debugging etc. 00073 **/ 00074 virtual const char * widgetClass() const { return "YComboBox"; } 00075 00076 /** 00077 * Return 'true' if this ComboBox is editable, i.e. if the user can freely 00078 * enter any value without being restricted to the items of the ComboBox's 00079 * list. 00080 * 00081 * Notice that this can only be set in the constructor. 00082 **/ 00083 bool editable() const; 00084 00085 /** 00086 * Return the value of this ComboBox: 00087 * 00088 * The text of a list item if the user (or the appplication) selected a 00089 * list item or the content of the ComboBox's input field if the ComboBox 00090 * is editable and the user (or the application) entered text there. 00091 * 00092 * See also YComboBox::selectedItem(). 00093 **/ 00094 std::string value(); 00095 00096 /** 00097 * Set the value of this ComboBox by string: Try to find a list item with 00098 * that label and select it. 00099 * 00100 * If there is no matching list item, editable ComboBoxes will set their 00101 * input field to that text. Non-editable ComboBoxes will throw an 00102 * exception. 00103 * 00104 * See also selectItem(). 00105 **/ 00106 void setValue( const std::string & newText ); 00107 00108 /** 00109 * Return the (first) selected item or 0 if none is selected or if this 00110 * ComboBox is editable and the user entered something that does not match 00111 * any of the ComboBox's list items (in that case, use value() instead). 00112 * 00113 * Reimplemented from YSelectionWidget for better reliability: This will 00114 * compare an editable ComboBox's user input against the text labels of 00115 * all items and try to return an item if there is any match. 00116 **/ 00117 virtual YItem * selectedItem(); 00118 00119 /** 00120 * Return all selected items. 00121 * 00122 * This is not particularly useful for ComboBoxes since there can be no 00123 * more than one selected item anyway; * better use selectedItem() or 00124 * value() instead. 00125 * 00126 * This function does not transfer ownership of those items to the caller, 00127 * so don't try to delete them! 00128 * 00129 * Reimplemented from YSelectionWidget for better reliability. 00130 **/ 00131 virtual YItemCollection selectedItems(); 00132 00133 /** 00134 * Select or deselect an item. See also setValue(). 00135 * 00136 * Reimplemented from YSelectionWidget. 00137 **/ 00138 virtual void selectItem( YItem * item, bool selected = true ); 00139 00140 /** 00141 * Get the valid input characters. No input validation is performed (i.e., 00142 * the user can enter anything) if this is empty. 00143 * 00144 * This is only meaningful for if the ComboBox is editable. 00145 **/ 00146 std::string validChars(); 00147 00148 /** 00149 * Set the valid input characters. No input validation is performed (i.e., 00150 * the user can enter anything) if this is empty. 00151 * 00152 * This is only meaningful for if the ComboBox is editable. 00153 * 00154 * Derived classes are free to reimplement this, but they should call this 00155 * base class method at the end of the overloaded function. 00156 **/ 00157 virtual void setValidChars( const std::string & validChars ); 00158 00159 /** 00160 * The maximum input length, i.e., the maximum number of characters the 00161 * user can enter. -1 means no limit. 00162 * 00163 * This is only meaningful for if the ComboBox is editable. 00164 **/ 00165 int inputMaxLength() const; 00166 00167 /** 00168 * Set the maximum input length, i.e., the maximum number of characters the 00169 * user can enter. -1 means no limit. 00170 * 00171 * This is only meaningful for if the ComboBox is editable. 00172 * 00173 * Derived classes are free to reimplement this, but they should call this 00174 * base class method at the end of the overloaded function. 00175 **/ 00176 virtual void setInputMaxLength( int numberOfChars ); 00177 00178 /** 00179 * Set a property. 00180 * Reimplemented from YWidget. 00181 * 00182 * This function may throw YUIPropertyExceptions. 00183 * 00184 * This function returns 'true' if the value was successfully set and 00185 * 'false' if that value requires special handling (not in error cases: 00186 * those are covered by exceptions). 00187 **/ 00188 virtual bool setProperty( const std::string & propertyName, 00189 const YPropertyValue & val ); 00190 00191 /** 00192 * Get a property. 00193 * Reimplemented from YWidget. 00194 * 00195 * This method may throw YUIPropertyExceptions. 00196 **/ 00197 virtual YPropertyValue getProperty( const std::string & propertyName ); 00198 00199 /** 00200 * Return this class's property set. 00201 * This also initializes the property upon the first call. 00202 * 00203 * Reimplemented from YWidget. 00204 **/ 00205 virtual const YPropertySet & propertySet(); 00206 00207 /** 00208 * The name of the widget property that will return user input. 00209 * Inherited from YWidget. 00210 **/ 00211 const char * userInputProperty() { return YUIProperty_Value; } 00212 00213 00214 protected: 00215 00216 /** 00217 * Return this ComboBox's current value as text. 00218 * 00219 * Called internally from value(), selectedItem() and related. 00220 * 00221 * Derived classes are required to implement this function. 00222 **/ 00223 virtual std::string text() = 0; 00224 00225 /** 00226 * 00227 * Set this ComboBox's current value as text. 00228 * 00229 * Called internally whenever the content is to change 00230 * programmatically. Don't call setValue() or selectItem() from here. 00231 * 00232 * Derived classes are required to implement this function. 00233 **/ 00234 virtual void setText( const std::string & newText ) = 0; 00235 00236 00237 private: 00238 00239 ImplPtr<YComboBoxPrivate> priv; 00240 }; 00241 00242 00243 #endif // YComboBox_h