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
YWidget::parent
YWidget * parent() const
Return this widget's parent or 0 if it doesn't have a parent.
Definition: YWidget.cc:271
YWidget
Abstract base class of all UI widgets.
Definition: YWidget.h:55
YSelectionWidget
Base class for various kinds of multi-value widgets.
Definition: YSelectionWidget.h:43
YItemSelector::setProperty
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YItemSelector.cc:239
YItemSelector::getProperty
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YItemSelector.cc:260
YItemSelector::validCustomStatusIndex
bool validCustomStatusIndex(int index) const
Return 'true' if a custom status index is within the valid range, i.e.
Definition: YItemSelector.cc:161
YItemCustomStatus
Class describing a non-binary status for an item.
Definition: YItemCustomStatus.h:45
YItemSelector
Scrollable item selector widget with not only a label for each item, but also a (possible multi-line)...
Definition: YItemSelector.h:44
YItemSelector::setItemStatus
virtual void setItemStatus(YItem *item, int status)
Set the status of an item.
Definition: YItemSelector.cc:115
YPropertySet
A set of properties to check names and types against.
Definition: YProperty.h:198
YItemSelector::setVisibleItems
virtual void setVisibleItems(int newVal)
Set the number of visible items.
Definition: YItemSelector.cc:106
YItemSelector::updateCustomStatusIndicator
virtual void updateCustomStatusIndicator(YItem *item)
Update the status indicator (status icon or text indicator) if this widget is using custom status val...
Definition: YItemSelector.h:204
YSelectionWidget::enforceSingleSelection
bool enforceSingleSelection() const
Return 'true' if this base class should enforce single selection.
Definition: YSelectionWidget.cc:111
YItemSelector::customStatus
const YItemCustomStatus & customStatus(int index)
Return the custom status with the specified index (counting from 0).
Definition: YItemSelector.cc:149
YItemSelector::activateItem
virtual void activateItem(YItem *item)=0
Activate selected item.
YItemSelector::propertySet
virtual const YPropertySet & propertySet()
Return this class's property set.
Definition: YItemSelector.cc:209
ImplPtr< YItemSelectorPrivate >
YItemSelector::visibleItems
int visibleItems() const
Return the number of visible items (i.e.
Definition: YItemSelector.cc:100
YItemSelector::~YItemSelector
virtual ~YItemSelector()
Destructor.
Definition: YItemSelector.cc:74
YItemSelector::usingCustomStatus
bool usingCustomStatus() const
Return 'true' if this widget uses custom status values, 'false' if not (i.e.
Definition: YItemSelector.cc:136
YItemSelector::YItemSelector
YItemSelector(YWidget *parent, bool enforceSingleSelection=true)
Standard constructor.
Definition: YItemSelector.cc:46
YItemSelector::widgetClass
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YItemSelector.cc:90
YItemSelector::cycleCustomStatus
int cycleCustomStatus(int oldStatus)
Cycle through the custom status values according to the custom status table, i.e.
Definition: YItemSelector.cc:196
YPropertyValue
Transport class for the value of simple properties.
Definition: YProperty.h:105
YItemSelectorPrivate
Definition: YItemSelector.cc:36
YItemSelector::userInputProperty
const char * userInputProperty()
The name of the widget property that will return user input.
Definition: YItemSelector.h:187
YItemSelector::customStatusCount
int customStatusCount() const
Return the number of custom status values or 0 if no custom status values are used.
Definition: YItemSelector.cc:142
YItem
Simple item class for SelectionBox, ComboBox, MultiSelectionBox etc.
Definition: YItem.h:50