Development/Tutorials/Plasma4/JavaScript/API-UIElements

User Interface Elements

The Plasma framework provides a set of standard user interface elements 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.

Note that some UI elements have functions that are synonymous with a read-write property. In those cases, the function can serve as a slot and be connected to signals for easy setting of the property.

DataEngine-Aware UI Elements

Some of the UI elements are able to accept data directly from DataEngines. These widgets will have a dataUpdated function and can be passed into the DataEngine::connectSource method successfully.

DataEngine-aware UI elements include:

• Label
• TextEdit
• Meter

Common Properties

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

• String objectName
• number opacity
• boolean enabled
• boolean visible
• QPointF pos
• number x
• number y
• number z
• number rotation
• number scale
• QPointF transformOriginPoint
• QPalette palette
• QFont font
• QSizeF size
• QtFocusPolicy focusPolicy
• QRectF geometry

Importantly, most elements also support:

• QSizeF preferredSize: this size is used to control the default sizing of windows and other containers that the element may be shown in. This is particularly useful for, e.g., popupWidget in PopupApplets.

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

• String styleSheet: A CSS stylesheet describing visual properties to apply to the widget; see the Qt Documentation for more information

CheckBox

Read-write properties:

• String text
• String image
• boolean checked
• toggled(bool)

ComboBox

Read-only properties:

• number count: (API v 3) the number of items in the combobox

Read-write properties:

• String text: the text of the currently selected item in the combobox
• number currentIndex: (API v 3) the index of the current item

Funtions:

• clear()

Signals:

• activated(String)
• textChanged(String)
• currentIndexChanged(number)

Frame

Read-write properties:

• Shadow frameShadow
• String text
• String image

Enumerations:

• Shadow
• Plain
• Raised
• Sunken

GroupBox

Read-write properties:

• String text

Label

Read-write properties:

