AppletInterface

#include <appletinterface.h>

Inheritance diagram for AppletInterface:

Public Types
enum	ActionPriority { LowPriorityAction = QAction::LowPriority, NormalPriorityAction = QAction::NormalPriority, HighPriorityAction = QAction::HighPriority }

Properties
int	apiVersion

QString	associatedApplication

QList< QUrl >	associatedApplicationUrls

QRect	availableScreenRect

QVariantList	availableScreenRegion

Plasma::Types::BackgroundHints	backgroundHints

bool	busy

QObject	configuration

bool	configurationRequired

QString	configurationRequiredReason

Plasma::Types::ConstraintHints	constraintHints

Plasma::Types::ContainmentDisplayHints	containmentDisplayHints

QList< QObject * >	contextualActions

QString	currentActivity

bool	editMode

Plasma::Types::BackgroundHints	effectiveBackgroundHints

Plasma::Types::FormFactor	formFactor

QKeySequence	globalShortcut

bool	hideOnWindowDeactivate

QString	icon

uint	id

Plasma::Types::ImmutabilityType	immutability

bool	immutable

bool	loading

Plasma::Types::Location	location

KPluginMetaData	metaData

QObject	nativeInterface

QString	pluginName

int	screen

QRect	screenGeometry

AppletInterface	self

Plasma::Types::ItemStatus	status

QString	title

QQuickItem	toolTipItem

QString	toolTipMainText

QString	toolTipSubText

int	toolTipTextFormat

Plasma::Types::BackgroundHints	userBackgroundHints

bool	userConfiguring

Signals
void	activated ()

void	associatedApplicationChanged ()

void	associatedApplicationUrlsChanged ()

void	availableScreenRectChanged ()

void	availableScreenRegionChanged ()

void	backgroundHintsChanged ()

void	busyChanged ()

void	configNeedsSaving ()

void	configurationRequiredChanged ()

void	configurationRequiredReasonChanged ()

void	constraintHintsChanged ()

void	containmentDisplayHintsChanged ()

void	contextChanged ()

void	contextualActionsAboutToShow ()

void	contextualActionsChanged ()

void	editModeChanged ()

void	effectiveBackgroundHintsChanged ()

void	externalData (const QString &mimetype, const QVariant &data)

void	formFactorChanged ()

void	globalShortcutChanged ()

void	hideOnWindowDeactivateChanged ()

void	iconChanged ()

void	immutabilityChanged ()

void	isLoadingChanged ()

void	locationChanged ()

void	screenChanged ()

void	screenGeometryChanged ()

void	statusChanged ()

void	titleChanged ()

void	toolTipItemChanged ()

void	toolTipMainTextChanged ()

void	toolTipSubTextChanged ()

void	toolTipTextFormatChanged ()

void	userBackgroundHintsChanged ()

void	userConfiguringChanged ()

Public Member Functions
	AppletInterface (DeclarativeAppletScript script, const QVariantList &args=QVariantList(), QQuickItem parent=nullptr)

Q_INVOKABLE QAction *	action (QString name) const

int	apiVersion () const

DeclarativeAppletScript *	appletScript () const

QString	associatedApplication () const

QList< QUrl >	associatedApplicationUrls () const

QRect	availableScreenRect () const

QVariantList	availableScreenRegion () const

Plasma::Types::BackgroundHints	backgroundHints () const

Q_INVOKABLE void	clearActions ()

QObject *	configuration () const

bool	configurationRequired () const

QString	configurationRequiredReason () const

Plasma::Types::ConstraintHints	constraintHints () const

Plasma::Types::ContainmentDisplayHints	containmentDisplayHints () const

QList< QAction * >	contextualActions () const

QList< QObject * >	contextualActionsObjects () const

QString	currentActivity () const

Q_INVOKABLE QStringList	downloadedFiles () const

Q_INVOKABLE QString	downloadPath () const

