Difference between revisions of "Development/Tutorials/Plasma4/JavaScript/API"

Jump to: navigation, search
m (Fixed list formatting)
Line 1: Line 1:
= Introduction to Plasmoids JavaScript API =
+
= Introduction to Plasmoids JavaScript API =
  
If you have not done so already, please read the "plasmoid" design document first.
+
If you have not done so already, please read the "plasmoid" design document first.  
  
== What Is A Simplified JavaScript Plasmoid? ==
+
== What Is A Simplified JavaScript Plasmoid? ==
  
This document describes the native Plasma API available to Simplified JavaScript Plasmoids. What makes them "Simplified" is that they do not have access to the entire C++ API in the Plasma, KDE and Qt libraries (let alone things lower in the API stack). This helps ensure that these Plasmoids are more likely to work properly between releases as changes in underlying API don't affect them as well as allowing Plasma to offer stronger security guarantees around them.
+
This document describes the native Plasma API available to Simplified JavaScript Plasmoids. What makes them "Simplified" is that they do not have access to the entire C++ API in the Plasma, KDE and Qt libraries (let alone things lower in the API stack). This helps ensure that these Plasmoids are more likely to work properly between releases as changes in underlying API don't affect them as well as allowing Plasma to offer stronger security guarantees around them.  
  
To denote that this Plasmoid is a Simplified JavaScript widget, ensure that in the metadata.desktop file there is this line:
+
To denote that this Plasmoid is a Simplified JavaScript widget, ensure that in the metadata.desktop file there is this line:  
  
X-Plasma-API=javascript
+
X-Plasma-API=javascript  
  
What follows is a description of the runtime environment available to a Simplified JavaScript Plasmoid.
+
What follows is a description of the runtime environment available to a Simplified JavaScript Plasmoid.  
  
== QtScript ==
+
== QtScript ==
  
The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid. As an interesting implementation note, QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.
+
The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid. As an interesting implementation note, QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.  
  
On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in this context is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with diconnnect()) and any function defined in the Plasmoid may be used as a slot. For example:
+
On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in this context is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with diconnnect()) and any function defined in the Plasmoid may be used as a slot. For example:  
  
 
     function onClick()
 
     function onClick()
Line 35: Line 35:
 
     button.clicked()
 
     button.clicked()
  
This will print out:
+
This will print out:  
  
We got clicked!
+
We got clicked! First click!  
First click!
 
  
on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.
+
on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.  
  
== The Global plasmoid Object ==
+
== 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.
+
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 ===
  
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:  
 +
 
 +
plasmoid.formFactorChanged = function() {
  
plasmoid.formFactorChanged = function()
 
{
 
 
     print("the form factor has changed to: " + plasmoid.formFactor())
 
     print("the form factor has changed to: " + plasmoid.formFactor())
}
 
  
=== 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:
+
* apiVersion: the integer version of the Simlified JavaScript API in the current execution environment; can be used to change behaviour or usage of functions depending on the version number.
* apiVersion: the integer version of the Simlified 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.
* 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.
 
   When the form factor changes, the plasmoid.formFactorChanged function, if defined in the Plasmoid, is called.
* location: one of Floating (no specific location), Desktop (on the application's main view are), FullScreen, LeftEdge, RightEdge, TopEdge or ButtomEdge
+
* 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.locatationChanged function, if defined in the Plasmoid, is called.
 
   When the location changes, the plasmoid.locatationChanged 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.
+
* 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.
 
   When the immutability changes, the plasmoid.immutabilityChanged function, if defined in the Plasmoid, is called.
* currentActivity: the current contextual activity name
+
* currentActivity: the current contextual activity name
 
   When the current activity changes, the plasmoid.currentActivityChanged function, if defined in the Plasmoid, is called.
 
   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
+
* 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: defines how to treat the aspect ratio of a Plasmoid when resizing it, one of:
 +
**** IgnoreAspectRatio: The Plasmoid can be freely resized
 +
**** KeepAspectRatio: The Plasmoid keeps a fixed aspect ratio
 +
**** Square: The Plasmoid is always a square
 +
**** ConstrainedSquare: The Plasmoid is no wider (in horizontal formfactors) or no higher (in vertical ones) than a square
 +
**** FixedSize: The Plasmoid cannot be resized
 +
* 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  ===
 +
 
 +
Functions:
 +
 
 +
* resize(width, height)
 +
* setMinimumSize(width, height)
 +
* setPreferredSize(width, height)
 +
 
 +
Properties:
  
=== Properties ===
+
* rect: the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0); this property is read only
  
A set of read/write properties that allow the Plasmoid to set various visual or functional properties:
+
=== Painting and Layout ===
  * aspectRatioMode: defines how to treat the aspect ratio of a Plasmoid when resizing it, one of:
 
    * IgnoreAspectRatio: The Plasmoid can be freely resized
 
    * KeepAspectRatio: The Plasmoid keeps a fixed aspect ratio
 
    * Square: The Plasmoid is always a square
 
    * ConstrainedSquare: The Plasmoid is no wider (in horizontal formfactors) or no higher (in vertical ones) than a square
 
    * FixedSize: The Plasmoid cannot be resized
 
* 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 ===
+
To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:
  
Functions:
+
    plasmoid.paintInterface = function(painter) { /* painting code goes here*/ }
* resize(width, height)
 
* setMinimumSize(width, height)
 
* setPreferredSize(width, height)
 
  
Properties:
+
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.
* rect: the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0); this property is read only
 
  
=== Painting and Layout ===
+
Functions:
  
To paint directly on to the canvas, a widget may implement the paintInterface function in the plasmoid object:
+
* 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
  
    plasmoid.paintInterface = function(painter) { /* painting code goes here */ }
+
Properties:
  
See the Painting section below for information about helpful classes and functions that can be used when implementing a paintInterface function.
+
* 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:
+
<br>
* 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
 
  
Properties:
+
=== Access To Packaged Files ===
  * 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:
  
=== Access To Packaged Files ===
+
* string file(string type, string fileName): returns the path to a file named fileName in the Plasmoid package of the given type; e.g. file("images", "mypixmap.png")
 +
* string file(string type): returns the path to a file named as part of the package, e.g.: file("mainscript")
 +
* bool include(string filename): attempts to include the script defined from the package's scripts directory
  
Functions:
+
== User Interface Elements ==
  * string file(string type, string fileName): returns the path to a file named fileName in the Plasmoid package of the given type; e.g. file("images", "mypixmap.png")
 
* string file(string type): returns the path to a file named as part of the package, e.g.: file("mainscript")
 
* bool include(string filename): attempts to include the script defined from the package's scripts directory
 
  
== User Interface Elements ==
+
=== Plasma Widgets  ===
  
 +
The Plasma framework provides a set of standard user interface elmenets such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.
  
=== Plasma Widgets ===
+
=== Properties  ===
  
The Plasma framework provides a set of standard user interface elmenets such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.
+
By default, all of the Plasma user interface elements have the following properties:
  
