Development/Tutorials/Plasma4/JavaScript/API-PlasmoidObject

Plasma1

The Global plasmoid Object

There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are read only, but many of which are read/write), functions, constant values and callbacks. Each are enumerated below. All of those are valid for both JavaScript and QML bindings.

Callbacks

See the section on Events above.

There are some events that are generated by Plasma for the Plasmoid. These can often be caught by providing a function assigned to a specific name in the plasmoid object. For instance, to get notified of form factor changes, one would provide a formFactorChanged method as follows:

plasmoid.formFactorChanged = function() { 

    print("the form factor has changed to: " + plasmoid.formFactor())

}

The following callbacks are used to notify the Plasmoid of changes in its running environment:

• configChanged()
• currentActivityChanged()
• formFactorChanged()
• immutabilityChanged()
• locationChanged()
• sizeChanged()

Other callbacks include:

• dataUpdated(String source, Map[String, Any] data): used to pass in DataEngine updates
• activate(): called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance. (API v2)
• initExtenderItem(Extender extender): Called when an Extender should be set up. (API v2)
• popupEvent(boolean shown): called on PopupApplets when the popup is shown or hidden. (API v2)

In API v2, all of these callbacks can also be used as events. So, for instance, instead of implementing plasmoid.popupEvent, one could also write:

plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )

This would also suppress any calls to plasmoid.popupEvent.

Further documentation on these callbacks can be found in the relevant sections below.

Environment

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

• apiVersion: the integer version of the Simplified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.

• formFactor: one of Planar (e.g. on a desktop or in an application main view), Horizontal, Vertical or MediaCenter. When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.

• size: the size of the Plasmoid, expressed in QSizeF (explained below). when it changes, plasmoid.sizeChanged() will be called.

• location: one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge. When the location changes, the plasmoid.locationChanged function, if defined in the Plasmoid, is called.

• immutable: this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.

• currentActivity: the current contextual activity name. When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.

• shouldConserveResources: true if the plasmoid should not be doing anything that would create too much draw on power, e.g. when on a device with low battery power it may be a good idea not to run a computationally expensive but optional animation

• userConfiguring: true if the user configuration interface is currently being displayed.

Properties

A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

• AspectRatioMode aspectRatioMode: defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[1]] documentation for values and their meaning.

• BackgroundHints backgroundHints: defines how the background of the widget is rendered. See the BackgroundHints documentation for values and their meaning.

• boolean busy: set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

• SizePolicy horizontalSizePolicy: behaviour of the plasmoid in an horizontal layout such as a panel. It may be:
  • Fixed: The QWidget::sizeHint() is the only acceptable alternative, so the widget can never grow or shrink (e.g. the vertical direction of a push button).
  • Minimum: The sizeHint() is minimal, and sufficient. The widget can be expanded, but there is no advantage to it being larger (e.g. the horizontal direction of a push button). It cannot be smaller than the size provided by sizeHint().
  • Maximum: The sizeHint() is a maximum. The widget can be shrunk any amount without detriment if other widgets need the space (e.g. a separator line). It cannot be larger than the size provided by sizeHint().
  • Preferred: The sizeHint() is best, but the widget can be shrunk and still be useful. The widget can be expanded, but there is no advantage to it being larger than sizeHint() (the default QWidget policy).
  • Expanding: The sizeHint() is a sensible size, but the widget can be shrunk and still be useful. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
  • MinimumExpanding: The sizeHint() is minimal, and sufficient. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
  • Ignored: The sizeHint() is ignored. The widget will get as much space as possible.

• SizePolicy verticalSizePolicy: behaviour of the plasmoid in a vertical layout such as a panel.

PopupApplet specific

• QIcon popupIcon: it will be used instead of the applet content when the applet is in a panel
• Object popupIconToolTip: it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
  • variant image: the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
  • String mainText: the tooltip title
  • String subText: the tooltip descriptive subtext

      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data

• bool passivePopup: if true when the popup is opened other windows can gain focus and the popup won't close

• bool popupShowing: true when the popupapplet is iconified and its popup is open

Containment specific

• Array(Object) applets: List of all applets in the containment
• bool drawWallpaper: Enable/disable the wallpaper painting by the containment
• enum containmentType: one of
  • DesktopContainment: A desktop containment
  • PanelContainment: A desktop panel
  • CustomContainment: A containment that is neither a desktop nor a panel but something application specific
  • CustomPanelContainment: A customized desktop panel

• int screen: Number of the screen this containment is in
• string activityName: The name of the activity this containment belongs to.
• string activityId: The id of the activity this containment belongs to.

The following API is only available from declarative containments.

• ToolBox toolBox(): The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:
  • Array(QAction) actions: A list of actions provided by the Containment.

Geometry

Read Only Properties:

• QRectF rect: the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0)

Functions:

