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

From KDE TechBase
(→‎Svg: code sample for Svg, as well as link to more information)
 
(58 intermediate revisions by 15 users not shown)
Line 5: Line 5:
The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.
The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.


The QML ScriptEngine is bassed upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine.
To see the api of the global ''Plasmoid'' object, see the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API] documentation.
The most important API for using graphical widgets is the [http://api.kde.org/4.x-api/plasma-qml-apidocs/ Plasma QtComponents API]
(TODO: the JavaScript api paged should probably be copied and stripped down the imperative bits not present there, it would make harder to update tough)
 


== What Is a Declarative Plasmoid?  ==
== What Is a Declarative Plasmoid?  ==
Line 17: Line 17:
What follows is a description of the Plasma declarative classes instantiable from QML.
What follows is a description of the Plasma declarative classes instantiable from QML.


= Main QML classes =
== fetching data from the plasmoid package ==
 
If you have a file in your plasmoid package under contents, let's say an image, you can access it with the plasmapackage url protocol:
 
<syntaxhighlight lang="javascript">
Image {
    source: "plasmapackage:/images/foo.png"
}
</syntaxhighlight>
 
The above code will load in the Image component the file foo.png located in contents/images of your plasmoid package.
 
<syntaxhighlight lang="javascript">
import "plasmapackage:/code/foo.js" as Foo
</syntaxhighlight>
 
Similarly, the above code will import a javascript file from the folder contents/code of your plasmoid package.
 
= Properties exported from the main QML item =
The root qml item can export some properties to influence its behavior:
* '''property int minimumWidth''': the plasmoid won't ever become narrower then that, size in pixels.
* '''property int minimumHeight''': minum height of the plasmoid, size in pixels.
* '''property Component compactRepresentation''': if the plasmoid is a popupapplet, the component in compactRepresentation will be used instead of the icon and will always be collapsed, regardless if it's in a panel or not.
 
= The Global Plasmoid Object =
 
As in the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#The_Global_plasmoid_Object JavaScript API], there is a global ''plasmoid'' object.  However, its API is a little different, largely because QML directly provides access to many functions and events that the global plasmoid object provides in the JavaScript API.  There are differences in event reporting, in particular.
 
== Environment  ==
 
A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:
 
* ''FormFactor'' '''formFactor''': See the [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#ad4a234ba4043af84f610c376159a862a FormFactor] documentation for values and their meaning. When the form factor changes, the plasmoid.formFactorChanged signal is emitted.
 
* ''Location'' '''location''': See the [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#a2e56eee20e28bd3df07081e9ac7cf72b Location] documentation for values and their meaning. When the location changes, the plasmoid.locationChanged signal is emitted.
 
* ''boolean'' '''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.immutableChanged signal is emitted.
 
* ''string'' '''currentActivity''': the current contextual activity name. When the current activity changes, the plasmoid.contextChanged signal is emitted.
 
* ''boolean'' '''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
 
* ''boolean'' '''userConfiguring''': true if the user configuration interface is currently being displayed.
 
== 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 [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#a19549b928c541b25f018703effeea236 AspectRatioMode] documentation for values and their meaning.
 
* ''BackgroundHints'' '''backgroundHints''': defines how the background of the widget is rendered. See the [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/classPlasma_1_1Applet.html#a0d91e3f0a945121e5cd399c6850e8754 BackgroundHints] documentation for values and their meaning.
 
* ''boolean'' '''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
 
* ''SizePolicy'' '''horizontalSizePolicy''': behaviour of the plasmoid in an horizontal layout such as a panel. See the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API-PlasmoidObject#Properties JavaScript API documentation] for more information.
 
* ''SizePolicy'' '''verticalSizePolicy''': behaviour of the plasmoid in a vertical layout such as a panel.
 
* ''ItemStatus'' '''status''': See [http://api.kde.org/4.10-api/kdelibs-apidocs/plasma/html/namespacePlasma.html#a4d967711130487b1070311626ad285cb ItemStatus documentation] for values and their meaning.  The plasmoid.statusChanged signal is emitted when the status changes.
 
=== PopupApplet specific ===
* ''QIcon'' '''popupIcon''': it will be used instead of the applet content when the applet is in a panel
* ''Object'' '''popupIconToolTip''': it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
** ''variant'' '''image''': the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
** ''String'' '''mainText''': the tooltip title
** ''String'' '''subText''': the tooltip descriptive subtext
 
  <syntaxhighlight lang="javascript">
      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data
  </syntaxhighlight>


== Data engines ==
* ''bool'' '''passivePopup''': if true when the popup is opened other windows can gain focus and the popup won't close
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], however it is preferrable to use the following declarative classes:
 
* ''bool'' '''popupShowing''': true when the popupapplet is iconified and its popup is open
 
=== Containment specific ===
* ''Array(Object)'' '''applets''': List of all applets in the containment
* ''bool'' '''drawWallpaper''': Enable/disable the wallpaper painting by the containment
* ''enum'' '''containmentType''': one of
** ''DesktopContainment'': A desktop containment
** ''PanelContainment'': A desktop panel
** ''CustomContainment'': A containment that is neither a desktop nor a panel  but something application specific
** ''CustomPanelContainment'': A customized desktop panel
 
* ''int'' '''screen''': Number of the screen this containment is in
* ''string'' '''activityName''': The name of the activity this containment belongs to.
* ''string'' '''activityId''': The id of the activity this containment belongs to.
 
* ''ToolBox'' '''toolBox()''': The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:
** ''Array(QAction)'' '''actions''': A list of actions provided by the Containment.
 
 
== Events ==
 
Note that many of the events of the JavaScript API are signals in the declarative API (eg: formFactorChanged).  These should be connected to in the usual way, for example:
<syntaxhighlight lang="javascript">
    plasmoid.formFactorChanged.connect(function() { ... });
</syntaxhighlight>
<br>
However, some notifications are still delivered by events, which should be connected to using ''addEventListener'':
<syntaxhighlight lang="javascript">
    plasmoid.addEventListener('configChanged', function() { print('config changed') } )
</syntaxhighlight>
<br>
The events delivered to declarative applets are:
 
* '''configChanged()''': the plasmoid's configuration changed
* '''popupEvent(boolean shown)''': called on PopupApplets when the popup is shown or hidden
* '''dataUpdated(String source, Map[String, Any] data)''': used to pass in DataEngine updates
* '''activate()''': called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance.
* '''initExtenderItem(Extender extender)''': called when an Extender should be set up.
 
 
= Main Plasma QML Classes =
 
== Data Engines ==
While it's possible to fetch data from a Plasma DataEngine in the same way as the [http://techbase.kde.org/Development/Tutorials/Plasma/JavaScript/API#DataEngine JavaScript API], it is preferrable to use the following declarative classes:


=== DataSource ===
=== DataSource ===
Line 39: Line 156:
It has the following properties:
It has the following properties:
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* bool '''valid''' (read only): true when the DataSource is successfully connected to a data engine
* int '''interval''': interval of polling of the dataengine, if 0 (default value) no polling will be executed
* int '''interval''': interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
* string '''engine''': the plugin name of the dataengine to load
* string '''engine''': the plugin name of the dataengine to load, e.g. "nowplaying", etc.
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''connectedSources''': all the sources of the dataengine we are connected to (and whose data will appear in the '''data''' property)
* Array(string) '''sources''' (read only): all the sources available from the dataengine
* Array(string) '''sources''' (read only): all the sources available from the dataengine
Line 51: Line 168:
It has the following signals:
It has the following signals:


Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData''(...) becomes '''onNewData'''(...).
Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. '''newData'''(...) becomes '''onNewData'''(...).  


* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data)
* '''onNewData'''(String sourceName, Plasma::DataEngine::Data data) the local vairables are named to '''sourceName''' and '''data'''
* '''onSourceAdded'''(String source)
* '''onSourceAdded'''(String source)
* '''onSourceRemoved'''(String source)
* '''onSourceRemoved'''(String source)
Line 63: Line 180:
* '''onConnectedSourcesChanged'''()
* '''onConnectedSourcesChanged'''()
* '''onSourcesChanged'''()
* '''onSourcesChanged'''()
You normaly wants to use '''onNewData''' (that is the aquivalent to '''dataUpdated''' in other languages). Here is sample with the time dataengine:
<syntaxhighlight lang="javascript">
import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore
Item {
        PlasmaCore.DataSource {
                id: dataSource
                engine: "time"
                connectedSources: ["Local","UTC"]
                interval: 500
                onNewData:{
                        if(sourceName== "Local"){
                                local.text = data.Time
                        }
                        else if(sourceName== "UTC"){
                                label_utc.text = data.Timezone
                        }
                }
        }
        Grid{
                columns: 2
                spacing: 5
                Text{text: dataSource.data.Local.Timezone}
                Text {
                        id: local
                        text: "XX:XX:XX"
                }
              Text{id: label_utc; text: "XXXX"}
              Text {
                      id: utc
                      text: dataSource.data.UTC.Time
                }
        }
}
</syntaxhighlight>
You see two different approches to get to the data:
* One is to act on ''onNewData''
* Use the ''data'' parameter from dataSource


==== Methods ====
==== Methods ====
Line 92: Line 254:


=== ServiceJob ===
=== ServiceJob ===
If is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
It is necessary to monitor the result of a Service operation, it's possible to connect to the '''finished''' signal provided by the job return paramenter of the '''startOperationCall''' service method.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.
The '''finished''' signal has the same job as parameter, from which is possible to check the variant '''result''' property, to check the result.
<syntaxhighlight lang="javascript">
    var service = messagesDataSource.serviceForSource(src)
    var operation = "auth";
    function result(job) {
        statusItem.authorizationStatus = job.result;
        print("ServiceJob result: " + job.result + " op: " + job.operationName);
    }
    var operation = service.operationDescription(operation);
    operation.user = userName;
    operation.password = password;
    var serviceJob = service.startOperationCall(operation);
    serviceJob.finished.connect(result);
</syntaxhighlight>


=== DataModel ===
=== DataModel ===
Some data engines return as their data something that can be interpreted as a list of items, rather than simple key/value pairs.
Some data engines return a list of items as their DataSources; for example the hotplug DataEngine lists all devices currently plugged in and the microblog engine lists all tweets/dents visible to a given account. QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''. Using a DataSource, the '''DataModel''' QML object can provide a suitable model for those QML item views.
QML provides some item views such as '''ListView''', '''GridView''' and '''Repeater'''.
The '''DataModel''' QML object can provide, based on a DataSource a model suitable for those QML item views.


It has the following properties:
It has the following properties:
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* DataSource '''dataSource''': the id of an existing (and connected) DataSource
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''sourceFilter''': it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model
* String '''keyRoleFilter''': it's a regular expression. Only data with keys that match this filter expression will be inserted in the model. If you need all data inserted in the mode, you must explicitly request it using the regular expression ".*"
* int '''count''' (read only): how many items are in the model
* int '''count''' (read only): how many items are in the model


Line 137: Line 315:
* String '''sortRole'''
* String '''sortRole'''
* Qt::SortOrder '''sortOrder'''
* Qt::SortOrder '''sortOrder'''
* Qt::CaseSensitivity '''sortCaseSensitivity'''
* int '''count''' (read only)
* int '''count''' (read only)


This is an example from the feed widget:
<syntaxhighlight lang="javascript">
model: PlasmaCore.SortFilterModel {
  id: postTitleFilter
  filterRole: "title"
  sortRole: "time"
  sortOrder: "DescendingOrder"
  filterRegExp: toolbarFrame.searchQuery
  sourceModel: PlasmaCore.SortFilterModel {
      id: feedCategoryFilter
      filterRole: "feed_url"
      sourceModel: PlasmaCore.DataModel {
        dataSource: feedSource
        keyRoleFilter: "items"
      }
  }
}
</syntaxhighlight>


== Popup Applet ==
== Popup Applet ==
Line 145: Line 342:
Why, that's easy.
Why, that's easy.


To change your plasmoid from being a regular boring one, simply change
To change your plasmoid from being a regular boring one, in your '''metadata.desktop''', simply change this following line:


<syntaxhighlight lang="ini">
<syntaxhighlight lang="ini">
Line 158: Line 355:


Then in the main QML item's Component.onCompleted, do:
Then in the main QML item's Component.onCompleted, do:
NOTE: the below code presently has no affect, yet the icons seems to get retrieved from the desktop file (FIXME - is this needed?).


<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
     plasmoid.popupIcon("konqueror")
     plasmoid.popupIcon = "konqueror"
</syntaxhighlight>
</syntaxhighlight>
If you want to use other elements instead of an icon when collapsed in a panel, use the '''compactRepresentation''' property in the root Item.


== Plasma Themes ==
== Plasma Themes ==
Line 169: Line 366:
=== Theme ===
=== Theme ===
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts.
From KDE 4.8 a Theme instance is always present given the org.kde.plasma.core plugin was imported, is not necessary to create it by hand.
It has the following properties:
It has the following properties:
* String '''themeName''' (read only)
* String '''themeName''' (read only)
* QFont '''font''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* bool '''windowTranslucentEnabled''' (read only)
* Url '''homepage''' (read only)
* Url '''homepage''' (read only)
Line 182: Line 379:
* color '''buttonBackgroundColor''' (read only)
* color '''buttonBackgroundColor''' (read only)
* color '''linkColor''' (read only)
* color '''linkColor''' (read only)
* color visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''visitedLinkColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonHoverColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''buttonFocusColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewTextColor''' (read only)
* color '''viewBackgroundColo''' (read only)r
* color '''viewBackgroundColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewHoverColor''' (read only)
* color '''viewFocusColor''' (read only)
* color '''viewFocusColor''' (read only)
* String '''styleSheet''' (read only)
* String '''styleSheet''' (read only)
* Font '''defaultFont''' (read only)
* Font '''desktopFont''' (read only)
* Font '''smallestFont''' (read only)
* int '''smallIconSize''' (read only)
* int '''smallMediumIconSize''' (read only)
* int '''mediumIconSize''' (read only)
* int '''largeIconSize''' (read only)
* int '''hugeIconSize''' (read only)
* int '''enormousIconSize''' (read only)
* int '''defaultIconSize''' (read only)
Each Font element has the following properties:
* bool bold
* Capitalization '''capitalization''' (MixedCase, AllUppercase, AllLowercase, SmallCaps, Capitalize) (read only)
* String '''family''' (read only)
* bool '''italic''' (read only)
* real '''letterSpacing''' (read only)
* int '''pixelSize''' (read only)
* real '''pointSize''' (read only)
* bool '''strikeout''' (read only)
* bool '''underline''' (read only)
* Weight '''weight''' (Light, Normal, DemiBold, Bold, Black) (read only)
* real '''wordSpacing''' (read only)
* size '''mSize''' the size, width and height of an uppercase "M" in this font (read only)
Theme is also used to control icon sizes, with the property '''iconSizes'''. it is an Object, that has the following properties:
* int '''desktop''': size of icons suited for the workspace
* int '''toolbar''': icons to be put in a ToolBar component
* int '''small''': smallest size for still "readable" icons
* int '''dialog''': icons to be put in popup dialogs


=== Svg ===
=== Svg ===
Line 197: Line 424:
* QSize '''size'''
* QSize '''size'''
* bool '''multipleImages'''
* bool '''multipleImages'''
* String '''imagePath'''
* String '''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]. Make sure to strip the final extension from this string, so you should for example use <code>"dialogs/background"</code> to get the standard background.
* bool '''usingRenderingCache'''
* bool '''usingRenderingCache'''


Line 208: Line 435:
* bool hasElement(QString elementId)
* bool hasElement(QString elementId)
* bool isValid(): true if valid svg file
* bool isValid(): true if valid svg file
=== FrameSvg ===
Declaring a FrameSvg element instantiates a Plasma FrameSvg instance. This class doesn't draw anything. For drawing, FrameSvgItem is used.
This is to be used when you need informations about the framesvg, such as hasElementPrefix().
Properties:
* All properties from Svg
* EnabledBorders '''enabledBorders''': flag combination of:
** NoBorder
** TopBorder
** BottomBorder
** LeftBorder
** RightBorder
Methods:
* All methods from Svg
* void setImagePath(QString path)
* void resizeFrame(QSize size)
* QSize frameSize()
* qreal marginSize(Plasma::MarginEdge edge)
* void getMargins(qreal left, qreal top, qreal right, qreal bottom): parameters are output, they get set with the margins from the FrameSvg
* QRectF contentsRect(): the rectangle of the center element, taking the margins into account.
* void setElementPrefix(QString prefix)
* bool hasElementPrefix(const QString prefix)
* QString prefix()
* void setCacheAllRenderedFrames(bool cache)
* bool cacheAllRenderedFrames()
* void clearCache()
* QPixmap framePixmap()


Sample Code:
Sample Code:
<syntaxhighlight lang="javascript">
<syntaxhighlight lang="javascript">
     PlasmaCore.Svg {
     PlasmaCore.FrameSvg {
         id: mySvg
         id: myFrameSvg
         imagePath: "widgets/line"
         imagePath: "widgets/button"
        prefix: "pressed"
     }
     }
</syntaxhighlight>
</syntaxhighlight>
'''imagePath''' can be anything in the '''desktoptheme/''' folder. For more information on what is available, see [http://techbase.kde.org/Projects/Plasma/Theme#Current_Theme_Elements Plasma Theme Elements]


=== SvgItem ===
=== SvgItem ===
Line 225: Line 482:
* QSizeF '''naturalSize''' (read only): default size of the Svg
* QSizeF '''naturalSize''' (read only): default size of the Svg
* bool '''smooth''': paint with antialias (default false)
* bool '''smooth''': paint with antialias (default false)
Sample Code:
<syntaxhighlight lang="javascript">
    PlasmaCore.SvgItem {
        id: mySvgItem
        anchors {
            top: parent.top
            left: parent.left
        }
        width: 300
        height: 3
        svg: mySvg
        elementId: "horizontal-line"
    }
</syntaxhighlight>


=== FrameSvgItem ===
=== FrameSvgItem ===
Line 244: Line 519:
* real '''right''' (read only)
* real '''right''' (read only)
* real '''bottom''' (read only)
* real '''bottom''' (read only)
Sample Code:
<syntaxhighlight lang="javascript">
PlasmaCore.FrameSvgItem {
    id: myFrameSvgItem
    anchors.fill: parent
    imagePath: "translucent/dialogs/background"
}
</syntaxhighlight>


== Top Level windows ==
== Top Level windows ==
Line 251: Line 536:


Properties:
Properties:
* Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
* Item '''mainItem''': the Item contained in the Dialog, it can be any QML Item instance
* bool '''visible''': if the window (not the mainItem) is visible
* bool '''visible''': if the window (not the mainItem) is visible
* int '''x''': x position of the window in screen coordinates
* int '''x''': x position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''y''': y position of the window in screen coordinates
* int '''width''' (read only): total width of the dialog, including margins
* int '''width''' (read only): total width of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins
* int '''height''' (read only): total height of the dialog, including margins.
* int '''windowFlags''': Qt window flags of the Dialog
* int '''windowFlags''': Qt window flags of the Dialog
* Margins '''margins''' (read only): margins of the Dialog
* Margins '''margins''' (read only): margins of the Dialog
{{Note|The width and height will scale with size of the main item within this Dialog component.}}
<syntaxhighlight lang="javascript">
import QtQuick 1.1
import org.kde.plasma.core 0.1 as PlasmaCore
Item {
    PlasmaCore.Dialog {
        visible: true
        mainItem: Item {
            width: 500
            height: 500
            Text {
                anchors.centerIn: parent
                color: "red"
                text: qsTr("text")
            }
        }
    }
}
</syntaxhighlight>


Methods:
Methods:
Line 279: Line 587:
* String '''subText'''
* String '''subText'''
* String '''image''': freedesktop compliant icon name as image of the tooltip
* String '''image''': freedesktop compliant icon name as image of the tooltip
== Containments ==
A Plasma Containment manages the position and manipulation of Plasmoids. The declarative containment is responsible for layout of applets and can provide custom applet handles. The containment should listen to the plasmoid.immutability property. In order to lay out applets in your containment, you can use the AppletContainer class to access geometry information of applets.
Actions such as configure and close are available through plasmoid.actions.
You can access the plasmoid global property from containments in the same way as from declarative and javascript plasmoids. If the plasmoid is a Containment, you can get a list of actions for it. If you want to provide background rendering in your Containment yourself, read the applet.backgroundHints property and after that set applet.backgroundHints to 0 to tell the Applet that is should not render the background.
=== AppletContainer ===
The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment.
Properties:
* ''Item'' '''applet''': The applet item, this property allows you to track destruction of the actual applet and update your layout.
** ''int'' '''backgroundHints''': Should the Applet be rendered on top of a background frame? 0 for no background, 1 for default background, 2 for translucent background
* ''int'' '''minimumWidth''': The minimum width of the applet
* ''int'' '''minimumHeight''': The minimum height of the applet
* ''int'' '''maximumWidth''': The maximum width of the applet
* ''int'' '''maximumHeight''': The maximum height of the applet
* ''int'' '''preferredWidth''': The preferred height of the applet
* ''int'' '''preferredHeight''': The preferred height of the applet
* ''enum'' '''status''': The status of the applet, one in the enum
** '''UnknownStatus''': The status is unknown
** '''PassiveStatus''': The applet is passive
** '''ActiveStatus''': The applet is active
** '''NeedsAttentionStatus''': The applet asks for attention
** '''AcceptingInputStatus''': The applet is accepting input
They can be imported in your code with:
<syntaxhighlight lang="javascript">
import org.kde.plasma.containments 0.1 as PlasmaContainments
</syntaxhighlight>
AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10.
=== ToolBox ===
The ToolBox is only available through the plasmoid object, through plasmoid.toolBox(). The ToolBox is rendered as a separate item  on top of the scene covering the entire containment. It is loaded from the "org.kde.toolbox" Plasma Package, if the package is not found, no ToolBox will be loaded.
The ToolBox provides a listmodel of actions that can be rendered using Repeaters or ListViews. The ''actions'' list property contains actions from the Corona and Containments. Examples for these actions are showing the add widget or activities interface, lock and unlock. The actions in the list change dynamically whenever the widgets are locked or unlocked.
Actions such as lock screen and leave can be implemented using the powermanagement dataengine's services for these functions.
ToolBox provides access to the following properties:
* ''Array(QAction)'' '''actions''': A list of actions provided by the Containment. These actions' most interesting properties are:
** ''QIcon'' '''icon''': The icon belonging to this action.
** ''String'' '''text''': The icon belonging to this action.
** '''trigger()''': Call trigger from your action delegate to trigger the action.
<syntaxhighlight lang="javascript">
import org.kde.plasma.containments 0.1 as PlasmaContainments
</syntaxhighlight>
ToolBox is only available for Containments and new in 4.10.


= Plasma QtComponents (4.8) =
= Plasma QtComponents (4.8) =
TODO
Plasma components documentation online at [http://api.kde.org/4.x-api/plasma-qml-apidocs/ api.kde.org]
 
=QtExtraComponents=
The QtExtraComponents make some very convenient Qt classes usable from within QML.
 
They can be imported in your code with:
<syntaxhighlight lang="javascript">
import org.kde.qtextracomponents 0.1
</syntaxhighlight>
 
==QPixmapItem==
This one wraps around a QPixmap class and allows you to send a QPixmap directly to QPixmapItem.
Properties:
* QPixmap '''pixmap''': The QPixmap object.
* bool '''smooth''': Set to true to render smooth.
* int '''nativeWidth''': (verification needed) The QPixmap width
* int '''nativeHeight''': (verification needed) The QPixmap height
* FillMode '''fillMode''': see below
 
==QImageItem==
This one wraps around a QImage class and allows you to send a QImage directly to QImageItem.
Properties:
* QImage '''image''': The QImage object.
* bool '''smooth''': Set to true to render smooth.
* int '''nativeWidth''': (verification needed) The QImage width
* int '''nativeHeight''': (verification needed) The QImage height
* FillMode '''fillMode''': see below
 
==FillMode==
Both QPixmapItem and QImageItem expose a FillMode enum. This enum defines how the image is going to be used to fill the item.
 
For QPixmapItem, possible values are:
 
* QPixmapItem.Stretch: the image is scaled to fit
* QPixmapItem.PreserveAspectFit: the image is scaled uniformly to fit without cropping
* QPixmapItem.PreserveAspectCrop: the image is scaled uniformly to fill, cropping if necessary
* QPixmapItem.Tile: the image is duplicated horizontally and vertically
* QPixmapItem.TileVertically: the image is stretched horizontally and tiled vertically
* QPixmapItem.TileHorizontally : the image is stretched vertically and tiled horizontally
 
QImageItem defines the same values, you just need to replace QPixmapItem with QImageItem.
 
==QIconItem==
This one wraps around a QPixmap class and allows you to send a QIcon directly to QIconItem.
Properties:
* QIcon/QString '''icon''': If you provide a QIcon it uses that directly. If you provide a string it uses a KIcon internally!
* bool '''smooth''': Set to true to render smooth.
* int '''implicitWidth''': Default width of as set in SystemSettings->Applications Appearance->Icons
* int '''implicitHeight''': Default height of as set in SystemSettings->Applications Appearance->Icons
* State '''state''': Icon state (DefaultState, ActiveState, DisabledState)

Latest revision as of 23:27, 11 September 2014

Introduction to the Plasmoid QML Declarative API

This document provides an overview/reference of the Declarative QML API for Plasmoids. It isn't a full binding to all of Qt or KDE's libraries, but a focused set of bindings designed to make writing Plasmoids fast and easy, while remaining powerful.

The API in this documentation covers the API of the Plasma specific QML components, so only the Declarative part of the API.

The QML ScriptEngine is based upon the Plasma JavaScript engine, making the API of the JavaScript part identical to the one of the JavaScript plasmoids engine. The most important API for using graphical widgets is the Plasma QtComponents API


What Is a Declarative Plasmoid?

To denote that this Plasmoid is a Declarative widget, ensure that in the metadata.desktop file there is this line:

X-Plasma-API=declarativeappletscript

What follows is a description of the Plasma declarative classes instantiable from QML.

fetching data from the plasmoid package

If you have a file in your plasmoid package under contents, let's say an image, you can access it with the plasmapackage url protocol:

Image {
    source: "plasmapackage:/images/foo.png"
}

The above code will load in the Image component the file foo.png located in contents/images of your plasmoid package.

import "plasmapackage:/code/foo.js" as Foo

Similarly, the above code will import a javascript file from the folder contents/code of your plasmoid package.

Properties exported from the main QML item

The root qml item can export some properties to influence its behavior:

  • property int minimumWidth: the plasmoid won't ever become narrower then that, size in pixels.
  • property int minimumHeight: minum height of the plasmoid, size in pixels.
  • property Component compactRepresentation: if the plasmoid is a popupapplet, the component in compactRepresentation will be used instead of the icon and will always be collapsed, regardless if it's in a panel or not.

The Global Plasmoid Object

As in the JavaScript API, there is a global plasmoid object. However, its API is a little different, largely because QML directly provides access to many functions and events that the global plasmoid object provides in the JavaScript API. There are differences in event reporting, in particular.

Environment

A set of read-only properties (and in most cases notification functions) that tell the Plasmoid about its current environment:

  • FormFactor formFactor: See the FormFactor documentation for values and their meaning. When the form factor changes, the plasmoid.formFactorChanged signal is emitted.
  • Location location: See the Location documentation for values and their meaning. When the location changes, the plasmoid.locationChanged signal is emitted.
  • boolean 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.immutableChanged signal is emitted.
  • string currentActivity: the current contextual activity name. When the current activity changes, the plasmoid.contextChanged signal is emitted.
  • boolean 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
  • boolean userConfiguring: true if the user configuration interface is currently being displayed.

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 AspectRatioMode documentation for values and their meaning.
  • BackgroundHints backgroundHints: defines how the background of the widget is rendered. See the BackgroundHints documentation for values and their meaning.
  • boolean 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
  • SizePolicy horizontalSizePolicy: behaviour of the plasmoid in an horizontal layout such as a panel. See the JavaScript API documentation for more information.
  • SizePolicy verticalSizePolicy: behaviour of the plasmoid in a vertical layout such as a panel.
  • ItemStatus status: See ItemStatus documentation for values and their meaning. The plasmoid.statusChanged signal is emitted when the status changes.

PopupApplet specific

  • QIcon popupIcon: it will be used instead of the applet content when the applet is in a panel
  • Object popupIconToolTip: it contains the icon, mainText and subtext for the tooltip the applet will have when collapsed in an icon, properties:
    • variant image: the icon, it may be an icon name, an image path, a QIcon, QImage or a QPixmap
    • String mainText: the tooltip title
    • String subText: the tooltip descriptive subtext
      var data = new Object
      data["image"] = "konqueror"
      data["mainText"] = "ToolTip title"
      data["subText"] = "ToolTip descriptive sub text"
      plasmoid.popupIconToolTip = data
  • bool passivePopup: if true when the popup is opened other windows can gain focus and the popup won't close
  • bool popupShowing: true when the popupapplet is iconified and its popup is open

Containment specific

  • Array(Object) applets: List of all applets in the containment
  • bool drawWallpaper: Enable/disable the wallpaper painting by the containment
  • enum containmentType: one of
    • DesktopContainment: A desktop containment
    • PanelContainment: A desktop panel
    • CustomContainment: A containment that is neither a desktop nor a panel but something application specific
    • CustomPanelContainment: A customized desktop panel
  • int screen: Number of the screen this containment is in
  • string activityName: The name of the activity this containment belongs to.
  • string activityId: The id of the activity this containment belongs to.
  • ToolBox toolBox(): The toolbox of the Containment. The ToolBox is rendered as a separate item on the scene and provides access to the following properties:
    • Array(QAction) actions: A list of actions provided by the Containment.


Events

Note that many of the events of the JavaScript API are signals in the declarative API (eg: formFactorChanged). These should be connected to in the usual way, for example:

    plasmoid.formFactorChanged.connect(function() { ... });


However, some notifications are still delivered by events, which should be connected to using addEventListener:

    plasmoid.addEventListener('configChanged', function() { print('config changed') } )


The events delivered to declarative applets are:

  • configChanged(): the plasmoid's configuration changed
  • popupEvent(boolean shown): called on PopupApplets when the popup is shown or hidden
  • dataUpdated(String source, Map[String, Any] data): used to pass in DataEngine updates
  • activate(): called when the widget is activated by the user, e.g. by a keyboard shortcut. Useful for setting the focus on a specific input widget, for instance.
  • initExtenderItem(Extender extender): called when an Extender should be set up.


Main Plasma QML Classes

Data Engines

While it's possible to fetch data from a Plasma DataEngine in the same way as the JavaScript API, it is preferrable to use the following declarative classes:

DataSource

DataSource is a receiver for a dataEngine and can be declared inside QML:

 import org.kde.plasma.core 0.1 as PlasmaCore

 PlasmaCore.DataSource {
     id: dataSource
     engine: "time"
     connectedSources: ["Local"]
     interval: 500
 }

Properties

It has the following properties:

  • bool valid (read only): true when the DataSource is successfully connected to a data engine
  • int interval: interval of polling of the dataengine, if 0 (default value, so no need to specify if you don't need it) no polling will be executed
  • string engine: the plugin name of the dataengine to load, e.g. "nowplaying", etc.
  • Array(string) connectedSources: all the sources of the dataengine we are connected to (and whose data will appear in the data property)
  • Array(string) sources (read only): all the sources available from the dataengine
  • variant map data (read only): It's the most important property, it's a map of all the data available from the dataengine: its structure will be as follows:
    • each key of the map will be a source name, in connectedSources
    • each value will be a variant hash, so an hash with strings as keys and any variant as value
    • example: dataSource.data["Local"]["Time"] indicates the Time key of the dataengine source called "Local"

Signals

It has the following signals:

Note that javascript/qml applies the 'on' prefix to signals. So the actual signal name in C++ which is e.g. newData(...) becomes onNewData(...).

  • onNewData(String sourceName, Plasma::DataEngine::Data data) the local vairables are named to sourceName and data
  • onSourceAdded(String source)
  • onSourceRemoved(String source)
  • onSourceConnected(String source)
  • onSourceDisconnected(String source)
  • onIntervalChanged()
  • onEngineChanged()
  • onDataChanged()
  • onConnectedSourcesChanged()
  • onSourcesChanged()

You normaly wants to use onNewData (that is the aquivalent to dataUpdated in other languages). Here is sample with the time dataengine:

import QtQuick 1.0
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
        PlasmaCore.DataSource {
                id: dataSource
                engine: "time"
                connectedSources: ["Local","UTC"]
                interval: 500

                onNewData:{
                        if(sourceName== "Local"){
                                local.text = data.Time
                        }
                        else if(sourceName== "UTC"){
                                label_utc.text = data.Timezone
                        }
                }

        }
        Grid{
                columns: 2
                spacing: 5
                Text{text: dataSource.data.Local.Timezone}
                Text {
                        id: local
                        text: "XX:XX:XX"
                }
               Text{id: label_utc; text: "XXXX"}
               Text {
                       id: utc
                       text: dataSource.data.UTC.Time
                }
        }
}

You see two different approches to get to the data:

  • One is to act on onNewData
  • Use the data parameter from dataSource

Methods

It has the following methods:

  • StringList keysForSource(String source): lists all the keys corresponding to a certain source: for instance in the "time" dataengine, for the "Local" source, keys will be:
    • "Timezone Continent"
    • "Offset"
    • "Timezone"
    • "Time"
    • "Date"
    • "Timezone City"
  • Service serviceForSource(String source): returns a Plasma service that corresponds a given source: see the section about services for how to use it.
  • void connectSource(String source): adds to connectedSources the new source
  • void disconnectSource(String source): removes that source from connectedSources

Service

Due to their imperative nature, Plasma Services are not instantiated as QML classes, but rather created out of a DataSource with the method serviceForSource and used in the JavaScript portions of the QML files. This following example is a simplified version from the Now Playing QML widget in the kdeexamples git repository:

  var service = dataSource.serviceForSource(activeSource)
  var operation = service.operationDescription("seek")
  operation.seconds = 10

  var job = service.startOperationCall(operation)

Here dataSource is the id of a DataSource object, and activeSource is a source contained in one of its connectedSources. The service provides an operation called "seek", with a parameter called "seconds", that can be written on it as a property of a JavaScript object.

ServiceJob

It is necessary to monitor the result of a Service operation, it's possible to connect to the finished signal provided by the job return paramenter of the startOperationCall service method. The finished signal has the same job as parameter, from which is possible to check the variant result property, to check the result.

    var service = messagesDataSource.serviceForSource(src)
    var operation = "auth";

    function result(job) {
        statusItem.authorizationStatus = job.result;
        print("ServiceJob result: " + job.result + " op: " + job.operationName);
    }

    var operation = service.operationDescription(operation);
    operation.user = userName;
    operation.password = password;
    var serviceJob = service.startOperationCall(operation);
    serviceJob.finished.connect(result);

DataModel

Some data engines return a list of items as their DataSources; for example the hotplug DataEngine lists all devices currently plugged in and the microblog engine lists all tweets/dents visible to a given account. QML provides some item views such as ListView, GridView and Repeater. Using a DataSource, the DataModel QML object can provide a suitable model for those QML item views.

It has the following properties:

  • DataSource dataSource: the id of an existing (and connected) DataSource
  • String sourceFilter: it's a regular expression. If the DataSource is connected to more than one source, only inserts data from sources matching this filter expression in the model. To, for example, have a source watch all sources beginning with say "name:", the required regexp would be sourceFilter: "name:.*"
  • String keyRoleFilter: it's a regular expression. Only data with keys that match this filter expression will be inserted in the model. If you need all data inserted in the mode, you must explicitly request it using the regular expression ".*"
  • int count (read only): how many items are in the model


Example:

 ListView {
   model: PlasmaCore.DataModel {
        dataSource: microblogSource
        keyRoleFilter: "[\\d]*"
    }
    delegate: Text {
        text: title
    }
 }

In the example, microblogSource is the id of a DataSource, and inserts in the model only entries that have a number as the key name (matched with [\\d]*, in this case tweets ids)

Each item in the model will have the form of a variant hash: all the keys of the hash will be registered as model role names, in the example, "title" is a role of the model containing a string (also reachable with model["title"]).

A special reserved role will always be present: "DataEngineSource": it will contain the name of the data engine source that gave origin to this item. Therefore, if you want merely the string of the current source that the model is at...do model["DataEngineSource"].

Note that view.currentItem holds the item currently selected. However, due to (http://bugreports.qt.nokia.com/browse/QTBUG-16347) this does not work in PathView. A workaround is to make your own.

SortFilterModel

SortFilterModel is a proxy model for easy sorting and/or filtering of the items in a DataModel (or any other QAbstractItemModel subclass that has been registered in QML with setContextProperty from a C++ application) Properties:

  • model sourceModel
  • String filterRegExp
  • String filterRole
  • String sortRole
  • Qt::SortOrder sortOrder
  • Qt::CaseSensitivity sortCaseSensitivity
  • int count (read only)

This is an example from the feed widget:

model: PlasmaCore.SortFilterModel {
   id: postTitleFilter
   filterRole: "title"
   sortRole: "time"
   sortOrder: "DescendingOrder"
   filterRegExp: toolbarFrame.searchQuery
   sourceModel: PlasmaCore.SortFilterModel {
      id: feedCategoryFilter
      filterRole: "feed_url"
      sourceModel: PlasmaCore.DataModel {
         dataSource: feedSource
         keyRoleFilter: "items"
      }
   }
}

Popup Applet

So you want your QML applet to be a popup applet, like the device notifier (an icon in the panel shows and expands the applet)?

Why, that's easy.

To change your plasmoid from being a regular boring one, in your metadata.desktop, simply change this following line:

ServiceTypes=Plasma/Applet

To:

ServiceTypes=Plasma/Applet,Plasma/PopupApplet

Then in the main QML item's Component.onCompleted, do:

    plasmoid.popupIcon = "konqueror"

If you want to use other elements instead of an icon when collapsed in a panel, use the compactRepresentation property in the root Item.

Plasma Themes

Theme

This class instantiable from QML provides access to the Plasma Theme colors and other facilities such as fonts. From KDE 4.8 a Theme instance is always present given the org.kde.plasma.core plugin was imported, is not necessary to create it by hand. It has the following properties:

  • String themeName (read only)
  • bool windowTranslucentEnabled (read only)
  • Url homepage (read only)
  • bool useGlobalSettings (read only)
  • QString wallpaperPath (read only)
  • color textColor (read only)
  • color highlightColor (read only)
  • color backgroundColor (read only)
  • color buttonTextColor (read only)
  • color buttonBackgroundColor (read only)
  • color linkColor (read only)
  • color visitedLinkColor (read only)
  • color visitedLinkColor (read only)
  • color buttonHoverColor (read only)
  • color buttonFocusColor (read only)
  • color viewTextColor (read only)
  • color viewBackgroundColor (read only)
  • color viewHoverColor (read only)
  • color viewFocusColor (read only)
  • String styleSheet (read only)
  • Font defaultFont (read only)
  • Font desktopFont (read only)
  • Font smallestFont (read only)
  • int smallIconSize (read only)
  • int smallMediumIconSize (read only)
  • int mediumIconSize (read only)
  • int largeIconSize (read only)
  • int hugeIconSize (read only)
  • int enormousIconSize (read only)
  • int defaultIconSize (read only)

Each Font element has the following properties:

  • bool bold
  • Capitalization capitalization (MixedCase, AllUppercase, AllLowercase, SmallCaps, Capitalize) (read only)
  • String family (read only)
  • bool italic (read only)
  • real letterSpacing (read only)
  • int pixelSize (read only)
  • real pointSize (read only)
  • bool strikeout (read only)
  • bool underline (read only)
  • Weight weight (Light, Normal, DemiBold, Bold, Black) (read only)
  • real wordSpacing (read only)
  • size mSize the size, width and height of an uppercase "M" in this font (read only)

Theme is also used to control icon sizes, with the property iconSizes. it is an Object, that has the following properties:

  • int desktop: size of icons suited for the workspace
  • int toolbar: icons to be put in a ToolBar component
  • int small: smallest size for still "readable" icons
  • int dialog: icons to be put in popup dialogs

Svg

Declaring a Svg element instantiates a Plasma Svg instance. This class doesn't draw anything. For drawing, SvgItem is used. Properties:

  • QSize size
  • bool multipleImages
  • String imagePath can be anything in the desktoptheme/ folder. For more information on what is available, see Plasma Theme Elements. Make sure to strip the final extension from this string, so you should for example use "dialogs/background" to get the standard background.
  • bool usingRenderingCache

Methods:

  • QPixmap pixmap(QString elementID)
  • void resize(qreal width, qreal height)
  • void resize(): resets the image to its default dimension
  • QSize elementSize(QString elementId)
  • QRectF elementRect(QString elementId)
  • bool hasElement(QString elementId)
  • bool isValid(): true if valid svg file

FrameSvg

Declaring a FrameSvg element instantiates a Plasma FrameSvg instance. This class doesn't draw anything. For drawing, FrameSvgItem is used. This is to be used when you need informations about the framesvg, such as hasElementPrefix().

Properties:

  • All properties from Svg
  • EnabledBorders enabledBorders: flag combination of:
    • NoBorder
    • TopBorder
    • BottomBorder
    • LeftBorder
    • RightBorder

Methods:

  • All methods from Svg
  • void setImagePath(QString path)
  • void resizeFrame(QSize size)
  • QSize frameSize()
  • qreal marginSize(Plasma::MarginEdge edge)
  • void getMargins(qreal left, qreal top, qreal right, qreal bottom): parameters are output, they get set with the margins from the FrameSvg
  • QRectF contentsRect(): the rectangle of the center element, taking the margins into account.
  • void setElementPrefix(QString prefix)
  • bool hasElementPrefix(const QString prefix)
  • QString prefix()
  • void setCacheAllRenderedFrames(bool cache)
  • bool cacheAllRenderedFrames()
  • void clearCache()
  • QPixmap framePixmap()


Sample Code:

    PlasmaCore.FrameSvg {
        id: myFrameSvg
        imagePath: "widgets/button"
        prefix: "pressed"
    }

SvgItem

It's a graphical element that will actually paint a Svg instance. Properties:

  • String elementId: what element to render. If null, the whole svg will be rendered
  • Svg svg: instance of the Svg class mentioned above
  • QSizeF naturalSize (read only): default size of the Svg
  • bool smooth: paint with antialias (default false)

Sample Code:

    PlasmaCore.SvgItem {
        id: mySvgItem
        anchors {
            top: parent.top
            left: parent.left
        }

        width: 300
        height: 3

        svg: mySvg
        elementId: "horizontal-line"
    }

FrameSvgItem

It's a graphical element that paints a Plasma::FrameSvg, so a rectangular image composed by 9 elements contained in a Svg file, useful for things like buttons and frames.

Flags

  • EnabledBorders: combination of TopBorder | BottomBorder | LeftBorder | RightBorder, NoBorder if no border of the frame is enabled

Properties:

  • String imagePath: path of the file relative to the Plasma Theme, for instance "widgets/background"
  • String prefix: a FrameSvg can contain multiple frames, for instance a button contains "normal", "raised" and "pressed"
  • Margins margins (read only): the margins of the frame, see documentation below
  • EnabledBorders enabledBorders: what borders are enabled

Margins

Properties:

  • real left (read only)
  • real top (read only)
  • real right (read only)
  • real bottom (read only)

Sample Code:

PlasmaCore.FrameSvgItem {
    id: myFrameSvgItem
    anchors.fill: parent
    imagePath: "translucent/dialogs/background"
}

Top Level windows

Dialog

Dialog instantiates a Plasma::Dialog, it will be a Plasma themed top level window that can contain any QML component.

Properties:

  • Item mainItem: the Item contained in the Dialog, it can be any QML Item instance
  • bool visible: if the window (not the mainItem) is visible
  • int x: x position of the window in screen coordinates
  • int y: y position of the window in screen coordinates
  • int width (read only): total width of the dialog, including margins
  • int height (read only): total height of the dialog, including margins.
  • int windowFlags: Qt window flags of the Dialog
  • Margins margins (read only): margins of the Dialog
Note
The width and height will scale with size of the main item within this Dialog component.


import QtQuick 1.1
import org.kde.plasma.core 0.1 as PlasmaCore

Item {
    PlasmaCore.Dialog {
        visible: true
        mainItem: Item {
            width: 500
            height: 500

            Text {
                anchors.centerIn: parent
                color: "red"
                text: qsTr("text")
            }
        }
    }
}

Methods:

  • QPoint popupPosition(Item item, Qt::Alignment alignment=Qt::AlignLeft): the suggested position for the Dialog if it has to be correctly placed as popup of the QML item passed as parameter.
  • void setAttribute(Qt::WindowAttribute attribute, bool on): set an attribute for the dialog window

Margins

Properties:

  • real left (read only)
  • real top (read only)
  • real right (read only)
  • real bottom (read only)

ToolTip

Declaring a ToolTip instance makes it possible to use Plasma tooltips with any QML item.

Properties:

  • Item target: the QML item we want to show a tooltip of
  • String mainText
  • String subText
  • String image: freedesktop compliant icon name as image of the tooltip

Containments

A Plasma Containment manages the position and manipulation of Plasmoids. The declarative containment is responsible for layout of applets and can provide custom applet handles. The containment should listen to the plasmoid.immutability property. In order to lay out applets in your containment, you can use the AppletContainer class to access geometry information of applets. Actions such as configure and close are available through plasmoid.actions. You can access the plasmoid global property from containments in the same way as from declarative and javascript plasmoids. If the plasmoid is a Containment, you can get a list of actions for it. If you want to provide background rendering in your Containment yourself, read the applet.backgroundHints property and after that set applet.backgroundHints to 0 to tell the Applet that is should not render the background.

AppletContainer

The AppletContainer class provides access to the geometry and status of Plasmoids in this Containment. Properties:

  • Item applet: The applet item, this property allows you to track destruction of the actual applet and update your layout.
    • int backgroundHints: Should the Applet be rendered on top of a background frame? 0 for no background, 1 for default background, 2 for translucent background
  • int minimumWidth: The minimum width of the applet
  • int minimumHeight: The minimum height of the applet
  • int maximumWidth: The maximum width of the applet
  • int maximumHeight: The maximum height of the applet
  • int preferredWidth: The preferred height of the applet
  • int preferredHeight: The preferred height of the applet
  • enum status: The status of the applet, one in the enum
    • UnknownStatus: The status is unknown
    • PassiveStatus: The applet is passive
    • ActiveStatus: The applet is active
    • NeedsAttentionStatus: The applet asks for attention
    • AcceptingInputStatus: The applet is accepting input


They can be imported in your code with:

import org.kde.plasma.containments 0.1 as PlasmaContainments


AppletContainer is only available for Plasma/Containment packages, and only if they are loaded as containment. AppletContainer is new in 4.10.

ToolBox

The ToolBox is only available through the plasmoid object, through plasmoid.toolBox(). The ToolBox is rendered as a separate item on top of the scene covering the entire containment. It is loaded from the "org.kde.toolbox" Plasma Package, if the package is not found, no ToolBox will be loaded. The ToolBox provides a listmodel of actions that can be rendered using Repeaters or ListViews. The actions list property contains actions from the Corona and Containments. Examples for these actions are showing the add widget or activities interface, lock and unlock. The actions in the list change dynamically whenever the widgets are locked or unlocked. Actions such as lock screen and leave can be implemented using the powermanagement dataengine's services for these functions.

ToolBox provides access to the following properties:

  • Array(QAction) actions: A list of actions provided by the Containment. These actions' most interesting properties are:
    • QIcon icon: The icon belonging to this action.
    • String text: The icon belonging to this action.
    • trigger(): Call trigger from your action delegate to trigger the action.


import org.kde.plasma.containments 0.1 as PlasmaContainments


ToolBox is only available for Containments and new in 4.10.

Plasma QtComponents (4.8)

Plasma components documentation online at api.kde.org

QtExtraComponents

The QtExtraComponents make some very convenient Qt classes usable from within QML.

They can be imported in your code with:

import org.kde.qtextracomponents 0.1

QPixmapItem

This one wraps around a QPixmap class and allows you to send a QPixmap directly to QPixmapItem.

Properties:

  • QPixmap pixmap: The QPixmap object.
  • bool smooth: Set to true to render smooth.
  • int nativeWidth: (verification needed) The QPixmap width
  • int nativeHeight: (verification needed) The QPixmap height
  • FillMode fillMode: see below

QImageItem

This one wraps around a QImage class and allows you to send a QImage directly to QImageItem.

Properties:

  • QImage image: The QImage object.
  • bool smooth: Set to true to render smooth.
  • int nativeWidth: (verification needed) The QImage width
  • int nativeHeight: (verification needed) The QImage height
  • FillMode fillMode: see below

FillMode

Both QPixmapItem and QImageItem expose a FillMode enum. This enum defines how the image is going to be used to fill the item.

For QPixmapItem, possible values are:

  • QPixmapItem.Stretch: the image is scaled to fit
  • QPixmapItem.PreserveAspectFit: the image is scaled uniformly to fit without cropping
  • QPixmapItem.PreserveAspectCrop: the image is scaled uniformly to fill, cropping if necessary
  • QPixmapItem.Tile: the image is duplicated horizontally and vertically
  • QPixmapItem.TileVertically: the image is stretched horizontally and tiled vertically
  • QPixmapItem.TileHorizontally : the image is stretched vertically and tiled horizontally

QImageItem defines the same values, you just need to replace QPixmapItem with QImageItem.

QIconItem

This one wraps around a QPixmap class and allows you to send a QIcon directly to QIconItem.

Properties:

  • QIcon/QString icon: If you provide a QIcon it uses that directly. If you provide a string it uses a KIcon internally!
  • bool smooth: Set to true to render smooth.
  • int implicitWidth: Default width of as set in SystemSettings->Applications Appearance->Icons
  • int implicitHeight: Default height of as set in SystemSettings->Applications Appearance->Icons
  • State state: Icon state (DefaultState, ActiveState, DisabledState)