Differential D22375 Diff 61506 src/kbusyindicatorwidget.h

Changeset View

Standalone View

View Options

src/kbusyindicatorwidget.h

  • This file was added.
1​/*
2​ Copyright 2019 Harald Sitter <sitter@kde.org>
3​
4​ This library is free software; you can redistribute it and/or
5​ modify it under the terms of the GNU Lesser General Public
6​ License as published by the Free Software Foundation; either
7​ version 2.1 of the License, or (at your option) version 3, or any
8​ later version accepted by the membership of KDE e.V. (or its
9​ successor approved by the membership of KDE e.V.), which shall
10​ act as a proxy defined in Section 6 of version 3 of the license.
11​
12​ This library is distributed in the hope that it will be useful,
13​ but WITHOUT ANY WARRANTY; without even the implied warranty of
14​ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15​ Lesser General Public License for more details.
16​
17​ You should have received a copy of the GNU Lesser General Public
18​ License along with this library. If not, see <https://www.gnu.org/licenses/>.
19​*/
20​
21​#ifndef KBUSYINDICATORWIDGET_H
22​#define KBUSYINDICATORWIDGET_H
23​
24​#include <kwidgetsaddons_export.h>
25​
26​#include <QWidget>
27​
28​/**
29​ * @brief Rotating spinning icon to indicate busyness
30​ *
31​ * When you need to communicate to the user that your application is busy with
32​ * something you'll want to use a KBusyIndicatorWidget to display an infinately
33​ * spinnning indicator icon.
34​ *
35​ * KBusyIndicatorWidget is set apart from KPixmapSequenceWidget in that it
36​ * does not render a pixmap sequence but rather animates a scaled Icon.
37​ * It can support multiple semi-abitrary sizes and quality is only limited
38​ * by the resolution of available icons. It is also easier to use as its use
39​ * is more specific.
40​ */
41​class KWIDGETSADDONS_EXPORT KBusyIndicatorWidget : public QWidget
kossebauUnsubmitted
Not Done

Any chance of getting some samples how this class is supposed to be used?

Sounds one should show & hide the complete widget when needed? How to best integrate in one's layout? As overlay?

BTW, the KDE HIG does not mention such a spinner. So the purpose from a KDE developer following the HIG raises a question with me wearing my naive hat :)
https://hig.kde.org/components/assistance/progress.html

kossebau: Any chance of getting some samples how this class is supposed to be used? Sounds one should…
sitterAuthorUnsubmitted
Not Done

I am not sure there is a generally useful code sample to give here. Certainly not a helpful one.

auto indicator = KBusyIndicatorWidget(this);
layout().addWidget(indicator);
auto label = QLabel("Busy watering the folowers", this);
layout().addWidget(this);

Maybe this, but then I am not convinced of its usefulessness. That's just how one would use any widget ^^

You could overlay it on something, or HBox it next to a label, or add it as permanent widget to a StatusBar, or VBox it with something. Sky's the limit really.

sitter: I am not sure there is a generally useful code sample to give here. Certainly not a helpful one.
42​{
43​ Q_OBJECT
44​ /**
45​ * Whether the indicator is running or not. For the indicator to actually
46​ * animate it must be both visible **and** running.
47​ */
48​ Q_PROPERTY(bool running READ running WRITE setRunning NOTIFY runningChanged)
cfeckUnsubmitted
Done

Why is this property needed? If the (parent) widget is no longer busy, this spinner needs to be hidden anyway.

cfeck: Why is this property needed? If the (parent) widget is no longer busy, this spinner needs to be…
sitterAuthorUnsubmitted
Done

Mimics the QML API, haven't given it any thought TBH. You can have the spinner visible but paused, I am not sure why exactly you'd want a paused spinner but that's what the property does anyway.

i.e.

  • you can have a visible but !running spinner which would simply be the spinner at whatever the last rotation update was.
  • a visibile and running spinner = animation
  • a running but !visible spinner = effectively noop

That said, I have no use case for it so we can remove it for the time being if you'd prefer.

sitter: Mimics the QML API, haven't given it any thought TBH. You can have the spinner visible but…
cfeckUnsubmitted
Done

Please remove it unless you find a justification. I don't like its name either (the widget isn't running).

cfeck: Please remove it unless you find a justification. I don't like its name either (the widget…
49​public:
50​ explicit KBusyIndicatorWidget(QWidget *parent = nullptr);
51​ virtual ~KBusyIndicatorWidget();
broulikUnsubmitted
Done

override instead

broulik: `override` instead
52​
53​ /// @returns Whether this widget is running.
cfeckUnsubmitted
Not Done

5.61.0

cfeck: 5.61.0
54​ bool running() const;
55​
56​public Q_SLOTS:
57​ /// Set whether this widget is running.
58​ void setRunning(bool running);
59​
kossebauUnsubmitted
Not Done

You can make this a non-nested class by implcitly forward declaring here:

class KBusyIndicatorWidgetPrivate *const d;

This allows not needing the Q_DECL_HIDDEN for the symbols of the then no longe nested private class.

Even more fancy:

QScopedPointer<class KBusyIndicatorWidgetPrivate> const d;

No longer the need to delete the d explicitely :)
Though perhaps not familiar in look of cod too many.

kossebau: You can make this a non-nested class by implcitly forward declaring here: ``` class…
60​Q_SIGNALS:
61​ /// Emitted when the running state changes.
62​ void runningChanged(bool running);
63​
64​protected:
65​ virtual void showEvent(QShowEvent *event) override;
broulikUnsubmitted
Done

override is enough

broulik: `override` is enough
broulikUnsubmitted
Not Done

I heard for good measure one should always re-implement the generic event just in case

broulik: I heard for good measure one should always re-implement the generic `event` just in case
sitterAuthorUnsubmitted
Not Done

Do we have this document somewhere? That's the sort of thing that sounds like an urban myth someone started in the 90's ^^

sitter: Do we have this document somewhere? That's the sort of thing that sounds like an urban myth…
66​ virtual void hideEvent(QHideEvent *event) override;
67​ virtual void resizeEvent(QResizeEvent *event) override;
68​ virtual void paintEvent(QPaintEvent *) override;
69​
70​private:
71​ class Private;
72​ Private *d;
cfeckUnsubmitted
Done

*const d

cfeck: `*const d`
73​};
74​
75​#endif // KBUSYINDICATORWIDGET_H