• resize(width, height) - must not be called on widget creation (that will break external resizing; e.g. user interaction), and should only be called as a last resort during runtime. Almost always content should scale to the size of the plasmoid.
• setMinimumSize(width, height) - Not to be used from QML, where top level minimumWidth and minimumHeight properties are used instead
• setPreferredSize(width, height) - Not to be used from QML
• setBackgroundHints(background) - use NoBackground as value if you want to remove the default plasmoid background box.
• popupIcon(QIcon("some icon")) - set icon to show when the plasmoid is added to the taskbar. NOTE if the plasmoid is made in QML, you MUST specify a default size for the main Item. This size will be used for the plasmoid when added to the taskbar

Painting and Layout

To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:

    plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }

See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.

Read/Write Properties:

• Layout layout: the QGraphicsLayout associated with the Plasmoid for laying out top level items; this property is read-write, though the property is not usually set as one can simply do "new LinearLayout" (or one of the other layout classes provided) and it will be automatically associated with the Plasmoid.

Functions:

• update(): triggers a full repaint of the Plasmoid.
• update(QRectF rect) triggers a repaint of the rect area of the Plasmoid.
• failedToLaunch(bool failed[, string reason]) sets the launch status of the Plasmoid; if set to true, the script will stop executing and the reason message, if any, will be displayed to the user.

Access To Packaged Files

Functions:

• string file(string type[, string fileName]): returns the path to a file in the Plasmoid package of the given type, optionally with a file name to match, e.g.
  

var path = plasmoid.file("mainscript")

or

var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))

• bool include(string filename): attempts to include the script defined from the package's code directory

Configuration Data

Configuration values can be defined using KConfig XT XML files in the contents/config/ directory of the Plasmoid's package. The default file that is looked for and used is contents/config/main.xml.

Accessing Configuration Data

Read-write properties:

• String activeConfig: The current active configuration description. For instance, setting it to "foo" would cause the Plasmoid to try and reference the contents/config/foo.xml KConfigXT file. Setting this to an empty string will switch to the main.xml file.

Functions:

• any readConfig(String key): reads the value from the configuration data for the given key as defined by the currently active configuration.

• writeConfig(String key, any value) : writes a value to the configuration store under the given key

User Customization

User customization can be offered by providing a Qt Designer file called contents/ui/config.ui in the Plasmoid's package.

Callbacks:

• configChanged(): callback function called when the configuration is changed external to the Plasmoid, e.g. when the user changes settings in a configuration dialog.

Context menu

It's possible to add some items to the popup menu of the Plasmoid.

Functions:

• setAction(String name, String text, String icon, String shortcut): adds an item to the context menu with the given text and icon;

In pure JavaScript plasmoids you need to define plasmoid.action_<name> function, where <name> is the first argument for setAction call, and this function will be called each time user clicks the item.
Similarly in QML plasmoids you must define a function action_<name> in the root qml item that will handle the action click.

• setActionSeparator(String name): (API v5) adds a separator item to the context menu
• removeAction(String name): removes the item with <name>

Plasma2

The Global plasmoid Object

There is a global object available to the Plasmoid called, appropriately, "plasmoid". It has a number of useful properties (some of which are read only, but many of which are read/write), functions, constant values and callbacks. Each are enumerated below. All of those are valid for both JavaScript and QML bindings.

Callbacks

See the section on Events above.

There are some events that are generated by Plasma2 for the Plasmoid. These can often be caught by providing a function assigned to a specific name in the plasmoid object.

The following callbacks are used to notify the Plasmoid of changes in its running environment:

• currentActivityChanged()
• formFactorChanged()
• immutabilityChanged()
• locationChanged()
• sizeChanged()

Other callbacks include:

• dataUpdated(String source, Map[String, Any] data): used to pass in DataEngine updates
• activate(): called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance. (API v2)
• initExtenderItem(Extender extender): Called when an Extender should be set up. (API v2)
• popupEvent(boolean shown): called on PopupApplets when the popup is shown or hidden. (API v2)

Further documentation on these callbacks can be found in the relevant sections below.

Environment

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

• apiVersion: the integer version of the Simplified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.

• formFactor: one of Planar (e.g. on a desktop or in an application main view), Horizontal, Vertical or MediaCenter. When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.

• size: the size of the Plasmoid, expressed in QSizeF (explained below). when it changes, plasmoid.sizeChanged() will be called.

• location: one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge. When the location changes, the plasmoid.locationChanged function, if defined in the Plasmoid, is called.

• immutable: this property is set to true when the Plasmoid is set to not be movable or otherwise changeable, and false otherwise. Configuration is still usually allowed in this state. When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.

• currentActivity: the current contextual activity name. When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.

• shouldConserveResources: true if the plasmoid should not be doing anything that would create too much draw on power, e.g. when on a device with low battery power it may be a good idea not to run a computationally expensive but optional animation

Properties

A set of read/write properties that allow the Plasmoid to set various visual or functional properties:

• AspectRatioMode aspectRatioMode: defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[2]] documentation for values and their meaning.

