libyui  3.0.10
/usr/src/RPM/BUILD/libyui-3.0.10/src/YBarGraph.h
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:         YBarGraph.h
00020 
00021   Author:       Stefan Hundhammer <sh@suse.de>
00022 
00023 /-*/
00024 
00025 #ifndef YBarGraph_h
00026 #define YBarGraph_h
00027 
00028 #include "YWidget.h"
00029 #include "YColor.h"
00030 
00031 
00032 class YBarGraphPrivate;
00033 class YBarGraphSegment;
00034 
00035 
00036 class YBarGraph : public YWidget
00037 {
00038     friend class YBarGraphMultiUpdate;
00039 
00040 protected:
00041     /**
00042      * Constructor.
00043      **/
00044     YBarGraph( YWidget * parent );
00045 
00046 public:
00047     /**
00048      * Destructor.
00049      **/
00050     virtual ~YBarGraph();
00051 
00052     /**
00053      * Return a descriptive name of this widget class for logging,
00054      * debugging etc.
00055      **/
00056     virtual const char * widgetClass() const { return "YBarGraph"; }
00057 
00058     /**
00059      * Add one segment.
00060      *
00061      * If the segment's background and text colors are not explicitly
00062      * specified, the YBarGraph widget will assign them from a list of (at
00063      * least 5 different) color sets.
00064      *
00065      * When adding multiple segments, use a YBarGraphMultiUpdate object for
00066      * improved performance to hold back display updates until all segments are
00067      * added.
00068      **/
00069     void addSegment( const YBarGraphSegment & segment );
00070 
00071     /**
00072      * Delete all segments.
00073      **/
00074     void deleteAllSegments();
00075 
00076     /**
00077      * Return the current number of segments.
00078      **/
00079     int segments();
00080 
00081     /**
00082      * Return the segment with the specified index (from 0 on).
00083      *
00084      * This will throw an exception if there are not this many segments.
00085      **/
00086     const YBarGraphSegment & segment( int segmentIndex ) const;
00087 
00088     /**
00089      * Set the value of the segment with the specifie index (from 0 on).
00090      *
00091      * This will throw an exception if there are not this many segments.
00092      *
00093      * Note: Use a YBarGraphMultiUpdate object for improved performance
00094      * when doing multiple changes at the same time.
00095      **/
00096     void setValue( int segmentIndex, int newValue );
00097 
00098     /**
00099      * Set the label of the segment with the specified index (from 0 on).
00100      * Use %1 as a placeholder for the current value.
00101      *
00102      * This will throw an exception if there are not this many segments.
00103      *
00104      * Note: Use a YBarGraphMultiUpdate object for improved performance
00105      * when doing multiple changes at the same time.
00106      **/
00107     void setLabel( int segmentIndex, const std::string & newLabel );
00108 
00109     /**
00110      * Set the background color of the segment with the specified index
00111      * (from 0 on).
00112      *
00113      * This will throw an exception if there are not this many segments
00114      * or if the color is undefined.
00115      **/
00116     void setSegmentColor( int segmentIndex, const YColor & color );
00117 
00118     /**
00119      * Set the text color of the segment with the specified index
00120      * (from 0 on).
00121      *
00122      * This will throw an exception if there are not this many segments
00123      * or if the color is undefined.
00124      **/
00125     void setTextColor( int segmentIndex, const YColor & color );
00126 
00127     /**
00128      * Set a property.
00129      * Reimplemented from YWidget.
00130      *
00131      * This function may throw YUIPropertyExceptions.
00132      *
00133      * This function returns 'true' if the value was successfully set and
00134      * 'false' if that value requires special handling (not in error cases:
00135      * those are covered by exceptions).
00136      **/
00137     virtual bool setProperty( const std::string & propertyName,
00138                               const YPropertyValue & val );
00139 
00140     /**
00141      * Get a property.
00142      * Reimplemented from YWidget.
00143      *
00144      * This method may throw YUIPropertyExceptions.
00145      **/
00146     virtual YPropertyValue getProperty( const std::string & propertyName );
00147 
00148     /**
00149      * Return this class's property set.
00150      * This also initializes the property upon the first call.
00151      *
00152      * Reimplemented from YWidget.
00153      **/
00154     virtual const YPropertySet & propertySet();
00155 
00156 
00157 protected:
00158     /**
00159      * Perform a display update after any change to any of the segments.
00160      *
00161      * Derived classes are required to implement this.
00162      **/
00163     virtual void doUpdate() = 0;
00164 
00165 
00166 private:
00167     /**
00168      * Conditionally perform display update if not currently postponed.
00169      **/
00170     void updateDisplay();
00171 
00172     ImplPtr<YBarGraphPrivate> priv;
00173 };
00174 
00175 
00176 
00177 
00178 /**
00179  * Helper class to describe one segment of a YBarGraph.
00180  **/
00181 class YBarGraphSegment
00182 {
00183 public:
00184     /**
00185      * Constructor.
00186      *
00187      * 'value' is the initial value of this segment.
00188      *
00189      * 'label' is the label text in the segment.
00190      *  Use %1 as a placeholder for the current  value.
00191      *
00192      * 'segmentColor' is the background color of this segment.
00193      *
00194      * 'textColor' is the color for the label text.
00195      *
00196      * The YBarGraph widget will automatically assign some default colors (one
00197      * of at least 5 different ones) if none are specified.
00198      **/
00199     YBarGraphSegment( int                       value           = 0,
00200                       const std::string &       label           = std::string(),
00201                       const YColor &            segmentColor    = YColor(),
00202                       const YColor &            textColor       = YColor() )
00203         : _value( value )
00204         , _label( label )
00205         , _segmentColor( segmentColor )
00206         , _textColor( textColor )
00207         {}
00208 
00209     /**
00210      * Return the current value of this segment.
00211      **/
00212     int value() const { return _value; }
00213 
00214     /**
00215      * Set the value of this segment.
00216      **/
00217     void setValue( int newValue ) { _value = newValue; }
00218 
00219     /**
00220      * Return the current text label of this segment.
00221      * Any %1 placeholder will be returned as %1 (not expanded).
00222      **/
00223     std::string label() const { return _label; }
00224 
00225     /**
00226      * Set the text label of this segment.
00227      * Use %1 as a placeholder for the current value.
00228      **/
00229     void setLabel( const std::string & newLabel ) { _label = newLabel; }
00230 
00231     /**
00232      * Return the segment background color.
00233      **/
00234     YColor segmentColor() const { return _segmentColor; }
00235 
00236     /**
00237      * Return 'true' if this segment's background color is defined,
00238      * i.e. it has a real RGB value and was not just created with the default
00239      * constructor.
00240      **/
00241     bool hasSegmentColor() const { return _segmentColor.isDefined(); }
00242 
00243     /**
00244      * Set this segment's background color.
00245      **/
00246     void setSegmentColor( const YColor & color ) { _segmentColor = color; }
00247 
00248     /**
00249      * Return this segment's text color.
00250      **/
00251     YColor textColor() const { return _textColor; }
00252 
00253     /**
00254      * Return 'true' if this segment's text color is defined,
00255      * i.e. it has a real RGB value and was not just created with the default
00256      * constructor.
00257      **/
00258     bool hasTextColor() const { return _textColor.isDefined(); }
00259 
00260     /**
00261      * Set this segment's text color.
00262      **/
00263     void setTextColor( const YColor & color ) { _textColor = color; }
00264 
00265 
00266 private:
00267 
00268     int         _value;
00269     std::string _label;
00270     YColor      _segmentColor;
00271     YColor      _textColor;
00272 };
00273 
00274 
00275 
00276 /**
00277  * Helper class for multiple updates to a YBarGraph widget:
00278  * This will hold back display updates until this object goes out of scope.
00279  **/
00280 class YBarGraphMultiUpdate
00281 {
00282 public:
00283     /**
00284      * Constructor.
00285      *
00286      * This will make the corresponding YBarGraph widget hold back any
00287      * pending display updates (due to changed values, labels, or colors) until
00288      * this object is destroyed (goes out of scope).
00289      *
00290      * Create objects of this class on the stack (as local variables) and
00291      * simply let them go out of scope.
00292      *
00293      * Example:
00294      *
00295      * {
00296      *     YBarGraphMultiUpdate multiUpdate( myBarGraph );
00297      *     myBarGraph->setValue( 0, 42 ); // No display update yet
00298      *     myBarGraph->setValue( 1, 84 ); // No display update yet
00299      *     myBarGraph->setValue( 2, 21 ); // No display update yet
00300      *
00301      * } // multiUpdate goes out of scope, will trigger display update now
00302      *
00303      **/
00304     YBarGraphMultiUpdate( YBarGraph * barGraph );
00305 
00306     /**
00307      * Destructor.
00308      *
00309      * This will trigger display updates of the corresponding YBarGraph widget
00310      * if any are necessary.
00311      **/
00312     ~YBarGraphMultiUpdate();
00313 
00314 private:
00315 
00316     YBarGraph * _barGraph;
00317 };
00318 
00319 
00320 #endif // YBarGraph_h
 All Classes Functions Variables Enumerations Friends