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

(Created page with '= 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 availa...')

* ''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.

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:

StringobjectName

numberopacity

booleanenabled

booleanvisible

QPointFpos

numberx

numbery

numberz

numberrotation

numberscale

QPointFtransformOriginPoint

QPalettepalette

QFontfont

QSizeFsize

QtFocusPolicyfocusPolicy

QRectFgeometry

Importantly, most elements also support:

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

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:

Stringtext

booleanclearButtonShown

Signals:

editingFinished()

returnPressed()

textEdited(String)

textChanged(String)

PushButton

Read-write properties:

Stringtext

Stringimage

QActionaction

QIconicon

booleancheckable

booleanchecked

booleandown

Signals:

pressed()

released()

clicked()

toggled(bool)

RadioButton

Read-write properties:

Stringtext

Stringimage

booleanchecked

Signals:

toggled(bool)

ScrollWidget

Read-write properties:

QGraphicsWidgetwidget

numberhorizontalScrollBarPolicy

numberverticalScrollBarPolicy

QPointFscrollPosition

QSizeFcontentsSize

QRectFviewportGeometry

Functions:

ensureRectVisible(QRectF)

ensureItemVisible(QGraphicsItem)

registerAsDragHandle(QGraphicsWidget)

unregisterAsDragHandle(QGraphicsWidget)

ScrollBar

Read-write properties:

numbersingleStep

numberpageStep

numbervalue

numberminimum

numbermaximum

QtOrientationsetOrientation

Functions:

setValue(number)

setOrientation(QtOrientation)

Signals:

valueChanged(number)

Slider

Read-write properties:

numbermaximum

numberminimum

numbervalue

numberorientation

Signals:

sliderMoved(number)

valueChanged(number)

Functions:

setMaximum(number)

setMinimum(number)

setRange(number, number)

setValue(number)

setOrientation(QtOrientation)

SpinBox

Read-write properties:

numbermaximum

numberminimum

numbervalue

Functins:

setMaximum(number)

setMinimum(number)

setRange(number, number)

setValue(number)

Signals:

sliderMoved(number)

valueChanged(number)

editingFinished()

TabBar

Read-write properties:

numbercurrentIndex

numbercount

booleantabBarShown

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:

Stringtext

booleanreadOnly

Functions:

dataUpdated(String, Data)

Signals:

textChanged()

ToolButton

Read-write properties:

''QActionaction: the action associated with this ToolButton

'booleanautoRaise: whether or not the ToolButton should raise automatically when the user interacts with it

''Stringimage: path to an icon or image (e.g. in the widget's Package) to show on the ToolButton

''Stringtext: the text shown on the ToolButton

API v2 adds:

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

Signals:

clicked()

pressed()

released()

TreeView

Read-write properties:

QAbstractModelmodel

VideoWidget

Read-writeproperties:

Stringurl

numbercurrentTime

numbertotalTime

numberremainingTime

ControlsusedControls

booleancontrolsVisible

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:

booleanrunning

Stringlabel

Signals:

clicked()

FlashingLabel

Read-write properties:

booleanautohide

QColorcolor

numberduration

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:

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

Read-write properties:

Stringtext

StringinfoText

QIconicon

QColortextBackgroundColor

Stringsvg

QActionaction

QtOrientationorientation

numbernumDisplayLines

Functions:

setPressed(boolean)

setUnpressed()

setIcon(String)

Signals:

pressed(bool)

clicked()

doubleClicked()

activated()

changed()

ItemBackground

Read-write properties:

QRectFtarget

QGraphicsItemtargetItem

Signals:

appearanceChanged()

animationStep(qreal)

targetReached(QRectF)

targetItemReached(QGraphicsItem)

Meter

Read-write properties:

numberminimum

numbermaximum

numbervalue

Stringsvg

MeterTypemeterType

Functions:

dataUpdated(String, Data)

Enumerations:

MeterType

BarMeterHorizontal

BarMeterVertical

AnalogMeter

Separator

Read-write properties:

QtOrientationorientation

SignalPlotter

Read-write properties:

Stringtitle

Stringunit

booleanuseAutoRange

numberhorizontalScale

booleanshowVerticalLines

QColorverticalLinesColor

numberverticalLinesDistance

booleanverticalLinesScroll

booleanshowHorizontalLines

QColorhorizontalLinesColor

QColorfontColor

numberhorizontalLinesCount

booleanshowLabels

booleanshowTopBar

QColorbackgroundColor

StringsvgBackground

booleanthinFrame

booleanstackPlots

SvgWidget

Read-write properties:

Svgsvg

StringelementID

Signals:

clicked(QtMouseButton)

WebView

Read-only properties:

QSizeFcontentsSize

QRectFviewportGeometry

Read-write properties:

Urlurl

Stringhtml

booleandragToScroll

QPointFscrollPosition

Signals:

loadProgress(number)

loadFinished(bool)

Layouts

LinearLayout

numberspacing

QtOrientationorientation (QtVertical or QtHorizontal)

functionremoveAt

functionaddStretch

functionsetStretchFactor

functionsetAlignment

functioninsertStretch

functionsetItemSpacing

functionsetContentsMargins

functionaddItem

functionremoveItem

functioninsertItem

functiontoString

functionactivate (API v3)

AnchorLayout

numberhorizontalSpacing

numberverticalSpacing

functionsetSpacing

functionremoveAt

functionaddAnchor

functionanchor

functionaddAnchors

functionaddCornerAnchors

functiontoString

functionactivate (API v3)

GridLayout

number horizontalSpacing

number verticalSpacing

functionrowSpacing

functionsetRowSpacing

functioncolumnSpacing

functionsetColumnSpacing

functionrowMinimumHeight

functionsetRowMinimumHeight

functionrowPreferredHeight

functionsetRowPreferredHeight

functionrowMaximumHeight

functionsetRowMaximumHeight

functionrowFixedHeight

functionsetRowFixedHeight

functioncolumnMinimumWidth

functionsetColumnMinimumWidth

functioncolumnPreferredWidth

functionsetColumnPreferredWidth

functioncolumnMaximumWidth

functionsetColumnMaximumWidth

functioncolumnFixedWidth

functionsetColumnFixedWidth

functionremoteAt

functionsetAlignment

functionsetSpacing

functionsetContentsMargins

functionaddItem

functiontoString

functionactivate (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.