reorder methods grouped for what they do
will make work in refactoring easier see http://community.kde.org/Plasma/libplasma2/API_Review/Applet
This commit is contained in:
Marco Martin
parent
dd00f217a5
commit
436d6c35e7
681
plasma/applet.h
681
plasma/applet.h
@ -75,114 +75,72 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
typedef QList<Applet*> List;
|
typedef QList<Applet*> List;
|
||||||
typedef QHash<QString, Applet*> Dict;
|
typedef QHash<QString, Applet*> Dict;
|
||||||
|
|
||||||
|
//CONSTRUCTORS
|
||||||
|
/**
|
||||||
|
* @param parent the QObject this applet is parented to
|
||||||
|
* @param serviceId the name of the .desktop file containing the
|
||||||
|
* information about the widget
|
||||||
|
* @param appletId a unique id used to differentiate between multiple
|
||||||
|
* instances of the same Applet type
|
||||||
|
*/
|
||||||
|
explicit Applet(QObject *parent = 0, const QString &serviceId = QString(), uint appletId = 0);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @param parent the QObject this applet is parented to
|
||||||
|
* @param info the plugin information object for this Applet
|
||||||
|
* @param appletId a unique id used to differentiate between multiple
|
||||||
|
* instances of the same Applet type
|
||||||
|
* @since 4.6
|
||||||
|
*/
|
||||||
|
explicit Applet(const KPluginInfo &info, QObject *parent = 0, uint appletId = 0);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @param parent the QObject this applet is parented to
|
||||||
|
* @param serviceId the name of the .desktop file containing the
|
||||||
|
* information about the widget
|
||||||
|
* @param appletId a unique id used to differentiate between multiple
|
||||||
|
* instances of the same Applet type
|
||||||
|
* @param args a list of strings containing two entries: the service id
|
||||||
|
* and the applet id
|
||||||
|
* @since 4.3
|
||||||
|
*/
|
||||||
|
explicit Applet(QObject *parent, const QString &serviceId, uint appletId, const QVariantList &args);
|
||||||
|
|
||||||
~Applet();
|
~Applet();
|
||||||
|
|
||||||
|
//BOOKKEEPING
|
||||||
/**
|
/**
|
||||||
* @return the id of this applet
|
* @return the id of this applet
|
||||||
*/
|
*/
|
||||||
uint id() const;
|
uint id() const;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the KConfigGroup to access the applets configuration.
|
* @return The type of immutability of this applet
|
||||||
*
|
*/
|
||||||
* This config object will write to an instance
|
ImmutabilityType immutability() const;
|
||||||
* specific config file named \<appletname\>\<instanceid\>rc
|
|
||||||
* in the Plasma appdata directory.
|
|
||||||
**/
|
|
||||||
KConfigGroup config() const;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Saves state information about this applet that will
|
* If for some reason, the applet fails to get up on its feet (the
|
||||||
* be accessed when next instantiated in the restore(KConfigGroup&) method.
|
* library couldn't be loaded, necessary hardware support wasn't found,
|
||||||
*
|
* etc..) this method returns true
|
||||||
* This method does not need to be reimplmented by Applet
|
|
||||||
* subclasses, but can be useful for Applet specializations
|
|
||||||
* (such as Containment) to do so.
|
|
||||||
*
|
|
||||||
* Applet subclasses may instead want to reimplement saveState().
|
|
||||||
**/
|
**/
|
||||||
virtual void save(KConfigGroup &group) const;
|
bool hasFailedToLaunch() const;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Restores state information about this applet saved previously
|
* @return true if destroy() was called; useful for Applets which should avoid
|
||||||
* in save(KConfigGroup&).
|
* certain tasks if they are about to be deleted permanently
|
||||||
*
|
*/
|
||||||
* This method does not need to be reimplmented by Applet
|
bool destroyed() const;
|
||||||
* subclasses, but can be useful for Applet specializations
|
|
||||||
* (such as Containment) to do so.
|
/**
|
||||||
|
* @return the Containment, if any, this applet belongs to
|
||||||
**/
|
**/
|
||||||
virtual void restore(KConfigGroup &group);
|
Containment *containment() const;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns a KConfigGroup object to be shared by all applets of this
|
* @return true if this Applet is currently being used as a Containment, false otherwise
|
||||||
* type.
|
|
||||||
*
|
|
||||||
* This config object will write to an applet-specific config object
|
|
||||||
* named plasma_\<appletname\>rc in the local config directory.
|
|
||||||
*/
|
*/
|
||||||
KConfigGroup globalConfig() const;
|
bool isContainment() const;
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the config skeleton object from this applet's package,
|
|
||||||
* if any.
|
|
||||||
*
|
|
||||||
* @return config skeleton object, or 0 if none
|
|
||||||
**/
|
|
||||||
ConfigLoader *configScheme() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Loads the given DataEngine
|
|
||||||
*
|
|
||||||
* Tries to load the data engine given by @p name. Each engine is
|
|
||||||
* only loaded once, and that instance is re-used on all subsequent
|
|
||||||
* requests.
|
|
||||||
*
|
|
||||||
* If the data engine was not found, an invalid data engine is returned
|
|
||||||
* (see DataEngine::isValid()).
|
|
||||||
*
|
|
||||||
* Note that you should <em>not</em> delete the returned engine.
|
|
||||||
*
|
|
||||||
* @param name Name of the data engine to load
|
|
||||||
* @return pointer to the data engine if it was loaded,
|
|
||||||
* or an invalid data engine if the requested engine
|
|
||||||
* could not be loaded
|
|
||||||
*/
|
|
||||||
DataEngine *dataEngine(const QString &name) const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Accessor for the associated Package object if any.
|
|
||||||
* Generally, only Plasmoids come in a Package.
|
|
||||||
*
|
|
||||||
* @return the Package object, or 0 if none
|
|
||||||
**/
|
|
||||||
Package package() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Reccomended position for a popup window like a menu or a tooltip
|
|
||||||
* given its size
|
|
||||||
* @param s size of the popup
|
|
||||||
* @returns recommended position
|
|
||||||
*/
|
|
||||||
QPoint popupPosition(const QSize &s) const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @since 4.4
|
|
||||||
* Reccomended position for a popup window like a menu or a tooltip
|
|
||||||
* given its size
|
|
||||||
* @param s size of the popup
|
|
||||||
* @param alignment alignment of the popup, valid flags are Qt::AlignLeft, Qt::AlignRight and Qt::AlignCenter
|
|
||||||
* @returns recommended position
|
|
||||||
*/
|
|
||||||
QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Called when any of the geometry constraints have been updated.
|
|
||||||
* This method calls constraintsEvent, which may be reimplemented,
|
|
||||||
* once the Applet has been prepared for updating the constraints.
|
|
||||||
*
|
|
||||||
* @param constraints the type of constraints that were updated
|
|
||||||
*/
|
|
||||||
void updateConstraints(Plasma::Constraints constraints = Plasma::AllConstraints);
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the current form factor the applet is being displayed in.
|
* Returns the current form factor the applet is being displayed in.
|
||||||
@ -208,6 +166,121 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
void setAspectRatioMode(Plasma::AspectRatioMode);
|
void setAspectRatioMode(Plasma::AspectRatioMode);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return true is there is a popup assoiated with this Applet
|
||||||
|
* showing, such as the dialog of a PopupApplet. May be reimplemented
|
||||||
|
* for custom popup implementations.
|
||||||
|
*/
|
||||||
|
virtual bool isPopupShowing() const;
|
||||||
|
|
||||||
|
//CONFIGURATION
|
||||||
|
/**
|
||||||
|
* Returns the KConfigGroup to access the applets configuration.
|
||||||
|
*
|
||||||
|
* This config object will write to an instance
|
||||||
|
* specific config file named \<appletname\>\<instanceid\>rc
|
||||||
|
* in the Plasma appdata directory.
|
||||||
|
**/
|
||||||
|
KConfigGroup config() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns a KConfigGroup object to be shared by all applets of this
|
||||||
|
* type.
|
||||||
|
*
|
||||||
|
* This config object will write to an applet-specific config object
|
||||||
|
* named plasma_\<appletname\>rc in the local config directory.
|
||||||
|
*/
|
||||||
|
KConfigGroup globalConfig() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Returns the config skeleton object from this applet's package,
|
||||||
|
* if any.
|
||||||
|
*
|
||||||
|
* @return config skeleton object, or 0 if none
|
||||||
|
**/
|
||||||
|
ConfigLoader *configScheme() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Saves state information about this applet that will
|
||||||
|
* be accessed when next instantiated in the restore(KConfigGroup&) method.
|
||||||
|
*
|
||||||
|
* This method does not need to be reimplmented by Applet
|
||||||
|
* subclasses, but can be useful for Applet specializations
|
||||||
|
* (such as Containment) to do so.
|
||||||
|
*
|
||||||
|
* Applet subclasses may instead want to reimplement saveState().
|
||||||
|
**/
|
||||||
|
virtual void save(KConfigGroup &group) const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Restores state information about this applet saved previously
|
||||||
|
* in save(KConfigGroup&).
|
||||||
|
*
|
||||||
|
* This method does not need to be reimplmented by Applet
|
||||||
|
* subclasses, but can be useful for Applet specializations
|
||||||
|
* (such as Containment) to do so.
|
||||||
|
**/
|
||||||
|
virtual void restore(KConfigGroup &group);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return true if the applet currently needs to be configured,
|
||||||
|
* otherwise, false
|
||||||
|
*/
|
||||||
|
bool configurationRequired() const;
|
||||||
|
|
||||||
|
//UTILS
|
||||||
|
/**
|
||||||
|
* Accessor for the associated Package object if any.
|
||||||
|
* Generally, only Plasmoids come in a Package.
|
||||||
|
*
|
||||||
|
* @return the Package object, or 0 if none
|
||||||
|
**/
|
||||||
|
Package package() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Loads the given DataEngine
|
||||||
|
*
|
||||||
|
* Tries to load the data engine given by @p name. Each engine is
|
||||||
|
* only loaded once, and that instance is re-used on all subsequent
|
||||||
|
* requests.
|
||||||
|
*
|
||||||
|
* If the data engine was not found, an invalid data engine is returned
|
||||||
|
* (see DataEngine::isValid()).
|
||||||
|
*
|
||||||
|
* Note that you should <em>not</em> delete the returned engine.
|
||||||
|
*
|
||||||
|
* @param name Name of the data engine to load
|
||||||
|
* @return pointer to the data engine if it was loaded,
|
||||||
|
* or an invalid data engine if the requested engine
|
||||||
|
* could not be loaded
|
||||||
|
*/
|
||||||
|
DataEngine *dataEngine(const QString &name) const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Called when any of the geometry constraints have been updated.
|
||||||
|
* This method calls constraintsEvent, which may be reimplemented,
|
||||||
|
* once the Applet has been prepared for updating the constraints.
|
||||||
|
*
|
||||||
|
* @param constraints the type of constraints that were updated
|
||||||
|
*/
|
||||||
|
void updateConstraints(Plasma::Constraints constraints = Plasma::AllConstraints);
|
||||||
|
|
||||||
|
|
||||||
|
//METADATA
|
||||||
|
/**
|
||||||
|
* Returns the user-visible name for the applet, as specified in the
|
||||||
|
* .desktop file. Can be changed with @see setName
|
||||||
|
*
|
||||||
|
* @return the user-visible name for the applet.
|
||||||
|
**/
|
||||||
|
QString name() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sets a custom name for this instance of the applet. E.g. a clock might
|
||||||
|
* use the timezone as its name rather than the .desktop file
|
||||||
|
*/
|
||||||
|
void setName(const QString &name) const;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns a list of all known applets.
|
* Returns a list of all known applets.
|
||||||
* This may skip applets based on security settings and ExcludeCategories in the application's config.
|
* This may skip applets based on security settings and ExcludeCategories in the application's config.
|
||||||
@ -302,38 +375,11 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
static QString category(const QString &appletName);
|
static QString category(const QString &appletName);
|
||||||
|
|
||||||
/**
|
|
||||||
* Returns the user-visible name for the applet, as specified in the
|
|
||||||
* .desktop file. Can be changed with @see setName
|
|
||||||
*
|
|
||||||
* @return the user-visible name for the applet.
|
|
||||||
**/
|
|
||||||
QString name() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Sets a custom name for this instance of the applet. E.g. a clock might
|
|
||||||
* use the timezone as its name rather than the .desktop file
|
|
||||||
*/
|
|
||||||
void setName(const QString &name) const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return the font currently set for this widget
|
|
||||||
**/
|
|
||||||
QFont font() const;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the plugin name for the applet
|
* Returns the plugin name for the applet
|
||||||
*/
|
*/
|
||||||
QString pluginName() const;
|
QString pluginName() const;
|
||||||
|
|
||||||
/**
|
|
||||||
* Whether the applet should conserve resources. If true, try to avoid doing stuff which
|
|
||||||
* is computationally heavy. Try to conserve power and resources.
|
|
||||||
*
|
|
||||||
* @return true if it should conserve resources, false if it does not.
|
|
||||||
*/
|
|
||||||
bool shouldConserveResources() const;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns the icon related to this applet
|
* Returns the icon related to this applet
|
||||||
**/
|
**/
|
||||||
@ -346,33 +392,16 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
QString category() const;
|
QString category() const;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* @return The type of immutability of this applet
|
* Whether the applet should conserve resources. If true, try to avoid doing stuff which
|
||||||
|
* is computationally heavy. Try to conserve power and resources.
|
||||||
|
*
|
||||||
|
* @return true if it should conserve resources, false if it does not.
|
||||||
*/
|
*/
|
||||||
ImmutabilityType immutability() const;
|
bool shouldConserveResources() const;
|
||||||
|
|
||||||
/**
|
|
||||||
* If for some reason, the applet fails to get up on its feet (the
|
|
||||||
* library couldn't be loaded, necessary hardware support wasn't found,
|
|
||||||
* etc..) this method returns true
|
|
||||||
**/
|
|
||||||
bool hasFailedToLaunch() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true if the applet is busy and is showing an indicator widget for that
|
|
||||||
*/
|
|
||||||
bool isBusy() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true if the applet currently needs to be configured,
|
|
||||||
* otherwise, false
|
|
||||||
*/
|
|
||||||
bool configurationRequired() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true if this plasmoid provides a GUI configuration
|
|
||||||
**/
|
|
||||||
bool hasConfigurationInterface() const;
|
|
||||||
|
|
||||||
|
//ACTIONS
|
||||||
/**
|
/**
|
||||||
* Returns a list of context-related QAction instances.
|
* Returns a list of context-related QAction instances.
|
||||||
*
|
*
|
||||||
@ -394,29 +423,6 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
void addAction(QString name, QAction *action);
|
void addAction(QString name, QAction *action);
|
||||||
|
|
||||||
/**
|
|
||||||
* Sets the BackgroundHints for this applet @see BackgroundHint
|
|
||||||
*
|
|
||||||
* @param hints the BackgroundHint combination for this applet
|
|
||||||
*/
|
|
||||||
void setBackgroundHints(const Plasma::BackgroundHints hint);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return BackgroundHints flags combination telling if the standard background is shown
|
|
||||||
* and if it has a drop shadow
|
|
||||||
*/
|
|
||||||
Plasma::BackgroundHints backgroundHints() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true if this Applet is currently being used as a Containment, false otherwise
|
|
||||||
*/
|
|
||||||
bool isContainment() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return the Containment, if any, this applet belongs to
|
|
||||||
**/
|
|
||||||
Containment *containment() const;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Sets the global shortcut to associate with this widget.
|
* Sets the global shortcut to associate with this widget.
|
||||||
*/
|
*/
|
||||||
@ -428,13 +434,6 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
KShortcut globalShortcut() const;
|
KShortcut globalShortcut() const;
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true is there is a popup assoiated with this Applet
|
|
||||||
* showing, such as the dialog of a PopupApplet. May be reimplemented
|
|
||||||
* for custom popup implementations.
|
|
||||||
*/
|
|
||||||
virtual bool isPopupShowing() const;
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* associate actions with this widget, including ones added after this call.
|
* associate actions with this widget, including ones added after this call.
|
||||||
* needed to make keyboard shortcuts work.
|
* needed to make keyboard shortcuts work.
|
||||||
@ -447,68 +446,6 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
virtual void removeAssociatedWidget(QWidget *widget);
|
virtual void removeAssociatedWidget(QWidget *widget);
|
||||||
|
|
||||||
/**
|
|
||||||
* @param parent the QObject this applet is parented to
|
|
||||||
* @param serviceId the name of the .desktop file containing the
|
|
||||||
* information about the widget
|
|
||||||
* @param appletId a unique id used to differentiate between multiple
|
|
||||||
* instances of the same Applet type
|
|
||||||
*/
|
|
||||||
explicit Applet(QObject *parent = 0, const QString &serviceId = QString(), uint appletId = 0);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @param parent the QObject this applet is parented to
|
|
||||||
* @param info the plugin information object for this Applet
|
|
||||||
* @param appletId a unique id used to differentiate between multiple
|
|
||||||
* instances of the same Applet type
|
|
||||||
* @since 4.6
|
|
||||||
*/
|
|
||||||
explicit Applet(const KPluginInfo &info, QObject *parent = 0, uint appletId = 0);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @param parent the QObject this applet is parented to
|
|
||||||
* @param serviceId the name of the .desktop file containing the
|
|
||||||
* information about the widget
|
|
||||||
* @param appletId a unique id used to differentiate between multiple
|
|
||||||
* instances of the same Applet type
|
|
||||||
* @param args a list of strings containing two entries: the service id
|
|
||||||
* and the applet id
|
|
||||||
* @since 4.3
|
|
||||||
*/
|
|
||||||
explicit Applet(QObject *parent, const QString &serviceId, uint appletId, const QVariantList &args);
|
|
||||||
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return true if destroy() was called; useful for Applets which should avoid
|
|
||||||
* certain tasks if they are about to be deleted permanently
|
|
||||||
*/
|
|
||||||
bool destroyed() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Reimplement this method so provide a configuration interface,
|
|
||||||
* parented to the supplied widget. Ownership of the widgets is passed
|
|
||||||
* to the parent widget.
|
|
||||||
*
|
|
||||||
* Typically one would add custom pages to the config dialog @p parent
|
|
||||||
* and then connect to the applyClicked() and okClicked() signals
|
|
||||||
* or @p parent to react on config changes:
|
|
||||||
*
|
|
||||||
* @code
|
|
||||||
* connect(parent, SIGNAL(applyClicked()), this, SLOT(myConfigAccepted()));
|
|
||||||
* connect(parent, SIGNAL(okClicked()), this, SLOT(myConfigAccepted()));
|
|
||||||
* @endcode
|
|
||||||
*
|
|
||||||
* With this approach it makes sense to store the custom pages in member
|
|
||||||
* variables to make their fields accessible from the myConfigAccepted()
|
|
||||||
* slot.
|
|
||||||
*
|
|
||||||
* Use config() to store your configuration.
|
|
||||||
*
|
|
||||||
* @param parent the dialog which is the parent of the configuration
|
|
||||||
* widgets
|
|
||||||
*/
|
|
||||||
virtual void createConfigurationInterface(KConfigDialog *parent);
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Returns true if the applet is allowed to perform functions covered by the given constraint
|
* Returns true if the applet is allowed to perform functions covered by the given constraint
|
||||||
* eg. hasAuthorization("FileDialog") returns true if applets are allowed to show filedialogs.
|
* eg. hasAuthorization("FileDialog") returns true if applets are allowed to show filedialogs.
|
||||||
@ -516,6 +453,7 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
bool hasAuthorization(const QString &constraint) const;
|
bool hasAuthorization(const QString &constraint) const;
|
||||||
|
|
||||||
|
// ASSOCIATED APPLICATION
|
||||||
/**
|
/**
|
||||||
* Sets an application associated to this applet, that will be
|
* Sets an application associated to this applet, that will be
|
||||||
* regarded as a full view of what is represented in the applet
|
* regarded as a full view of what is represented in the applet
|
||||||
@ -556,8 +494,130 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
bool hasValidAssociatedApplication() const;
|
bool hasValidAssociatedApplication() const;
|
||||||
|
|
||||||
Q_SIGNALS:
|
//Completely UI-specific, remove or move to scriptengine
|
||||||
|
/**
|
||||||
|
* Reccomended position for a popup window like a menu or a tooltip
|
||||||
|
* given its size
|
||||||
|
* @param s size of the popup
|
||||||
|
* @returns recommended position
|
||||||
|
*/
|
||||||
|
QPoint popupPosition(const QSize &s) const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @since 4.4
|
||||||
|
* Reccomended position for a popup window like a menu or a tooltip
|
||||||
|
* given its size
|
||||||
|
* @param s size of the popup
|
||||||
|
* @param alignment alignment of the popup, valid flags are Qt::AlignLeft, Qt::AlignRight and Qt::AlignCenter
|
||||||
|
* @returns recommended position
|
||||||
|
*/
|
||||||
|
QPoint popupPosition(const QSize &s, Qt::AlignmentFlag alignment) const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return the font currently set for this widget
|
||||||
|
**/
|
||||||
|
QFont font() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return true if the applet is busy and is showing an indicator widget for that
|
||||||
|
*/
|
||||||
|
bool isBusy() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return true if this plasmoid provides a GUI configuration
|
||||||
|
**/
|
||||||
|
bool hasConfigurationInterface() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Sets the BackgroundHints for this applet @see BackgroundHint
|
||||||
|
*
|
||||||
|
* @param hints the BackgroundHint combination for this applet
|
||||||
|
*/
|
||||||
|
void setBackgroundHints(const Plasma::BackgroundHints hint);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return BackgroundHints flags combination telling if the standard background is shown
|
||||||
|
* and if it has a drop shadow
|
||||||
|
*/
|
||||||
|
Plasma::BackgroundHints backgroundHints() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Reimplement this method so provide a configuration interface,
|
||||||
|
* parented to the supplied widget. Ownership of the widgets is passed
|
||||||
|
* to the parent widget.
|
||||||
|
*
|
||||||
|
* Typically one would add custom pages to the config dialog @p parent
|
||||||
|
* and then connect to the applyClicked() and okClicked() signals
|
||||||
|
* or @p parent to react on config changes:
|
||||||
|
*
|
||||||
|
* @code
|
||||||
|
* connect(parent, SIGNAL(applyClicked()), this, SLOT(myConfigAccepted()));
|
||||||
|
* connect(parent, SIGNAL(okClicked()), this, SLOT(myConfigAccepted()));
|
||||||
|
* @endcode
|
||||||
|
*
|
||||||
|
* With this approach it makes sense to store the custom pages in member
|
||||||
|
* variables to make their fields accessible from the myConfigAccepted()
|
||||||
|
* slot.
|
||||||
|
*
|
||||||
|
* Use config() to store your configuration.
|
||||||
|
*
|
||||||
|
* @param parent the dialog which is the parent of the configuration
|
||||||
|
* widgets
|
||||||
|
*/
|
||||||
|
virtual void createConfigurationInterface(KConfigDialog *parent);
|
||||||
|
|
||||||
|
Q_SIGNALS:
|
||||||
|
//BOOKEEPING
|
||||||
|
/**
|
||||||
|
* Emitted when the immutability changes
|
||||||
|
* @since 4.4
|
||||||
|
*/
|
||||||
|
void immutabilityChanged(Plasma::ImmutabilityType immutable);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Emitted when the applet status changes
|
||||||
|
* @since 4.4
|
||||||
|
*/
|
||||||
|
void newStatus(Plasma::ItemStatus status);
|
||||||
|
|
||||||
|
|
||||||
|
//CONFIGURATION
|
||||||
|
/**
|
||||||
|
* Emitted when an applet has changed values in its configuration
|
||||||
|
* and wishes for them to be saved at the next save point. As this implies
|
||||||
|
* disk activity, this signal should be used with care.
|
||||||
|
*
|
||||||
|
* @note This does not need to be emitted from saveState by individual
|
||||||
|
* applets.
|
||||||
|
*/
|
||||||
|
void configNeedsSaving();
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
//ACTIONS
|
||||||
|
/**
|
||||||
|
* Emitted when activation is requested due to, for example, a global
|
||||||
|
* keyboard shortcut. By default the wiget is given focus.
|
||||||
|
*/
|
||||||
|
void activate();
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Emitted when the user clicked on a button of the message overlay
|
||||||
|
*
|
||||||
|
* @see showMessage
|
||||||
|
* @see Plasma::MessageButton
|
||||||
|
* @since 4.3
|
||||||
|
*/
|
||||||
|
void messageButtonPressed(const Plasma::MessageButton button);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Emitted when background hints change
|
||||||
|
* @since 5.0
|
||||||
|
*/
|
||||||
|
void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints);
|
||||||
|
|
||||||
|
|
||||||
|
//Completely UI-specific, remove or move to scriptengine
|
||||||
/**
|
/**
|
||||||
* This signal indicates that an application launch, window
|
* This signal indicates that an application launch, window
|
||||||
* creation or window focus event was triggered. This is used, for instance,
|
* creation or window focus event was triggered. This is used, for instance,
|
||||||
@ -576,55 +636,14 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
void appletTransformedItself();
|
void appletTransformedItself();
|
||||||
|
|
||||||
/**
|
//TODO: fix usage in containment, port to QObject::destroyed
|
||||||
* Emitted when an applet has changed values in its configuration
|
|
||||||
* and wishes for them to be saved at the next save point. As this implies
|
|
||||||
* disk activity, this signal should be used with care.
|
|
||||||
*
|
|
||||||
* @note This does not need to be emitted from saveState by individual
|
|
||||||
* applets.
|
|
||||||
*/
|
|
||||||
void configNeedsSaving();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Emitted when activation is requested due to, for example, a global
|
|
||||||
* keyboard shortcut. By default the wiget is given focus.
|
|
||||||
*/
|
|
||||||
void activate();
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Emitted when the user clicked on a button of the message overlay
|
|
||||||
*
|
|
||||||
* @see showMessage
|
|
||||||
* @see Plasma::MessageButton
|
|
||||||
* @since 4.3
|
|
||||||
*/
|
|
||||||
void messageButtonPressed(const Plasma::MessageButton button);
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Emitted when the applet is deleted
|
* Emitted when the applet is deleted
|
||||||
*/
|
*/
|
||||||
void appletDeleted(Plasma::Applet *applet);
|
void appletDeleted(Plasma::Applet *applet);
|
||||||
|
|
||||||
/**
|
|
||||||
* Emitted when the applet status changes
|
|
||||||
* @since 4.4
|
|
||||||
*/
|
|
||||||
void newStatus(Plasma::ItemStatus status);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Emitted when the immutability changes
|
|
||||||
* @since 4.4
|
|
||||||
*/
|
|
||||||
void immutabilityChanged(Plasma::ImmutabilityType immutable);
|
|
||||||
|
|
||||||
/**
|
|
||||||
* Emitted when background hints change
|
|
||||||
* @since 5.0
|
|
||||||
*/
|
|
||||||
void backgroundHintsChanged(Plasma::BackgroundHints backgroundHints);
|
|
||||||
|
|
||||||
public Q_SLOTS:
|
public Q_SLOTS:
|
||||||
|
//BOOKKEEPING
|
||||||
/**
|
/**
|
||||||
* Sets the immutability type for this applet (not immutable,
|
* Sets the immutability type for this applet (not immutable,
|
||||||
* user immutable or system immutable)
|
* user immutable or system immutable)
|
||||||
@ -638,6 +657,25 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
virtual void destroy();
|
virtual void destroy();
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return the status of the applet
|
||||||
|
* @since 4.4
|
||||||
|
*/
|
||||||
|
ItemStatus status() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* sets the status for this applet
|
||||||
|
* @since 4.4
|
||||||
|
*/
|
||||||
|
void setStatus(const ItemStatus stat);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* @return the list of arguments which the applet was called with
|
||||||
|
* @since KDE4.3
|
||||||
|
*/
|
||||||
|
QVariantList startupArguments() const;
|
||||||
|
|
||||||
|
//CONFIGURATION
|
||||||
/**
|
/**
|
||||||
* Lets the user interact with the plasmoid options.
|
* Lets the user interact with the plasmoid options.
|
||||||
* Called when the user selects the configure entry
|
* Called when the user selects the configure entry
|
||||||
@ -669,6 +707,13 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
bool isUserConfiguring() const;
|
bool isUserConfiguring() const;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Called when applet configuration values have changed.
|
||||||
|
*/
|
||||||
|
virtual void configChanged();
|
||||||
|
|
||||||
|
|
||||||
|
//UTILS
|
||||||
/**
|
/**
|
||||||
* Sends all pending constraints updates to the applet. Will usually
|
* Sends all pending constraints updates to the applet. Will usually
|
||||||
* be called automatically, but can also be called manually if needed.
|
* be called automatically, but can also be called manually if needed.
|
||||||
@ -687,35 +732,19 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
**/
|
**/
|
||||||
virtual void init();
|
virtual void init();
|
||||||
|
|
||||||
/**
|
|
||||||
* Called when applet configuration values have changed.
|
|
||||||
*/
|
|
||||||
virtual void configChanged();
|
|
||||||
|
|
||||||
/**
|
//ASSOCIATED APPLICATION
|
||||||
* Shows a busy indicator that overlays the applet
|
/**
|
||||||
* @param busy show or hide the busy indicator
|
* Open the application associated to this applet, if it's not set
|
||||||
*/
|
* but some urls are, open those urls with the proper application
|
||||||
void setBusy(bool busy);
|
* for their mimetype
|
||||||
|
* @see setAssociatedApplication()
|
||||||
/**
|
* @see setAssociatedApplicationUrls()
|
||||||
* @return the list of arguments which the applet was called with
|
|
||||||
* @since KDE4.3
|
|
||||||
*/
|
|
||||||
QVariantList startupArguments() const;
|
|
||||||
|
|
||||||
/**
|
|
||||||
* @return the status of the applet
|
|
||||||
* @since 4.4
|
* @since 4.4
|
||||||
*/
|
*/
|
||||||
ItemStatus status() const;
|
void runAssociatedApplication();
|
||||||
|
|
||||||
/**
|
|
||||||
* sets the status for this applet
|
|
||||||
* @since 4.4
|
|
||||||
*/
|
|
||||||
void setStatus(const ItemStatus stat);
|
|
||||||
|
|
||||||
|
//REMOTE WIDGETS
|
||||||
/**
|
/**
|
||||||
* Publishes and optionally announces this applet on the network for remote access.
|
* Publishes and optionally announces this applet on the network for remote access.
|
||||||
* @param methods the methods to use for announcing this applet.
|
* @param methods the methods to use for announcing this applet.
|
||||||
@ -728,20 +757,18 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
|
|
||||||
bool isPublished() const;
|
bool isPublished() const;
|
||||||
|
|
||||||
|
//Completely UI-specific, remove or move to scriptengine
|
||||||
/**
|
/**
|
||||||
* Open the application associated to this applet, if it's not set
|
* Shows a busy indicator that overlays the applet
|
||||||
* but some urls are, open those urls with the proper application
|
* @param busy show or hide the busy indicator
|
||||||
* for their mimetype
|
|
||||||
* @see setAssociatedApplication()
|
|
||||||
* @see setAssociatedApplicationUrls()
|
|
||||||
* @since 4.4
|
|
||||||
*/
|
*/
|
||||||
void runAssociatedApplication();
|
void setBusy(bool busy);
|
||||||
|
|
||||||
bool hasFocus() const;
|
bool hasFocus() const;
|
||||||
void setFocus(Qt::FocusReason);
|
void setFocus(Qt::FocusReason);
|
||||||
|
|
||||||
protected:
|
protected:
|
||||||
|
//CONSTRUCTORS
|
||||||
/**
|
/**
|
||||||
* This constructor is to be used with the plugin loading systems
|
* This constructor is to be used with the plugin loading systems
|
||||||
* found in KPluginInfo and KService. The argument list is expected
|
* found in KPluginInfo and KService. The argument list is expected
|
||||||
@ -754,6 +781,7 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
Applet(QObject *parent, const QVariantList &args);
|
Applet(QObject *parent, const QVariantList &args);
|
||||||
|
|
||||||
|
//BOOKEEPING
|
||||||
/**
|
/**
|
||||||
* Call this method when the applet fails to launch properly. An
|
* Call this method when the applet fails to launch properly. An
|
||||||
* optional reason can be provided.
|
* optional reason can be provided.
|
||||||
@ -768,6 +796,7 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
**/
|
**/
|
||||||
void setFailedToLaunch(bool failed, const QString &reason = QString());
|
void setFailedToLaunch(bool failed, const QString &reason = QString());
|
||||||
|
|
||||||
|
//CONFIGURATION
|
||||||
/**
|
/**
|
||||||
* When called, the Applet should write any information needed as part
|
* When called, the Applet should write any information needed as part
|
||||||
* of the Applet's running state to the configuration object in config()
|
* of the Applet's running state to the configuration object in config()
|
||||||
@ -803,22 +832,7 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
|
void setConfigurationRequired(bool needsConfiguring, const QString &reason = QString());
|
||||||
|
|
||||||
/**
|
//UTILS
|
||||||
* Shows a message as an overlay of the applet: the message has an
|
|
||||||
* icon, text and (optional) buttons
|
|
||||||
*
|
|
||||||
* @param icon the icon that will be shown
|
|
||||||
* @param message the message string that will be shown.
|
|
||||||
* If the message is empty nothng will be shown
|
|
||||||
* and if there was a message already it will be hidden
|
|
||||||
* @param buttons an OR combination of all the buttons needed
|
|
||||||
*
|
|
||||||
* @see Plasma::MessageButtons
|
|
||||||
* @see messageButtonPressed
|
|
||||||
* @since 4.3
|
|
||||||
*/
|
|
||||||
void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);
|
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* Called when any of the constraints for the applet have been updated. These constraints
|
* Called when any of the constraints for the applet have been updated. These constraints
|
||||||
* range from notifying when the applet has officially "started up" to when geometry changes
|
* range from notifying when the applet has officially "started up" to when geometry changes
|
||||||
@ -839,7 +853,24 @@ class PLASMA_EXPORT Applet : public QObject
|
|||||||
*/
|
*/
|
||||||
virtual void constraintsEvent(Plasma::Constraints constraints);
|
virtual void constraintsEvent(Plasma::Constraints constraints);
|
||||||
|
|
||||||
|
//Completely UI-specific, remove or move to scriptengine
|
||||||
|
/**
|
||||||
|
* Shows a message as an overlay of the applet: the message has an
|
||||||
|
* icon, text and (optional) buttons
|
||||||
|
*
|
||||||
|
* @param icon the icon that will be shown
|
||||||
|
* @param message the message string that will be shown.
|
||||||
|
* If the message is empty nothng will be shown
|
||||||
|
* and if there was a message already it will be hidden
|
||||||
|
* @param buttons an OR combination of all the buttons needed
|
||||||
|
*
|
||||||
|
* @see Plasma::MessageButtons
|
||||||
|
* @see messageButtonPressed
|
||||||
|
* @since 4.3
|
||||||
|
*/
|
||||||
|
void showMessage(const QIcon &icon, const QString &message, const Plasma::MessageButtons buttons);
|
||||||
|
|
||||||
|
//TODO: timerEvent should go into AppletPrivate
|
||||||
/**
|
/**
|
||||||
* Reimplemented from QObject
|
* Reimplemented from QObject
|
||||||
*/
|
*/
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user