=== Properties ===
+
*''string'' '''stylesheet'''<br>A CSS stylesheet describing visual properties to apply to the widget; see [http://doc.trolltech.com/4.5/stylesheet.html the Qt Documentation for more information]
  
By default, all of the Plasma user interface elements have the following properties:
+
*objectName
 +
*opacity
 +
*enabled
 +
*visible
 +
*pos
 +
*x
 +
*y
 +
*z
 +
*rotation
 +
*scale
 +
*transformOriginPoint
 +
*palette
 +
*font
 +
*size
 +
*focusPolicy
 +
*geometry
  
* ''string'' '''stylesheet'''<br>A CSS stylesheet describing visual properties to apply to the widget; see [http://doc.trolltech.com/4.5/stylesheet.html the Qt Documentation for more information]
+
=== Signals  ===
  
* objectName
+
opacityChanged() visibleChanged() enabledChanged() xChanged() yChanged() zChanged() rotationChanged() scaleChanged()
* opacity
 
* enabled
 
* visible
 
* pos
 
* x
 
* y
 
* z
 
* rotation
 
* scale
 
* transformOriginPoint
 
* palette
 
* font
 
* size
 
* focusPolicy
 
* geometry
 
  
=== Signals ===
+
=== Undocumented Properties and Functions  ===
  
opacityChanged()
+
There are a handful of other undocument properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should be used or relied upon.
visibleChanged()
 
enabledChanged()
 
xChanged()
 
yChanged()
 
zChanged()
 
rotationChanged()
 
scaleChanged()
 
  
=== Undocumented Properties and Functions ===
+
=== UI Element Gallery  ===
  
There are a handful of other undocument properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should be used or relied upon.
+
BusyWidget
  
=== UI Element Gallery ===
+
** boolean running
 +
** string label
 +
** function clicked()
  
BusyWidget
+
CheckBox
  * boolean running
 
  * string label
 
  * function clicked()
 
  
CheckBox
+
** string text
  * string text
+
** string image
  * string image
+
** string styleSheet
  * string styleSheet
+
** boolean isChecked
  * boolean isChecked
+
** function toggled(bool)
  * function toggled(bool)
 
  
ComboBox
+
ComboBox  
  * string text
 
  * string styleSheet
 
  * function activated(QString)
 
  * function textChanged(QString)
 
  * function clear()
 
  
FlashingLabel
+
** string text
  * boolean autohide
+
** string styleSheet
  * object color
+
** function activated(QString)
  * number duration
+
** function textChanged(QString)
  * function kill()
+
** function clear()
  * function fadeIn()
 
  * function fadeOut()
 
  * function flash(QString,int,QTextOption)
 
  * function flash(QString,int)
 
  * function flash(QString)
 
  * function flash(QPixmap,int,Qt::Alignment)
 
  * function flash(QPixmap,int)
 
  * function flash(QPixmap)
 
  
Frame
+
FlashingLabel
  * number frameShadow
 
  * string text
 
  * string image
 
  * string styleSheet
 
  * number Plain
 
  * number Raised
 
  * number Sunken
 
  
GroupBox
+
** boolean autohide
  * string text
+
** object color
  * string styleSheet
+
** number duration
 +
** function kill()
 +
** function fadeIn()
 +
** function fadeOut()
 +
** function flash(QString,int,QTextOption)
 +
** function flash(QString,int)
 +
** function flash(QString)
 +
** function flash(QPixmap,int,Qt::Alignment)
 +
** function flash(QPixmap,int)
 +
** function flash(QPixmap)
  
IconWidget
+
Frame
  * string text
 
  * string infoText
 
  * object icon
 
  * object textBackgroundColor
 
  * object iconSize
 
  * string svg
 
  * undefined action
 
  * number orientation
 
  * number numDisplayLines
 
  * function pressed(bool)
 
  * function clicked()
 
  * function doubleClicked()
 
  * function activated()
 
  * function changed()
 
  * function setPressed(bool)
 
  * function setPressed()
 
  * function setUnpressed()
 
  * function setIcon(QString)
 
  
ItemBackground
+
** number frameShadow
  * object target
+
** string text
  * object targetItem
+
** string image
  * function appearanceChanged()
+
** string styleSheet
  * function animationStep(qreal)
+
** number Plain
  * function targetReached(QRectF)
+
** number Raised
  * function targetItemReached(QGraphicsItem*)
+
** number Sunken
  
Label
+
GroupBox
  * string text
 
  * string image
 
  * number alignment
 
  * boolean hasScaledContents
 
  * string styleSheet
 
  * function linkActivated(QString)
 
  * function linkHovered(QString)
 
  * function dataUpdated(QString,Plasma::DataEngine::Data)
 
  
LineEdit
+
** string text
  * string text
+
** string styleSheet
  * boolean isClearButtonShown
 
  * string styleSheet
 
  * function editingFinished()
 
  * function returnPressed()
 
  * function textEdited(QString)
 
  * function textChanged(QString)
 
  
Meter
+
IconWidget
  * number minimum
 
  * number maximum
 
  * number value
 
  * string svg
 
  * number meterType
 
  * function dataUpdated(QString,Plasma::DataEngine::Data)
 
  * number BarMeterHorizontal
 
  * number BarMeterVertical
 
  * number AnalogMeter
 
  
PushButton
+
** string text
  * string text
+
** string infoText
  * string image
+
** object icon
  * undefined action
+
** object textBackgroundColor
  * object icon
+
** object iconSize
  * boolean checkable
+
** string svg
  * boolean checked
+
** undefined action
  * boolean down
+
** number orientation
  * function pressed()
+
** number numDisplayLines
  * function released()
+
** function pressed(bool)
  * function clicked()
+
** function clicked()
  * function toggled(bool)
+
** function doubleClicked()
 +
** function activated()
 +
** function changed()
 +
** function setPressed(bool)
 +
** function setPressed()
 +
** function setUnpressed()
 +
** function setIcon(QString)
  
RadioButton
+
ItemBackground
  * string text
 
  * string image
 
  * string styleSheet
 
  * boolean isChecked
 
  * function toggled(bool)
 
  
ScrollWidget
+
** object target
  * object widget
+
** object targetItem
  * number horizontalScrollBarPolicy
+
** function appearanceChanged()
  * number verticalScrollBarPolicy
+
** function animationStep(qreal)
  * object scrollPosition
+
** function targetReached(QRectF)
  * object contentsSize
+
** function targetItemReached(QGraphicsItem*)
  * object viewportGeometry
 
  * string styleSheet
 
  * function ensureRectVisible(QRectF)
 
  * function ensureItemVisible(QGraphicsItem*)
 
  * function registerAsDragHandle(QGraphicsWidget*)
 
  * function unregisterAsDragHandle(QGraphicsWidget*)
 
  
ScrollBar
+
Label
  * number singleStep
 
  * number pageStep
 
  * number value
 
  * number minimum
 
  * number maximum
 
  * function valueChanged(int)
 
  * function setValue(int)
 
  * function setOrientation(Qt::Orientation)
 
  
Separator
+
** string text
  * number orientation
+
** string image
 +
** number alignment
 +
** boolean hasScaledContents
 +
** string styleSheet
 +
** function linkActivated(QString)
 +
** function linkHovered(QString)
 +
** function dataUpdated(QString,Plasma::DataEngine::Data)
  
SignalPlotter
+
LineEdit
  * string title
 
  * string unit
 
  * boolean useAutoRange
 
  * number horizontalScale
 
  * boolean showVerticalLines
 
  * object verticalLinesColor
 
  * number verticalLinesDistance
 
  * boolean verticalLinesScroll
 
  * boolean showHorizontalLines
 
  * object horizontalLinesColor
 
  * object fontColor
 
  * number horizontalLinesCount
 
  * boolean showLabels
 
  * boolean showTopBar
 
  * object backgroundColor
 
  * string svgBackground
 
  * boolean thinFrame
 
  * boolean stackPlots
 
  
Slider
+
** string text
  * number maximum
+
** boolean isClearButtonShown
  * number minimum
+
** string styleSheet
  * number value
+
** function editingFinished()
  * number orientation
+
** function returnPressed()
  * string styleSheet
+
** function textEdited(QString)
  * function sliderMoved(int)
+
** function textChanged(QString)
  * function valueChanged(int)
 
  * function setMaximum(int)
 
  * function setMinimum(int)
 
  * function setRange(int,int)
 
  * function setValue(int)
 
  * function setOrientation(Qt::Orientation)
 
  
SpinBox
+
Meter
  * number maximum
 
  * number minimum
 
  * number value
 
  * string styleSheet
 
  * function sliderMoved(int)
 
  * function valueChanged(int)
 
  * function editingFinished()
 
  * function setMaximum(int)
 
  * function setMinimum(int)
 
  * function setRange(int,int)
 
  * function setValue(int)
 
  
SvgWidget
+
** number minimum
  * undefined svg
+
** number maximum
  * string elementID
+
** number value
  * function clicked(Qt::MouseButton)
+
** string svg
 +
** number meterType
 +
** function dataUpdated(QString,Plasma::DataEngine::Data)
 +
** number BarMeterHorizontal
 +
** number BarMeterVertical
 +
** number AnalogMeter
  
TabBar
+
PushButton
  * number currentIndex
 
  * number count
 
  * string styleSheet
 
  * boolean tabBarShown
 
  * function currentChanged(int)
 
  * function setCurrentIndex(int)
 
  * function insertTab(int,QIcon,QString,QGraphicsLayoutItem*)
 
  * function insertTab(int,QIcon,QString)
 
  * function insertTab(int,QString,QGraphicsLayoutItem*)
 
  * function insertTab(int,QString)
 
  * function addTab(QIcon,QString,QGraphicsLayoutItem*)
 
  * function addTab(QIcon,QString)
 
  * function addTab(QString,QGraphicsLayoutItem*)
 
  * function addTab(QString)
 
  * function removeTab(int)
 
  * function takeTab(int)
 
  * function tabAt(int)
 
  * function setTabText(int,QString)
 
  * function tabText(int)
 
  * function setTabIcon(int,QIcon)
 
  * function tabIcon(int)
 
  
TextEdit
+
** string text
  * string text
+
** string image
  * boolean readOnly
+
** undefined action
  * function textChanged()
+
** object icon
  * function dataUpdated(QString,Plasma::DataEngine::Data)
+
** boolean checkable
 +
** boolean checked
 +
** boolean down
 +
** function pressed()
 +
** function released()
 +
** function clicked()
 +
** function toggled(bool)
  
ToolButton
+
RadioButton
  * string text
 
  * boolean autoRaise
 
  * string image
 
  * undefined action
 
  * function clicked()
 
  * function pressed()
 
  * function released()
 
  
TreeView
+
** string text
  * undefined model
+
** string image
  * string styleSheet
+
** string styleSheet
 +
** boolean isChecked
 +
** function toggled(bool)
  
VideoWidget
+
ScrollWidget
  * string url
 
  * number currentTime
 
  * number totalTime
 
  * number remainingTime
 
  * number usedControls
 
  * boolean controlsVisible
 
  * string styleSheet
 
  * function tick(qint64)
 
  * function aboutToFinish()
 
  * function nextRequested()
 
  * function previousRequested()
 
  * function play()
 
  * function pause()
 
  * function stop()
 
  * function seek(qint64)
 
  * function mediaObject()
 
  * function audioOutput()
 
  * number NoControls
 
  * number Play
 
  * number Pause
 
  * number Stop
 
  * number PlayPause
 
  * number Previous
 
  * number Next
 
  * number Progress
 
  * number Volume
 
  * number OpenFile
 
  * number DefaultControls
 
  
WebView
+
** object widget
  * object url
+
** number horizontalScrollBarPolicy
  * string html
+
** number verticalScrollBarPolicy
  * boolean dragToScroll
+
** object scrollPosition
  * object scrollPosition
+
** object contentsSize
  * object contentsSize
+
** object viewportGeometry
  * object viewportGeometry
+
** string styleSheet
  * function loadProgress(int)
+
** function ensureRectVisible(QRectF)
  * function loadFinished(bool)
+
** function ensureItemVisible(QGraphicsItem*)
 +
** function registerAsDragHandle(QGraphicsWidget*)
 +
** function unregisterAsDragHandle(QGraphicsWidget*)
  
=== Layouts ===
+
ScrollBar
  
LinearLayout
+
** number singleStep
AnchorLayout
+
** number pageStep
 +
** number value
 +
** number minimum
 +
** number maximum
 +
** function valueChanged(int)
 +
** function setValue(int)
 +
** function setOrientation(Qt::Orientation)
  
=== Creating Items From UI Files ===
+
Separator
  
TODO
+
** number orientation
  
== Animations ==
+
SignalPlotter
  
An animation object can be retrieved by calling the animation(string) method.
+
** string title
The string corresponds to the Plasma::Animator::Animation enumeration, and currently
+
** string unit
the following are supported (case insensitive) along with a list of their properties:
+
** boolean useAutoRange
 +
** number horizontalScale
 +
** boolean showVerticalLines
 +
** object verticalLinesColor
 +
** number verticalLinesDistance
 +
** boolean verticalLinesScroll
 +
** boolean showHorizontalLines
 +
** object horizontalLinesColor
 +
** object fontColor
 +
** number horizontalLinesCount
 +
** boolean showLabels
 +
** boolean showTopBar
 +
** object backgroundColor
 +
** string svgBackground
 +
** boolean thinFrame
 +
** boolean stackPlots
  
* fade
+
Slider
* grow
 
* expand
 
* pause
 
* pulse
 
* rotate
 
* rotateStacked
 
* slide
 
  
All animations support the following properties:
+
** number maximum
 +
** number minimum
 +
** number value
 +
** number orientation
 +
** string styleSheet
 +
** function sliderMoved(int)
 +
** function valueChanged(int)
 +
** function setMaximum(int)
 +
** function setMinimum(int)
 +
** function setRange(int,int)
 +
** function setValue(int)
 +
** function setOrientation(Qt::Orientation)
  
* duration (int): length of the animation in ms
+
SpinBox
* widgetToAnimate: the QGraphicsWidget (e.g. a Plasma::Widget) to operate on
 
* forwards (bool): true if the animation should play forwards or false if backwards (rewind)
 
* visible (bool): whether or not the animation is currently visible (??!?!)
 
  
By default the animation object is associated with the plasmoid itself. By setting
+
** number maximum
the widgetToAnimate property, however, it can be re-assigned to any QGraphicsWidget
+
** number minimum
(e.g. Plasma widgets such as push buttons, sliders, etc) one wants.
+
** number value
 +
** string styleSheet
 +
** function sliderMoved(int)
 +
** function valueChanged(int)
 +
** function editingFinished()
 +
** function setMaximum(int)
 +
** function setMinimum(int)
 +
** function setRange(int,int)
 +
** function setValue(int)
  
Animations may also be put into groups for convenient sequential or parallel running
+
SvgWidget
by creating an AnimationGroup object and then calling add(widget) on it. The parallel (bool)
 
property holds whether or not the animations should be run in parallel or sequentially.
 
The default is sequential.
 
  
== Painting ==
+
** undefined svg
 +
** string elementID
 +
** function clicked(Qt::MouseButton)
  
See the "Painting and Layout" section, part of the Global Plasmoid chapter, for information on using these classes within a widget.
+
TabBar
  
=== Pixmaps ===
+
** number currentIndex
 +
** number count
 +
** string styleSheet
 +
** boolean tabBarShown
 +
** function currentChanged(int)
 +
** function setCurrentIndex(int)
 +
** function insertTab(int,QIcon,QString,QGraphicsLayoutItem*)
 +
** function insertTab(int,QIcon,QString)
 +
** function insertTab(int,QString,QGraphicsLayoutItem*)
 +
** function insertTab(int,QString)
 +
** function addTab(QIcon,QString,QGraphicsLayoutItem*)
 +
** function addTab(QIcon,QString)
 +
** function addTab(QString,QGraphicsLayoutItem*)
 +
** function addTab(QString)
 +
** function removeTab(int)
 +
** function takeTab(int)
 +
** function tabAt(int)
 +
** function setTabText(int,QString)
 +
** function tabText(int)
 +
** function setTabIcon(int,QIcon)
 +
** function tabIcon(int)
  
The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap contrustor:
+
TextEdit
 +
 
 +
** string text
 +
** boolean readOnly
 +
** function textChanged()
 +
** function dataUpdated(QString,Plasma::DataEngine::Data)
 +
 
 +
ToolButton
 +
 
 +
** string text
 +
** boolean autoRaise
 +
** string image
 +
** undefined action
 +
** function clicked()
 +
** function pressed()
 +
** function released()
 +
 
 +
TreeView
 +
 
 +
** undefined model
 +
** string styleSheet
 +
 
 +
VideoWidget
 +
 
 +
** string url
 +
** number currentTime
 +
** number totalTime
 +
** number remainingTime
 +
** number usedControls
 +
** boolean controlsVisible
 +
** string styleSheet
 +
** function tick(qint64)
 +
** function aboutToFinish()
 +
** function nextRequested()
 +
** function previousRequested()
 +
** function play()
 +
** function pause()
 +
** function stop()
 +
** function seek(qint64)
 +
** function mediaObject()
 +
** function audioOutput()
 +
** number NoControls
 +
** number Play
 +
** number Pause
 +
** number Stop
 +
** number PlayPause
 +
** number Previous
 +
** number Next
 +
** number Progress
 +
** number Volume
 +
** number OpenFile
 +
** number DefaultControls
 +
 
 +
WebView
 +
 
 +
** object url
 +
** string html
 +
** boolean dragToScroll
 +
** object scrollPosition
 +
** object contentsSize
 +
** object viewportGeometry
 +
** function loadProgress(int)
 +
** function loadFinished(bool)
 +
 
 +
=== Layouts  ===
 +
 
 +
LinearLayout AnchorLayout
 +
 
 +
=== Creating Items From UI Files  ===
 +
 
 +
TODO
 +
 
 +
== Animations  ==
 +
 
 +
An animation object can be retrieved by calling the animation(string) method. The string corresponds to the Plasma::Animator::Animation enumeration, and currently the following are supported (case insensitive) along with a list of their properties:
 +
 
 +
*fade
 +
*grow
 +
*expand
 +
*pause
 +
*pulse
 +
*rotate
 +
*rotateStacked
 +
*slide
 +
 
 +
All animations support the following properties:
 +
 
 +
*duration (int): length of the animation in ms
 +
*widgetToAnimate: the QGraphicsWidget (e.g. a Plasma::Widget) to operate on
 +
*forwards (bool): true if the animation should play forwards or false if backwards (rewind)
 +
*visible (bool): whether or not the animation is currently visible (??!?!)
 +
 
 +
By default the animation object is associated with the plasmoid itself. By setting the widgetToAnimate property, however, it can be re-assigned to any QGraphicsWidget (e.g. Plasma widgets such as push buttons, sliders, etc) one wants.
 +
 
 +
Animations may also be put into groups for convenient sequential or parallel running by creating an AnimationGroup object and then calling add(widget) on it. The parallel (bool) property holds whether or not the animations should be run in parallel or sequentially. The default is sequential.
 +
 
 +
== Painting  ==
 +
 
 +
See the "Painting and Layout" section, part of the Global Plasmoid chapter, for information on using these classes within a widget.
 +
 
 +
=== Pixmaps  ===
 +
 
 +
The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap contrustor:  
  
 
     var pixmap = new QPixmap("myimage.png")
 
     var pixmap = new QPixmap("myimage.png")
  
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.
+
In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.  
 +
 
 +
Properties
  
Properties
+
** bool isNull: returns true if the pixmap is empty or not
  * bool isNull: returns true if the pixmap is empty or not
+
** QRectF rect: the rect of the pixmap
  * QRectF rect: the rect of the pixmap
+
** QPixmap scaled(width, height): returns a scaled version of the pixmap with width and height dimensions
  * QPixmap scaled(width, height): returns a scaled version of the pixmap with width and height dimensions
 
  
 +
<br>
  
=== SVG Images ===
+
=== SVG Images ===
  
Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:
+
Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:  
  
 
     http://www.w3.org/Graphics/SVG/
 
     http://www.w3.org/Graphics/SVG/
  
Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directdory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:
+
Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directdory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:  
  
 
     http://techbase.kde.org/Projects/Plasma/Theme
 
     http://techbase.kde.org/Projects/Plasma/Theme
  
Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).
+
Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).  
 +
 
 +
