Member Function Documentation

[since 5.86] Applet::Applet(QObject *parentObject, const KPluginMetaData &data, const QVariantList &args)

This constructor can be used with the KCoreAddons plugin loading system. The argument list is expected to have contain the KPackage of the applet, the meta data file path (for compatibility) and an applet ID which must be a base 10 number.

parent a QObject parent; you probably want to pass in 0

data, KPluginMetaData used to create this plugin

args a list of strings containing the applet id

This function was introduced in 5.86.

[signal] void Applet::activated()

Emitted when activation is requested due to, for example, a global keyboard shortcut. By default the widget is given focus.

[signal] void Applet::appletDeleted(Plasma::Applet *applet)

Emitted when the applet is deleted

[since 5.65] Plasma::Types::BackgroundHints Applet::backgroundHints() const

How the applet wants its background to be drawn. The containment may chose to ignore this hint.

This function was introduced in 5.65.

See also setBackgroundHints().

[signal, since 5.65] void Applet::backgroundHintsChanged()

Emitted when the background hints have changed

This function was introduced in 5.65.

[signal, since 5.21] void Applet::busyChanged(bool busy)

Emitted when the busy status has changed

This function was introduced in 5.21.

KConfigGroup Applet::config() const

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.

[virtual slot] void Applet::configChanged()

Called when applet configuration values have changed.

[signal] void Applet::configNeedsSaving()

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.

KConfigLoader *Applet::configScheme() const

Returns the config skeleton object from this applet's package, if any.

Returns config skeleton object, or 0 if none

KConfigPropertyMap *Applet::configuration()

Returns a KConfigPropertyMap instance that represents the configuration which is usable from QML to read and write settings like any JavaScript Object

bool Applet::configurationRequired() const

Returns true if the applet currently needs to be configured, otherwise, false

See also setConfigurationRequired().

[signal, since 5.20] void Applet::configurationRequiredChanged(bool needsConfig, const QString &reason)

Emitted when setConfigurationRequired was called

This function was introduced in 5.20.

See also setConfigurationRequired.

[since 5.20] QString Applet::configurationRequiredReason() const

Returns A translated message for the user explaining that the applet needs configuring; this should note what needs to be configured

This function was introduced in 5.20.

See also setConfigurationRequired.

Plasma::Applet::ConstraintHints Applet::constraintHints() const

Returns The constraint hints such as CanFillArea or MarginAreasSeparator, they can be in bitwise OR

See also setConstraintHints().

[signal] void Applet::constraintHintsChanged(Plasma::Applet::ConstraintHints constraintHints)

Emitted when the constraint hints changed

See also setConstraintHints.

