libyui  3.10.0
YItemSelector.h
1 /*
2  Copyright (c) [2019] SUSE LLC
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: YItemSelector.h
20 
21  Author: Stefan Hundhammer <shundhammer@suse.de>
22 
23 /-*/
24 
25 #ifndef YItemSelector_h
26 #define YItemSelector_h
27 
28 #include "YSelectionWidget.h"
29 #include "YDescribedItem.h"
30 #include "YItemCustomStatus.h"
31 
32 
34 
35 /**
36  * Scrollable item selector widget with not only a label for each item, but
37  * also a (possible multi-line) description and an optional icon.
38  *
39  * This widget supports both 1-of-n or n-of-m selection, i.e. it can act as a
40  * (more verbose and more screen space consuming) replacement for YSelectionBox
41  * or YMultiSelectionBox.
42  **/
44 {
45 public:
46 
47  /**
48  * Standard constructor.
49  **/
51  bool enforceSingleSelection = true );
52 
53  /**
54  * Constructor for custom item status values.
55  *
56  * This makes it possible to set a wider variety of values than just 0 or
57  * 1. The semantics behind the individual status values is purely
58  * application defined; the specified customStates description only
59  * provides an icon (for graphical UIs) or a text representation (for
60  * text-based UIs) and an optional "next" status value that can be used to
61  * let the user cycle through different status values. The numeric value of
62  * each status is implicitly its index in the vector.
63  *
64  * Notice that this constructor is the only way to set custom status value
65  * descriptions; they cannot be changed anymore after initializing the
66  * widget. This is by design so that any derived widgets in concrete UIs do
67  * not have to bother with possibly recreating any subwidgets if this
68  * should change; this guarantees that it does not change, neither the fact
69  * that there are custom status values nor their number or indicator icons
70  * or texts.
71  *
72  * This constructor implicitly sets 'enforceSingleSelection' to 'false'.
73  *
74  * In this mode, the widget sends YMenuEvents (which include the item that
75  * the user changed) if the notify option is set. For anything beyond the
76  * simple status transitions that are defined here in 'customStates', it is
77  * highly recommended to set that notify option and to handle those
78  * YMenuEvents on the application level.
79  **/
81  const YItemCustomStatusVector & customStates );
82 
83  /**
84  * Destructor.
85  **/
86  virtual ~YItemSelector();
87 
88  /**
89  * Return a descriptive name of this widget class for logging,
90  * debugging etc.
91  **/
92  virtual const char * widgetClass() const;
93 
94  /**
95  * Return the number of visible items (i.e. items that are visible without
96  * scrolling). This is used to calculate the preferred height. If the
97  * widget gets more or less screen space than desired due to layout
98  * constraints, this number is not updated; this is purely the desired
99  * value for initializing layout negotiations.
100  **/
101  int visibleItems() const;
102 
103  /**
104  * Set the number of visible items. When changing this, make sure to
105  * recalculate the layout (YDialog::recalc()) so the change has any effect.
106  *
107  * Derived classes are free to reimplement this, but they should call this
108  * base class method in the overloaded function.
109  **/
110  virtual void setVisibleItems( int newVal );
111 
112  /**
113  * Set the status of an item. Unlike YItem::setStatus(), this informs the
114  * widget of the change so it can set the corresponding status icon.
115  *
116  * Reimplemented from YSelectionWidget.
117  **/
118  virtual void setItemStatus( YItem * item, int status );
119 
120  /**
121  * Return 'true' if this widget uses custom status values, 'false' if not
122  * (i.e. only 0 or 1).
123  **/
124  bool usingCustomStatus() const;
125 
126  /**
127  * Return the number of custom status values or 0 if no custom status
128  * values are used.
129  **/
130  int customStatusCount() const;
131 
132  /**
133  * Return the custom status with the specified index (counting from 0).
134  *
135  * Notice that this may throw a std::out_of_range exception if the index is
136  * invalid.
137  **/
138  const YItemCustomStatus & customStatus( int index );
139 
140  /**
141  * Return 'true' if a custom status index is within the valid range,
142  * i.e. 0..customStatusCount()-1, 'false' otherwise.
143  **/
144  bool validCustomStatusIndex( int index ) const;
145 
146  /**
147  * Cycle through the custom status values according to the custom status
148  * table, i.e. return the 'nextStatus' field of table index 'oldStatus'.
149  * This may be -1 if no next status was specified there or if 'oldStatus'
150  * is out of range of that table.
151  **/
152  int cycleCustomStatus( int oldStatus );
153 
154  /**
155  * Set a property.
156  * Reimplemented from YWidget.
157  *
158  * This function may throw YUIPropertyExceptions.
159  *
160  * This function returns 'true' if the value was successfully set and
161  * 'false' if that value requires special handling (not in error cases:
162  * those are covered by exceptions).
163  **/
164  virtual bool setProperty( const std::string & propertyName,
165  const YPropertyValue & val );
166 
167  /**
168  * Get a property.
169  * Reimplemented from YWidget.
170  *
171  * This method may throw YUIPropertyExceptions.
172  **/
173  virtual YPropertyValue getProperty( const std::string & propertyName );
174 
175  /**
176  * Return this class's property set.
177  * This also initializes the property upon the first call.
178  *
179  * Reimplemented from YWidget.
180  **/
181  virtual const YPropertySet & propertySet();
182 
183  /**
184  * The name of the widget property that will return user input.
185  * Inherited from YWidget.
186  **/
187  const char * userInputProperty() { return YUIProperty_Value; }
188 
189  /**
190  * Activate selected item. Can be used in tests to simulate user input.
191  *
192  * Derived classes are required to implement this.
193  **/
194  virtual void activateItem( YItem * item ) = 0;
195 
196 protected:
197 
198  /**
199  * Update the status indicator (status icon or text indicator) if this
200  * widget is using custom status values.
201  *
202  * Derived classes should overwrite this.
203  **/
204  virtual void updateCustomStatusIndicator( YItem * item ) {}
205 
206 
207 private:
208 
209  /**
210  * Common initializations for all constructors.
211  **/
212  void init();
213 
214  /**
215  * Perform a sanity check on the custom status value descriptions.
216  **/
217  void checkCustomStates();
218 
219 
220  // Data members
221 
223 
224 }; // class YItemSelector
225 
226 #endif // YItemSelector_h
Class describing a non-binary status for an item.
Scrollable item selector widget with not only a label for each item, but also a (possible multi-line)...
Definition: YItemSelector.h:44
virtual void setVisibleItems(int newVal)
Set the number of visible items.
int visibleItems() const
Return the number of visible items (i.e.
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
int customStatusCount() const
Return the number of custom status values or 0 if no custom status values are used.
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
virtual const YPropertySet & propertySet()
Return this class's property set.
virtual void activateItem(YItem *item)=0
Activate selected item.
int cycleCustomStatus(int oldStatus)
Cycle through the custom status values according to the custom status table, i.e.
YItemSelector(YWidget *parent, bool enforceSingleSelection=true)
Standard constructor.
bool validCustomStatusIndex(int index) const
Return 'true' if a custom status index is within the valid range, i.e.
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
const YItemCustomStatus & customStatus(int index)
Return the custom status with the specified index (counting from 0).
virtual void setItemStatus(YItem *item, int status)
Set the status of an item.
virtual void updateCustomStatusIndicator(YItem *item)
Update the status indicator (status icon or text indicator) if this widget is using custom status val...
bool usingCustomStatus() const
Return 'true' if this widget uses custom status values, 'false' if not (i.e.
const char * userInputProperty()
The name of the widget property that will return user input.
virtual ~YItemSelector()
Destructor.
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:50
A set of properties to check names and types against.
Definition: YProperty.h:198
Transport class for the value of simple properties.
Definition: YProperty.h:105
Base class for various kinds of multi-value widgets.
bool enforceSingleSelection() const
Return 'true' if this base class should enforce single selection.
Abstract base class of all UI widgets.
Definition: YWidget.h:55
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271