Svg
 +
 
 +
** Constructors
 +
**** Svg(fileName): fileName can be a file in the desktop theme or the plasmoid package
 +
** object size
 +
** boolean multipleImages
 +
** string imagePath
 +
** boolean usingRenderingCache
 +
** function repaintNeeded()
 +
** function pixmap(QString)
 +
** function pixmap()
 +
** function paint(QPainter*,QPointF,QString)
 +
** function paint(QPainter*,QPointF)
 +
** function paint(QPainter*,int,int,QString)
 +
** function paint(QPainter*,int,int)
 +
** function paint(QPainter*,QRectF,QString)
 +
** function paint(QPainter*,QRectF)
 +
** function paint(QPainter*,int,int,int,int,QString)
 +
** function paint(QPainter*,int,int,int,int)
 +
** function resize(qreal,qreal)
 +
** function resize(QSizeF)
 +
** function resize()
 +
** function elementSize(QString)
 +
** function elementRect(QString)
 +
** function hasElement(QString)
 +
** function elementAtPoint(QPoint)
 +
** function isValid()
 +
 
 +
FrameSvg
 +
 
 +
** Constructors
 +
**** FrameSvg(fileName): fileName can be a file in the desktop theme or the plasmoid package
 +
** boolean multipleImages
 +
** function setEnabledBorders(EnabledBorders)
 +
