File: kcapacitybar.h

package info (click to toggle)
kwidgetsaddons 5.28.0-3
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 62,388 kB
  • ctags: 3,611
  • sloc: cpp: 26,647; python: 682; sh: 23; makefile: 6
file content (236 lines) | stat: -rw-r--r-- 7,643 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
/*
 * This file is part of the KDE project
 * Copyright (C) 2008 Rafael Fernández López <ereslibre@kde.org>
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public License
 * along with this library; see the file COPYING.LIB.  If not, write to
 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
 * Boston, MA 02110-1301, USA.
 */

#ifndef KCAPACITYBAR_H
#define KCAPACITYBAR_H

#include <QWidget>

#include <kwidgetsaddons_export.h>

class QPaintEvent;

/**
  * @brief This widget shows a bar which is filled to show the level of usage of
  *        a certain device.
  *
  * This widget represents a bar which goal is to show the level of usage of a
  * device. Its look is similar to a progress bar, but different, because this
  * widget does not want to give a notion of progress.
  *
  * @since 4.2
  *
  * \image html kcapacitybar.png "KDE Capacity Bar"
  *
  * @author Rafael Fernández López <ereslibre@kde.org>
  */
class KWIDGETSADDONS_EXPORT KCapacityBar
    : public QWidget
{
    Q_OBJECT

    Q_PROPERTY(int value READ value WRITE setValue)
    Q_PROPERTY(QString text READ text WRITE setText)
    Q_PROPERTY(DrawTextMode drawTextMode READ drawTextMode WRITE setDrawTextMode)
    Q_PROPERTY(bool fillFullBlocks READ fillFullBlocks WRITE setFillFullBlocks)
    Q_PROPERTY(bool continuous READ continuous WRITE setContinuous)
    Q_PROPERTY(int barHeight READ barHeight WRITE setBarHeight)
    Q_PROPERTY(Qt::Alignment horizontalTextAlignment READ horizontalTextAlignment
               WRITE setHorizontalTextAlignment)
    Q_ENUMS(DrawTextMode)

public:
    enum DrawTextMode {
        DrawTextInline = 0,     ///< If any text set, draw it into the capacity bar
        DrawTextOutline         ///< If any text set, draw it out of the capacity bar
    };


    /**
     * Constructs a capacity bar with DrawTextOutline as draw text mode.
     * @param parent The parent of the widget.
     * @since 5.24
     */
    explicit KCapacityBar(QWidget *parent = Q_NULLPTR);

    /**
      * Capacity bar constructor.
      *
      * @param drawTextMode If any text set, whether to draw it into the capacity bar
      *                     or not.
      * @param parent       The parent of the widget.
      */
    explicit KCapacityBar(DrawTextMode drawTextMode, QWidget *parent = 0);
    ~KCapacityBar();

    /**
      * Capacity bar fill value.
      *
      * @param value    This parameter can take values from 0 to 100.
      *
      * @note Its value is 0 by default.
      */
    void setValue(int value);

    /**
      * @return The fill value of the capacity bar.
      */
    int value() const;

    /**
      * Sets the text for the capacity bar.
      *
      * @param text The text that the capacity bar will show.
      *
      * @note This is an empty string by default.
      */
    void setText(const QString &text);

    /**
      * @return The text that the capacity bar will show.
      */
    QString text() const;

    /**
      * When the capacity bar is non-continuous, sets whether the last block
      * shown should be drawn full or can be cut off (depending on the capacity
      * bar width, and the value set on it).
      *
      * @param fillFullBlocks If true, the last block drawn will be fully filled,
      *                       on other case, the last block drawn could be cut off.
      *
      * @note This method is only relevant if the capacity bar is in
      *       non-continuous mode.
      *
      * @note Its value is true by default.
      *
      * @see setContinuous, continuous
      */
    void setFillFullBlocks(bool fillFullBlocks);

    /**
      * @return Whether the last block shown can be cut off when necessary.
      */
    bool fillFullBlocks() const;

    /**
      * Sets whether the fill of the capacity bar should be continuous or in
      * block mode.
      *
      * @param continuous If true, the fill of the capacity bar is done in a
      *                   continuous way. In other case, the fill is done with
      *                   separated blocks.
      *
      * @note Its value is true by default.
      */
    void setContinuous(bool continuous);

    /**
      * @return Whether the fill of the capacity bar should be continuous or
      *         block-based.
      */
    bool continuous() const;

    /**
      * Sets the height (in pixels) of the bar.
      *
      * @param barHeight The preferred height (in pixels) of the capacity bar.
      *
      * @note If you set a certain text and the capacity bar is in inline mode,
      *       the height of the bar will be the maximum of the font height and
      *       this value.
      *
      * @note If you set a certain text and the capacity bar is in outline mode,
      *       the height of the whole capacity bar will be bigger than this
      *       value. Take in count the height of this widget is got from adding
      *       the bar height, the font metrics height and a small separator
      *       between the bar and the outline text.
      *
      * @note Its value is 12 pixels by default.
      */
    void setBarHeight(int barHeight);

    /**
      * @return The preferred height of the capacity bar.
      */
    int barHeight() const;

    /**
      * If the capacity bar is in outline text mode, draw the text with
      * @p textAlignment alignment.
      *
      * @param textAlignment    Sets the horizontal alignment for the text if
      *                         the capacity bar is in outline text mode.
      *
      * @note If @p textAlignemt contains vertical alignment flags, they will be
      *       ignored.
      *
      * @note If the capacity bar is in inline text mode, the text is always
      *       centered, and both vertical and horizontal flags set through this
      *       method are ignored.
      *
      * @note Its value is centered by default.
      */
    void setHorizontalTextAlignment(Qt::Alignment textAlignment);

    /**
      * @return The horizontal alignment for the text that will be drawn.
      */
    Qt::Alignment horizontalTextAlignment() const;

    /**
     * Set the way text is drawn if any is set
     *
     * @param drawTextMode If any text set, whether to draw it into the capacity bar
     *                     or not.
     */
    void setDrawTextMode(DrawTextMode mode);

    /**
     * The way text is drawn, inside the capacity bar or outside of it
     */
    DrawTextMode drawTextMode() const;

    /**
      * This method allows you to draw the widget, directly, for example on
      * item delegates. You only need the painter object and the rect where
      * this widget should be drawn.
      */
    void drawCapacityBar(QPainter *p, const QRect &rect) const;

    // Reimplemented from QWidget
    QSize minimumSizeHint() const Q_DECL_OVERRIDE;

protected:
    // Reimplemented from QWidget
    void paintEvent(QPaintEvent *event) Q_DECL_OVERRIDE;

    // Reimplemented from QWidget
    void changeEvent(QEvent *event) Q_DECL_OVERRIDE;

private:
    /**
      * @internal
      */
    class Private;
    Private *const d;
};

#endif