[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-commits
Subject:    KDE/kdebase/workspace/powerdevil/daemon
From:       Dario Freddi <drf () kde ! org>
Date:       2011-01-24 10:12:00
Message-ID: 20110124101200.2E198AC8BD () svn ! kde ! org
[Download RAW message or body]

SVN commit 1216707 by dafre:

Apidox for Action and ActionConfig

 M  +123 -0    powerdevilaction.h  
 M  +74 -0     powerdevilactionconfig.h  


--- trunk/KDE/kdebase/workspace/powerdevil/daemon/powerdevilaction.h #1216706:1216707
@@ -35,34 +35,157 @@
 class BackendInterface;
 class Core;
 
+/**
+ * @brief The base class for Power Management Actions
+ *
+ * The Action class is the very base class for writing a new Power Management \
action. + * Developers wishing to implement their own action are supposed to subclass \
Action. + *
+ * @par Creating a brand new Action
+ *
+ * If you are already familiar with KDE's plugin system, you have to know that \
actions are + * nothing but a KService plugin which will be loaded on demand. Each \
action has an ID associated to it + * which represents it in the config file and \
uniquely identifies it in the loading phase. + *
+ * In addition to standard parameters, the .desktop file representing your action \
should contain the following + * entries:
+ *
+ * @code
+ * X-KDE-ServiceTypes=PowerDevil/Action
+ * X-KDE-PowerDevil-Action-ID=YourActionID
+ * X-KDE-PowerDevil-Action-IsBundled=false
+ * X-KDE-PowerDevil-Action-UIComponentLibrary=myactionplugin_config
+ * X-KDE-PowerDevil-Action-ConfigPriority=98
+ * @endcode
+ *
+ * The @c UIComponentLibrary field refers to the library which contains the \
configuration UI + * for your action. Please see ActionConfig documentation for more \
details. + *
+ * The @c ConfigPriority is relevant to the configuration UI as well, and determines \
where your config UI will appear. + * The higher the number, the higher your config \
UI will be in the list of actions. Choose this value wisely: usually + * only very \
basic power management functions should have a value > 50. + *
+ * The most important functions you need to reimplement are loadAction and \
triggerImpl. The first is called + * whenever an action is loaded, carrying the \
action's configuration. The other is called whenever + * the action is triggered. You \
usually want to process the action here as triggerImpl is guaranteed + * to be called \
just when policies are satisfied. + *
+ * @par Handling policies from within the action
+ *
+ * As you might know, the KDE Power Management system features a very efficient \
policy handler, which + * prevents Power Management actions when certain condition \
occurs. The integration with Actions is very easy: + * in your Action's constructor, \
you want to call setRequiredPolicies, stating which policies have to be + * satisfied \
to perform the action. For example, if your action should not be performed whenever \
the session + * cannot be interrupted, you would pass @c InterruptSession.
+ *
+ * Done that, your action is already obeying to the policy. trigger, in fact, calls \
triggerImpl just when + * the policies are allowing your action to be performed.
+ *
+ * @since 4.6
+ */
 class KDE_EXPORT Action : public QObject
 {
     Q_OBJECT
     Q_DISABLE_COPY(Action)
 
 public:
+    /**
+     * Default constructor
+     */
     explicit Action(QObject *parent);
+    /**
+     * Default destructor
+     */
     virtual ~Action();
 
+    /**
+     * Reimplement this function when creating a new Action. This function is called \
whenever the action is loaded or +     * its configuration changes. It carries the \
KConfigGroup associated with your action and generated from your +     * config \
interface. +     *
+     * @param config The action's configuration which should be loaded.
+     * @returns Whether the action has been successfully loaded.
+     *
+     * @see ActionConfig
+     */
     virtual bool loadAction(const KConfigGroup &config) = 0;
+    /**
+     * Unloads the action. You usually shouldn't reimplement this function: \
reimplement onUnloadAction instead. +     *
+     * @returns Whether the action has been successfully unloaded
+     */
     virtual bool unloadAction();
 
+    /**
+     * Triggers the action with the given argument. This function is meant to be \
used by the caller only - +     * if you are implementing your own action, \
reimplement triggerImpl instead. +     *
+     * @param args The arguments for triggering the action
+     */
     void trigger(const QVariantMap &args);
 
 protected:
+    /**
+     * Registers an idle timeout for this action. Call this function and not \
KIdleTime directly to take advantage +     * of Action's automated handling of idle \
timeouts. Also, please reimplement onIdleTimeout instead of listening +     * to \
KIdleTime's signals to catch idle timeout events. +     *
+     * @param msec The idle timeout to be registered in milliseconds.
+     */
     void registerIdleTimeout(int msec);
+    /**
+     * Sets the required policies needed for this Action to run. Usually, you want \
to call this function in your +     * Action's constructor.
+     *
+     * @param requiredPolicies A set of policies which are required to run this \
action. It can be empty if your +     *                         Action does not rely \
on policies. +     */
     void setRequiredPolicies(PowerDevil::PolicyAgent::RequiredPolicies \
requiredPolicies);  
+    /**
+     * This function's body should undertake the Action's execution. It has to be \
reimplemented in a new Action. +     *
+     * @param args The arguments for triggering the action
+     */
     virtual void triggerImpl(const QVariantMap &args) = 0;
 
+    /**
+     * @returns The BackendInterface
+     */
     PowerDevil::BackendInterface *backend();
+    /**
+     * @returns The PowerDevil Core
+     */
     PowerDevil::Core *core();
 
 protected Q_SLOTS:
+    /**
+     * This function is called whenever a profile is loaded. Please note that this \
is slightly different from +     * loadAction: in fact a profile can be reloaded \
without having the action change its configuration. +     * If your action should do \
something as soon as a profile switches, it should be done inside this function. +    \
*/  virtual void onProfileLoad() = 0;
+    /**
+     * This slot is triggered whenever an idle timeout registered with \
registerIdleTimeout is reached. +     *
+     * @param msec The idle timeout reached in milliseconds
+     */
     virtual void onIdleTimeout(int msec) = 0;
+    /**
+     * This slot is triggered whenever the PC wakes up from an Idle state. It is @b \
always called after a registered +     * idle timeout has been reached.
+     */
     virtual void onWakeupFromIdle() = 0;
+    /**
+     * This function is called when the profile is unloaded.
+     */
     virtual void onProfileUnload() = 0;
+    /**
+     * This function is called when the action is unloaded. You usually want to put \
what would have gone in your +     * destructor here.
+     *
+     * @returns Whether the action was unloaded successfully.
+     */
     virtual bool onUnloadAction();
 
 Q_SIGNALS:
--- trunk/KDE/kdebase/workspace/powerdevil/daemon/powerdevilactionconfig.h \
#1216706:1216707 @@ -29,27 +29,101 @@
 
 namespace PowerDevil {
 
+/**
+ * @brief The base class for Action's config interfaces
+ *
+ * This class should be reimplemented when creating a new Action. It is used to \
generate + * a configuration UI for your action and integrate it into KDE Power \
Management System's + * config module seamlessly.
+ *
+ * @par Creating an ActionConfig
+ *
+ * If you already have been through creating an Action, you have seen that Action's \
desktop + * file contains already all the needed information for loading its \
respective ActionConfig. For this + * reason, despite ActionConfig being a plugin, \
you do not need to create a desktop file for it - + * you just have to write the \
correct info into the Action's one. + *
+ * @par The key/value pair rationale
+ *
+ * The config UI works in a key/value fashion, where value is a generic QWidget. \
This is done + * to keep the UI consistent without hurting the flexibility of the \
implementation. + * Please remember to keep the configuration as easy and essential \
as possible: if you have gone + * beyond 2 rows, you might be doing something wrong.
+ *
+ * @par Loading and saving configuration
+ *
+ * Of course, you should also be providing the logic for saving and loading your \
action's configuration. + * This is done through KConfigGroup: your action has a \
KConfigGroup assigned by KDE Power Management System + * which can be accessed \
through configGroup or overwritten through setConfigGroup. The very same group + * \
you are loading/saving here will be the one passed to Action::loadAction. + *
+ * @see Action
+ *
+ * @since 4.6
+ */
 class KDE_EXPORT ActionConfig : public QObject
 {
     Q_OBJECT
     Q_DISABLE_COPY(ActionConfig)
 
 public:
+    /**
+     * Default constructor
+     */
     ActionConfig(QObject *parent);
+    /**
+     * Default destructor
+     */
     virtual ~ActionConfig();
 
+    /**
+     * @returns The KConfigGroup associated to this action, where data should be \
saved (and loaded) +     *
+     * @note You should not track this KConfigGroup, as it might change from profile \
to profile. +     *       Always use this function to access it.
+     */
     KConfigGroup configGroup() const;
+    /**
+     * Overwrites the config group associated with this Action with @c group.
+     *
+     * @param group A KConfigGroup carrying the settings for this Action.
+     */
     void setConfigGroup(const KConfigGroup &group);
 
+    /**
+     * This function should return the key/value pairs containing your Action's \
configuration UI. +     *
+     * @returns A list of QString, QWidget pairs representing your Action's \
configuration UI +     */
     virtual QList< QPair< QString, QWidget* > > buildUi() = 0;
 
+    /**
+     * This function gets called whenever the parent module requires to load a \
specific configuration. This +     * usually occurs when @c configGroup is updated, \
for example due to the fact that the user wants to modify +     * a different \
profile. In this function, you should update the info contained in the widgets \
generated +     * by @c buildUi accordingly.
+     */
     virtual void load() = 0;
+    /**
+     * This function gets called whenever the parent module requires to save the \
configuration. Usually, you +     * want to read values from the widgets generated \
with @c buildUi and call @c setConfigGroup to update the +     * Action's \
configuration. +     */
     virtual void save() = 0;
 
 protected Q_SLOTS:
+    /**
+     * Call this slot whenever the user makes some changes to the widgets.
+     */
     void setChanged();
 
 Q_SIGNALS:
+    /**
+     * This signal gets emitted every time the user changes the (unsaved) \
configuration. Do not emit this signal +     * directly: call setChanged instead.
+     *
+     * @see setChanged
+     */
     void changed();
 
 private:


[prev in list] [next in list] [prev in thread] [next in thread]