** function enabledBorders()
 +
** function resizeFrame(QSizeF)
 +
** function frameSize()
 +
** function marginSize(Plasma::MarginEdge)
 +
** function getMargins(qreal&amp;,qreal&amp;,qreal&amp;,qreal&amp;)
 +
** function contentsRect()
 +
** function setElementPrefix(Plasma::Location)
 +
** function setElementPrefix(QString)
 +
** function hasElementPrefix(QString)
 +
** function hasElementPrefix(Plasma::Location)
 +
** function prefix()
 +
** function mask()
 +
** function setCacheAllRenderedFrames(bool)
 +
** function cacheAllRenderedFrames()
 +
** function framePixmap()
 +
** function paintFrame(QPainter*,QRectF,QRectF)
 +
** function paintFrame(QPainter*,QRectF)
 +
** function paintFrame(QPainter*,QPointF)
 +
** function paintFrame(QPainter*)
 +
 
 +
=== Painting on the Canvas  ===
 +
 
 +
QPainter
 +
 
 +
** function background
 +
** function backgroundMode
 +
** function begin
 +
** function boundingRect
 +
** function brush
 +
** function brushOrigin
 +
** function clipPath
 +
** function clipRegion
 +
** function combinedMatrix
 +
** function combinedTransform
 +
** function compositionMode
 +
** function device
 +
** function deviceMatrix
 +
** function deviceTransform
 +
** function drawChord
 +
** function drawConvexPolygon
 +
** function drawArc
 +
** function drawEllipse
 +
** function drawImage
 +
** function drawLine
 +
** function drawLines
 +
** function drawPath
 +
** function drawPicture
 +
** function drawPie
 +
** function drawPixmap
 +
** function drawPoint
 +
** function drawPoints
 +
** function drawPolygon
 +
** function drawPolyline
 +
** function drawRect
 +
** function drawRects
 +
