libyui  3.3.2
YBarGraph.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: YBarGraph.h
20 
21  Author: Stefan Hundhammer <sh@suse.de>
22 
23 /-*/
24 
25 #ifndef YBarGraph_h
26 #define YBarGraph_h
27 
28 #include "YWidget.h"
29 #include "YColor.h"
30 
31 
32 class YBarGraphPrivate;
33 class YBarGraphSegment;
34 
35 /**
36  * A graph showing partitioning of a whole.
37  * The whole is divided into YBarGraphSegment each of which has
38  * a relative size, a text color, a background color, and a label.
39  */
40 class YBarGraph : public YWidget
41 {
42  friend class YBarGraphMultiUpdate;
43 
44 protected:
45  /**
46  * Constructor.
47  **/
49 
50 public:
51  /**
52  * Destructor.
53  **/
54  virtual ~YBarGraph();
55 
56  /**
57  * Return a descriptive name of this widget class for logging,
58  * debugging etc.
59  **/
60  virtual const char * widgetClass() const { return "YBarGraph"; }
61 
62  /**
63  * Add one segment.
64  *
65  * If the segment's background and text colors are not explicitly
66  * specified, the YBarGraph widget will assign them from a list of (at
67  * least 5 different) color sets.
68  *
69  * When adding multiple segments, use a YBarGraphMultiUpdate object for
70  * improved performance to hold back display updates until all segments are
71  * added.
72  **/
73  void addSegment( const YBarGraphSegment & segment );
74 
75  /**
76  * Delete all segments.
77  **/
78  void deleteAllSegments();
79 
80  /**
81  * Return the current number of segments.
82  **/
83  int segments();
84 
85  /**
86  * Return the segment with the specified index (from 0 on).
87  *
88  * This will throw an exception if there are not this many segments.
89  **/
90  const YBarGraphSegment & segment( int segmentIndex ) const;
91 
92  /**
93  * Set the value of the segment with the specifie index (from 0 on).
94  *
95  * This will throw an exception if there are not this many segments.
96  *
97  * Note: Use a YBarGraphMultiUpdate object for improved performance
98  * when doing multiple changes at the same time.
99  **/
100  void setValue( int segmentIndex, int newValue );
101 
102  /**
103  * Set the label of the segment with the specified index (from 0 on).
104  * Use %1 as a placeholder for the current value.
105  *
106  * This will throw an exception if there are not this many segments.
107  *
108  * Note: Use a YBarGraphMultiUpdate object for improved performance
109  * when doing multiple changes at the same time.
110  **/
111  void setLabel( int segmentIndex, const std::string & newLabel );
112 
113  /**
114  * Set the background color of the segment with the specified index
115  * (from 0 on).
116  *
117  * This will throw an exception if there are not this many segments
118  * or if the color is undefined.
119  **/
120  void setSegmentColor( int segmentIndex, const YColor & color );
121 
122  /**
123  * Set the text color of the segment with the specified index
124  * (from 0 on).
125  *
126  * This will throw an exception if there are not this many segments
127  * or if the color is undefined.
128  **/
129  void setTextColor( int segmentIndex, const YColor & color );
130 
131  /**
132  * Set a property.
133  * Reimplemented from YWidget.
134  *
135  * This function may throw YUIPropertyExceptions.
136  *
137  * This function returns 'true' if the value was successfully set and
138  * 'false' if that value requires special handling (not in error cases:
139  * those are covered by exceptions).
140  **/
141  virtual bool setProperty( const std::string & propertyName,
142  const YPropertyValue & val );
143 
144  /**
145  * Get a property.
146  * Reimplemented from YWidget.
147  *
148  * This method may throw YUIPropertyExceptions.
149  **/
150  virtual YPropertyValue getProperty( const std::string & propertyName );
151 
152  /**
153  * Return this class's property set.
154  * This also initializes the property upon the first call.
155  *
156  * Reimplemented from YWidget.
157  **/
158  virtual const YPropertySet & propertySet();
159 
160 
161 protected:
162  /**
163  * Perform a display update after any change to any of the segments.
164  *
165  * Derived classes are required to implement this.
166  **/
167  virtual void doUpdate() = 0;
168 
169 
170 private:
171  /**
172  * Conditionally perform display update if not currently postponed.
173  **/
174  void updateDisplay();
175 
177 };
178 
179 
180 
181 
182 /**
183  * One segment of a YBarGraph.
184  * It has a relative size, a label, label color and background color.
185  **/
187 {
188 public:
189  /**
190  * Constructor.
191  *
192  * 'value' is the initial value of this segment.
193  *
194  * 'label' is the label text in the segment.
195  * Use %1 as a placeholder for the current value.
196  *
197  * 'segmentColor' is the background color of this segment.
198  *
199  * 'textColor' is the color for the label text.
200  *
201  * The YBarGraph widget will automatically assign some default colors (one
202  * of at least 5 different ones) if none are specified.
203  **/
204  YBarGraphSegment( int value = 0,
205  const std::string & label = std::string(),
206  const YColor & segmentColor = YColor(),
207  const YColor & textColor = YColor() )
208  : _value( value )
209  , _label( label )
210  , _segmentColor( segmentColor )
211  , _textColor( textColor )
212  {}
213 
214  /**
215  * Return the current value of this segment.
216  **/
217  int value() const { return _value; }
218 
219  /**
220  * Set the value of this segment.
221  **/
222  void setValue( int newValue ) { _value = newValue; }
223 
224  /**
225  * Return the current text label of this segment.
226  * Any %1 placeholder will be returned as %1 (not expanded).
227  **/
228  std::string label() const { return _label; }
229 
230  /**
231  * Set the text label of this segment.
232  * Use %1 as a placeholder for the current value.
233  **/
234  void setLabel( const std::string & newLabel ) { _label = newLabel; }
235 
236  /**
237  * Return the segment background color.
238  **/
239  YColor segmentColor() const { return _segmentColor; }
240 
241  /**
242  * Return 'true' if this segment's background color is defined,
243  * i.e. it has a real RGB value and was not just created with the default
244  * constructor.
245  **/
246  bool hasSegmentColor() const { return _segmentColor.isDefined(); }
247 
248  /**
249  * Set this segment's background color.
250  **/
251  void setSegmentColor( const YColor & color ) { _segmentColor = color; }
252 
253  /**
254  * Return this segment's text color.
255  **/
256  YColor textColor() const { return _textColor; }
257 
258  /**
259  * Return 'true' if this segment's text color is defined,
260  * i.e. it has a real RGB value and was not just created with the default
261  * constructor.
262  **/
263  bool hasTextColor() const { return _textColor.isDefined(); }
264 
265  /**
266  * Set this segment's text color.
267  **/
268  void setTextColor( const YColor & color ) { _textColor = color; }
269 
270 
271 private:
272 
273  int _value;
274  std::string _label;
275  YColor _segmentColor;
276  YColor _textColor;
277 };
278 
279 
280 
281 /**
282  * Helper class for multiple updates to a YBarGraph widget:
283  * This will hold back display updates until this object goes out of scope.
284  **/
286 {
287 public:
288  /**
289  * Constructor.
290  *
291  * This will make the corresponding YBarGraph widget hold back any
292  * pending display updates (due to changed values, labels, or colors) until
293  * this object is destroyed (goes out of scope).
294  *
295  * Create objects of this class on the stack (as local variables) and
296  * simply let them go out of scope.
297  *
298  * Example:
299  *
300  * {
301  * YBarGraphMultiUpdate multiUpdate( myBarGraph );
302  * myBarGraph->setValue( 0, 42 ); // No display update yet
303  * myBarGraph->setValue( 1, 84 ); // No display update yet
304  * myBarGraph->setValue( 2, 21 ); // No display update yet
305  *
306  * } // multiUpdate goes out of scope, will trigger display update now
307  *
308  **/
309  YBarGraphMultiUpdate( YBarGraph * barGraph );
310 
311  /**
312  * Destructor.
313  *
314  * This will trigger display updates of the corresponding YBarGraph widget
315  * if any are necessary.
316  **/
318 
319 private:
320 
321  YBarGraph * _barGraph;
322 };
323 
324 
325 #endif // YBarGraph_h
One segment of a YBarGraph.
Definition: YBarGraph.h:186
virtual bool setProperty(const std::string &propertyName, const YPropertyValue &val)
Set a property.
Definition: YBarGraph.cc:195
virtual YPropertyValue getProperty(const std::string &propertyName)
Get a property.
Definition: YBarGraph.cc:211
YBarGraphSegment(int value=0, const std::string &label=std::string(), const YColor &segmentColor=YColor(), const YColor &textColor=YColor())
Constructor.
Definition: YBarGraph.h:204
YColor textColor() const
Return this segment&#39;s text color.
Definition: YBarGraph.h:256
Transport class for the value of simple properties.
Definition: YProperty.h:104
virtual const YPropertySet & propertySet()
Return this class&#39;s property set.
Definition: YBarGraph.cc:174
A set of properties to check names and types against.
Definition: YProperty.h:197
A graph showing partitioning of a whole.
Definition: YBarGraph.h:40
YWidget * parent() const
Return this widget&#39;s parent or 0 if it doesn&#39;t have a parent.
Definition: YWidget.cc:269
void setLabel(int segmentIndex, const std::string &newLabel)
Set the label of the segment with the specified index (from 0 on).
Definition: YBarGraph.cc:138
Helper class to define an RGB color.
Definition: YColor.h:34
void setLabel(const std::string &newLabel)
Set the text label of this segment.
Definition: YBarGraph.h:234
void setSegmentColor(int segmentIndex, const YColor &color)
Set the background color of the segment with the specified index (from 0 on).
Definition: YBarGraph.cc:148
void deleteAllSegments()
Delete all segments.
Definition: YBarGraph.cc:104
void setTextColor(int segmentIndex, const YColor &color)
Set the text color of the segment with the specified index (from 0 on).
Definition: YBarGraph.cc:161
std::string label() const
Return the current text label of this segment.
Definition: YBarGraph.h:228
bool hasSegmentColor() const
Return &#39;true&#39; if this segment&#39;s background color is defined, i.e.
Definition: YBarGraph.h:246
void setTextColor(const YColor &color)
Set this segment&#39;s text color.
Definition: YBarGraph.h:268
YColor segmentColor() const
Return the segment background color.
Definition: YBarGraph.h:239
virtual ~YBarGraph()
Destructor.
Definition: YBarGraph.cc:76
int value() const
Return the current value of this segment.
Definition: YBarGraph.h:217
void setValue(int segmentIndex, int newValue)
Set the value of the segment with the specifie index (from 0 on).
Definition: YBarGraph.cc:128
YBarGraph(YWidget *parent)
Constructor.
Definition: YBarGraph.cc:67
void addSegment(const YBarGraphSegment &segment)
Add one segment.
Definition: YBarGraph.cc:96
int segments()
Return the current number of segments.
Definition: YBarGraph.cc:121
void setSegmentColor(const YColor &color)
Set this segment&#39;s background color.
Definition: YBarGraph.h:251
bool hasTextColor() const
Return &#39;true&#39; if this segment&#39;s text color is defined, i.e.
Definition: YBarGraph.h:263
Abstract base class of all UI widgets.
Definition: YWidget.h:54
virtual const char * widgetClass() const
Return a descriptive name of this widget class for logging, debugging etc.
Definition: YBarGraph.h:60
const YBarGraphSegment & segment(int segmentIndex) const
Return the segment with the specified index (from 0 on).
Definition: YBarGraph.cc:112
virtual void doUpdate()=0
Perform a display update after any change to any of the segments.
Helper class for multiple updates to a YBarGraph widget: This will hold back display updates until th...
Definition: YBarGraph.h:285
void setValue(int newValue)
Set the value of this segment.
Definition: YBarGraph.h:222