Development/Tutorials/Plasma4/JavaScript/API-UIElements

    From KDE TechBase

    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:

    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.