Development/Tutorials/Plasma4/JavaScript/API-PlasmoidObject: Difference between revisions

From KDE TechBase
(Created page with '== 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 r...')
 
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
== The Global plasmoid Object ==
=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.


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.
== Callbacks  ==


=== Callbacks  ===
See the section on Events above.


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:


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: <code javascript="javascript">
<syntaxhighlight lang="javascript">
plasmoid.formFactorChanged = function() {  
plasmoid.formFactorChanged = function() {  


Line 13: Line 16:


}  
}  
</code>
</syntaxhighlight>


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


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:
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:
 
<br>
<code javascript>plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )</code>
<syntaxhighlight lang="javascript">
 
plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )
</syntaxhighlight>
<br>
This would also suppress any calls to plasmoid.popupEvent.
This would also suppress any calls to plasmoid.popupEvent.


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


=== Environment  ===
== Environment  ==


A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:  
A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:  
Line 59: Line 64:
* '''userConfiguring''': true if the user configuration interface is currently being displayed.
* '''userConfiguring''': true if the user configuration interface is currently being displayed.


=== Properties  ===
== Properties  ==
A set of read/write properties that allow the Plasmoid to set various visual or functional 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 [[#AspectRatioMode|AspectRatioMode]] documentation for values and their meaning.  
* ''AspectRatioMode'' '''aspectRatioMode''': defines how to treat the aspect ratio of a Plasmoid when resizing it. See the [[http://lxr.kde.org/source/kde/kde-runtime/plasma/scriptengines/javascript/plasmoid/appletinterface.h#120|AspectRatioMode]] documentation for values and their meaning.  


* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [[#BackgroundHints|BackgroundHints]] documentation for values and their meaning.  
* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [[#BackgroundHints|BackgroundHints]] documentation for values and their meaning.  
Line 68: Line 73:
* ''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
* ''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


=== Geometry  ===
* ''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
 
  <syntaxhighlight lang="javascript">
      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data
  </syntaxhighlight>
 
* ''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:  
Read Only Properties:  
Line 77: Line 129:
Functions:  
Functions:  


* '''resize(width, height)'''
* '''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)'''
* '''setMinimumSize(width, height)''' - Not to be used from QML, where top level minimumWidth and minimumHeight properties are used instead
* '''setPreferredSize(width, height)'''
* '''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.
* '''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
* '''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  ===
== Painting and Layout  ==


To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:  
To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:  
<code javascript>
 
<syntaxhighlight lang="javascript">
     plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
     plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
</code>
</syntaxhighlight>
<br>
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.  
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.  


Line 101: Line 155:
* '''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.
* '''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  ===
== Access To Packaged Files  ==


Functions:  
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. <code javascript>var path = plasmoid.file("mainscript")</code> or <code javascript>var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</code>
* ''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. <br>
<syntaxhighlight lang="javascript">var path = plasmoid.file("mainscript")</syntaxhighlight>
<br>
or  
<br>
<syntaxhighlight lang="javascript">var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</syntaxhighlight>


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


=== Configuration Data  ===
== Configuration Data  ==
Configuration values can be defined using [[Development/Tutorials/Using_KConfig_XT|KConfig XT]] XML files in the {{path|contents/config/}} directory of the Plasmoid's package. The default file that is looked for and used is {{path|contents/config/main.xml}}.
Configuration values can be defined using [[Development/Tutorials/Using_KConfig_XT|KConfig XT]] XML files in the {{path|contents/config/}} directory of the Plasmoid's package. The default file that is looked for and used is {{path|contents/config/main.xml}}.


==== Accessing Configuration Data  ====
===Accessing Configuration Data  ===
Read-write properties:
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 {{path|contents/config/foo.xml}} KConfigXT file. Setting this to an empty string will switch to the main.xml file.
* ''String'' '''activeConfig''': The current active configuration description. For instance, setting it to "foo" would cause the Plasmoid to try and reference the {{path|contents/config/foo.xml}} KConfigXT file. Setting this to an empty string will switch to the main.xml file.
Line 121: Line 180:
* '''writeConfig(String key, any value) ''': writes a value to the configuration store under the given key
* '''writeConfig(String key, any value) ''': writes a value to the configuration store under the given key


==== User Customization  ====
== User Customization  ==


User customization can be offered by providing a Qt Designer file called {{path|contents/ui/config.ui}} in the Plasmoid's package.
User customization can be offered by providing a Qt Designer file called {{path|contents/ui/config.ui}} in the Plasmoid's package.
Line 128: Line 187:
* '''configChanged()''': callback function called when the configuration is changed external to the Plasmoid, e.g. when the user changes settings in a configuration dialog.
* '''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 ===
== Context menu ==


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


Functions:
Functions:
* '''setAction(name, text, icon, shortcut)''': adds an item to the context menu with the given text and icon; 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
* '''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.


* '''removeAction(name)''': removes the item
== 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 [[http://lxr.kde.org/source/kde/kde-runtime/plasma/scriptengines/javascript/plasmoid/appletinterface.h#120|AspectRatioMode]] documentation for values and their meaning.
For eg:
<syntaxhighlight lang="javascript">
  plasmoid.aspectRatioMode = IgnoreAspectRatio;
</syntaxhighlight>
 
* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered.
For eg:
  <syntaxhighlight lang="javascript">
plasmoid.backgroundHints = 0;
  </syntaxhighlight>
See the [[#BackgroundHints|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
 
  <syntaxhighlight lang="javascript">
      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data
  </syntaxhighlight>
 
* ''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:
 
<syntaxhighlight lang="javascript">
    plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
</syntaxhighlight>
<br>
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. <br>
<syntaxhighlight lang="javascript">var path = plasmoid.file("mainscript")</syntaxhighlight>
<br>
or
<br>
<syntaxhighlight lang="javascript">var pm = new QPixmap(plasmoid.file("images", "mypixmap.png"))</syntaxhighlight>
 
* ''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>

Latest revision as of 23:27, 11 September 2014

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>