** function drawRoundRect
 +
** function drawText
 +
** function drawTiledPixmap
 +
** function end
 +
** function eraseRect
 +
** function fillPath
 +
** function fillRect
 +
** function font
 +
** function fontInfo
 +
** function fontMetrics
 +
** function hasClipping
 +
** function initFrom
 +
** function isActive
 +
** function layoutDirection
 +
** function opacity
 +
** function paintEngine
 +
** function pen
 +
** function renderHints
 +
** function resetMatrix
 +
** function resetTransform
 +
** function restore
 +
** function rotate
 +
** function save
 +
** function scale
 +
** function setBackground
 +
** function setBackgroundMode
 +
** function setBrush
 +
** function setBrushOrigin
 +
** function setClipPath
 +
** function setClipRect
 +
** function setClipRegion
 +
** function setClipping
 +
** function setCompositionMode
 +
** function setFont
 +
** function setLayoutDirection
 +
** function setOpacity
 +
** function setPen
 +
** function setRenderHint
 +
** function setRenderHints
 +
** function setTransform
 +
** function setViewTransformEnabled
 +
** function setViewport
 +
** function setWindow
 +
** function setWorldMatrix
 +
** function setWorldMatrixEnabled
 +
** function setWorldTransform
 +
** function shear
 +
** function strokePath
 +
** function testRenderHint
 +
** function toString
 +
** function transform
 +
** function translate
 +
** function viewTransformEnabled
 +
** function viewport
 +
** function window
 +
** function worldMatrix
 +
** function worldMatrixEnabled
 +
** function worldTransform
 +
 
 +
QColor
 +
 
 +
** Constructors:
 +
**** QColor
 +
**** QColor(string colorName)
 +
**** QColor(number red, number green, number blue, number alpha)
 +
** number red
 +
** number green
 +
** number blue
 +
** number alpha
 +
** boolean isValid
 +
 
 +
QFont
  
Svg
+
** Constructors:
  * Constructors
+
**** QFont
    * Svg(fileName): fileName can be a file in the desktop theme or the plasmoid package
+
**** QFont(string fontName)
  * object size
+
**** QFont(string fontName, number pointSize)
  * boolean multipleImages
+
**** QFont(string fontName, number pointSize, number weight)
  * string imagePath
+
**** QFont(string fontName, number pointSize, number weight, boolean italic)
  * boolean usingRenderingCache
+
** boolean bold
  * function repaintNeeded()
+
** function defaultFamily
  * function pixmap(QString)
+
** function exactMatch
  * function pixmap()
+
** string family
  * function paint(QPainter*,QPointF,QString)
+
** boolean fixedPitch
  * function paint(QPainter*,QPointF)
+
** function fromString
  * function paint(QPainter*,int,int,QString)
+
** function handle
  * function paint(QPainter*,int,int)
+
** function isCopyOf
  * function paint(QPainter*,QRectF,QString)
+
** boolean italic
  * function paint(QPainter*,QRectF)
+
** boolean kerning
  * function paint(QPainter*,int,int,int,int,QString)
+
** string key
  * function paint(QPainter*,int,int,int,int)
+
** function lastResortFamily
  * function resize(qreal,qreal)
+
** function lastResortFont
  * function resize(QSizeF)
+
** boolean overline
  * function resize()
+
** number pixelSize
  * function elementSize(QString)
+
** number pointSize
  * function elementRect(QString)
+
** number pointSizeF
  * function hasElement(QString)
+
** boolean rawMode
  * function elementAtPoint(QPoint)
+
** string rawName
  * function isValid()
+
** function resolve
 +
** undefined bamily
 +
** number stretch
 +
** boolean strikeOut
 +
** function setStyle
 +
** function setStyleHint
 +
** function setStyleStrategy
 +
** boolean underline
 +
** number weight
 +
** function style
 +
** function styleHint
 +
** function styleStrategy
 +
** function toString
  
FrameSvg
+
QRectF  
  * Constructors
 
    * FrameSvg(fileName): fileName can be a file in the desktop theme or the plasmoid package
 
  * boolean multipleImages
 
  * function setEnabledBorders(EnabledBorders)
 
  * function enabledBorders()
 
  * function resizeFrame(QSizeF)
 
  * function frameSize()
 
  * function marginSize(Plasma::MarginEdge)
 
  * function getMargins(qreal&,qreal&,qreal&,qreal&)
 
  * function contentsRect()
 
  * function setElementPrefix(Plasma::Location)
 
  * function setElementPrefix(QString)
 
  * function hasElementPrefix(QString)
 
  * function hasElementPrefix(Plasma::Location)
 
  * function prefix()
 
  * function mask()
 
  * function setCacheAllRenderedFrames(bool)
 
  * function cacheAllRenderedFrames()
 
  * function framePixmap()
 
  * function paintFrame(QPainter*,QRectF,QRectF)
 
  * function paintFrame(QPainter*,QRectF)
 
  * function paintFrame(QPainter*,QPointF)
 
  * function paintFrame(QPainter*)
 
  
=== Painting on the Canvas ===
+
** Constructors:
 +
**** QRectF
 +
**** QRectF(number x, number y, number width, number height)
 +
** function adjust
 +
** object adjusted
 +
** function translate
 +
** function setCoords
 +
** function setRect
 +
** function contains
 +
** function moveBottom
 +
** function moveLeft
 +
** function moveRight
 +
** function moveTo
 +
** function moveTop
 +
** boolean isEmpty
 +
** boolean isNull
 +
** boolean isValid
 +
** number left
 +
** number top
 +
** number bottom
 +
** number right
 +
** number height
 +
** number width
 +
** number x
 +
** number y
  
QPainter
+
QSizeF
  * function background
 
  * function backgroundMode
 
  * function begin
 
  * function boundingRect
 
  * function brush
 
  * function brushOrigin
 
  * function clipPath
 
  * function clipRegion
 
  * function combinedMatrix
 
  * function combinedTransform
 
  * function compositionMode
 
  * function device
 
  * function deviceMatrix
 
  * function deviceTransform
 
  * function drawChord
 
  * function drawConvexPolygon
 
  * function drawArc
 
  * function drawEllipse
 
  * function drawImage
 
  * function drawLine
 
  * function drawLines
 
  * function drawPath
 
  * function drawPicture
 
  * function drawPie
 
  * function drawPixmap
 
  * function drawPoint
 
  * function drawPoints
 
  * function drawPolygon
 
  * function drawPolyline
 
  * function drawRect
 
  * function drawRects
 
  * function drawRoundRect
 
  * function drawText
 
  * function drawTiledPixmap
 
  * function end
 
  * function eraseRect
 
  * function fillPath
 
  * function fillRect
 
  * function font
 
  * function fontInfo
 
  * function fontMetrics
 
  * function hasClipping
 
  * function initFrom
 
  * function isActive
 
  * function layoutDirection
 
  * function opacity
 
  * function paintEngine
 
  * function pen
 
  * function renderHints
 
  * function resetMatrix
 
  * function resetTransform
 
  * function restore
 
  * function rotate
 
  * function save
 
  * function scale
 
  * function setBackground
 
  * function setBackgroundMode
 
  * function setBrush
 
  * function setBrushOrigin
 
  * function setClipPath
 
  * function setClipRect
 
  * function setClipRegion
 
  * function setClipping
 
  * function setCompositionMode
 
  * function setFont
 
  * function setLayoutDirection
 
  * function setOpacity
 
  * function setPen
 
  * function setRenderHint
 
  * function setRenderHints
 
  * function setTransform
 
  * function setViewTransformEnabled
 
  * function setViewport
 
  * function setWindow
 
  * function setWorldMatrix
 
  * function setWorldMatrixEnabled
 
  * function setWorldTransform
 
  * function shear
 
  * function strokePath
 
  * function testRenderHint
 
  * function toString
 
  * function transform
 
  * function translate
 
  * function viewTransformEnabled
 
  * function viewport
 
  * function window
 
  * function worldMatrix
 
  * function worldMatrixEnabled
 
  * function worldTransform
 
  
