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