Q_INVOKABLE PLASMA_DEPRECATED QString	downloadPath (const QString &file)

Plasma::Types::BackgroundHints	effectiveBackgroundHints () const

void	executeAction (const QString &name)

Q_INVOKABLE QString	file (const QString &fileName)

Q_INVOKABLE QString	file (const QString &fileType, const QString &filePath)

Plasma::Types::FormFactor	formFactor () const

QKeySequence	globalShortcut () const

bool	hideOnWindowDeactivate () const

QString	icon () const

uint	id () const

Plasma::Types::ImmutabilityType	immutability () const

bool	immutable () const

bool	isBusy () const

bool	isEditMode () const

Plasma::Types::Location	location () const

KPluginMetaData	metaData () const

QObject *	nativeInterface ()

QString	pluginName () const

Q_INVOKABLE void	prepareContextualActions ()

	Q_ENUM (ActionPriority)

Q_INVOKABLE void	removeAction (const QString &name)

int	screen () const

QRect	screenGeometry () const

AppletInterface *	self ()

Q_INVOKABLE void	setAction (const QString &name, const QString &text, const QString &icon=QString(), const QString &shortcut=QString())

Q_INVOKABLE void	setActionGroup (const QString &action, const QString &group)

Q_INVOKABLE void	setActionSeparator (const QString &name)

void	setAssociatedApplication (const QString &string)

void	setAssociatedApplicationUrls (const QList< QUrl > &urls)

void	setBackgroundHints (Plasma::Types::BackgroundHints hint)

void	setBusy (bool busy)

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

void	setConfigurationRequiredProperty (bool required)

void	setConfigurationRequiredReason (const QString &reason)

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

void	setGlobalShortcut (const QKeySequence &keySequence=QKeySequence())

void	setHideOnWindowDeactivate (bool hide)

void	setIcon (const QString &icon)

void	setStatus (const Plasma::Types::ItemStatus &status)

void	setTitle (const QString &title)

void	setToolTipItem (QQuickItem *toolTipItem)

void	setToolTipMainText (const QString &text)

void	setToolTipSubText (const QString &text)

void	setToolTipTextFormat (int format)

void	setUserBackgroundHints (Plasma::Types::BackgroundHints hint)

Plasma::Types::ItemStatus	status () const

QString	title () const

QQuickItem *	toolTipItem () const

QString	toolTipMainText () const

QString	toolTipSubText () const

int	toolTipTextFormat () const

Plasma::Types::BackgroundHints	userBackgroundHints () const

bool	userConfiguring () const

Static Public Member Functions
static AppletInterface *	qmlAttachedProperties (QObject *object)

Protected Slots
void	init () override

Protected Member Functions
bool	event (QEvent *event) override

bool	eventFilter (QObject watched, QEvent event) override

virtual bool	isLoading () const

void	updateUiReadyConstraint ()

Detailed Description

This class is exposed to applets in QML as the attached property Plasmoid.

@import org.kde.plasma.plasmoid

Definition at line 51 of file appletinterface.h.

Member Enumeration Documentation

◆ ActionPriority

enum AppletInterface::ActionPriority

Expose the QAction::Priority values which cannot be directly accessed from plasmoids.

Since: 5.101

Definition at line 288 of file appletinterface.h.

Property Documentation

◆ apiVersion

int AppletInterface::apiVersion

read

The QML root object defined in the applet main.qml will be direct child of an AppletInterface instance.

Version of the QML2 script engine

Definition at line 62 of file appletinterface.h.

◆ associatedApplication

QString AppletInterface::associatedApplication

readwrite

Sets the associated application of this plasmoid, if the plasmoid is representing the "compact" view for some application or for some document type.

Definition at line 190 of file appletinterface.h.

◆ associatedApplicationUrls

QList< QUrl > AppletInterface::associatedApplicationUrls

readwrite

Sets the associated application of this plasmoid, if the plasmoid is representing the "compact" view for some application or for some document type.