QColor
+
** Constructors:
  * Constructors:
+
**** QSizeF
    * QColor
+
**** QSizeF(number width, number height)
    * QColor(string colorName)
+
** number height
    * QColor(number red, number green, number blue, number alpha)
+
** number width
  * number red
 
  * number green
 
  * number blue
 
  * number alpha
 
  * boolean isValid
 
  
QFont
+
QPoint
  * Constructors:
 
    * QFont
 
    * QFont(string fontName)
 
    * QFont(string fontName, number pointSize)
 
    * QFont(string fontName, number pointSize, number weight)
 
    * QFont(string fontName, number pointSize, number weight, boolean italic)
 
  * boolean bold
 
  * function defaultFamily
 
  * function exactMatch
 
  * string family
 
  * boolean fixedPitch
 
  * function fromString
 
  * function handle
 
  * function isCopyOf
 
  * boolean italic
 
  * boolean kerning
 
  * string key
 
  * function lastResortFamily
 
  * function lastResortFont
 
  * boolean overline
 
  * number pixelSize
 
  * number pointSize
 
  * number pointSizeF
 
  * boolean rawMode
 
  * string rawName
 
  * function resolve
 
  * undefined bamily
 
  * number stretch
 
  * boolean strikeOut
 
  * function setStyle
 
  * function setStyleHint
 
  * function setStyleStrategy
 
  * boolean underline
 
  * number weight
 
  * function style
 
  * function styleHint
 
  * function styleStrategy
 
  * function toString
 
  
QRectF
+
** Constructors:
  * Constructors:
+
**** QPoint
    * QRectF
+
**** QPoint(number x, number y)
    * QRectF(number x, number y, number width, number height)
+
** bool isNull
  * function adjust
+
** number manhattanLength
  * object adjusted
+
** number x
  * function translate
+
** number y
  * function setCoords
 
  * function setRect
 
  * function contains
 
  * function moveBottom
 
  * function moveLeft
 
  * function moveRight
 
  * function moveTo
 
  * function moveTop
 
  * boolean isEmpty
 
  * boolean isNull
 
  * boolean isValid
 
  * number left
 
  * number top
 
  * number bottom
 
  * number right
 
  * number height
 
  * number width
 
  * number x
 
  * number y
 
  
QSizeF
+
<br>
  * Constructors:
 
    * QSizeF
 
    * QSizeF(number width, number height)
 
  * number height
 
  * number width
 
  
QPoint
+
== Accessing Sources of Data  ==
  * Constructors:
 
    * QPoint
 
    * QPoint(number x, number y)
 
  * bool isNull
 
  * number manhattanLength
 
  * number x
 
  * number y
 
  
 +
dataEngine(string name) dataUpdate
  
== Accessing Sources of Data ==
+
== Configuration  ==
  
dataEngine(string name)
+
=== Declaring Config Values  ===
dataUpdate
 
  
== Configuration ==
+
KConfigXt XML -&gt; main.xml
  
=== Declaring Config Values ===
+
=== Accessing Configuration Data  ===
  
KConfigXt XML -> main.xml
+
activeConfig plasmoid.readConfig(string) WriteConfig(string, var)
  
=== Accessing Configuration Data ===
+
=== User Customization  ===
  
activeConfig
+
Qt UI file configChanged()  
plasmoid.readConfig(string)
 
WriteConfig(string, var)
 
  
=== User Customization ===
+
== Other Functions and Classes  ==
  
Qt UI file
+
print(string) debug(string) GraphicsItem Timer Url
configChanged()
 
  
== Other Functions and Classes ==
+
== Extensions  ==
print(string)
 
debug(string)
 
GraphicsItem
 
Timer
 
Url
 
  
== Extensions ==
+
Extensions to the standard API plasmoid.hasExtension
Extensions to the standard API
 
plasmoid.hasExtension
 

Revision as of 18:00, 27 November 2009

Introduction to Plasmoids JavaScript API

If you have not done so already, please read the "plasmoid" design document first.

What Is A Simplified JavaScript Plasmoid?

This document describes the native Plasma API available to Simplified JavaScript Plasmoids. What makes them "Simplified" is that they do not have access to the entire C++ API in the Plasma, KDE and Qt libraries (let alone things lower in the API stack). This helps ensure that these Plasmoids are more likely to work properly between releases as changes in underlying API don't affect them as well as allowing Plasma to offer stronger security guarantees around them.

To denote that this Plasmoid is a Simplified JavaScript widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=javascript

What follows is a description of the runtime environment available to a Simplified JavaScript Plasmoid.

QtScript

The Simplified JavaScript API is powered by Qt's QtScript system which provides access to a full featured ECMA Script interpreter. If it works in ECMA Script, it will work in a Simplified JavaScript Plasmoid. As an interesting implementation note, QtScript uses the high performance ECMA Script interpreter from WebKit and shares this code with QtWebKit.

On top of the ECMA Script language, QtScript provides Qt integration features. Probably the most useful one in this context is the use of signals and slots which is Qt's callback mechanism. Signals may be emitted in QtScript by calling the signal method in question, a signal can be connected to a slot by using the connect() method (and disconnected with diconnnect()) and any function defined in the Plasmoid may be used as a slot. For example:

   function onClick()
   {
       print("We got clicked!")
   }
   function onFirstClick()
   {
       print("First click!")
       button.clicked.disconnect(onFirstClick)
   }
   button = new PushButton
   button.clicked.connect(onClick)
   button.clicked.connect(onFirstClick)
   button.clicked()

This will print out:

We got clicked! First click!

on the console when the Plasmoid starts, and the "We got clicked!" again whenever the button is clicked by the user.

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.

Callbacks

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())

}

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 Simlified 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.
  • 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.locatationChanged 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: defines how to treat the aspect ratio of a Plasmoid when resizing it, one of:
        • IgnoreAspectRatio: The Plasmoid can be freely resized
        • KeepAspectRatio: The Plasmoid keeps a fixed aspect ratio
        • Square: The Plasmoid is always a square
        • ConstrainedSquare: The Plasmoid is no wider (in horizontal formfactors) or no higher (in vertical ones) than a square
        • FixedSize: The Plasmoid cannot be resized
  • 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

Functions:

  • resize(width, height)
  • setMinimumSize(width, height)
  • setPreferredSize(width, height)

Properties:

  • rect: the current rect of the Plasmoid; note that the top left may be not be the origin point (0,0); this property is read only

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.

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

Properties:

  • 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


Access To Packaged Files

Functions:

  • string file(string type, string fileName): returns the path to a file named fileName in the Plasmoid package of the given type; e.g. file("images", "mypixmap.png")
  • string file(string type): returns the path to a file named as part of the package, e.g.: file("mainscript")
  • bool include(string filename): attempts to include the script defined from the package's scripts directory

User Interface Elements

Plasma Widgets

The Plasma framework provides a set of standard user interface elmenets such as pushbuttons and checkboxes for use in Plasmoids, and these are available from the Simplified Javascript API as well. These elements follow the Plasma style and other conventions so that widgets blend well both visually and functionally with other Plasma elements.

Properties

By default, all of the Plasma user interface elements have the following properties:

  • objectName
  • opacity
  • enabled
  • visible
  • pos
  • x
  • y
  • z
  • rotation
  • scale
  • transformOriginPoint
  • palette
  • font
  • size
  • focusPolicy
  • geometry

Signals

