File indexing completed on 2025-02-02 14:19:56
0001 /* 0002 This file is part of the KDE project 0003 SPDX-FileCopyrightText: 2008 Rafael Fernández López <ereslibre@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.0-or-later 0006 */ 0007 0008 #ifndef KCAPACITYBAR_H 0009 #define KCAPACITYBAR_H 0010 0011 #include <QWidget> 0012 #include <memory> 0013 0014 #include <kwidgetsaddons_export.h> 0015 0016 class QPaintEvent; 0017 0018 /** 0019 * @class KCapacityBar kcapacitybar.h KCapacityBar 0020 * 0021 * @brief This widget shows a bar which is filled to show the level of usage of 0022 * a certain device. 0023 * 0024 * This widget represents a bar which goal is to show the level of usage of a 0025 * device. Its look is similar to a progress bar, but different, because this 0026 * widget does not want to give a notion of progress. 0027 * 0028 * @since 4.2 0029 * 0030 * \image html kcapacitybar.png "KCapacityBar Widget" 0031 * 0032 * @author Rafael Fernández López <ereslibre@kde.org> 0033 */ 0034 class KWIDGETSADDONS_EXPORT KCapacityBar : public QWidget 0035 { 0036 Q_OBJECT 0037 0038 Q_PROPERTY(int value READ value WRITE setValue) 0039 Q_PROPERTY(QString text READ text WRITE setText) 0040 Q_PROPERTY(DrawTextMode drawTextMode READ drawTextMode WRITE setDrawTextMode) 0041 Q_PROPERTY(bool fillFullBlocks READ fillFullBlocks WRITE setFillFullBlocks) 0042 Q_PROPERTY(bool continuous READ continuous WRITE setContinuous) 0043 Q_PROPERTY(int barHeight READ barHeight WRITE setBarHeight) 0044 Q_PROPERTY(Qt::Alignment horizontalTextAlignment READ horizontalTextAlignment WRITE setHorizontalTextAlignment) 0045 0046 public: 0047 enum DrawTextMode { 0048 DrawTextInline = 0, ///< If any text set, draw it into the capacity bar 0049 DrawTextOutline, ///< If any text set, draw it out of the capacity bar 0050 }; 0051 Q_ENUM(DrawTextMode) 0052 0053 /** 0054 * Constructs a capacity bar with DrawTextOutline as draw text mode. 0055 * @param parent The parent of the widget. 0056 * @since 5.24 0057 */ 0058 explicit KCapacityBar(QWidget *parent = nullptr); 0059 0060 /** 0061 * Capacity bar constructor. 0062 * 0063 * @param drawTextMode If any text set, whether to draw it into the capacity bar 0064 * or not. 0065 * @param parent The parent of the widget. 0066 */ 0067 explicit KCapacityBar(DrawTextMode drawTextMode, QWidget *parent = nullptr); 0068 ~KCapacityBar() override; 0069 0070 /** 0071 * Capacity bar fill value. 0072 * 0073 * @param value This parameter can take values from 0 to 100. 0074 * 0075 * @note Its value is 0 by default. 0076 */ 0077 void setValue(int value); 0078 0079 /** 0080 * @return The fill value of the capacity bar. 0081 */ 0082 int value() const; 0083 0084 /** 0085 * Sets the text for the capacity bar. 0086 * 0087 * @param text The text that the capacity bar will show. 0088 * 0089 * @note This is an empty string by default. 0090 */ 0091 void setText(const QString &text); 0092 0093 /** 0094 * @return The text that the capacity bar will show. 0095 */ 0096 QString text() const; 0097 0098 /** 0099 * When the capacity bar is non-continuous, sets whether the last block 0100 * shown should be drawn full or can be cut off (depending on the capacity 0101 * bar width, and the value set on it). 0102 * 0103 * @param fillFullBlocks If true, the last block drawn will be fully filled, 0104 * on other case, the last block drawn could be cut off. 0105 * 0106 * @note This method is only relevant if the capacity bar is in 0107 * non-continuous mode. 0108 * 0109 * @note Its value is true by default. 0110 * 0111 * @see setContinuous, continuous 0112 */ 0113 void setFillFullBlocks(bool fillFullBlocks); 0114 0115 /** 0116 * @return Whether the last block shown can be cut off when necessary. 0117 */ 0118 bool fillFullBlocks() const; 0119 0120 /** 0121 * Sets whether the fill of the capacity bar should be continuous or in 0122 * block mode. 0123 * 0124 * @param continuous If true, the fill of the capacity bar is done in a 0125 * continuous way. In other case, the fill is done with 0126 * separated blocks. 0127 * 0128 * @note Its value is true by default. 0129 */ 0130 void setContinuous(bool continuous); 0131 0132 /** 0133 * @return Whether the fill of the capacity bar should be continuous or 0134 * block-based. 0135 */ 0136 bool continuous() const; 0137 0138 /** 0139 * Sets the height (in pixels) of the bar. 0140 * 0141 * @param barHeight The preferred height (in pixels) of the capacity bar. 0142 * 0143 * @note If you set a certain text and the capacity bar is in inline mode, 0144 * the height of the bar will be the maximum of the font height and 0145 * this value. 0146 * 0147 * @note If you set a certain text and the capacity bar is in outline mode, 0148 * the height of the whole capacity bar will be bigger than this 0149 * value. Take in count the height of this widget is got from adding 0150 * the bar height, the font metrics height and a small separator 0151 * between the bar and the outline text. 0152 * 0153 * @note Its value is 12 pixels by default. 0154 */ 0155 void setBarHeight(int barHeight); 0156 0157 /** 0158 * @return The preferred height of the capacity bar. 0159 */ 0160 int barHeight() const; 0161 0162 /** 0163 * If the capacity bar is in outline text mode, draw the text with 0164 * @p textAlignment alignment. 0165 * 0166 * @param textAlignment Sets the horizontal alignment for the text if 0167 * the capacity bar is in outline text mode. 0168 * 0169 * @note If @p textAlignemt contains vertical alignment flags, they will be 0170 * ignored. 0171 * 0172 * @note If the capacity bar is in inline text mode, the text is always 0173 * centered, and both vertical and horizontal flags set through this 0174 * method are ignored. 0175 * 0176 * @note Its value is centered by default. 0177 */ 0178 void setHorizontalTextAlignment(Qt::Alignment textAlignment); 0179 0180 /** 0181 * @return The horizontal alignment for the text that will be drawn. 0182 */ 0183 Qt::Alignment horizontalTextAlignment() const; 0184 0185 /** 0186 * Set the way text is drawn if any is set 0187 * 0188 * @param mode If any text set, whether to draw it into the capacity bar 0189 * or not. 0190 */ 0191 void setDrawTextMode(DrawTextMode mode); 0192 0193 /** 0194 * The way text is drawn, inside the capacity bar or outside of it 0195 */ 0196 DrawTextMode drawTextMode() const; 0197 0198 /** 0199 * This method allows you to draw the widget, directly, for example on 0200 * item delegates. You only need the painter object and the rect where 0201 * this widget should be drawn. 0202 */ 0203 void drawCapacityBar(QPainter *p, const QRect &rect) const; 0204 0205 // Reimplemented from QWidget 0206 QSize minimumSizeHint() const override; 0207 0208 protected: 0209 // Reimplemented from QWidget 0210 void paintEvent(QPaintEvent *event) override; 0211 0212 // Reimplemented from QWidget 0213 void changeEvent(QEvent *event) override; 0214 0215 private: 0216 /** 0217 * @internal 0218 */ 0219 std::unique_ptr<class KCapacityBarPrivate> const d; 0220 }; 0221 0222 #endif