[virtual protected] void Applet::constraintsEvent(Plasma::Applet::Constraints 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 to when the form factor changes.

Each constraint that has been changed is passed in the constraints flag. All of the constraints and how they work is documented in the

enumeration.

On applet creation, this is always called prior to painting and can be used as an opportunity to layout the widget, calculate sizings, etc.

Do not call update() from this method; an update() will be triggered at the appropriate time for the applet.

constraints the type of constraints that were updated

See also Plasma::Constraints.

Plasma::Containment *Applet::containment() const

Returns the Containment, if any, this applet belongs to

[signal] void Applet::containmentChanged(Plasma::Containment *containment)

Emitted when the containment changes

[since 5.77] Plasma::Types::ContainmentDisplayHints Applet::containmentDisplayHints() const

Returns Display hints that come from the containment that suggest the applet how to look and behave.

This function was introduced in 5.77.

[signal] void Applet::containmentDisplayHintsChanged(Plasma::Types::ContainmentDisplayHints hints)

Emitted when the containment display hints change

[virtual] QList<QAction *> Applet::contextualActions()

Returns a list of context-related QAction instances.

This is used e.g. within the DesktopView to display a contextmenu.

Returns A list of actions. The default implementation returns an empty list.

[signal] void Applet::contextualActionsAboutToShow()

Emitted just before the contextual actions are about to show For instance just before the context menu containing the actions added with setAction() is shown

[signal] void Applet::contextualActionsChanged(const QList<QAction *> &actions)

Emitted when the list of contextual actions has changed

[slot] void Applet::destroy()

Destroys the applet; it will be removed nicely and deleted. Its configuration will also be deleted. If you want to remove the Applet configuration, use this, don't just delete the Applet *

bool Applet::destroyed() const

Returns true if destroy() was called; useful for Applets which should avoid certain tasks if they are about to be deleted permanently

[signal, since 5.4] void Applet::destroyedChanged(bool destroyed)

Emitted when the applet has been scheduled for destruction or the destruction has been undone

This function was introduced in 5.4.

[since 5.65] Plasma::Types::BackgroundHints Applet::effectiveBackgroundHints() const

The effective background hints the applet will have: it will follow userBackgroundHints only if backgroundHints has the Plasma::Types::ConfigurableBackground flag set

This function was introduced in 5.65.

[signal, since 5.65] void Applet::effectiveBackgroundHintsChanged()

Emitted when the effective background hints have changed

This function was introduced in 5.65.

bool Applet::failedToLaunch() 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.

[slot] void Applet::flushPendingConstraintsEvents()

Sends all pending constraints updates to the applet. Will usually be called automatically, but can also be called manually if needed.

Plasma::Types::FormFactor Applet::formFactor() const

Returns the current form factor the applet is being displayed in.

[signal] void Applet::formFactorChanged(Plasma::Types::FormFactor formFactor)

Emitted when the formfactor changes

KConfigGroup Applet::globalConfig() 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.

QKeySequence Applet::globalShortcut() const

Returns the global shortcut associated with this widget, or an empty shortcut if no global shortcut is associated.

See also setGlobalShortcut().

[signal] void Applet::globalShortcutChanged(const QKeySequence &sequence)

Emitted when the global shortcut to activate this applet has chanaged

bool Applet::hasConfigurationInterface() const

Returns true if this plasmoid provides a GUI configuration

See also setHasConfigurationInterface().

[signal, since 6.0] void Applet::hasConfigurationInterfaceChanged(bool hasConfiguration)

Emitted when the applet gains or loses the ability to show a configuration interface

This function was introduced in 6.0.

See also hasConfigurationInterface.

QString Applet::icon() const

Returns The icon name related to this applet By default is the one in the plasmoid desktop file

See also setIcon().

[signal, since 5.20] void Applet::iconChanged(const QString &icon)

Emitted when the icon name for the applet has changed

This function was introduced in 5.20.

uint Applet::id() const

Returns the id of this applet

Plasma::Types::ImmutabilityType Applet::immutability() const

Returns The type of immutability of this applet

See also setImmutability().

[signal, since 4.4] void Applet::immutabilityChanged(Plasma::Types::ImmutabilityType immutable)

Emitted when the immutability changes

This function was introduced in 4.4.

bool Applet::immutable() const

Returns true if immutability() is not Types::Mutable

[virtual slot] void Applet::init()

This method is called once the applet is loaded and added to a Corona. If the applet requires a Scene or has an particularly intensive set of initialization routines to go through, consider implementing it in this method instead of the constructor.

[invokable] QAction *Applet::internalAction(const QString &name) const

Returnss the internal action with the given name if available

name the unique name of the action we want

See also setInternalAction().

QList<QAction *> Applet::internalActions() const

Returnss All the internal actions such as configure, remove, alternatives etc

[signal] void Applet::internalActionsChanged(const QList<QAction *> &actions)

Emitted when the list of internal actions has changed

[since 5.21] bool Applet::isBusy() const

Returns true if the applet should show a busy status, for instance doing some network operation

This function was introduced in 5.21.

bool Applet::isContainment() const

Returns true if this Applet is currently being used as a Containment, false otherwise

[since 4.5] bool Applet::isUserConfiguring() const

Returns true when the configuration interface is being shown

This function was introduced in 4.5.

[since 5.0] QString Applet::launchErrorMessage() 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 the reason why, in an user-readable way.

This function was introduced in 5.0.

See also setLaunchErrorMessage().

Plasma::Types::Location Applet::location() const

Returns the location of the scene which is displaying applet.

[signal] void Applet::locationChanged(Plasma::Types::Location location)

Emitted when the location changes

[since 5.27] KPluginMetaData Applet::pluginMetaData() const

Returns metadata information about this plugin

This function was introduced in 5.27.

QString Applet::pluginName() const

Returns the plugin name form KPluginMetaData

[invokable] void Applet::removeInternalAction(const QString &name)

Removes an action from the internal actions

name the action to be removed

[virtual] void Applet::restore(KConfigGroup &group)

Restores state information about this applet saved previously in save(KConfigGroup&).

This method does not need to be reimplemented by Applet subclasses, but can be useful for Applet specializations (such as Containment) to do so.

[virtual] void Applet::save(KConfigGroup &group) 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 reimplemented 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 protected] void Applet::saveState(KConfigGroup &config) const

When called, the Applet should write any information needed as part of the Applet's running state to the configuration object in config() and/or globalConfig().

Applets that always sync their settings/state with the config objects when these settings/states change do not need to reimplement this method.

[signal, since 6.3] void Applet::secondaryActivated()

Emitted when activation is requested due to, for example, middle click.

This function was introduced in 6.3.

[since 5.65] void Applet::setBackgroundHints(Plasma::Types::BackgroundHints hint)

Sets the applet background hints. Only Applet implementations should write this property

This function was introduced in 5.65.

See also backgroundHints().

[since 5.21] void Applet::setBusy(bool busy)

