View source for Development/Tutorials/Plasma4/JavaScript/API-PlasmoidObject

= 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: 

<syntaxhighlight lang="javascript">
plasmoid.formFactorChanged = function() { 

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

} 
</syntaxhighlight>

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:
<br>
<syntaxhighlight lang="javascript">
plasmoid.addEventListener('popupEvent', function(shown) { print('shown? ' + shown) } )
</syntaxhighlight>
<br>
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 [[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. 

* ''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 ==
* ''popupIconToolTip'': it's a JavaScript Object, it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
** ''image'': the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
** ''mainText'': the tooltip title
** ''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>

= 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)'''
* '''setMinimumSize(width, height)'''
* '''setPreferredSize(width, height)'''
* '''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: 

<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

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

== 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 {{path|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 {{path|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; 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
* '''setActionSeparator(String name)''': (API v5) adds a separator item to the context menu
* '''removeAction(String name)''': removes the item with <name>