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

    From KDE TechBase
    Line 58: Line 58:


    }  
    }  
    </code>  
    </code>
     
    The following callbacks are used (with further documentation on each in the relevant sections below):
     
    * configChanged()
    * formFactorChanged()
    * locatationChanged()
    * immutabilityChanged()
    * currentActivityChanged()
    * dataUpdated(String source, Map[String, Any] data)


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

    Revision as of 21:16, 20 January 2010

    Introduction to Plasmoids JavaScript API

    This document provides an overview/reference of the Simplified JavaScript API for Plasmoids. The "Simplified" refers to the fact that it isn't a full binding to all of Qt or KDE's libraries, but a highly focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

    The API in this documentation covers the JavaScript API as it appears in the KDE Software Compilation as of version 4.4, unless otherwise noted. This API ships as part of the KDE Base Runtime package, so can be relied on being there by any application that is Powered By KDE.

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

    }

    The following callbacks are used (with further documentation on each in the relevant sections below):

    • configChanged()
    • formFactorChanged()
    • locatationChanged()
    • immutabilityChanged()
    • currentActivityChanged()
    • dataUpdated(String source, Map[String, Any] data)

    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 aspectRatioMode: defines how to treat the aspect ratio of a Plasmoid when resizing it. See the #BackgroundHints AspectRatioMode documentation for values and their meaning.
    • 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

    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)

    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 = file("mainscript") or var pm = new QPixmap(file("images", "mypixmap.png"))
    • bool include(string filename): attempts to include the script defined from the package's code directory

    Configuration Data

    Declaring Config Values

    KConfigXt XML -> main.xml

    Accessing Configuration Data

    • activeConfig
    • readConfig(string key)
    • writConfig(string key, var value)

    User Customization

    Qt UI file

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

    Global Enumerations

    In the global namespace are a set of useful enumerations that can be used with various classes in the Simplified Javascript Plasmoid API. These include:

    AspectRatioMode

    • 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


    FormFactor

    • Planar: The Plasmoid lives in a plane and has two degrees of freedom to grow. Optimize for desktop, laptop or tablet usage: a high resolution screen 1-3 feet distant from the viewer.
    • MediaCenter: As with Plasmoidthe applet lives in a but the interface should be optimized for medium-to-high resolution screens that 5-15 feet distant from the viewer. Sometimes referred to as a "ten foot interface".
    • Horizontal: The Plasmoid is constrained vertically, but can expand horizontally.
    • Vertical: The Plasmoid is constrained horizontally, but can expand vertically.

    Location

    • Floating: Free floating. Neither geometry or z-ordering is described precisely by this value.
    • Desktop: On the planar desktop layer, extending acrossthe full screen from edge to edge
    • FullScreen
    • TopEdge
    • BottomEdge
    • LeftEdge
    • RightEdge

    AnimationDirection

    • AnimationForward
    • AnimationBackward

    BackgroundHints

    • NoBackground
    • StandardBackground
    • TranslucentBackground
    • DefaultBackground

    QtAlignment

    • QtAlignLeft
    • QtAlignRight
    • QtAlignHCenter
    • QtAlignJustify
    • QtAlignTop
    • QtAlignBottom
    • QtAlignVCenter

    QtAnchorPoint

    • QtAnchorLeft
    • QtAnchorRight
    • QtAnchorBottom
    • QtAnchorTop
    • QtAnchorHorizontalCenter
    • QtAnchorVerticalCenter

    QtCorner

    • QtTopLeftCorner
    • QtTopRightCorner
    • QtBottomLeftCorner
    • QtBottomRightCorner

    QtOrientation

    • QtHorizontal
    • QtVertical

    QtScrollBarPolicy

    • QtScrollBarAsNeeded
    • QtScrollBarAlwaysOff
    • QtScrollBarAlwaysOn

    QtSizePolicy

    • QSizePolicyFixed
    • QSizePolicyMinimum
    • QSizePolicyMaximum
    • QSizePolicyPreferred
    • QSizePolicyExpanding
    • QSizePolicyMinimumExpanding
    • QSizePolicyIgnored

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

    UI Element Gallery

    CSS Styleable UI Elements

    Most UI Elements are able to have their appearance adjust using a CSS stylesheet. All of these elements have the following read/write property:

    CheckBox
    • string text
    • string image
    • boolean isChecked
    • toggled(bool)
    ComboBox
    • string text
    • activated(QString)
    • textChanged(QString)
    • clear()
    Frame
    • number frameShadow
    • string text
    • string image
    • number Plain
    • number Raised
    • number Sunken
    GroupBox
    • string text
    • string styleSheet
    Label
    • string text
    • string image
    • number alignment
    • boolean hasScaledContents
    • linkActivated(QString)
    • linkHovered(QString)
    • dataUpdated(QString,Plasma::DataEngine::Data)
    LineEdit
    • string text
    • boolean isClearButtonShown
    • editingFinished()
    • returnPressed()
    • textEdited(QString)
    • textChanged(QString)
    PushButton
    • string text
    • string image
    • QAction action
    • QIcon icon
    • boolean checkable
    • boolean checked
    • boolean down
    • pressed()
    • released()
    • clicked()
    • toggled(bool)
    RadioButton
    • string text
    • string image
    • boolean isChecked
    • toggled(bool)
    ScrollWidget
    • QGraphicsWidget widget
    • number horizontalScrollBarPolicy
    • number verticalScrollBarPolicy
    • QPointF scrollPosition
    • QSizeF contentsSize
    • QRectF viewportGeometry
    • ensureRectVisible(QRectF)
    • ensureItemVisible(QGraphicsItem*)
    • registerAsDragHandle(QGraphicsWidget*)
    • unregisterAsDragHandle(QGraphicsWidget*)
    ScrollBar
    • number singleStep
    • number pageStep
    • number value
    • number minimum
    • number maximum
    • valueChanged(int)
    • setValue(int)
    • setOrientation(Qt::Orientation)
    Slider
    • number maximum
    • number minimum
    • number value
    • number orientation
    • sliderMoved(int)
    • valueChanged(int)
    • setMaximum(int)
    • setMinimum(int)
    • setRange(int,int)
    • setValue(int)
    • setOrientation(Qt::Orientation)
    SpinBox
    • number maximum
    • number minimum
    • number value
    • sliderMoved(int)
    • valueChanged(int)
    • editingFinished()
    • setMaximum(int)
    • setMinimum(int)
    • setRange(int,int)
    • setValue(int)
    TabBar
    • number currentIndex
    • number count
    • boolean tabBarShown
    • currentChanged(int)
    • setCurrentIndex(int)
    • insertTab(int,QIcon,QString,QGraphicsLayoutItem*)
    • insertTab(int,QIcon,QString)
    • insertTab(int,QString,QGraphicsLayoutItem*)
    • insertTab(int,QString)
    • addTab(QIcon,QString,QGraphicsLayoutItem*)
    • addTab(QIcon,QString)
    • addTab(QString,QGraphicsLayoutItem*)
    • addTab(QString)
    • removeTab(int)
    • takeTab(int)
    • tabAt(int)
    • setTabText(int,QString)
    • tabText(int)
    • setTabIcon(int,QIcon)
    • tabIcon(int)
    TextEdit
    • string text
    • boolean readOnly
    • textChanged()
    • dataUpdated(QString,Plasma::DataEngine::Data)
    ToolButton

    Read/write properties:

    • ''QAction action: the action associated with this ToolButton
    • 'boolean autoRaise: whether or not the ToolButton should raise automatically when the user interacts with it
    • ''boolean down: whether or not the ToolButton is in the down position (since '4.5)
    • ''string image: path to an icon or image (e.g. in the widget's Package) to show on the ToolButton
    • ''string text: the text shown on the ToolButton

    Signals:

    • clicked()
    • pressed()
    • released()
    TreeView
    • QAbstractModel model
    VideoWidget
    • string url
    • number currentTime
    • number totalTime
    • number remainingTime
    • number usedControls
    • boolean controlsVisible
    • tick(qint64)
    • aboutToFinish()
    • nextRequested()
    • previousRequested()
    • play()
    • pause()
    • stop()
    • seek(qint64)
    • mediaObject()
    • audioOutput()
    • number NoControls
    • number Play
    • number Pause
    • number Stop
    • number PlayPause
    • number Previous
    • number Next
    • number Progress
    • number Volume
    • number OpenFile
    • number DefaultControls

    Other UI Elements

    BusyWidget
    • boolean running
    • string label
    • clicked()
    FlashingLabel
    • boolean autohide
    • QColor color
    • number duration
    • kill()
    • fadeIn()
    • fadeOut()
    • flash(QString,int,QTextOption)
    • flash(QString,int)
    • flash(QString)
    • flash(QPixmap,int,Qt::Alignment)
    • flash(QPixmap,int)
    • flash(QPixmap)
    IconWidget
    • string text
    • string infoText
    • QIcon icon
    • QColor textBackgroundColor
    • QSizeF iconSize
    • string svg
    • QAction action
    • number orientation
    • number numDisplayLines
    • pressed(bool)
    • clicked()
    • doubleClicked()
    • activated()
    • changed()
    • setPressed(bool)
    • setPressed()
    • setUnpressed()
    • setIcon(QString)
    ItemBackground
    • QRectF target
    • QGraphicsItem targetItem
    • appearanceChanged()
    • animationStep(qreal)
    • targetReached(QRectF)
    • targetItemReached(QGraphicsItem*)
    Meter
    • number minimum
    • number maximum
    • number value
    • string svg
    • number meterType
    • dataUpdated(QString,Plasma::DataEngine::Data)
    • number BarMeterHorizontal
    • number BarMeterVertical
    • number AnalogMeter
    Separator
    • number orientation
    SignalPlotter
    • string title
    • string unit
    • boolean useAutoRange
    • number horizontalScale
    • boolean showVerticalLines
    • QColor verticalLinesColor
    • number verticalLinesDistance
    • boolean verticalLinesScroll
    • boolean showHorizontalLines
    • QColor horizontalLinesColor
    • QColor fontColor
    • number horizontalLinesCount
    • boolean showLabels
    • boolean showTopBar
    • QColor backgroundColor
    • string svgBackground
    • boolean thinFrame
    • boolean stackPlots
    SvgWidget
    • Svg svg
    • string elementID
    • clicked(Qt::MouseButton)
    WebView
    • Url url
    • string html
    • boolean dragToScroll
    • QPointF scrollPosition
    • QSizeF contentsSize
    • QRectF viewportGeometry
    • loadProgress(int)
    • loadFinished(bool)

    Layouts

    LinearLayout

    • number spacing
    • QtOrientation setOrientation
    • function removeAt
    • function addStretch
    • function setStretchFactor
    • function setAlignment
    • function insertStretch
    • function setItemSpacing
    • function setContentsMargins
    • function addItem
    • function removeItem
    • function insertItem
    • function toString

    AnchorLayout

    • number horizontalSpacing
    • number verticalSpacing
    • function setSpacing
    • function removeAt
    • function addAnchor
    • function anchor
    • function addAnchors
    • function addCornerAnchors
    • function toString

    GridLayout

    • number horizontalSpacing
    • number verticalSpacing
    • function rowSpacing
    • function setRowSpacing
    • function columnSpacing
    • function setColumnSpacing
    • function rowMinimumHeight
    • function setRowMinimumHeight
    • function rowPreferredHeight
    • function setRowPreferredHeight
    • function rowMaximumHeight
    • function setRowMaximumHeight
    • function rowFixedHeight
    • function setRowFixedHeight
    • function columnMinimumWidth
    • function setColumnMinimumWidth
    • function columnPreferredWidth
    • function setColumnPreferredWidth
    • function columnMaximumWidth
    • function setColumnMaximumWidth
    • function columnFixedWidth
    • function setColumnFixedWidth
    • function remoteAt
    • function setAlignment
    • function setSpacing
    • function setContentsMargins
    • function addItem
    • function toString

    Undocumented Properties and Functions

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

    Animations

    Creating Animation Objects

    An Animation object can be retrieved by calling the Animation animation(string type) function. The string corresponds to the type of animation, which are listed below.

    New Animation objects are associated with (and therefore will animate) the Plasmoid by default. By setting the widgetToAnimate property, however, it can be assigned to animate any QGraphicsWidget desired (e.g. Plasma widgets such as push buttons, sliders, etc) .

    Enumerations

    All Animation objects have the following enumerations:

    MovementDirection

    • MoveUp
    • MoveUpRight
    • MoveRight
    • MoveDownRight
    • MoveDown
    • MoveDownLeft
    • MoveLeft
    • MoveUpLeft

    Reference

    The reference point, relative to the target widget, for the animation.

    • Center
    • Up
    • Down
    • Left
    • Right

    State

    • Paused
    • Running
    • Stopped

    Common API

    With the exception of Pause and Property animations, all animations support the following read/write properties:

    • AnimationDirection direction: the direction the animation should play: AnimationForward or AnimationBackward
    • int duration: length of the animation in ms.
    • EasingCurveType easingCurveType: The easing curve to use in the animation
    • QGraphicsWidget targetWidget: the QGraphicsWidget (e.g. a Plasma::Widget) that this animation should operate on

    Animation Groups

    Animations may be put into groups for convenient sequential or parallel running. Sequential groups, where the animations run one after the other, are handled by the AnimationGroup class. Parallel aniations, where the animations run simultaneously, are handled the ParallelAnimationGroup class.

    Animations are added to a group by calling add(Animation) on the group object. Groups may also be added to other groups.

    Animation Types

    Below is a list of all current animation types and their particular read/write properties:

    Fade

    • number startOpacity: the opacity, between 0 and 1, that the target widget starts at when the animation begins
    • number targetOpacity: the opacity, between 0 and 1, that the target widget will be at the end of the animation

    Geometry

    • QRectF startGeometry: the geometry that the target widget should start with
    • QRectF targetGeometry: the geometry the target widget will have at the end of the animation

    Grow

    • number factor: the factor by which the target widget will grow to by the end of the animation

    Pause

    • number duration: the number of milliseconds to pause for

    Property

    Animates an object (must be a QObject internally, which includes all Plasma Widgets) by manipulating one of its properties. Property animations have the following read/write properties:

    • any startValue
    • any endValue
    • ByteArray propertyName
    • QObject targetObject
    • number duration
    • EasingCurve easingCurve

    Pulser

    • number targetScale: the maximum scale of the pulse-shadow item, relative to the target widget

    Rotate

    • QtAxis axis: the axis along which to rotate the item
    • Reference reference: the reference point around which to rotate the target widget
    • number angle: the number of degrees to rotate the item

    RotateStacked

    • MovementDirection movementDirection: the direction to rotate the widgets in the stack around
    • QGraphicsLayoutItem layout
    • Reference reference: the reference point around which to rotate the target widget
    • QGraphicsWidget backingWidget: the widget in the "back" to rotate to the front of the target widget

    Slide

    • MovementDirection movementDirection: the direction to slide the widget
    • number distance: the distance to slide the widget

    Zoom

    • number zoom: the factor by which to zoom the target widget

    QEasingCurve

    Used to set the progress shape of Animation objects, this class has the following read-only properties:

    • string toString
    • number valueForProgress(number progress): returns effective progress for the easing curve at progress. While progress must be between 0 and 1, the returned effective progress can be outside those bounds.

    as well as the following read/write property:

    • EasingCurveType type: the shape of this easing curve

    and the following enumeration:

    • EasingCurveType
      • LinearEasingCurve
      • InQuadEasingCurve
      • OutQuadEasingCurve
      • InOutQuadEasingCurve
      • OutInQuadEasingCurve
      • InCubicEasingCurve
      • OutCubicEasingCurve
      • InOutCubicEasingCurve
      • OutInCubicEasingCurve
      • InQuartEasingCurve
      • OutQuartEasingCurve
      • InOutQuartEasingCurve
      • OutInQuartEasingCurve
      • InQuintEasingCurve
      • OutQuintEasingCurve
      • InOutQuintEasingCurve
      • OutInQuintEasingCurve
      • InSizeEasingCurve
      • OutSineEasingCurve
      • InOutSineEasingCurve
      • OutInSineEasingCurve
      • InExpoEasingCurve
      • OutExpoEasingCurve
      • InOutExpoEasingCurve
      • OutInExpoEasingCurve
      • InCircEasingCurve
      • OutCircEasingCurve
      • InOutCircEasingCurve
      • InOutCircEasingCurve
      • OutInCircEasingCurve
      • InElasticEasingCurve
      • OutElasticEasingCurve
      • InOutElasticEasingCurve
      • OutInElasticEasingCurve
      • InBackEasingCurve
      • OutBackEasingCurve
      • InOutBackEasingCurve
      • OutInBackEasingCurve
      • InBouncEasingCurve
      • OutBounceEasingCurve
      • InOutBounceEasingCurve
      • OutInBounceEasingCurve
      • InCurveEasingCurve
      • OutCurveEasingCurve
      • SineCurveEasingCurve
      • CosineCurveEasingCurve

    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(string fileName)': fileName can be a file in the desktop theme or the plasmoid package

    Read-only properties:

    • QSizeF size: the current size of the svg

    Read-write properties:

    • boolean multipleImages: whether or not the svg contains multiple separate images
    • string imagePath: the file path, including name of the svg
    • boolean 'usingRenderingCache: whether or not to cache rendered pixmaps; improves performance (at the cost of some disk and memory usage) for SVG data that is repeatedly rendered

    Functions:

    • QSizeF elementSize(String svgElemen)
    • QRectF elementRect(String svgElemen)
    • boolean hasElement(String svgElement)
    • elementAtPoint(QPoint pos)
    • boolean isValid()
    • QPixmap pixmap(String svgElement): a pixmap of the element in the svg rendered to the current size
    • Qixmap pixmap(): a pixmap of the entire svg rendered to the current size
    • paint(QPainter painter, QPointF point)
    • paint(QPainter painter, QPointF point, String svgElement)
    • paint(QPainter painter, number x, number y)
    • paint(QPainter painter, number x, number y, String svgElement)
    • paint(QPainter painter, QRectF destination)
    • paint(QPainter painter, QRectF destination, String svgElement)
    • paint(QPainter painter, number y, number width, number height)
    • paint(QPainter painter, number x, number y, number width, number height, QString svgElement)
    • resize(number width, number height)
    • resize(QSizeF size)
    • resize(): resizes the SVG to the document size defined in the SVG itself

    Signals:

    • repaintNeeded(): emitted when the SVG is in need of a repaint, such as when the theme changes and the SVG has reloaded its data

    FrameSvg

    Constructors:

    • FrameSvg(String fileName): fileName can be a file in the desktop theme or the plasmoid package

    Read-only properties:

    • boolean multipleImages: whether or not the svg contains multiple separate images

    Functions:

    • setEnabledBorders(EnabledBorders borders): sets which borders are enabled when painting
    • EnabledBorders enabledBorders(): the borders which are enabled when painting
    • resizeFrame(QSizeF size): resizes the frame to size
    • QSizeF frameSize(): the size of the current frame
    • number marginSize(MarginEdge margin): the size of the margin for a given edge
    • getMargins(number left, number top, number right, number bottom): stores the margin values in the variables passed in
    • QRectF contentsRect(): the rect containing the contents, e.g. the size of the SVG minus the space required by the enabled borders
    • setElementPrefix(Location): sets the frame element for the given location if it exists
    • setElementPrefix(String prefix): sets the element prefix
    • boolean hasElementPrefix(String prefix): returns true if the SVG contains a frame with the given prefix
    • boolean hasElementPrefix(Location location): true if the SVG contains a frame element for the given location
    • prefix()
    • mask()
    • setCacheAllRenderedFrames(bool)
    • cacheAllRenderedFrames()
    • QPixmap framePixmap(): a pixmap containing the current frame at the current size
    • paintFrame(QPainter painter)
    • paintFrame(QPainter painter, QPointF target)
    • paintFrame(QPainter painter, QRectF target)
    • paintFrame(QPainter painter, QRectF target, QRectF source)

    Enumerations

    • EnabledBorder
      • NoBorder
      • TopBorder
      • BottomBorder
      • LeftBorder
      • RightBorder
      • AllBorders

    Painting on the Canvas

    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)
    • string key
    • string lastResortFamily
    • string lastResortFont
    • string defaultFamily
    • boolean exactMatch
    • string toString
    • boolean bold
    • string family
    • boolean fixedPitch
    • undefined fromString
    • boolean italic
    • boolean kerning
    • boolean overline
    • number pixelSize
    • number pointSize
    • number pointSizeF
    • boolean strikeOut
    • number stretch
    • boolean underline
    • number weight
    • function isCopyOf
    • function resolve

    QPainter

    • Constructors
      • QPainter
      • QPainter(object paintDevice): used to start a painter on a specific QWidget; rarely if ever needed in a JavaScript Plasmoid
    • object background
    • number backgroundMode
    • object brush
    • undefined setBrush
    • object brushOrigin
    • undefined clipping
    • object clipPath
    • object clipRegion
    • number compositionMode
    • object font
    • number layoutDirection
    • number opacity
    • object pen
    • number renderHints
    • undefined transform
    • object viewport
    • boolean viewTransformEnabled
    • object window
    • object worldMatrix
    • object worldTransform
    • boolean worldMatrixEnabled
    • object combinedMatrix
    • object combinedTransform
    • boolean isActive
    • function begin
    • function end
    • function boundingRect
    • 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 eraseRect
    • function fillPath
    • function fillRect
    • function resetMatrix
    • function resetTransform
    • function restore
    • function rotate
    • function save
    • function scale
    • function setClipRect
    • function setRenderHint
    • function shear
    • function strokePath
    • function testRenderHint
    • function toString
    • function translate

    QPen

    • Constructors:
      • QPen
    • object brush
    • object color
    • number capStyle
    • number joinStyle
    • number style
    • number dashOffset
    • number miterLimit
    • number width
    • boolean isSolid
    • number red
    • number green
    • number blue
    • number alpha
    • boolean isValid

    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

    See the JavaScript Plasmoid DataEngine tutorials

    Global Functions to Access DataEngines and Services

    • dataEngine(string name): returns a DataEngine object
    • service(string dataEngineName, string sourceName): returns a ServiceObject, see also DataEngine::serviceForSource

    DataEngine

    • object sources
    • boolean valid
    • string icon
    • function destroyed(QObject*)
    • function destroyed()
    • function deleteLater()
    • function sourceAdded(QString)
    • function sourceRemoved(QString)
    • function scheduleSourcesUpdated()
    • function removeSource(QString)
    • function updateAllSources()
    • function forceImmediateUpdateOfAllVisualizations()
    • function sources()
    • function serviceForSource(QString)
    • function name()
    • function connectSource(QString,QObject*,uint,Plasma::IntervalAlignment)
    • function connectSource(QString,QObject*,uint)
    • function connectSource(QString,QObject*)
    • function connectAllSources(QObject*,uint,Plasma::IntervalAlignment)
    • function connectAllSources(QObject*,uint)
    • function connectAllSources(QObject*)
    • function disconnectSource(QString,QObject*)
    • function containerForSource(QString)
    • function query(QString)

    Service

    • function finished(Plasma::ServiceJob*)
    • function operationsChanged()
    • function serviceReady(Plasma::Service*)
    • function setDestination(QString)
    • function destination()
    • function operationNames()
    • function operationDescription(QString)
    • function startOperationCall(KConfigGroup,QObject*)
    • function startOperationCall(KConfigGroup)
    • function isOperationEnabled(QString)
    • function name()
    • function associateWidget(QWidget*,QString)
    • function disassociateWidget(QWidget*)
    • function associateWidget(QGraphicsWidget*,QString)
    • function disassociateWidget(QGraphicsWidget*)
    • function parametersFromDescription(KConfigGroup)

    Other Functions and Classes

    Print and Debug

    • print(string message): prints message to console
    • debug(string message): print message to console if it is running in a KDE debug build

    GraphicsItem

    This class represents an item on the canvas. Support is only provided so that GraphicsItem objects returned or taken by other objects work. There is no meaningful API provided directly in the JavaScript runtime for these objects and they should not need to be used directly.

    IOJob

    This object is returned by input/output access for asynchronous file and data access (see the section on Extensions for documentation on getUrl). It is used by connecting Javascript functions in your code to the relevant signals.

    Functions:

    • kill()
    • suspend()
    • resume()

    Signals:

    • data(IOJob job, ByteArray data): emitted whenever data arrives. If data is empty (data.length == 0) then the transmission has completed.
    • dataReq(IOJob job, ByteArray data): when sending data, this signal is emitted when data is requested; add the data to be sent ot the data member, or leave it empty to signal that the process is complete and there is no more data to send
    • finished(IOJob job): emitted when the transmission has completed
    • suspended(IOJob job): emitted when the job has been suspeneded
    • resumed(IOJob job)
    • canceled(IOJob job)
    • connected(IOJob job)
    • redirection(IOJob job, Url to)
    • permanentRedirection(IOJob job, Url from, Url to)
    • mimetype(IOJob job, String mimetype)

    Timer

    Read-write properties:

    • boolean isActive: true if active, false if not
    • boolean singleShot: true if the timer will fire once when started, false if it will fire repeatedly until stopped
    • boolean interval: the interval in milliseconds that the timer will trigger

    Functions:

    • start(int msec): starts the timer with msec as the interval
    • start(): starts the timer with the default interval
    • stop(): stops the timer

    Signals:

    • timeout(): this signal is emitted whenever the timer interval is reached

    Url

    Represents a local or remote address. To create a new Url (or assign to an existing one), use the following syntax:

    var url = new Url("http://kde.org")

    Read-only properties:

    • string toString: the URL as a String object

    Read-write properties (each representing a portion of the full URL):

    • string protocol
    • string host
    • string path
    • string user
    • string password

    ByteArray

    This class provides an array of bytes. This is often used by data centric objects, such as the Job classes returned by getUrl.

    Read-only properties:

    • number length: the size of the array (number of bytes)

    Functions:

    • chop(number numBytes): chops numBytes from the end of the array
    • bool equals(ByteArray other)
    • ByteArray left(number len): return len bytes from the left of the array
    • ByteArray mid(number pos, number len): returns an array of bytes starting a post and length len (if len is -1, it returns all remaining bytes)
    • ByteArray remove(number pos, number len): removes len bytes starting at index pos from the array and returns it
    • ByteArray right(number len): returns len bytes from the right of the array
    • ByteArray simplified(): returns a byte array that has whitespace removed from the start and the end, and which has each sequence of internal whitespace replaced with a single space
    • ByteArray toBase64(): returns the array encoded in base64
    • ByteArray toLower(): returns a lowercased copy of the array
    • ByteArray toUpper(): returns an uppercased copy of the array
    • ByteArray trimmed(): returns a copy of the array with whitespace remove from the start and end
    • truncate(number pos): truncates the array at index pos
    • String toLatin1String(): returns a Latin1-ized string based on the array
    • String valueOf(): returns the raw data in the array as a string

    Extensions

    An API extension is a security controlled set of functions and objects that are loaded on demand. These extensions are requested by the widget by listing the required and the optional extensions (if any) it wants loaded in its metadata.desktop file. This way, even prior to the widget being loaded, Plasma can know what it will want.

    Required extensions are requested using the X-Plasma-RequiredExtensions key, and optional extensions with the X-Plasma-OptionalExtensions. For example:

    X-Plasma-RequiredExtensions=FileDialog,MyCustomQScriptExtension X-Plasma-OptionalExtensions=LaunchApp,HTTP

    The Simplified Javascript Engine then decides if the widget will actually get that extension or not. Failure to load a required extension will result in script execution being aborted.

    Each of the built-in extensions provided are described below.

    FileDialog

    Provides access to open and save dialog classes: OpenFileDialog and SaveFileDialog. Both are non-modal and run asynchronously, so the signals must be used. Other than the name difference (and resulting UI variance) the API for each is identical:

    • Constructors
      • OpenFileDialog
      • SaveFileDialog
    • Properties
      • Read Only
        • array(Url) urls: the selected file, as a Url object
        • Url baseUrl, the current path (minus filename) as a Url
        • string file: the selected file, as a string
        • array(string) files: selected files (plural), as an array of strings
      • Read/Write
        • Url url: the current Url, can be read from when the user is done or assigned before to set the starting path
        • string filter: a string representing the mimetype filter; e.g. "*.cpp|C++ Source Files\n*.h|Header files" or "*.cpp" or "*.cpp|*h"
        • boolean localOnly: true to show only local files, false if network locations are Ok as well
        • boolean directoriesOnly: true to only allow selection of a directory (not a file)
        • boolean existingOnly: true if only existing files/directories may be selected
    • Functions
      • show(): when called, the dialog will be shown to the user
    • Signals
      • accepted(FileDialogProxy)': emitted when the file dialog has been successfully accepted by the user with one or more files/directories.
      • finished(FileDialogProxy): emitted when the file dialog closes, included when cancelled/closed without being accepted

    LocalIO

    This extension allows access to local files.

    Functions:

    • IOJob getUrl(Url url): attempts to fetch the file using an IOJob
    • IOJob getUrl(String url): attempts to fetch the file using an IOJob

    NetworkIO

    This extensions allows access to network addresses.

    Functions:

    • IOJob getUrl(Url url): attempts to fetch the file using an IOJob
    • IOJob getUrl(String url): attempts to fetch the file using an IOJob

    HTTP

    This extension allows access to data and files via http and https.

    Functions:

    • IOJob getUrl(Url url): attempts to fetch the file using an IOJob
    • IOJob getUrl(String url): attempts to fetch the file using an IOJob

    LaunchApp

    Adds methods to the global plasmoid object that allow launching applications, running commands and opening files and urls.

    • bool runApplication(string application[, array files])
      Runs an application by name (can reference an installed .desktop file as well as an executable in the user's $PATH) with an optional array of files. The file array may contain either Urls or strings. Returns true on success, false on failure.
    • bool runApplication(string exe[, array args])
      Runs the executable with the given arguments. Returns true on success, false on failure.
    • bool openUrl([string|Url] url):
      Opens the url in the default application (or asks the user if there is no default application for the file). The url parameter may be either a string or a Url. Returns true on success, false on failure.