For eg:

  plasmoid.aspectRatioMode = IgnoreAspectRatio;

• BackgroundHints backgroundHints: defines how the background of the widget is rendered.

For eg:

 plasmoid.backgroundHints = 0;

See the BackgroundHints documentation for values and their meaning.

• boolean busy: set to true when the Plasmoid is currently processing or waiting for data and the user interface should be blocked while doing so; will generally show a full-Plasmoid animated overlay to denote business

• SizePolicy horizontalSizePolicy: behaviour of the plasmoid in an horizontal layout such as a panel. It may be:
  • Fixed: The QWidget::sizeHint() is the only acceptable alternative, so the widget can never grow or shrink (e.g. the vertical direction of a push button).
  • Minimum: The sizeHint() is minimal, and sufficient. The widget can be expanded, but there is no advantage to it being larger (e.g. the horizontal direction of a push button). It cannot be smaller than the size provided by sizeHint().
  • Maximum: The sizeHint() is a maximum. The widget can be shrunk any amount without detriment if other widgets need the space (e.g. a separator line). It cannot be larger than the size provided by sizeHint().
  • Preferred: The sizeHint() is best, but the widget can be shrunk and still be useful. The widget can be expanded, but there is no advantage to it being larger than sizeHint() (the default QWidget policy).
  • Expanding: The sizeHint() is a sensible size, but the widget can be shrunk and still be useful. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
  • MinimumExpanding: The sizeHint() is minimal, and sufficient. The widget can make use of extra space, so it should get as much space as possible (e.g. the horizontal direction of a horizontal slider).
  • Ignored: The sizeHint() is ignored. The widget will get as much space as possible.

• SizePolicy verticalSizePolicy: behaviour of the plasmoid in a vertical layout such as a panel.

PopupApplet specific

• popupIcon: it will be used instead of the applet content when the applet is in a panel
• Object popupIconToolTip: it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
  • variant image: the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
  • String mainText: the tooltip title
  • String subText: the tooltip descriptive subtext

      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data

• bool passivePopup: if true when the popup is opened other windows can gain focus and the popup won't close

• bool popupShowing: true when the popupapplet is iconified and its popup is open

Containment specific

• Array(Object) applets: List of all applets in the containment
• bool drawWallpaper: Enable/disable the wallpaper painting by the containment
• enum containmentType: one of
  • DesktopContainment: A desktop containment
  • PanelContainment: A desktop panel
  • CustomContainment: A containment that is neither a desktop nor a panel but something application specific
  • CustomPanelContainment: A customized desktop panel

• int screen: Number of the screen this containment is in
• string activityName: The name of the activity this containment belongs to.
• string activityId: The id of the activity this containment belongs to.

The following API is only available from declarative containments.

• ToolBox toolBox(): The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:
  • Array(QAction) actions: A list of actions provided by the Containment.

Geometry

Read Only Properties:

• QRectF rect: the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0)

Functions:

• resize(width, height) - must not be called on widget creation (that will break external resizing; e.g. user interaction), and should only be called as a last resort during runtime. Almost always content should scale to the size of the plasmoid.
• backgroundHints(background) - use NoBackground as value if you want to remove the default plasmoid background box.
• popupIcon("some icon") - set icon to show when the plasmoid is added to the taskbar. NOTE if the plasmoid is made in QML, you MUST specify a default size for the main Item. This size will be used for the plasmoid when added to the taskbar

Painting and Layout

To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:

    plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }

See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.

Read/Write Properties:

• Layout layout: the QGraphicsLayout associated with the Plasmoid for laying out top level items; this property is read-write, though the property is not usually set as one can simply do "new LinearLayout" (or one of the other layout classes provided) and it will be automatically associated with the Plasmoid.

Functions:

• update(): triggers a full repaint of the Plasmoid.
• update(QRectF rect) triggers a repaint of the rect area of the Plasmoid.
• failedToLaunch(bool failed[, string reason]) sets the launch status of the Plasmoid; if set to true, the script will stop executing and the reason message, if any, will be displayed to the user.

Access To Packaged Files

Functions:

• string file(string type[, string fileName]): returns the path to a file in the Plasmoid package of the given type, optionally with a file name to match, e.g.
  

var path = plasmoid.file("mainscript")

or

var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))

• bool include(string filename): attempts to include the script defined from the package's code directory

User Customization

In plasma2 , config.ui no longer provides user customization , instead qml2.0 can be used instead .

Context menu

It's possible to add some items to the popup menu of the Plasmoid.

Functions:

• setAction(String name, String text, String icon, String shortcut): adds an item to the context menu with the given text and icon;

In pure JavaScript plasmoids you need to define plasmoid.action_<name> function, where <name> is the first argument for setAction call, and this function will be called each time user clicks the item.
Similarly in QML plasmoids you must define a function action_<name> in the root qml item that will handle the action click.

• setActionSeparator(String name): (API v5) adds a separator item to the context menu
• removeAction(String name): removes the item with <name>