opacityChanged() visibleChanged() enabledChanged() xChanged() yChanged() zChanged() rotationChanged() scaleChanged()

Undocumented Properties and Functions

There are a handful of other undocument properties and functions available to UI elements. These are not supported or guaranteed to exist in future versions however, and as such should be used or relied upon.

UI Element Gallery

BusyWidget

    • boolean running
    • string label
    • function clicked()

CheckBox

    • string text
    • string image
    • string styleSheet
    • boolean isChecked
    • function toggled(bool)

ComboBox

    • string text
    • string styleSheet
    • function activated(QString)
    • function textChanged(QString)
    • function clear()

FlashingLabel

    • boolean autohide
    • object color
    • number duration
    • function kill()
    • function fadeIn()
    • function fadeOut()
    • function flash(QString,int,QTextOption)
    • function flash(QString,int)
    • function flash(QString)
    • function flash(QPixmap,int,Qt::Alignment)
    • function flash(QPixmap,int)
    • function flash(QPixmap)

Frame

    • number frameShadow
    • string text
    • string image
    • string styleSheet
    • number Plain
    • number Raised
    • number Sunken

GroupBox

    • string text
    • string styleSheet

IconWidget

    • string text
    • string infoText
    • object icon
    • object textBackgroundColor
    • object iconSize
    • string svg
    • undefined action
    • number orientation
    • number numDisplayLines
    • function pressed(bool)
    • function clicked()
    • function doubleClicked()
    • function activated()
    • function changed()
    • function setPressed(bool)
    • function setPressed()
    • function setUnpressed()
    • function setIcon(QString)

ItemBackground

    • object target
    • object targetItem
    • function appearanceChanged()
    • function animationStep(qreal)
    • function targetReached(QRectF)
    • function targetItemReached(QGraphicsItem*)

Label

    • string text
    • string image
    • number alignment
    • boolean hasScaledContents
    • string styleSheet
    • function linkActivated(QString)
    • function linkHovered(QString)
    • function dataUpdated(QString,Plasma::DataEngine::Data)

LineEdit

    • string text
    • boolean isClearButtonShown
    • string styleSheet
    • function editingFinished()
    • function returnPressed()
    • function textEdited(QString)
    • function textChanged(QString)

Meter

    • number minimum
    • number maximum
    • number value
    • string svg
    • number meterType
    • function dataUpdated(QString,Plasma::DataEngine::Data)
    • number BarMeterHorizontal
    • number BarMeterVertical
    • number AnalogMeter

PushButton

    • string text
    • string image
    • undefined action
    • object icon
    • boolean checkable
    • boolean checked
    • boolean down
    • function pressed()
    • function released()
    • function clicked()
    • function toggled(bool)

RadioButton

    • string text
    • string image
    • string styleSheet
    • boolean isChecked
    • function toggled(bool)

ScrollWidget

    • object widget
    • number horizontalScrollBarPolicy
    • number verticalScrollBarPolicy
    • object scrollPosition
    • object contentsSize
    • object viewportGeometry
    • string styleSheet
    • function ensureRectVisible(QRectF)
    • function ensureItemVisible(QGraphicsItem*)
    • function registerAsDragHandle(QGraphicsWidget*)
    • function unregisterAsDragHandle(QGraphicsWidget*)

ScrollBar

    • number singleStep
    • number pageStep
    • number value
    • number minimum
    • number maximum
    • function valueChanged(int)
    • function setValue(int)
    • function setOrientation(Qt::Orientation)

Separator

    • number orientation

SignalPlotter

    • string title
    • string unit
    • boolean useAutoRange
    • number horizontalScale
    • boolean showVerticalLines
    • object verticalLinesColor
    • number verticalLinesDistance
    • boolean verticalLinesScroll
    • boolean showHorizontalLines
    • object horizontalLinesColor
    • object fontColor
    • number horizontalLinesCount
    • boolean showLabels
    • boolean showTopBar
    • object backgroundColor
    • string svgBackground
    • boolean thinFrame
    • boolean stackPlots

Slider

    • number maximum
    • number minimum
    • number value
    • number orientation
    • string styleSheet
    • function sliderMoved(int)
    • function valueChanged(int)
    • function setMaximum(int)
    • function setMinimum(int)
    • function setRange(int,int)
    • function setValue(int)
    • function setOrientation(Qt::Orientation)

SpinBox

    • number maximum
    • number minimum
    • number value
    • string styleSheet
    • function sliderMoved(int)
    • function valueChanged(int)
    • function editingFinished()
    • function setMaximum(int)
    • function setMinimum(int)
    • function setRange(int,int)
    • function setValue(int)

SvgWidget

    • undefined svg
    • string elementID
    • function clicked(Qt::MouseButton)

TabBar

    • number currentIndex
    • number count
    • string styleSheet
    • boolean tabBarShown
    • function currentChanged(int)
    • function setCurrentIndex(int)
    • function insertTab(int,QIcon,QString,QGraphicsLayoutItem*)
    • function insertTab(int,QIcon,QString)
    • function insertTab(int,QString,QGraphicsLayoutItem*)
    • function insertTab(int,QString)
    • function addTab(QIcon,QString,QGraphicsLayoutItem*)
    • function addTab(QIcon,QString)
    • function addTab(QString,QGraphicsLayoutItem*)
    • function addTab(QString)
    • function removeTab(int)
    • function takeTab(int)
    • function tabAt(int)
    • function setTabText(int,QString)
    • function tabText(int)
    • function setTabIcon(int,QIcon)
    • function tabIcon(int)

TextEdit

    • string text
    • boolean readOnly
    • function textChanged()
    • function dataUpdated(QString,Plasma::DataEngine::Data)

ToolButton

    • string text
    • boolean autoRaise
    • string image
    • undefined action
    • function clicked()
    • function pressed()
    • function released()

TreeView

    • undefined model
    • string styleSheet

VideoWidget

    • string url
    • number currentTime
    • number totalTime
    • number remainingTime
    • number usedControls
    • boolean controlsVisible
    • string styleSheet
    • function tick(qint64)
    • function aboutToFinish()
    • function nextRequested()
    • function previousRequested()
    • function play()
    • function pause()
    • function stop()
    • function seek(qint64)
    • function mediaObject()
    • function audioOutput()
    • number NoControls
    • number Play
    • number Pause
    • number Stop
    • number PlayPause
    • number Previous
    • number Next
    • number Progress
    • number Volume
    • number OpenFile
    • number DefaultControls

WebView

    • object url
    • string html
    • boolean dragToScroll
    • object scrollPosition
    • object contentsSize
    • object viewportGeometry
    • function loadProgress(int)
    • function loadFinished(bool)

Layouts

LinearLayout AnchorLayout

Creating Items From UI Files

TODO

Animations

An animation object can be retrieved by calling the animation(string) method. The string corresponds to the Plasma::Animator::Animation enumeration, and currently the following are supported (case insensitive) along with a list of their properties:

  • fade
  • grow
  • expand
  • pause
  • pulse
  • rotate
  • rotateStacked
  • slide

All animations support the following properties:

  • duration (int): length of the animation in ms
  • widgetToAnimate: the QGraphicsWidget (e.g. a Plasma::Widget) to operate on
  • forwards (bool): true if the animation should play forwards or false if backwards (rewind)
  • visible (bool): whether or not the animation is currently visible (??!?!)

By default the animation object is associated with the plasmoid itself. By setting the widgetToAnimate property, however, it can be re-assigned to any QGraphicsWidget (e.g. Plasma widgets such as push buttons, sliders, etc) one wants.

Animations may also be put into groups for convenient sequential or parallel running by creating an AnimationGroup object and then calling add(widget) on it. The parallel (bool) property holds whether or not the animations should be run in parallel or sequentially. The default is sequential.

