Latest revision as of 23:27, 11 September 2014

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 orientation

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
String preferredIconSize (use as "64x64")
String minimumIconSize
String maximumIconSize

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.