Definition at line 195 of file appletinterface.h.

◆ availableScreenRect

QRect AppletInterface::availableScreenRect

read

screen area free of panels: the coordinates are relative to the containment, it's independent from the screen position For more precise available geometry use availableScreenRegion()

Definition at line 245 of file appletinterface.h.

◆ availableScreenRegion

QVariantList AppletInterface::availableScreenRegion

read

The available region of this screen, panels excluded.

It's a list of rectangles

Definition at line 250 of file appletinterface.h.

◆ backgroundHints

Plasma::Types::BackgroundHints AppletInterface::backgroundHints

readwrite

How the applet wants its background to be drawn.

The containment may chose to ignore this hint.

Definition at line 148 of file appletinterface.h.

◆ busy

bool AppletInterface::busy

readwrite

When true the plasmoid is busy.

The containment may graphically indicate that drawing for instance a spinner busy widget over it

Definition at line 143 of file appletinterface.h.

◆ configuration

QObject * AppletInterface::configuration

read

Configuration object: each config key will be a writable property of this object.

property bindings work.

Definition at line 138 of file appletinterface.h.

◆ configurationRequired

bool AppletInterface::configurationRequired

readwrite

If true the applet requires manual configuration from the user.

Definition at line 232 of file appletinterface.h.

◆ configurationRequiredReason

QString AppletInterface::configurationRequiredReason

readwrite

Reason why the manual user configuration is required.

Definition at line 238 of file appletinterface.h.

◆ constraintHints

Plasma::Types::ConstraintHints AppletInterface::constraintHints

readwrite

The hints that the applet gives to its constraint, such as asking to fill all the available space ignoring margins.

Definition at line 258 of file appletinterface.h.

◆ containmentDisplayHints

Plasma::Types::ContainmentDisplayHints AppletInterface::containmentDisplayHints

read

Type of the containment we're in.

Since: 5.77

Definition at line 123 of file appletinterface.h.

◆ currentActivity

QString AppletInterface::currentActivity

read

Current activity name the plasmoid is in.

Definition at line 133 of file appletinterface.h.

◆ editMode

bool AppletInterface::editMode

read

True when the Corona is in an edit mode that allows to move things around.

This is global to the Corona, all containments will have the same value for editMode

Since: 5.96

Definition at line 281 of file appletinterface.h.

◆ effectiveBackgroundHints

Plasma::Types::BackgroundHints AppletInterface::effectiveBackgroundHints

read

The effective background hints the applet has, internally decided how to mix with userBackgroundHints.

Definition at line 158 of file appletinterface.h.

◆ formFactor

Plasma::Types::FormFactor AppletInterface::formFactor

read

FormFactor for the plasmoid.

Definition at line 117 of file appletinterface.h.

◆ globalShortcut

QKeySequence AppletInterface::globalShortcut

readwrite

The global shortcut to activate the plasmoid.

This is typically only used by the default configuration module

Definition at line 222 of file appletinterface.h.

◆ hideOnWindowDeactivate

bool AppletInterface::hideOnWindowDeactivate

readwrite

Whether the dialog should be hidden when the dialog loses focus.

The default value is false.

Definition at line 214 of file appletinterface.h.

◆ icon

QString AppletInterface::icon

readwrite

Icon to represent the plasmoid.

Definition at line 107 of file appletinterface.h.

◆ id

uint AppletInterface::id

read

Applet id: is unique in the whole Plasma session and will never change across restarts.

Definition at line 112 of file appletinterface.h.

◆ immutability

Plasma::Types::ImmutabilityType AppletInterface::immutability

read

The immutability of the Corona.

Use this if you need more granular control than just using the immutable property

See also: immutable

Since: 5.23

Definition at line 175 of file appletinterface.h.

◆ immutable

bool AppletInterface::immutable

read

Whether the Corona is immutable.

