← Back to branch summary

~ubuntu-branches/ubuntu/utopic/kde-workspace/utopic-proposed

« back to all changes in this revision

Viewing changes to powerdevil/daemon/powerdevilactionconfig.h

  • Committer: Bazaar Package Importer
  • Author(s): Michał Zając
  • Date: 2011-07-09 08:31:15 UTC
  • Revision ID: james.westby@ubuntu.com-20110709083115-ohyxn6z93mily9fc
Tags: upstream-4.6.90
Import upstream version 4.6.90

Show diffs side-by-side

added added

removed removed

Lines of Context:
powerdevil/daemon/powerdevilactionconfig.h
 
1
/***************************************************************************
 
2
 *   Copyright (C) 2010 by Dario Freddi <drf@kde.org>                      *
 
3
 *                                                                         *
 
4
 *   This program is free software; you can redistribute it and/or modify  *
 
5
 *   it under the terms of the GNU General Public License as published by  *
 
6
 *   the Free Software Foundation; either version 2 of the License, or     *
 
7
 *   (at your option) any later version.                                   *
 
8
 *                                                                         *
 
9
 *   This program is distributed in the hope that it will be useful,       *
 
10
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
 
11
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
 
12
 *   GNU General Public License for more details.                          *
 
13
 *                                                                         *
 
14
 *   You should have received a copy of the GNU General Public License     *
 
15
 *   along with this program; if not, write to the                         *
 
16
 *   Free Software Foundation, Inc.,                                       *
 
17
 *   51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA .        *
 
18
 ***************************************************************************/
 
19
 
 
20
 
 
21
#ifndef POWERDEVIL_POWERDEVILACTIONCONFIG_H
 
22
#define POWERDEVIL_POWERDEVILACTIONCONFIG_H
 
23
 
 
24
#include <QtGui/QWidget>
 
25
 
 
26
#include <KConfigGroup>
 
27
 
 
28
#include <kdemacros.h>
 
29
 
 
30
namespace PowerDevil {
 
31
 
 
32
/**
 
33
 * @brief The base class for Action's config interfaces
 
34
 *
 
35
 * This class should be reimplemented when creating a new Action. It is used to generate
 
36
 * a configuration UI for your action and integrate it into KDE Power Management System's
 
37
 * config module seamlessly.
 
38
 *
 
39
 * @par Creating an ActionConfig
 
40
 *
 
41
 * If you already have been through creating an Action, you have seen that Action's desktop
 
42
 * file contains already all the needed information for loading its respective ActionConfig. For this
 
43
 * reason, despite ActionConfig being a plugin, you do not need to create a desktop file for it -
 
44
 * you just have to write the correct info into the Action's one.
 
45
 *
 
46
 * @par The key/value pair rationale
 
47
 *
 
48
 * The config UI works in a key/value fashion, where value is a generic QWidget. This is done
 
49
 * to keep the UI consistent without hurting the flexibility of the implementation.
 
50
 * Please remember to keep the configuration as easy and essential as possible: if you have gone
 
51
 * beyond 2 rows, you might be doing something wrong.
 
52
 *
 
53
 * @par Loading and saving configuration
 
54
 *
 
55
 * Of course, you should also be providing the logic for saving and loading your action's configuration.
 
56
 * This is done through KConfigGroup: your action has a KConfigGroup assigned by KDE Power Management System
 
57
 * which can be accessed through configGroup or overwritten through setConfigGroup. The very same group
 
58
 * you are loading/saving here will be the one passed to Action::loadAction.
 
59
 *
 
60
 * @see Action
 
61
 *
 
62
 * @since 4.6
 
63
 */
 
64
class KDE_EXPORT ActionConfig : public QObject
 
65
{
 
66
    Q_OBJECT
 
67
    Q_DISABLE_COPY(ActionConfig)
 
68
 
 
69
public:
 
70
    /**
 
71
     * Default constructor
 
72
     */
 
73
    ActionConfig(QObject *parent);
 
74
    /**
 
75
     * Default destructor
 
76
     */
 
77
    virtual ~ActionConfig();
 
78
 
 
79
    /**
 
80
     * @returns The KConfigGroup associated to this action, where data should be saved (and loaded)
 
81
     *
 
82
     * @note You should not track this KConfigGroup, as it might change from profile to profile.
 
83
     *       Always use this function to access it.
 
84
     */
 
85
    KConfigGroup configGroup() const;
 
86
    /**
 
87
     * Overwrites the config group associated with this Action with @c group.
 
88
     *
 
89
     * @param group A KConfigGroup carrying the settings for this Action.
 
90
     */
 
91
    void setConfigGroup(const KConfigGroup &group);
 
92
 
 
93
    /**
 
94
     * This function should return the key/value pairs containing your Action's configuration UI.
 
95
     *
 
96
     * @returns A list of QString, QWidget pairs representing your Action's configuration UI
 
97
     */
 
98
    virtual QList< QPair< QString, QWidget* > > buildUi() = 0;
 
99
 
 
100
    /**
 
101
     * This function gets called whenever the parent module requires to load a specific configuration. This
 
102
     * usually occurs when @c configGroup is updated, for example due to the fact that the user wants to modify
 
103
     * a different profile. In this function, you should update the info contained in the widgets generated
 
104
     * by @c buildUi accordingly.
 
105
     */
 
106
    virtual void load() = 0;
 
107
    /**
 
108
     * This function gets called whenever the parent module requires to save the configuration. Usually, you
 
109
     * want to read values from the widgets generated with @c buildUi and call @c setConfigGroup to update the
 
110
     * Action's configuration.
 
111
     */
 
112
    virtual void save() = 0;
 
113
 
 
114
protected Q_SLOTS:
 
115
    /**
 
116
     * Call this slot whenever the user makes some changes to the widgets.
 
117
     */
 
118
    void setChanged();
 
119
 
 
120
Q_SIGNALS:
 
121
    /**
 
122
     * This signal gets emitted every time the user changes the (unsaved) configuration. Do not emit this signal
 
123
     * directly: call setChanged instead.
 
124
     *
 
125
     * @see setChanged
 
126
     */
 
127
    void changed();
 
128
 
 
129
private:
 
130
    class Private;
 
131
    Private * const d;
 
132
};
 
133
 
 
134
}
 
135
 
 
136
#endif // POWERDEVIL_POWERDEVILACTIONCONFIG_H