Painting

See the "Painting and Layout" section, part of the Global Plasmoid chapter, for information on using these classes within a widget.

Pixmaps

The QPixmap object allows widgets to use pixmaps for painting. Widgets may include pixmaps in various common formats (PNG, JPEG, GIF, etc.) in the contents/images/ directory of the Plasmoid package and load them by passing the name of the file into the pixmap contrustor:

   var pixmap = new QPixmap("myimage.png")

In addition to being used as a file load, some objects return or take pixmaps and the QPixmap object facilitates that as well.

Properties

    • bool isNull: returns true if the pixmap is empty or not
    • QRectF rect: the rect of the pixmap
    • QPixmap scaled(width, height): returns a scaled version of the pixmap with width and height dimensions


SVG Images

Plasma makes heavy usage of SVG images. More information on this industry standard scalable vector format can be found here:

   http://www.w3.org/Graphics/SVG/

Free and Open Source Software tools for creating SVGs include Inkscape and Karbon13. Widgets may include their own SVG files in the contents/images/ directdory or may use SVG images that are part of the standard Plasma Desktop Theme as documented here:

   http://techbase.kde.org/Projects/Plasma/Theme

Two classes are provide: Svg and FrameSvg. Svg allows loading and painting entire SVG documents or individual elements in an SVG document. FrameSvg extends Svg with methods to paint bordered frames from specially crafted SVG documents (see the Plasma Desktop Theme documentation for more information on this).

Svg

    • Constructors
        • Svg(fileName): fileName can be a file in the desktop theme or the plasmoid package
    • object size
    • boolean multipleImages
    • string imagePath
    • boolean usingRenderingCache
    • function repaintNeeded()
    • function pixmap(QString)
    • function pixmap()
    • function paint(QPainter*,QPointF,QString)
    • function paint(QPainter*,QPointF)
    • function paint(QPainter*,int,int,QString)
    • function paint(QPainter*,int,int)
    • function paint(QPainter*,QRectF,QString)
    • function paint(QPainter*,QRectF)
    • function paint(QPainter*,int,int,int,int,QString)
    • function paint(QPainter*,int,int,int,int)
    • function resize(qreal,qreal)
    • function resize(QSizeF)
    • function resize()
    • function elementSize(QString)
    • function elementRect(QString)
    • function hasElement(QString)
    • function elementAtPoint(QPoint)
    • function isValid()

FrameSvg

    • Constructors
        • FrameSvg(fileName): fileName can be a file in the desktop theme or the plasmoid package
    • boolean multipleImages
    • function setEnabledBorders(EnabledBorders)
    • function enabledBorders()
    • function resizeFrame(QSizeF)
    • function frameSize()
    • function marginSize(Plasma::MarginEdge)
    • function getMargins(qreal&,qreal&,qreal&,qreal&)
    • function contentsRect()
    • function setElementPrefix(Plasma::Location)
    • function setElementPrefix(QString)
    • function hasElementPrefix(QString)
    • function hasElementPrefix(Plasma::Location)
    • function prefix()
    • function mask()
    • function setCacheAllRenderedFrames(bool)
    • function cacheAllRenderedFrames()
    • function framePixmap()
    • function paintFrame(QPainter*,QRectF,QRectF)
    • function paintFrame(QPainter*,QRectF)
    • function paintFrame(QPainter*,QPointF)
    • function paintFrame(QPainter*)

Painting on the Canvas

QPainter

    • function background
    • function backgroundMode
    • function begin
    • function boundingRect
    • function brush
    • function brushOrigin
    • function clipPath
    • function clipRegion
    • function combinedMatrix
    • function combinedTransform
    • function compositionMode
    • function device
    • function deviceMatrix
    • function deviceTransform
    • function drawChord
    • function drawConvexPolygon
    • function drawArc
    • function drawEllipse
    • function drawImage
    • function drawLine
    • function drawLines
    • function drawPath
    • function drawPicture
    • function drawPie
    • function drawPixmap
    • function drawPoint
    • function drawPoints
    • function drawPolygon
    • function drawPolyline
    • function drawRect
    • function drawRects
    • function drawRoundRect
    • function drawText
    • function drawTiledPixmap
    • function end
    • function eraseRect
    • function fillPath
    • function fillRect
    • function font
    • function fontInfo
    • function fontMetrics
    • function hasClipping
    • function initFrom
    • function isActive
    • function layoutDirection
    • function opacity
    • function paintEngine
    • function pen
    • function renderHints
    • function resetMatrix
    • function resetTransform
    • function restore
    • function rotate
    • function save
    • function scale
    • function setBackground
    • function setBackgroundMode
    • function setBrush
    • function setBrushOrigin
    • function setClipPath
    • function setClipRect
    • function setClipRegion
    • function setClipping
    • function setCompositionMode
    • function setFont
    • function setLayoutDirection
    • function setOpacity
    • function setPen
    • function setRenderHint
    • function setRenderHints
    • function setTransform
    • function setViewTransformEnabled
    • function setViewport
    • function setWindow
    • function setWorldMatrix
    • function setWorldMatrixEnabled
    • function setWorldTransform
    • function shear
    • function strokePath
    • function testRenderHint
    • function toString
    • function transform
    • function translate
    • function viewTransformEnabled
    • function viewport
    • function window
    • function worldMatrix
    • function worldMatrixEnabled
    • function worldTransform

QColor

    • Constructors:
        • QColor
        • QColor(string colorName)
        • QColor(number red, number green, number blue, number alpha)
    • number red
    • number green
    • number blue
    • number alpha
    • boolean isValid

QFont

    • Constructors:
        • QFont
        • QFont(string fontName)
        • QFont(string fontName, number pointSize)
        • QFont(string fontName, number pointSize, number weight)
        • QFont(string fontName, number pointSize, number weight, boolean italic)
    • boolean bold
    • function defaultFamily
    • function exactMatch
    • string family
    • boolean fixedPitch
    • function fromString
    • function handle
    • function isCopyOf
    • boolean italic
    • boolean kerning
    • string key
    • function lastResortFamily
    • function lastResortFont
    • boolean overline
    • number pixelSize
    • number pointSize
    • number pointSizeF
    • boolean rawMode
    • string rawName
    • function resolve
    • undefined bamily
    • number stretch
    • boolean strikeOut
    • function setStyle
    • function setStyleHint
    • function setStyleStrategy
    • boolean underline
    • number weight
    • function style
    • function styleHint
    • function styleStrategy
    • function toString

QRectF

    • Constructors:
        • QRectF
        • QRectF(number x, number y, number width, number height)
    • function adjust
    • object adjusted
    • function translate
    • function setCoords
    • function setRect
    • function contains
    • function moveBottom
    • function moveLeft
    • function moveRight
    • function moveTo
    • function moveTop
    • boolean isEmpty
    • boolean isNull
    • boolean isValid
    • number left
    • number top
    • number bottom
    • number right
    • number height
    • number width
    • number x
    • number y

QSizeF

    • Constructors:
        • QSizeF
        • QSizeF(number width, number height)
    • number height
    • number width

QPoint

    • Constructors:
        • QPoint
        • QPoint(number x, number y)
    • bool isNull
    • number manhattanLength
    • number x
    • number y


Accessing Sources of Data

dataEngine(string name) dataUpdate

Configuration

Declaring Config Values

KConfigXt XML -> main.xml

Accessing Configuration Data

activeConfig plasmoid.readConfig(string) WriteConfig(string, var)

User Customization

Qt UI file configChanged()

Other Functions and Classes

print(string) debug(string) GraphicsItem Timer Url

Extensions

Extensions to the standard API plasmoid.hasExtension


Content is available under Creative Commons License SA 4.0 unless otherwise noted.