The plasmoid implementation should avoid allowing "dangerous" modifications from the user when in an immutable mode

This is true when immutability is not Mutable

Definition at line 165 of file appletinterface.h.

◆ location

Plasma::Types::Location AppletInterface::location

read

Location for the plasmoid.

Definition at line 128 of file appletinterface.h.

◆ metaData

KPluginMetaData AppletInterface::metaData

read

The metadata of the applet.

Since: 5.73

Definition at line 264 of file appletinterface.h.

◆ nativeInterface

QObject * AppletInterface::nativeInterface

read

An interface to the native C++ plasmoid, if implemented.

Definition at line 227 of file appletinterface.h.

◆ pluginName

QString AppletInterface::pluginName

read

Plugin name of the plasmoid.

Definition at line 67 of file appletinterface.h.

◆ screenGeometry

QRect AppletInterface::screenGeometry

read

Provides access to the geometry of the applet is in.

Can be useful to figure out what's the absolute position of the applet.

Definition at line 207 of file appletinterface.h.

◆ self

AppletInterface * AppletInterface::self

read

Returns the Plasmoid object itself.

Workaround QML limitation/bug that does not allow to use attached properties themselves as the value of an expression.

Definition at line 273 of file appletinterface.h.

◆ status

Plasma::Types::ItemStatus AppletInterface::status

readwrite

Status of the plasmoid: useful to instruct the shell if this plasmoid is requesting attention, if is accepting input, or if is in an idle, inactive state.

Definition at line 185 of file appletinterface.h.

◆ title

QString AppletInterface::title

readwrite

User friendly title for the plasmoid: it's the localized applet name by default.

Definition at line 72 of file appletinterface.h.

◆ toolTipItem

QQuickItem * AppletInterface::toolTipItem

readwrite

This allows to set fully custom QML item as the tooltip.

It will ignore all texts set by setToolTipMainText or setToolTipSubText

Since: 5.19

Definition at line 102 of file appletinterface.h.

◆ toolTipMainText

QString AppletInterface::toolTipMainText

readwrite

Main title for the plasmoid tooltip or other means of quick information: it's the same as the title property by default, but it can be personalized.

Definition at line 78 of file appletinterface.h.

◆ toolTipSubText

QString AppletInterface::toolTipSubText

readwrite

Description for the plasmoid tooltip or other means of quick information: it comes from the pluginifo comment by default, but it can be personalized.

Definition at line 84 of file appletinterface.h.

◆ toolTipTextFormat

int AppletInterface::toolTipTextFormat

readwrite

how to handle the text format of the tooltip subtext:

Text.AutoText (default)
Text.PlainText
Text.StyledText
Text.RichText Note: in the default implementation the main text is always plain text

Definition at line 94 of file appletinterface.h.

◆ userBackgroundHints

Plasma::Types::BackgroundHints AppletInterface::userBackgroundHints

readwrite

The containment (and/or the user) may decide to use another kind of background instead (if supported by the applet)

Definition at line 153 of file appletinterface.h.

◆ userConfiguring

bool AppletInterface::userConfiguring

read

True when the user is configuring, for instance when the configuration dialog is open.

Definition at line 180 of file appletinterface.h.

Member Function Documentation

◆ activated

void AppletInterface::activated ( )

signal

Emitted when the applet's activation action is triggered.

◆ contextualActionsAboutToShow

void AppletInterface::contextualActionsAboutToShow ( )

signal

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.

◆ downloadedFiles()

QStringList AppletInterface::downloadedFiles ( ) const

Returns: The list of files that have been downloaded

Definition at line 710 of file appletinterface.cpp.

◆ downloadPath() [1/2]

QString AppletInterface::downloadPath ( ) const

Returns: A path where it is safe to write on disk downloaded files.

Since: 5.23

Definition at line 697 of file appletinterface.cpp.

◆ downloadPath() [2/2]