Sets the Applet to have a busy status hint, for instance the applet doing some network operation. The graphical representation of the busy status depends completely from the visualization.

busy true if the applet is busy

This function was introduced in 5.21.

See also isBusy().

void Applet::setConfigurationRequired(bool needsConfiguring, const QString &reason = QString())

When the applet needs to be configured before being usable, this method can be called to show a standard interface prompting the user to configure the applet

needsConfiguring true if the applet needs to be configured, or false if it doesn't

reason a translated message for the user explaining that the applet needs configuring; this should note what needs to be configured

See also configurationRequired().

void Applet::setConstraintHints(Plasma::Applet::ConstraintHints constraintHints)

Sets the constraint hits which give a more granular control over sizing in constrained layouts such as panels

constraintHints such as CanFillArea or MarginAreasSeparator, they can be in bitwise OR

See also constraintHints().

void Applet::setGlobalShortcut(const QKeySequence &shortcut = QKeySequence())

Sets the global shortcut to associate with this widget.

See also globalShortcut().

void Applet::setHasConfigurationInterface(bool hasInterface)

Sets whether or not this applet provides a user interface for configuring the applet.

It defaults to false, and if true is passed in you should also reimplement createConfigurationInterface()

hasInterface whether or not there is a user interface available

See also hasConfigurationInterface().

void Applet::setIcon(const QString &icon)

Sets an icon name for this applet icon Freedesktop compatible icon name

See also icon().

[slot] void Applet::setImmutability(const Plasma::Types::ImmutabilityType immutable)

Sets the immutability type for this applet (not immutable, user immutable or system immutable)

immutable the new immutability type of this applet

See also immutability().

[invokable] void Applet::setInternalAction(const QString &name, QAction *action)

Add a new internal action. if an internal action with the same name already exists, it will be replaced with this new one. Those are usually actions defined by the system, such as "configure" and "remove"

name The unique name for the action

action The new QAction to be added

See also internalAction().

[slot, since 5.0] void Applet::setLaunchErrorMessage(const QString &reason = QString())

Call this method when the applet fails to launch properly. An optional reason can be provided.

Not that all children items will be deleted when this method is called. If you have pointers to these items, you will need to reset them after calling this method.

failed true when the applet failed, false when it succeeded

reason an optional reason to show the user why the applet failed to launch

This function was introduced in 5.0.

See also launchErrorMessage().

[slot, since 4.4] void Applet::setStatus(const Plasma::Types::ItemStatus stat)

sets the status for this applet

This function was introduced in 4.4.

See also status().

[since 5.0] void Applet::setTitle(const QString &title)

Sets a custom title for this instance of the applet. E.g. a clock might use the timezone as its name rather than the .desktop file

title the user-visible title for the applet.

This function was introduced in 5.0.

See also title().

[since 5.65] void Applet::setUserBackgroundHints(Plasma::Types::BackgroundHints hint)

Sets the hints the user wished the background style for the applet to be.

This function was introduced in 5.65.

See also userBackgroundHints().

void Applet::setUserConfiguring(bool configuring)

Tells the applet the user is configuring

configuring true if the configuration ui is showing

See also isUserConfiguring().

QVariantList Applet::startupArguments() const

Returns the arguments this applet was started with.

Some applets support arguments, for instance the notes applet supports to be instantiated with a given text already passed as paramenter

[since 4.4] Plasma::Types::ItemStatus Applet::status() const

Returns the status of the applet

This function was introduced in 4.4.

See also setStatus().

[signal, since 4.4] void Applet::statusChanged(Plasma::Types::ItemStatus status)

Emitted when the applet status changes

This function was introduced in 4.4.

[since 5.0] QString Applet::title() const

Returns the user-visible title for the applet, as specified in the Name field of the .desktop file. Can be changed with setTitle

Returns the user-visible title for the applet.

This function was introduced in 5.0.

See also setTitle().

[signal, since 5.20] void Applet::titleChanged(const QString &title)

Emitted when the title has changed

This function was introduced in 5.20.

[since 6.1] QString Applet::translationDomain() const

The translation domain for this applet

This function was introduced in 6.1.

void Applet::updateConstraints(Plasma::Applet::Constraints constraints = AllConstraints)

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.

constraints the type of constraints that were updated

[since 5.65] Plasma::Types::BackgroundHints Applet::userBackgroundHints() const

The containment (and/or the user) may decide to use another kind of background instead if supported by the applet. In order for an applet to support user configuration of the background, it needs to have the Plasma::Types::ConfigurableBackground flag set in its backgroundHints

This function was introduced in 5.65.

See also setUserBackgroundHints().

[signal, since 5.65] void Applet::userBackgroundHintsChanged()

Emitted when the user background hints have changed

This function was introduced in 5.65.

[signal] void Applet::userConfiguringChanged(bool configuring)

emitted when the config ui appears or disappears