• String text
• String image
• number alignment (see #QtAlignment for the valid values)
• boolean hasScaledContents
• boolean textIsSelectable (since 4.4.1)
• boolean wordWrap (API v2)

Functions:

• dataUpdated(String, Data)

Signals:

• linkActivated(String): emitted when a link is clicked; includes the URL of link that is clicked; this is only available when textIsSelectable
• linkHovered(String): emitted when a link is hovered

LineEdit

Read-write properties:

• String text
• boolean clearButtonShown

Signals:

• editingFinished()
• returnPressed()
• textEdited(String)
• textChanged(String)

PushButton

Read-write properties:

• String text
• String image
• QAction action
• QIcon icon
• boolean checkable
• boolean checked
• boolean down

Signals:

• pressed()
• released()
• clicked()
• toggled(bool)

For example, the following snippet creates a simple button:

layout = new LinearLayout(plasmoid); // A layout object is required to display the PushButton UI component
helloButton = new PushButton();
helloButton.text = 'Hello';
layout.addItem(helloButton);

RadioButton

Read-write properties:

• String text
• String image
• boolean checked

Signals:

• toggled(bool)

ScrollWidget

Read-write properties:

• QGraphicsWidget widget
• number horizontalScrollBarPolicy
• number verticalScrollBarPolicy
• QPointF scrollPosition
• QSizeF contentsSize
• QRectF viewportGeometry

Functions:

• ensureRectVisible(QRectF)
• ensureItemVisible(QGraphicsItem)
• registerAsDragHandle(QGraphicsWidget)
• unregisterAsDragHandle(QGraphicsWidget)

ScrollBar

Read-write properties:

• number singleStep
• number pageStep
• number value
• number minimum
• number maximum
• QtOrientation setOrientation

Functions:

• setValue(number)
• setOrientation(QtOrientation)

Signals:

• valueChanged(number)

Slider

Read-write properties:

• number maximum
• number minimum
• number value
• number orientation

Signals:

• sliderMoved(number)
• valueChanged(number)

Functions:

• setMaximum(number)
• setMinimum(number)
• setRange(number, number)
• setValue(number)
• setOrientation(QtOrientation)

SpinBox

Read-write properties:

• number maximum
• number minimum
• number value

Functins:

• setMaximum(number)
• setMinimum(number)
• setRange(number, number)
• setValue(number)

Signals:

• sliderMoved(number)
• valueChanged(number)
• editingFinished()

TabBar

Read-write properties:

• number currentIndex
• number count
• boolean tabBarShown

Functions:

• setCurrentIndex(number)
• insertTab(number, QIcon,String,QGraphicsLayoutItem)
• insertTab(number, QIcon,String)
• insertTab(number, String,QGraphicsLayoutItem)
• insertTab(number, String)
• addTab(QIcon,String,QGraphicsLayoutItem)
• addTab(QIcon,String)
• addTab(String,QGraphicsLayoutItem)
• addTab(String)
• removeTab(number)
• takeTab(number)
• tabAt(number)
• setTabText(number, String)
• tabText(number)
• setTabIcon(number, QIcon)
• tabIcon(number)

Signals:

• currentChanged(number)

TextEdit

Read-write properties:

• String text
• boolean readOnly

Functions:

• dataUpdated(String, Data)

Signals:

• textChanged()

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
• ''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

API v2 adds:

• ''boolean down: whether or not the ToolButton is in the down position (since protocol version 2)

Signals:

• clicked()
• pressed()
• released()

TreeView

Read-write properties:

• QAbstractModel model

VideoWidget

Read-writeproperties:

• String url
• number currentTime
• number totalTime
• number remainingTime
• Controls usedControls
• boolean controlsVisible

Functions:

• play()
• pause()
• stop()
• seek(number)

Signals:

• tick(number)
• aboutToFinish()
• nextRequested()
• previousRequested()

Enumerations:

• Controls
  • NoControls
  • Play
  • Pause
  • Stop
  • PlayPause
  • Previous
  • Next
  • Progress
  • Volume
  • OpenFile
  • DefaultControls

Other UI Elements

BusyWidget

Read-write properties:

• boolean running
• String label

Signals:

• clicked()

FlashingLabel

Read-write properties:

• boolean autohide
• QColor color
• number duration

Functins:

• kill()
• fadeIn()
• fadeOut()
• flash(String, number, QTextOption)
• flash(String ,number)
• flash(String)
• flash(QPixmap, number, QtAlignment)
• flash(QPixmap, number)
• flash(QPixmap)

GraphicsWidget (API v3)

This is just a plain element with no painting or other features. It is useful primarily as a place holder, especially to contain layouts for other elements.

IconWidget

Read-only properties:

• QSizeF iconSize - the actual size of the icon given the size of the IconWidget, space reserved (if any) for text displayed, etc.

Read-write properties:

• String text
• String infoText
• QIcon icon
• QColor textBackgroundColor
• String svg
• QAction action
• QtOrientation orientation
• number numDisplayLines
• boolean drawBackground

Functions:

• setPressed(boolean)
• setUnpressed()
• setIcon(String)

Signals:

• pressed(bool)
• clicked()
• doubleClicked()
• activated()
• changed()

ItemBackground

Read-write properties:

• QRectF target
• QGraphicsItem targetItem

Signals:

• appearanceChanged()
• animationStep(qreal)
• targetReached(QRectF)
• targetItemReached(QGraphicsItem)

Meter

Read-write properties:

• number minimum
• number maximum
• number value
• String svg
• MeterType meterType

Functions:

• dataUpdated(String, Data)

Enumerations:

• MeterType
  • BarMeterHorizontal
  • BarMeterVertical
  • AnalogMeter

Separator

Read-write properties:

• QtOrientation orientation

SignalPlotter

Read-write properties:

• 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

Read-write properties:

• Svg svg
• String elementID

Signals:

• clicked(QtMouseButton)

WebView

Read-only properties:

• QSizeF contentsSize
• QRectF viewportGeometry

Read-write properties:

• Url url
• String html
• boolean dragToScroll
• QPointF scrollPosition

Signals:

• loadProgress(number)
• loadFinished(bool)

Layouts

LinearLayout

• number spacing
• QtOrientation orientation (QtVertical or QtHorizontal)
• function removeAt
• function addStretch
• function setStretchFactor
• function setAlignment
• function insertStretch
• function setItemSpacing
• function setContentsMargins
• function addItem
• function removeItem
• function insertItem
• function toString
• function activate (API v3)

AnchorLayout

• number horizontalSpacing
• number verticalSpacing
• function setSpacing
• function removeAt
• function addAnchor
• function anchor
• function addAnchors
• function addCornerAnchors
• function toString
• function activate (API v3)

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
• function activate (API v3)

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.