QString AppletInterface::downloadPath ( const QString & file )

Returns: A path where it is safe to write on disk downloaded files.

Parameters

file	that name of the file to download (unused).

Deprecated:: Since 5,23, use downloadPath() instead.

Definition at line 691 of file appletinterface.cpp.

◆ externalData

void AppletInterface::externalData	(	const QString &	mimetype,
		const QVariant &	data
	)

signal

somebody else, usually the containment sent some data to the applet

Parameters

mimetype	the mime type of the data such as text/plain
data	either the actual data or an URL representing it

◆ file() [1/2]

QString AppletInterface::file ( const QString & fileName )

FIXME: remove? Retrieve the path of a file from the Plasmoid package.

Parameters

fileName the package-recognized name, such as "mainscript"

Returns: the full absolute path of the file, if found, an empty string if not

Definition at line 408 of file appletinterface.cpp.

◆ file() [2/2]

QString AppletInterface::file	(	const QString &	fileType,
		const QString &	filePath
	)

FIXME: remove? Retrieve the path of a file from the Plasmoid package.

Parameters

fileType	the type supported from the package, such as "ui", "config" or "image"
filePath	the name of the file, such as "foo.qml" or "bar.png"

Returns: the full absolute path of the file, if found, an empty string if not

Definition at line 413 of file appletinterface.cpp.

◆ prepareContextualActions()

void AppletInterface::prepareContextualActions ( )

Should be called before retrieving any action to ensure contents are up to date.

See also: contextualActionsAboutToShow

Since: 5.58

Definition at line 854 of file appletinterface.cpp.

◆ setAction()

void AppletInterface::setAction	(	const QString &	name,
		const QString &	text,
		const QString &	icon = `QString()`,
		const QString &	shortcut = `QString()`
	)

Add an action to the Plasmoid contextual menu.

When the action is triggered a function called action_<name> will be called, if there is no function with that name actionTriggered(name) will be called instead.

Parameters

action name @text: user visible displayed text @icon: user visible optional displayed icon @shortcut: shortcut to trigger this action

Definition at line 488 of file appletinterface.cpp.

◆ setConfigurationRequired()

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

Set this to true if the plasmoid needs to be configured in order to work.

The containment will display reason as a message to ask the user to configure.

Parameters

needsConfiguring	If the plasmoid needs configuration
reason	The user readable (and localized) reason the plasmoid needs

Definition at line 403 of file appletinterface.cpp.

The documentation for this class was generated from the following files:

KDE's Doxygen guidelines are available online.

Class Picker

Quick Links

About Plasma

AppletInterface

Public Types

Properties

Signals

Public Member Functions

Static Public Member Functions

Protected Slots

Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ ActionPriority

Property Documentation

◆ apiVersion

◆ associatedApplication

◆ associatedApplicationUrls

◆ availableScreenRect

◆ availableScreenRegion

◆ backgroundHints

◆ busy

◆ configuration

◆ configurationRequired

◆ configurationRequiredReason

◆ constraintHints

◆ containmentDisplayHints

◆ currentActivity

◆ editMode

◆ effectiveBackgroundHints

◆ formFactor

◆ globalShortcut

◆ hideOnWindowDeactivate

◆ icon

◆ id

◆ immutability

◆ immutable

◆ location

◆ metaData

◆ nativeInterface

◆ pluginName

◆ screenGeometry

◆ self

◆ status

◆ title

◆ toolTipItem

◆ toolTipMainText

◆ toolTipSubText

◆ toolTipTextFormat

◆ userBackgroundHints

◆ userConfiguring

Member Function Documentation

◆ activated

◆ contextualActionsAboutToShow

◆ downloadedFiles()

◆ downloadPath() [1/2]

◆ downloadPath() [2/2]

◆ externalData

◆ file() [1/2]

◆ file() [2/2]

◆ prepareContextualActions()

◆ setAction()

◆ setConfigurationRequired()