KDE System Administration/PlasmaDesktopScripting: Difference between revisions

    From KDE UserBase Wiki
    m (Fix typo in example code)
    m (Fix typo showConfigurationInteface => showConfigurationInterface)
    (16 intermediate revisions by 6 users not shown)
    Line 8: Line 8:
    == Examples ==
    == Examples ==


    A set of examples can be found [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting here] that demonstrate the use of various aspects of Plasma shell scripting.
    Visit [[KDE_System_Administration/PlasmaDesktopScripting/Examples]] for more examples. Here's a couple highlights:


    Contributions of additional examples are welcome and an be sent to the Plasma development mailing list (plasma-devel at kde.org) for inclusion if you do not have commit rights to the kdeexamples module.
    === Advanced example: Adding a widget to the System Tray ===
    <syntaxhighlight lang="javascript">
    var widgetName = "org.kde.plasma.printmanager";
     
    for (i = 0; i < panelIds.length; ++i) { //search through the panels
        panel = panelById(pids[i]);
        if (!panel) continue;
     
        for (tmpIndex = 0; tmpIndex < panel.widgetIds.length; tmpIndex ++) {
            appletWidget = panel.widgetById(panel.widgetIds[tmpIndex]);
     
            if (appletWidget.type == "org.kde.plasma.systemtray") {
                systemtrayId = appletWidget.readConfig("SystrayContainmentId");
                if (systemtrayId) {
                  print("systemtray id: " + systemtrayId)
                  var systray = desktopById(systemtrayId);
                  systray.currentConfigGroup = ["General"];
                  var extraItems = systray.readConfig("extraItems").split(",");
                  if (extraItems.indexOf(widgetName) === -1) {
                      extraItems.push(widgetName)
                      systray.writeConfig("extraItems", extraItems);
                      systray.reloadConfig();
                  }
                }         
            }
        }
    }
    </syntaxhighlight>


    == Running Scripts ==
    == Running Scripts ==
    Line 25: Line 52:
    with a ".js" suffix for scripts that have not yet been run. If there is more than one script which has not been run yet they will be executed serially in the alphabetical order of the file names.
    with a ".js" suffix for scripts that have not yet been run. If there is more than one script which has not been run yet they will be executed serially in the alphabetical order of the file names.


    A record of which update scripts have been run is kept in the application's config file in the [Updates] group. This means that if the plasma-desktop configuraiton file is removed, all the update scripts will be run again.
    A record of which update scripts have been run is kept in the application's config file in the [Updates] group. This means that if the plasma-desktop configuration file is removed, all the update scripts will be run again.


    {{note|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}
    {{note|For security reasons, scripts located in the user's home directory will '''not''' be run during this phase.}}


    * '''interactively''': an interactive scripting dialog can be requested either via the KRunner window (Alt+F2, by default, or via the "Run Command" entry in various desktop menus) by entering "desktop console" as the search term. It can also be triggered directly via dbus with <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight>
    * '''interactively''': an interactive scripting dialog can be requested either via the KRunner window (Alt+F2, by default, or via the "Run Command" entry in various desktop menus) by entering "desktop console" as the search term. It can also be triggered directly via dbus with <syntaxhighlight lang="bash">qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole</syntaxhighlight> In Plasma 5 use <syntaxhighlight lang="bash">qdbus org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.showInteractiveConsole</syntaxhighlight>
     


    {{note|This method is not available for plasma-netbook.}}
    {{note|This method is not available for plasma-netbook.}}
    Line 75: Line 103:


    ==== Creating panels ====
    ==== Creating panels ====
    A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on first start. There is a Template called org.kde.plasma-desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and, because it is marked as a Panel Template in the metadata.desktop file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.
    A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on the first start. There is a Template called org.kde.plasma-desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and because it is marked as a Panel Template in the metadata.desktop file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.


    ==== Automating tasks ====
    ==== Automating tasks ====
    Line 140: Line 168:
    Update javascript scripts can be added per-shell at the location  
    Update javascript scripts can be added per-shell at the location  
       share/plasma/shells/org.kde.plasma.desktop/updates/
       share/plasma/shells/org.kde.plasma.desktop/updates/
    The API available from those config files is the same available from the normal init.js file. from there is possible to add or remove applets or modifiy config values.
    The API available from those config files is the same available from the normal init.js file. from there is possible to add or remove applets or modify config values.


    == Look and Feel dependent default setup for applets ==
    == Look and Feel dependent default setup for applets ==
    Line 164: Line 192:


    === Activities and desktops===
    === Activities and desktops===
    '''Desktop''' are the desktop layer in a plasma-desktop session and may contain widgts. In sightly more technical terms, they are desktop containments. Activities can be created, enumerated, modified and destroyed.
    '''Desktop''' are the desktop layer in a plasma-desktop session and may contain widgets. In slightly more technical terms, they are desktop containments. Activities can be created, enumerated, modified and destroyed.


    New Activities can be created using the '''newActivity''' function, like this:
    New Activities can be created using the '''newActivity''' function, like this:
    Line 187: Line 215:


    === Panels ===
    === Panels ===
    Panels can be created, enumerated, modified and destroyed. A panel object combines both a containment as well as the container itself, allowing for full control of things such as where it appears on screen and the hiding features associated with them.
    Panels can be created, enumerated, modified and destroyed. A panel object combines both a containment as well as the container itself, allowing for full control of things such as where it appears on the screen and the hiding features associated with them.


    New Panels can be created using the Panel constructor, like this:
    New Panels can be created using the Panel constructor, like this:
    Line 232: Line 260:
    * ''Widget'' '''addWidget(String name)''': adds a new widget to the activity; the name maps to the <tt>X-KDE-PluginInfo-Name=</tt> entry in the widget's .desktop file
    * ''Widget'' '''addWidget(String name)''': adds a new widget to the activity; the name maps to the <tt>X-KDE-PluginInfo-Name=</tt> entry in the widget's .desktop file
    * ''Widget'' '''addWidget(Widget widget)''': adds an existing widget to this activity; useful for moving widgets between Activities and Panels
    * ''Widget'' '''addWidget(Widget widget)''': adds an existing widget to this activity; useful for moving widgets between Activities and Panels
    * '''showConfigurationInteface()''': shows the configuration user interface for this Activity or Panel on the screen
    * '''showConfigurationInterface()''': shows the configuration user interface for this Activity or Panel on the screen
    * '''readConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the config with default for the default value
    * '''readConfig(String key, any default)''': (scriptingVersion >= 2) reads the value of key in the config with default for the default value
    * '''writeConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the config
    * '''writeConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the config
    Line 251: Line 279:


    === Widgets ===
    === Widgets ===
    Widgets may be enumerated by calling the widgetIds property on a Activity or Panel object. With a widget id in hand, a Widget object can be retrieved by calling widgetById(id) on an Activity or Panel object. New Widgets can be created with add addWidget(String) function provided by Activity and Panel objects.
    Widgets may be enumerated by calling the widgetIds property on an Activity or Panel object. With a widget id in hand, a Widget object can be retrieved by calling widgetById(id) on an Activity or Panel object. New Widgets can be created with add addWidget(String) function provided by Activity and Panel objects.


    ==== Checking if a widget is installed ====
    ==== Checking if a widget is installed ====
    Line 295: Line 323:
    * '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config
    * '''writeGlobalConfig(String key, any value)''': (scriptingVersion >= 2) sets key to value in the global config
    * '''reloadConfig()''': causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
    * '''reloadConfig()''': causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
    * '''showConfigurationInteface()''': shows the configuration user interface for this widget on the screen
    * '''showConfigurationInterface()''': shows the configuration user interface for this widget on the screen


    === Screen Geometry ===
    === Screen Geometry ===
    Line 379: Line 407:


    ConfigFile has the following read/write properties:
    ConfigFile has the following read/write properties:
    * ''file'': the name of the configuration file. May be an absolute path or just a file name to be located automatically in the system's configuration repository.
    * ''file'': the name of the configuration file. Maybe an absolute path or just a file name to be located automatically in the system's configuration repository.
    * ''group'': the name of the current group. To get to child groups, create a new ConfigFile with another ConfigFile as its parent.
    * ''group'': the name of the current group. To get to child groups, create a new ConfigFile with another ConfigFile as its parent.


    Line 412: Line 440:


    Functions:
    Functions:
    * '''sleep(number ms)''': sleeps the script for the specified number of millseconds
    * '''sleep(number ms)''': sleeps the script for the specified number of milliseconds


    === QRectF ===
    === QRectF ===
    Line 451: Line 479:


    == Configuration Keys ==
    == Configuration Keys ==
    Here you find a list of commonly used configuration keys to use with the '''writeConfig''' command. Where the documentation notes that a key is in a subgroup, remember to first use '''currentConfigGroup'''.
    Here you find a list of commonly used configuration keys to use with the '''writeConfig''' command. Where the documentation notes that a key is in a subgroup other than General, remember to first use '''currentConfigGroup'''.
     
    === Common configuration keys ===
    Here are some keys that can be used with all widgets:
     
    * '''Share''' (true/false): Whether or not the widget is to be announces throughout the network (Share tab)
     
    === Common time and date keys ===
    Most of the settings listed below apply to all widgets dealing with date and time (clock, digital-clock, binary-clock, …)
    Settings for individual plasmoids can be found in their respective category and usually only affect the plasmoid’s appearance.
    * '''announceInterval''' (number ≥ 0): Interval in minutes that the time is read out loud
    * '''calendarType''' (local/coptic/ethopian/gregorian/gregorian-proleptic/hebrew/hijri/indian-national/jalali/japanese/julian/minguo/thai): Calendar system to be used, defaults to local
    * '''defaultTimezone''' (Local/…): Time zone to be used
    * '''displayHolidays''' (true/false): Whether holidays are to be displayed
    * '''holidayRegions''' (tbd): tbd
    * '''holidayRegionaDaysOff''' (tbd): tbd
    * '''timeZones''' (Europe/Andorra,…): Comma-separated list of timezones to be used (e. g. Europe/Andorra,Indian/Antananarivo,Asia/Aqtau)
     
    === Analog clock (clock) ===
    * '''showSecondHand''' (true/false): self-explanatory
    * '''showTimezoneString''' (true/false): self-explanatory
     
    === Battery status (battery) ===
    * '''showBatteryString''' (true/false): Whether or not battery status is shown as overlay for the battery icon (if in systemtray or panel)
    * '''showMultipleBatteries''' (true/false): Whether or not battery status is shown for each battery separately
     
    === Digital clock (digital-clock) ===
    * '''plainClockColor''' (rrr,ggg,bbb): Color set for clock font (e. g. 192,0,0 - to be used with useCustomColor=true!)
    * '''plainClockDrawShadow''' (true/false): Whether a shadow is to bed drawn (defaults to true)
    * '''plainClockShadowColor''' (rrr,ggg,bbb): Color set for clock shadow (e. g. 64,97,128 - to be used with useCustomShadowColor=true!)
    * '''plainClockFont''' (tbd): Font to be used for clock (e. g. Serif,12,-1,5,75,0,0,0,0,0)
    * '''showDate''' (true/false): self-explanatory
    * '''showDay''' (true/false): self-explanatory
    * '''showSeconds''' (true/false): self-explanatory
    * '''showTimezone''' (true/false): self-explanatory
    * '''showYear''' (true/false): self-explanatory
    * '''useCustomColor''' (true/false): Whether or not a custom color is to be used (use with plainClockColor=rrr,ggg,bbb!)
    * '''useCustomShadowColor''' (true/false): Whether or not a custom shadow color is to be used (use with plainClockShadowColor=rrr,ggg,bbb!)
     
    === Folderview (folderview) ===
    * '''alignToGrid''' (true/false): self-explanatory
    * '''customIconSize''' (16/22/24/32/48/…): Use custom icon size for files/folders (use only default/common icon sizes, powers of 2)
    * '''customLabel''': Use custom title rather than default path or place name
    * '''drawShadows''' (true/false): Whether or not file labels are to draw shadows
    * '''filter''' (0/1/2): Defines whether a filter is to be used or not (0 = No filter, 1 = Show only matching files, 2 = Hide matching files)
    * '''filterFiles''': Wildcard filter to filter file names
    * '''mimeFilter''': Comma-separated list of mimetypes to be filtered (shown/hidden depends on filter-setting)
    * '''iconsLocked''' (true/false): Whether or not icons can be moved
    * '''numTextLines''' (number > 0): Amount of lines a file name can have before it is truncated
    * '''url''': Folder URL to be displayed (e. g. desktop:/// or file:///home/yourusername)
    * '''sortColumn''' (-1/0/1/2/3/4/5): The way files and folders are sorted (-1 = No sorting, 0 = By name, 1 = By size, 2 = By type, 3 = By date)
    * '''sortDirsFirst''' (true/false): Whether or not folders are displayed before files (defaults to true)
    * '''textColor''' (rrr,ggg,bbb): Color the icon labels will have
     
    === Kickoff menu (launcher) ===
    * '''SwitchTabsOnHover''' (true/false): self-explanatory
    * '''ShowAppsByName''' (true/false): Apps are sorted by name rather than by description
     
    === Pager (pager) ===
    * '''displayedText''' (0/1/2): Text to be shown on individual virtual desktops (0 = Workspace number, 1 = Workspace title, 2 = None)
    * '''ShowWindowIcons''' (true/false): Whether or not the application icon is to be shown on each individual window
    * '''currentDesktopSelected''' (0/1/2): Defines what should happen if the user clicks on the virtual desktop that is currently active (0 = Nothing, 1 = Show Workspace, i. e. minimize windows, 2 = Show Dashboard)
    * '''rows''' (number > 0): Amount of rows the pager should have. (Note: ''This is a global option, so you need to use '''writeGlobalConfig''' instead'')
     
    === Notifications (notifications) ===
    {{note|This applet is likely to be embedded to system tray. For Systrem Tray specific tasks, i. e. how to add, manage and remove plasmoids inside it, see sections below}}
    * '''AutoHidePopup''' (true/false): Whether or not popups are to be hidden automatiaclly
    * '''ShowJobs''' (true/false): Whether or not jobs are to be shown (e. g. file transfer progress)
    * '''ShowNotifications''' (true/false): Whether or not notifications are to be shown
     
    === Removable media notifier (notifier) ===
    * '''ShowDevices''' (0/1/2): Defines what kind of devices are to be shown (0 = Removable media only, 1 = Non-removable media only, 2 = All)
    {{note|Auto-mount settings and device actions are not stored in this Plasmoid’s settings.}}
     
    === Taskbar (tasks) ===
    * '''groupingStrategy''' (0/1/2): Defines how taskbar entries are to be grouped (0 = Never, 1 = Manually, 2 = By Program Name)
    * '''groupWhenFull''' (true/false): Only group when taskbar is full (to be used with groupingStrategy=2 only!)
    * '''highlightWindows''' (true/false): Highlight a window if your mouse cursor is hovering its taskbar entry (requires Desktop Compositing and “Highlight windows” effect enabled to work)
    * '''maxRows''' (number > 0): Amount of rows taskbar entries can take
    * '''forceRows''' (true/false): Force row setting for taskbar entries
    * '''showOnlyCurrentActivity''' (true/false): Show only windows from current activity
    * '''showOnlyCurrentDesktop''' (true/false): Show only windows from current virtual desktop
    * '''showOnlyCurrentScreen''' (true/false): Show only windows from current screen (multi monitor setup)
    * '''showTooltip''' (true/false): Whether or not tooltips are to be shown
    * '''sortingStrategy''' (0/1/2/3): How taskbar entries are to be sorted (0 = Never, 1 = Manually, 2 = Alphabetically, 3 = By Desktop)
     
    === System Tray ===
    The System Tray has some unique behaviors since it can host widgets and configuring it is not as easy as most other widgets, particularly when adding and removing widgets. This section will help you deal with its specific behavior.
     
    ==== Generic System Tray configuration keys ====
    * '''DefaultAppletAdded''' (true/false): Remembers whether the default plasmoids (networkmanagement, device manager, notifications) have already been added(??)
    * '''ShowApplicationStatus''' (true/false): Show system tray icons of applications that belong to the group “Applications”
    * '''ShowCommunications''' (true/false): Show system tray icons of applications that belong to the group “Applications” (i. e. Messenger, IRC chat)
    * '''ShowHardware''' (true/false): Show system tray icons of applications that belong to the group “Hardware” (i. e. volume control, printer applet)
    * '''ShowSystemServices''' (true/false): Show system tray icons of applications that belong to the group “System Services” (i. e. Nepomuk Indexing Agent)
    * '''ShowUnknown''' (true/false): Show system tray icons that do not belong into one of the categories mentioned above (or that do not use KDE’s system tray protocol and thus do not provide such information)
    * '''alwaysShown''': Comma-separated list of widgets and entries that are to be shown all the time (e. g. KMix,notifier)
    * '''hidden''': Comma-separated list of widgets and entries that are to be hidden all the time (e. g. Nepomuk Indexing Agent,Klipper,kmail)
    {{note|Although notifications appear to be part of the System Tray, they are handled by a separate plasmoid which is embedded to the system tray. For its configuration keys, see section above}}
     
    ==== Add a widget to systemtray ====
    You can not add widgets to the systemtray in a similar way like you would add them to a panel or containment using addWidget. Instead, to add, manage and remove them, you need to utilize writeConfig changing the currentConfigGroup.
    <syntaxhighlight lang="cpp-qt">
    systray = panel.addWidget("systemtray") // First add a systemtray to your panel
    systray.currentConfigGroup = Array("Applets","0") // then change the currentConfig Group
     
    // to the subnode [Applets][0]. Use any number you like(?)
    </syntaxhighlight>
     
    Now you can “create” the plasmoid by adding a “plugin” configuration entry
    <syntaxhighlight lang="cpp-qt">
    systray.writeConfig("plugin","notifier") // This will add a Device Notifier Plasmoid
    </syntaxhighlight>
    You can modify the plasmoid’s configuration by using writeConfig.
    <syntaxhighlight lang="cpp-qt">
    systray.writeConfig("property","value")
    </syntaxhighlight>
    To change back to the top configuration level and thus edit the systemtray plasmoid itself pass an empty array to currentConfigGroup.
     
    ==== Edit existing widgets in systemtray ====
     
    ==== Remove a widget from systemtray ====


    To remove a widget, delete the corresponding configuration group.
    ===org.kde.desktopcontainment===
    ======General======
    * '''icon''' (''String'', default ''folder'') The name of the custom icon to use for the compact representation (e.g. on a small panel) of the Folder View applet. Only used if useCustomIcon is true.
    * '''useCustomIcon''' (''Bool'', default ''false'') Whether to use a custom icon for the compact representation (e.g. on a small panel) of the Folder View Applet.
    * '''ToolBoxButtonState''' (''String'', default ''topleft'') Position state of the toolbox button.
    * '''ToolBoxButtonX''' (''int'', default ''null'') X coordinate of the toolbox.
    * '''ToolBoxButtonY''' (''int'', default ''null'') Y coordinate of the toolbox.
    * '''url''' (''String'', default ''desktop:/'') URL of the file system location being shown.
    * '''labelMode''' (''Int'', default ''1'') How to show the Folder View label: 0 = No label, 1 = Friendly version of path relative to closest Places entry, 2 = Full path, 3 = Custom title
    * '''labelText''' (''String'', default ''empty string'') Custom text for the Folder View label. Only used if labelMode is 3.
    * '''arrangement''' (''Int'', default ''0'') How Folder View icons are arranged: 0 = Rows, 1 = Columns
    * '''alignment''' (''Int'', default ''0'') How Folder View icons are aligned: 0 = Left, 1 = Right
    * '''locked''' (''Bool'', default ''false'') Whether Folder View icons are locked or not. Only used when serving as containment.
    * '''sortMode''' (''Int'', default ''0'') How Folder View icons are sorted: 0 = Unsorted, 1 = Name, 2 = Size, 3 = Type, 4 = Date
    * '''sortDesc''' (''Bool'', default ''false'') Whether to sort Folder View icons descending instead of ascending.
    * '''sortDirsFirst''' (''Bool'', default ''true'') Whether to sort folders before files in Folder View.
    * '''toolTips''' (''Bool'', default ''false'') Whether to show info tooltips when hovering Folder View icons.
    * '''selectionMarkers''' (''Bool'', default ''true'') Whether to show selection markers when hovering Folder View icons.
    * '''popups''' (''Bool'', default ''true'') Whether to show a popup preview window for Folder View icons for folders.
    * '''previews''' (''Bool'', default ''true'') Whether to show preview thumbnails in Folder View.
    * '''previewPlugins''' (''StringList'', default ''imagethumbnail,jpegthumbnail'') List of id's of the thumbnail preview plugins to use in Folder View.
    * '''viewMode''' (''Int'', default ''0'') The Folder View view mode (used only by the widget full represntation): 0 = Grid, 1 = List
    * '''iconSize''' (''Int'', default ''4'') The icon size to use for Folder View icons. One of the list of Plasma icon sizes.
    * '''textLines''' (''Int'', default ''2'') The (maximum) number of lines of text to use below Folder View icons.
    * '''textColor''' (''String'', default ''white'') The text color to use below Folder View icons. Only used when serving as containment.
    * '''iconHoverEffect''' (''Bool'', default ''true'') Whether icons should change in appearance when the mouse pointer is above them.
    * '''filterPattern''' (''String'', default ''*'') The pattern to filter files by. Supports wildcards.
    * '''filterMode''' (''Int'', default ''0'') The file filter mode: 0 = Show All Files, 1 = Show Files Matching, 2 = Hide Files Matching
    * '''filterMimeTypes''' (''StringList'', default ''all/all'') List of MIME types to filter by.
    * '''showTweaks''' (''Bool'', default ''true'') Whether to show the "Tweaks" config page. Only used when serving as containment.
    * '''showToolbox''' (''Bool'', default ''true'') Whether to show the Desktop Toolbox. Only used when serving as containment.
    * '''pressToMove''' (''Bool'', default ''true'') Whether to activate widget handles and widget move mode by long press. Only used when serving as containment.
    * '''pressToMoveHelp''' (''Bool'', default ''true'') Whether to show an info notification about pressToMove mode after enabling it or when the containment becomes mutable (i.e. widgets are unlocked).
    ===org.kde.ktp-chat===
    ======General======
    * '''pinnedContacts''' (''StringList'', default ''empty list'')
    ===org.kde.mediacentercontainment===
    ======General======
    * '''AppletOrder''' (''String'', default ''empty string'') encoded order of items
    ===org.kde.panel===
    ======General======
    * '''AppletOrder''' (''String'', default ''empty string'') encoded order of items
    ===org.kde.person===
    ======General======
    * '''personUri''' (''String'', default ''empty string'')
    ===org.kde.phone.homescreen===
    ======General======
    * '''AppletOrder''' (''String'', default ''empty string'') encoded order of items
    * '''AppOrder''' (''StringList'', default ''org.kde.phone.dialer.desktop'') order of apps
    ===org.kde.phone.panel===
    ======General======
    * '''AppletOrder''' (''String'', default ''empty string'') encoded order of items
    ===org.kde.phone.taskpanel===
    ======General======
    * '''PanelButtonsVisible''' (''Bool'', default ''true'') panel chrome visible
    ===org.kde.plasma.analogclock===
    ======General======
    * '''showSecondHand''' (''Bool'', default ''false'')
    * '''showTimezoneString''' (''Bool'', default ''false'')
    ===org.kde.plasma.appmenu===
    ======Appearance======
    * '''compactView''' (''Bool'', default ''false'') If true it only shows a button for the application menu.
    ===org.kde.plasma.battery===
    ======General======
    * '''showPercentage''' (''bool'', default ''false'') If true, the battery will display a little charge percentage label inside.
    ===org.kde.plasma.binaryclock===
    ======General======
    * '''showGrid''' (''Bool'', default ''true'')
    * '''showOffLeds''' (''Bool'', default ''true'')
    * '''showSeconds''' (''Bool'', default ''true'')
    * '''useCustomColorForActive''' (''Bool'', default ''false'')
    * '''customColorForActive''' (''Color'', default ''green'')
    * '''useCustomColorForInactive''' (''Bool'', default ''false'')
    * '''customColorForInactive''' (''Color'', default ''red'')
    * '''useCustomColorForGrid''' (''Bool'', default ''false'')
    * '''customColorForGrid''' (''Color'', default ''blue'')
    ===org.kde.plasma.calendar===
    ======Agenda======
    * '''startOfWorkingDay''' (''int'', default ''9'')
    * '''endOfWorkingDay''' (''int'', default ''17'')
    * '''showWeekNumbers''' (''Bool'', default ''false'')
    * '''compactDisplay''' (''String'', default ''d'')
    ===org.kde.plasma.colorpicker===
    ======General======
    * '''history''' (''StringList'', default ''empty list'')
    * '''autoClipboard''' (''Bool'', default ''true'')
    * '''defaultFormat''' (''String'', default ''#RRGGBB'')
    * '''pickOnActivate''' (''Bool'', default ''true'')
    ===org.kde.plasma.devicenotifier===
    ======General======
    * '''removableDevices''' (''Bool'', default ''true'') If true it lists removable devices, such as USB thumbdrives. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    * '''nonRemovableDevices''' (''Bool'', default ''false'') If true it lists non removable devices, such as internal harddrives. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    * '''allDevices''' (''Bool'', default ''false'') If true it lists all kind of devices. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    * '''popupOnNewDevice''' (''Bool'', default ''true'') If true it tries to open the plasmoid when a new device is inserted, as a kind of notification.
    ===org.kde.plasma.digitalclock===
    ======Appearance======
    * '''showLocalTimezone''' (''Bool'', default ''false'') Whether the timezone should be displayed when the clock is showing the local timezone.
    * '''showSeconds''' (''Bool'', default ''false'') Whether seconds should be shown in the clock.
    * '''showDate''' (''Bool'', default ''false'') Whether the date should be shown next to the clock.
    * '''dateFormat''' (''string'', default ''shortDate'') The date format to display. Options are: shortDate, longDate or isoDate.
    * '''fontFamily''' (''string'', default ''null'') Font family. e.g "arial". The system font is used if this is not set.
    * '''boldText''' (''Bool'', default ''false'') Sets the font to bold.
    * '''italicText''' (''Bool'', default ''false'') Sets the font to italic.
    * '''timeFormat''' (''string'', default ''default'')
    * '''selectedTimeZones''' (''StringList'', default ''Local'') A list of the time zones available on mouse wheel. Requires wheelChangesTimezone to be true. Format is "Europe/London". Special entry "Local" indicates system time zone.
    * '''lastSelectedTimezone''' (''String'', default ''Local'') When multiple time zones are configured, this is the one shown on widget restore.
    * '''wheelChangesTimezone''' (''Bool'', default ''false'') Whether the mouse wheel switches between the timezones configured in selectedTimeZones.
    * '''displayTimezoneAsCode''' (''Bool'', default ''true'') Whether the timezone is displayed as a code i.e. "GMT" or full text i.e. "London".
    * '''showWeekNumbers''' (''Bool'', default ''false'') Whether the calendar should show week numbers.
    * '''use24hFormat''' (''UInt'', default ''1'') Force the clock to use 12/24 hour time, instead of following the user locale.
    * '''enabledCalendarPlugins''' (''StringList'', default ''empty list'') A list of plugins where additional calendar event data can be sourced.
    * '''pin''' (''Bool'', default ''false'') Whether the popup should remain open when another window is activated
    ===org.kde.plasma.fifteenpuzzle===
    ======Appearance======
    * '''imagePath''' (''String'', default ''empty string'')
    * '''useImage''' (''Bool'', default ''false'')
    * '''showNumerals''' (''Bool'', default ''true'')
    * '''boardColor''' (''Color'', default ''#333333'')
    * '''numberColor''' (''Color'', default ''#ffffff'')
    * '''boardSize''' (''Int'', default ''4'')
    ===org.kde.plasma.fuzzyclock===
    ======Appearance======
    * '''fuzzyness''' (''Int'', default ''1'')
    * '''boldText''' (''Bool'', default ''false'')
    * '''italicText''' (''Bool'', default ''false'')
    ===org.kde.plasma.icon===
    ======General======
    * '''url''' (''String'', default ''empty string'')
    * '''localPath''' (''String'', default ''empty string'')
    ===org.kde.plasma.kicker===
    ======General======
    * '''icon''' (''String'', default ''start-here-kde'') The name of the icon to use for the compact representation (e.g. on a small panel).
    * '''useCustomButtonImage''' (''Bool'', default ''false'') Whether to use a custom image instead of an icon in the compact representation (e.g. on a small panel).
    * '''customButtonImage''' (''Url'', default ''null'') The URL of the custtom image to use instead of an icon in the compact representation (e.g. on a small panel).
    * '''appNameFormat''' (''Int'', default ''0'') The format used in the display of application names: 0 = NameOnly, 1 = GenericNameOnly, 2 = NameAndGenericName, 3 = GenericNameAndName
    * '''limitDepth''' (''Bool'', default ''false'') Whether to flatten top-level menu categories to a single level instead of displaying sub-categories.
    * '''alphaSort''' (''Bool'', default ''false'') Whether to sort menu contents alphabetically or use manual/system sort order.
    * '''recentOrdering''' (''Int'', default ''0'') How should the previously used apps/docs/contacts be ordered: 0 = RecentFirst, 1 = PopularFirst
    * '''favoriteApps''' (''StringList'', default ''preferred://browser,kontact.desktop,systemsettings.desktop,org.kde.dolphin.desktop,ktp-contactlist.desktop,org.kde.kate.desktop,org.kde.discover'') List of general favorites. Supported values are menu id's (usually .desktop file names), special URLs that expand into default applications (e.g. preferred://browser), document URLs and KPeople contact URIs.
    * '''favoriteSystemActions''' (''StringList'', default ''logout,reboot,shutdown'') List of system action favorites.
    * '''favoritesPortedToKAstats''' (''Bool'', default ''false'') Are the favorites ported to use KActivitiesStats to allow per-activity favorites
    * '''hiddenApplications''' (''StringList'', default ''empty list'') List of menu id's (usually .desktop file names) of apps that should not be shown in the menu.
    * '''showRecentApps''' (''Bool'', default ''true'') Whether to show the "Recent Applications" category.
    * '''showRecentDocs''' (''Bool'', default ''true'') Whether to show the "Recent Documents" category.
    * '''showRecentContacts''' (''Bool'', default ''false'') Whether to show the "Recent Contacts" category.
    * '''useExtraRunners''' (''Bool'', default ''true'') Whether to use additional KRunner plugins to produce results in the search.
    * '''extraRunners''' (''StringList'', default ''shell,bookmarks,baloosearch,locations'') The plugin id's of additional KRunner plugins to use. Only used if useExtraRunners is true.
    * '''alignResultsToBottom''' (''Bool'', default ''true'') Whether to align search results to the bottom of the menu representation (e.g. panel popup) instead of the top.
    ===org.kde.plasma.kickoff===
    ======General======
    * '''switchTabsOnHover''' (''Bool'', default ''true'') Whether to switch between menu tabs by hovering them.
    * '''showAppsByName''' (''Bool'', default ''false'') Whether to display specific application names instead of their generic names (e.g. Dolphin instead of File Manager).
    * '''icon''' (''String'', default ''start-here-kde'') The name of the icon used in the compact representation (e.g. on a small panel).
    * '''favorites''' (''StringList'', default ''preferred://browser,kontact.desktop,systemsettings.desktop,org.kde.dolphin.desktop,ktp-contactlist.desktop,org.kde.kate.desktop,org.kde.discover.desktop'') List of general favorites. Supported values are menu id's (usually .desktop file names), special URLs that expand into default applications (e.g. preferred://browser), document URLs and KPeople contact URIs.
    * '''favoritesPortedToKAstats''' (''Bool'', default ''false'') Are the favorites ported to use KActivitiesStats to allow per-activity favorites
    * '''systemApplications''' (''StringList'', default ''systemsettings.desktop,org.kde.kinfocenter.desktop,org.kde.discover.desktop'') List of applications at the top of the "Computer" tab.
    * '''useExtraRunners''' (''Bool'', default ''true'') Whether to use additional KRunner plugins to produce results in the search.
    * '''runners''' (''StringList'', default ''shell,bookmarks,recentdocuments,locations,baloosearch'') The plugin id's of additional KRunner plugins to use. Only used if useExtraRunners is true.
    * '''menuItems''' (''StringList'', default ''bookmark:t,application:t,computer:t,used:t,oftenUsed:f,leave:t'') The menu tabs to show.
    * '''alphaSort''' (''Bool'', default ''false'') Whether to sort menu contents alphabetically or use manual/system sort order.
    ===org.kde.plasma.kimpanel===
    ======Appearance======
    * '''vertical_lookup_table''' (''Bool'', default ''false'')
    * '''use_default_font''' (''Bool'', default ''true'')
    * '''font''' (''Font'', default ''null'')
    * '''hiddenList''' (''StringList'', default ''empty list'')
    ===org.kde.plasma.lock_logout===
    ======General======
    * '''show_requestShutDown''' (''Bool'', default ''true'') Show an option to shut down the system.
    * '''show_lockScreen''' (''Bool'', default ''true'') Show an option to lock the system.
    * '''show_switchUser''' (''Bool'', default ''false'') Show an option to switch user.
    * '''show_suspendToDisk''' (''Bool'', default ''false'') Show an option to suspend the system to disk (hibernate).
    * '''show_suspendToRam''' (''Bool'', default ''false'') Show an option to suspend the system suspend.
    ===org.kde.plasma.mediacontroller===
    ======General======
    * '''pauseWhenScreenLocked''' (''Bool'', default ''false'')
    ===org.kde.plasma.mediaframe===
    ======General======
    * '''interval''' (''Double'', default ''6.8'')
    * '''randomize''' (''Bool'', default ''true'')
    * '''pauseOnMouseOver''' (''Bool'', default ''true'')
    * '''useBackground''' (''Bool'', default ''true'')
    * '''leftClickOpenImage''' (''Bool'', default ''true'')
    * '''showCountdown''' (''Bool'', default ''true'')
    * '''fillMode''' (''int'', default ''1'')
    ======Paths======
    * '''pathList''' (''StringList'', default ''empty list'')
    ===org.kde.plasma.minimizeall===
    ======General======
    * '''icon''' (''String'', default ''user-desktop'')
    ===org.kde.plasma.networkmanagement===
    ======General======
    * '''unlockModemOnDetection''' (''Bool'', default ''true'') If true request PIN code as soon as modem is detected.
    * '''manageVirtualConnections''' (''Bool'', default ''false'') If true plasma-nm will be able to show and configure virtual connections.
    ===org.kde.plasma.notes===
    ======General======
    * '''color''' (''String'', default ''yellow'')
    * '''noteId''' (''String'', default ''empty string'')
    ===org.kde.plasma.notifications===
    ======General======
    * '''showNotifications''' (''Bool'', default ''true'') Show the notifications
    * '''showJobs''' (''Bool'', default ''true'') Show the jobs progress
    * '''showHistory''' (''Bool'', default ''true'') Show a history of notifications
    ===org.kde.plasma.pager===
    ======General======
    * '''displayedText''' (''Enum'', default ''2'') The text to show inside the desktop rectangles.
    * '''showWindowIcons''' (''Bool'', default ''false'') Whether to show window icons inside the window rectangles.
    * '''showOnlyCurrentScreen''' (''Bool'', default ''false'') Whether to limit the Pager to the set of windows and the geometry of the screen the widget resides on.
    * '''currentDesktopSelected''' (''Enum'', default ''0'') What to do on left-mouse click on a desktop rectangle.
    * '''pagerLayout''' (''Enum'', default ''0'') The layout style used for the presentation.
    ===org.kde.plasma.panelspacer===
    ======General======
    * '''expanding''' (''bool'', default ''true'') If true, the spacer tries to take all the available space in the panel.
    * '''length''' (''Int'', default ''0'') length in pixels of the spacer. Configuration effective only if expanding is set to false.
    ===org.kde.plasma.printmanager===
    ======General======
    * '''activeJobs''' (''Bool'', default ''true'')
    * '''completedJobs''' (''Bool'', default ''false'')
    * '''allJobs''' (''Bool'', default ''false'')
    ===org.kde.plasma.private.grouping===
    ======General======
    ===org.kde.plasma.private.systemtray===
    ======General======
    * '''applicationStatusShown''' (''bool'', default ''true'') If true, the items of "Application status" category are shown in the systray.
    * '''communicationsShown''' (''bool'', default ''true'') If true, the items of "Communications" category are shown in the systray.
    * '''systemServicesShown''' (''bool'', default ''true'') If true, the items of "System services" category are shown in the systray.
    * '''hardwareControlShown''' (''bool'', default ''true'') If true, the items of "Hardware Control" category are shown in the systray.
    * '''miscellaneousShown''' (''bool'', default ''true'') If true, the items of "miscellaneous" category are shown in the systray.
    * '''extraItems''' (''StringList'', default ''empty list'') All plasmoid items that are explicitly enabled in the systray. It's a comma-separated string list of plasmoid plugin ids.
    * '''hiddenItems''' (''StringList'', default ''empty list'') All items that are hidden, forced always in the popup. It's a comma-separated string list of unique identifiers that are either plasmoid plugin ids or StatusNotifier ids.
    * '''shownItems''' (''StringList'', default ''empty list'') All items that are shown. It's a comma-separated string list of unique identifiers that are either plasmoid plugin ids or StatusNotifier ids.
    * '''showAllItems''' (''bool'', default ''false'') If true, all systray entries will be always in the main area, outside the popup.
    * '''iconSize''' (''Int'', default ''1'') Default icon size for the systray icons, it's an enum which values mean, Small, SmallMedium, Medium, Large, Huge, Enormous respectively. On low DPI systems they correspond to 16, 22, 32, 48, 64, 128 pixels. On high DPI systems those values would be scaled up, depending on the DPI.
    * '''pin''' (''Bool'', default ''false'') Whether the popup should remain open when another window is activated
    ===org.kde.plasma.quicklaunch===
    ======General======
    * '''maxSectionCount''' (''Int'', default ''1'')
    * '''showLauncherNames''' (''Bool'', default ''false'')
    * '''enablePopup''' (''Bool'', default ''false'')
    * '''title''' (''String'', default ''empty string'')
    * '''launcherUrls''' (''StringList'', default ''empty list'')
    * '''popupUrls''' (''StringList'', default ''empty list'')
    ===org.kde.plasma.quickshare===
    ======Appearance======
    * '''copyAutomatically''' (''bool'', default ''false'')
    * '''historySize''' (''int'', default ''3'')
    ===org.kde.plasma.showdesktop===
    ======General======
    * '''icon''' (''String'', default ''user-desktop'')
    ===org.kde.plasma.systemloadviewer===
    ======General======
    * '''memApplicationColor''' (''Color'', default ''blue'')
    * '''memCachedColor''' (''Color'', default ''green'')
    * '''memBuffersColor''' (''Color'', default ''yellow'')
    * '''cacheDirtyColor''' (''Color'', default ''blue'')
    * '''cacheWritebackColor''' (''Color'', default ''yellow'')
    * '''swapUsedColor''' (''Color'', default ''turquoise'')
    * '''cpuUserColor''' (''Color'', default ''blue'')
    * '''cpuIOWaitColor''' (''Color'', default ''green'')
    * '''cpuSysColor''' (''Color'', default ''red'')
    * '''cpuNiceColor''' (''Color'', default ''yellow'')
    * '''cpuActivated''' (''Bool'', default ''true'')
    * '''cpuAllActivated''' (''Bool'', default ''false'')
    * '''memoryActivated''' (''Bool'', default ''true'')
    * '''swapActivated''' (''Bool'', default ''true'')
    * '''cacheActivated''' (''Bool'', default ''false'')
    * '''setColorsManually''' (''Bool'', default ''false'')
    * '''updateInterval''' (''Double'', default ''1.0'')
    * '''monitorType''' (''Enum'', default ''0'')
    ===org.kde.plasma.systemmonitor.cpu===
    ======General======
    * '''sources''' (''StringList'', default ''empty list'') Which "systemmonitor" dataengine sources this applet will take data from.
    ===org.kde.plasma.systemmonitor.diskactivity===
    ======General======
    * '''sources''' (''StringList'', default ''empty list'') Which "systemmonitor" dataengine sources this applet will take data from.
    ===org.kde.plasma.systemmonitor.diskusage===
    ======General======
    * '''sources''' (''StringList'', default ''empty list'') Which "systemmonitor" dataengine sources this applet will take data from.
    ===org.kde.plasma.systemmonitor.memory===
    ======General======
    * '''sources''' (''StringList'', default ''empty list'') Which "systemmonitor" dataengine sources this applet will take data from.
    ===org.kde.plasma.systemmonitor.net===
    ======General======
    * '''sources''' (''StringList'', default ''empty list'') Which "systemmonitor" dataengine sources this applet will take data from.
    ===org.kde.plasma.taskmanager===
    ======General======
    * '''showOnlyCurrentScreen''' (''Bool'', default ''false'') Whether to show only window tasks that are on the same screen as the widget.
    * '''showOnlyCurrentDesktop''' (''Bool'', default ''false'') Whether to only show tasks that are on the current virtual desktop.
    * '''showOnlyCurrentActivity''' (''Bool'', default ''true'') Whether to show only tasks that are on the current activity.
    * '''showOnlyMinimized''' (''Int'', default ''false'') Whether to show only window tasks that are minmized.
    * '''groupingStrategy''' (''Enum'', default ''1'') How tasks are grouped: 0 = Do Not Group, 1 = By Program Name
    * '''groupPopups''' (''Bool'', default ''true'') Whether groups are to be reduced to a single task button and expand into a popup or task buttons are grouped on the widget itself.
    * '''onlyGroupWhenFull''' (''Bool'', default ''true'') Whether to group always or only when the widget runs out of space to show additional task buttons comfortably.
    * '''groupingAppIdBlacklist''' (''StringList'', default ''empty list'') The id's (usually .desktop file names) of applications that should not have their tasks grouped.
    * '''groupingLauncherUrlBlacklist''' (''StringList'', default ''empty list'') The launcher URLs (usually .desktop file or executable URLs) of applications that should not have their tasks grouped.
    * '''sortingStrategy''' (''Int'', default ''2'') How to sort tasks: 0 = Do Not Sort, 1 = Manually, 2 = Alphabetically, 3 = By Desktop, 4 = By Activity
    * '''separateLaunchers''' (''Bool'', default ''true'') Whether launcher tasks are sorted separately at the left side of the widget or can be mixed with other tasks.
    * '''maxStripes''' (''Int'', default ''2'') The maximum number of rows (in a horizontal-orientation containment, i.e. panel) or columns (in a vertical-orientation containment) to layout task buttons in.
    * '''forceStripes''' (''Bool'', default ''false'') Whether to try and always layout task buttons in as many rows/columns as set via maxStripes.
    * '''showToolTips''' (''Bool'', default ''true'') Whether to show tooltips when hovering task buttons.
    * '''wheelEnabled''' (''Bool'', default ''true'') Whether using the mouse wheel with the mouse pointer above the widget should switch between tasks.
    * '''highlightWindows''' (''Bool'', default ''false'') Whether to request the window manager highlight windows when hovering corresponding task buttons.
    * '''launchers''' (''StringList'', default ''empty list'') The list of launcher tasks on the widget. Usually .desktop file or executable URLs. Special URLs such as preferred://browser that expand to default applications are supported.
    * '''middleClickAction''' (''Enum'', default ''0'') What to do on middle-mouse click on a task button.
    * '''smartLaunchersEnabled''' (''Bool'', default ''true'') Whether to show progress and status information on task buttons.
    * '''indicateAudioStreams''' (''Bool'', default ''true'') Whether to indicate applications that are playing audio including an option to mute them.
    * '''taskHoverEffect''' (''Bool'', default ''true'') Whether task buttons should change in appearance when the mouse pointer is above them.
    * '''maxTextLines''' (''Int'', default ''0'') The maximum number of text lines to show in a task button. 0 means no limit.
    * '''iconSize''' (''Enum'', default ''3'') The preferred size of task button icons in a vertical task manager.
    ===org.kde.plasma.timer===
    ======General======
    * '''running''' (''int'', default ''0'')
    * '''seconds''' (''int'', default ''0'')
    * '''savedAt''' (''DateTime'', default ''null'')
    * '''showTitle''' (''Bool'', default ''false'')
    * '''title''' (''String'', default ''Timer'')
    * '''showSeconds''' (''Bool'', default ''true'')
    * '''showNotification''' (''Bool'', default ''true'')
    * '''notificationText''' (''String'', default ''Timer finished'')
    * '''runCommand''' (''Bool'', default ''false'')
    * '''command''' (''String'', default ''empty string'')
    * '''predefinedTimers''' (''StringList'', default ''30,60,120,300,450,600,900,1200,1500,18𝟢0,2700,3600'')


    See removeSystrayApplet.js in [https://projects.kde.org/projects/kde/kdeexamples/repository/revisions/master/show/plasma/javascript/plasma-shell-scripting kdeexamples]
    ===org.kde.plasma.userswitcher===
    ======General======
    * '''showFace''' (''Bool'', default ''false'')
    * '''showName''' (''Bool'', default ''true'')
    * '''showFullName''' (''Bool'', default ''true'')
    * '''showTechnicalInfo''' (''Bool'', default ''false'')
    ===org.kde.plasma.volume===
    ======General======
    * '''maximumVolume''' (''Int'', default ''100'')
    * '''volumeStep''' (''Int'', default ''5'')
    * '''volumeFeedback''' (''Bool'', default ''true'')
    ===org.kde.plasma.webbrowser===
    ======General======
    * '''url''' (''String'', default ''https://www.kde.org/'')
    ===org.kde.plasma.worldclock===
    ======General======
    * '''projection''' (''Enum'', default ''Equirectangular'')
    * '''centerMode''' (''Enum'', default ''Daylight'')
    * '''fixedLongitude''' (''double'', default ''0'')
    * '''showDate''' (''Bool'', default ''false'')

    Revision as of 16:10, 10 December 2019

    ECMA Script Interaction With Plasma Shells

    It is possible to control and interact with a Plasma user interface shell such as a plasma-desktop or (starting in KDE SC 4.5) plasma-netbook session using ECMA Script (aka JavaScript). This scripting mechanism exposes containments (Desktop Activities and Panels), widgets and various other aspects of plasma-desktop configuration using the widely known and used ECMA Script language. The QtScript engine is used for the runtime environment.

    This document describes the API that is provided along with how to run such scripts in plasma-desktop.

    Examples

    Visit KDE_System_Administration/PlasmaDesktopScripting/Examples for more examples. Here's a couple highlights:

    Advanced example: Adding a widget to the System Tray

    var widgetName = "org.kde.plasma.printmanager";
    
    for (i = 0; i < panelIds.length; ++i) { //search through the panels
        panel = panelById(pids[i]);
        if (!panel) continue;
    
        for (tmpIndex = 0; tmpIndex < panel.widgetIds.length; tmpIndex ++) {
            appletWidget = panel.widgetById(panel.widgetIds[tmpIndex]);
    
            if (appletWidget.type == "org.kde.plasma.systemtray") {
                systemtrayId = appletWidget.readConfig("SystrayContainmentId");
                if (systemtrayId) {
                   print("systemtray id: " + systemtrayId)
                   var systray = desktopById(systemtrayId);
                   systray.currentConfigGroup = ["General"];
                   var extraItems = systray.readConfig("extraItems").split(",");
                   if (extraItems.indexOf(widgetName) === -1) {
                       extraItems.push(widgetName)
                       systray.writeConfig("extraItems", extraItems);
                       systray.reloadConfig();
                   }
                }          
            }
        }
    }
    

    Running Scripts

    There are three ways that scripts can be executed in plasma-desktop:

    • on first run: when plasma-desktop is started without any pre-existing configuration, any scripts in $APPDATA/plasma-desktop/init/ with a ".js" suffix are run. If there is more than one script, they are run sequentially in the alphabetical order of the file names.

    Note

    For security reasons, scripts located in the user's home directory will not be run during this phase.


    • on update: when plasma-desktop is started, it will check in
    `kde4-config --path data`/plasma-desktop/updates/
    

    with a ".js" suffix for scripts that have not yet been run. If there is more than one script which has not been run yet they will be executed serially in the alphabetical order of the file names.

    A record of which update scripts have been run is kept in the application's config file in the [Updates] group. This means that if the plasma-desktop configuration file is removed, all the update scripts will be run again.

    Note

    For security reasons, scripts located in the user's home directory will not be run during this phase.


    • interactively: an interactive scripting dialog can be requested either via the KRunner window (Alt+F2, by default, or via the "Run Command" entry in various desktop menus) by entering "desktop console" as the search term. It can also be triggered directly via dbus with
      qdbus org.kde.plasma-desktop /MainApplication showInteractiveConsole
      
      In Plasma 5 use
      qdbus org.kde.plasmashell /PlasmaShell org.kde.PlasmaShell.showInteractiveConsole
      


    Note

    This method is not available for plasma-netbook.


    ECMA Script may be entered directly into this window for execution and output appears in the lower half of the window. Ctrl+E is a shortcut to run scripts, and scripts can be saved to and loaded from disk.
    Scripts from files can also be loaded using KRunner with "desktop console /path/to/file" or via dbus with
    qdbus org.kde.plasma-desktop /MainApplication loadScriptInInteractiveConsole /path/to/file
    

    Templates

    Templates are named packages that contain scripts. This provides a way for common functionality to be easily reused, helping to increase consistency and lower maintenance costs. Templates can be loaded from other scripts by name and they are also used to populate some parts of the user interface, such as the entries in the Add Panels menu.

    A template is a small set of files in a specified file hierarchy (or, in Plasma terms, a "Package"). In particular, a Template package contains the following files:

    • metadata.desktop: a .desktop file describing the template
    • contents/layout.js: a Javascript file containing the actual script

    Templates are stored under share/apps/plasma/layout-templates and may be installed using `plasmapkg -t layout-template -i /path/to/package`. Template packages may also be provided as a .zip file with a .plasmalayout suffix.

    The metadata.desktop file contains the usual .desktop entries such as Name and Icon but must also contain Type=Service and ServiceTypes=Plasma/LayoutTemplate entries. If the layout is specific to a given Plasma application, such as plasma-desktop, this can be specific using X-Plasma-Shell. X-Plasma-ContainmentCategories defines what kind of layout it is with possible values being panel and desktop. Finally a X-KDE-PluginInfo-Name entry is required to provide a globally unique internal name for the Template. Here is an example of a Template that provides a Panel layout for Plasma Netbook:

    [Desktop Entry]
    Encoding=UTF-8
    Name=Cool Panel
    Type=Service
    ServiceTypes=Plasma/LayoutTemplate
    X-Plasma-Shell=plasma-netbook
    X-Plasma-ContainmentCategories=panel
    X-KDE-PluginInfo-Author=Aaron Seigo
    X-KDE-PluginInfo-Email=[email protected]
    X-KDE-PluginInfo-Name=org.kde.CoolNetbookPanel
    X-KDE-PluginInfo-Version=1.0
    X-KDE-PluginInfo-Website=http://plasma.kde.org/
    X-KDE-PluginInfo-Category=
    X-KDE-PluginInfo-Depends=
    X-KDE-PluginInfo-License=GPL
    X-KDE-PluginInfo-EnabledByDefault=true
    

    When running a template, two global variables will be accessible in read-only mode: templateName and templateComment. They will contain the Name and Comment fields of the above desktop file, and are translated if a localization is available.

    Examples of Usage

    Creating panels

    A good example of the use of templates is the use case that triggered the creation of this feature: the desire to make it easy for users to re-create the default panel that is created on the first start. There is a Template called org.kde.plasma-desktop.defaultPanel that ships with the KDE Plasma Workspace which contains the layout for the initial default panel. This is referenced by the default Plasma Desktop init script and because it is marked as a Panel Template in the metadata.desktop file it also shows up to the user in the Add Panels menu. When selected by the user from the menu, the exact same panel that is created on desktop start up is created for them, complete with Plasma Widgets and configuration.

    Automating tasks

    Another example of the usefulness of templates is the "Find Widgets" template. This template, which first shipped with Plasma Desktop v4.5, provides a function for finding widgets by name. It appears in the toolbar "Load" and "Use" menus in the Desktop Console in plasma-desktop, and makes finding widgets as simple as:

    var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
    template.findWidgets('systemtray')
    


    Since just finding the widget is not enough, you can connect a callback to do additional operations, such as removing the widget :

    removeWidget = function(widget, containment)
    {
      widget.remove()
    }
    
    var template = loadTemplate('org.kde.plasma-desktop.findWidgets')
    template.findWidgets('systemtray', removeWidget)
    


    Activity templates

    Probably the most user visible use of templates are "Activity templates". The structure of Activity templates is similar to the other use of templates, but a few extra features are provided in the metadata.desktop file. Here is an example of such an activity template:

    [Desktop Entry]
    Encoding=UTF-8
    Name=Cool Activity Template
    Icon=user-desktop
    Type=Service
    ServiceTypes=Plasma/LayoutTemplate
    X-Plasma-Shell=plasma-desktop
    X-Plasma-ContainmentCategories=desktop
    X-Plasma-ContainmentLayout-ExecuteOnCreation=dolphin $desktop, gwenview $pictures
    X-Plasma-ContainmentLayout-ShowAsExisting=true
    X-KDE-PluginInfo-Author=John Doe
    X-KDE-PluginInfo-Email=[email protected]
    X-KDE-PluginInfo-Name=org.kde.plasma-desktop.CoolTemplate
    X-KDE-PluginInfo-Version=1.0
    X-KDE-PluginInfo-Website=http://john.doe.org
    X-KDE-PluginInfo-Category=
    X-KDE-PluginInfo-Depends=
    X-KDE-PluginInfo-License=GPL
    X-KDE-PluginInfo-EnabledByDefault=true
    

    The layout itself is still created from the layout.js file as usual, but this template also shows as a precreated activity to the user thanks to the X-Plasma-ContainmentLayout-ShowAsExisting key. Additionally, it starts applications in the newly created activity using the X-Plasma-ContainmentLayout-ExecuteOnCreation key.

    That key is a list of commands to execute, and it supports the following variables:

    • $desktop
    • $autostart
    • $documents
    • $music
    • $video
    • $downloads
    • $pictures

    They all expand into the path toward the user corresponding default folder.

    Update scripts

    Update javascript scripts can be added per-shell at the location

      share/plasma/shells/org.kde.plasma.desktop/updates/
    

    The API available from those config files is the same available from the normal init.js file. from there is possible to add or remove applets or modify config values.

    Look and Feel dependent default setup for applets

    The look and feel package can contain JavaScript files to override the default configuration for applets, if distributions or system integrators want to have a different default setup. The JS files are located under the L&F package folder, for instance

      /opt/kde5/share/plasma/look-and-feel/org.kde.breeze.desktop/contents/plasmoidsetupscripts/org.kde.plasma.analogclock.js
    

    The API available is the same as the init.js script, with the addition of the global variables applet and containment that point to the instance of the applet and the instance of the containment the applet is in. In the case of a containment, the variables applet and containment will be the same.

    API

    In addition to the normal ECMA Script API and the Qt-specific extensions (such as signal/slot support) provided by QtScript, the following API is provided for use by scripts.

    All of the API below, unless otherwise noted with a version noticed, appear as below in the KDE Software Compilation v4.4.0 and later. API that is not noted as being part of a given class or object is part of the global namespace.

    Note

    API compatibility is guaranteed from version to version starting with KDE Software Compilation v4.4.0.


    Version Numbers

    Starting with KDE SC 4.5, the version number of both the scripting API and the application is available to the script via the following read-only properties:

    • String applicationVersion: the version of the application, e.g. 0.3
    • String platformVersion: the version of the KDE Platform, e.g. 0.3
    • number scriptingVersion: the version of the scripting API; e.g. in KDE SC 4.5 this is 2

    Activities and desktops

    Desktop are the desktop layer in a plasma-desktop session and may contain widgets. In slightly more technical terms, they are desktop containments. Activities can be created, enumerated, modified and destroyed.

    New Activities can be created using the newActivity function, like this:

    var activityId = newActivity("org.kde.plasma.folderview")
    

    it returns the activity string Id (to not be confused from the numerical id of the Deskop object) The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry in the plugin's .desktop file). See the documentation on the Containment object class below.

    Read-only properties:

    • Array[number] activityIds: returns a list of integer ids of all existing Plasma activities
    • Array[String] knownActivityTypes: (scripting version >= 2) a list of types of activities that can be created. This is useful to check if an Activity type is available on the system before trying to construct one.

    Functions:

    • Array[Desktop] desktopsForActivity(string id): return all the desktops associated to a specific activity id (one per phisical screen)
    • Desktop desktopById(number id): return an object representing the activity with the given id
    • Desktop desktopForScreen(number screen[, number dekstop]): returns an object representing the activity currently associated with the given screen and, optionally, the given desktop.
    • Array[Desktop] desktops(): returns an array of all desktops that currently exist
    • Array[string] activities(): returns an array of all activity ids of the activities that currently exist

    Panels

    Panels can be created, enumerated, modified and destroyed. A panel object combines both a containment as well as the container itself, allowing for full control of things such as where it appears on the screen and the hiding features associated with them.

    New Panels can be created using the Panel constructor, like this:

    var panel = new Panel("dock")
    

    The string passed into the constructor maps to the X-KDE-PluginInfo-Name= entry in the plugin's .desktop file).

    Read-only properties:

    • Array[number] panelIds: returns a list of integer ids of all existing Plasma panels
    • Array[String] knownPanelTypes: (scripting version >= 2) a list of types of panels that can be created. This is useful to check if a Panel type is available on the system before trying to construct one.

    Functions:

    • Panel panelById(int id): returns an object representing the Panel that matches the given id
    • Array[Panels] panels(): returns an array of all panels that currently exist

    Activities and Panels

    Activity and Panel objects, once created by the script, or as returned by activityById, activityForScreen, or panelById) provide the following read-only properties:

    • number id: the integer id of this activity
    • String formFactor: returns the form factor of the activity, e.g. "planar" for most desktop activities,"mediacenter" for media centers and either "horizontal" or "vertical" for panels.
    • Array[number] widgetIds: a list of integer ids of all the widgets in this Activity
    • Array[String] configKeys: (scriptingVersion >= 2) a list of all keys that are set in the current configuration group
    • Array[String] configGroups: (scriptingVersion >= 2) a list of all the groups in the current configuration group
    • Array[String] globalConfigKeys: (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
    • Array[String] globalConfigGroups: (scriptingVersion >= 2) a list of all the groups in the current global configuration group

    as well as the following read/write properties:

    • number desktop: the virtual desktop this activity is associated with, or -1 for none
    • number screen: the screen this activity is associated with, or -1 for none
    • String name: the name of this activity
    • String wallpaperPlugin: (scriptingVersion >= 2) the wallpaper plugin to use with the Activity
    • String wallpaperMode: (scriptingVersion >= 2) the wallpaper plugin mode to use with the Activity
    • Array[String] currentConfigGroup: (scriptingVersion >= 2) the current configuration group path, with each entry in the array representing a sub-group. This allows one to access trees of groups with code such as: widget.currentConfigGroup = new Array('topGroup', 'subGroupOfTopGroup'). An empty Array means the default (top-level) configuration group for the widget
    • String version: (scriptingVersion >= 2) the version of the Activity or Panel

    and the following methods:

    • remove(): deletes this activity and all widgets inside of it
    • Widget widgetById(number id): returns an object representing the widget with the given id
    • Widget addWidget(String name): adds a new widget to the activity; the name maps to the X-KDE-PluginInfo-Name= entry in the widget's .desktop file
    • Widget addWidget(Widget widget): adds an existing widget to this activity; useful for moving widgets between Activities and Panels
    • showConfigurationInterface(): shows the configuration user interface for this Activity or Panel on the screen
    • readConfig(String key, any default): (scriptingVersion >= 2) reads the value of key in the config with default for the default value
    • writeConfig(String key, any value): (scriptingVersion >= 2) sets key to value in the config
    • readGlobalConfig(String key, any default): (scriptingVersion >= 2) reads the value of key in the global config with default for the default value
    • writeGlobalConfig(String key, any value): (scriptingVersion >= 2) sets key to value in the global config
    • reloadConfig(): (scriptingVersion >= 2) causes the Activity or Panel to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
    • Array[String] currentGlobalConfigGroup: (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of panels and activities of the same type.
    • Array[Widget] widgets([String type]): (scriptingVersion >= 2) returns all the widgets in the Panel or Activity. If the optional type is specified, only widgets matching that type will be returned.

    In addition to all of the above properties and functions, Panel objects also provide the folowing read/write properties:

    • number length: the number of pixels along the screen edge used
    • number minimumLength: (scriptingVersion >= 7) the minimum number of pixels along the screen edge used (auto-resize panels)
    • number maximumLength: (scriptingVersion >= 7) the maximum number of pixels along the screen edge used (auto-resize panels)
    • number height: the height (or for vertical panels, the width) of the panel
    • String hiding: the hiding mode of the panel, one of "none" (for no hiding), "autohide", "windowscover" or "windowsbelow"
    • String alignment: right, left or center alignment of the panel (for vertical panels, right corrsponds to top and left to bottom)
    • String location: returns the location of the activity (only relevant for Panels); valid values include "top", "bottom", "left", "right" and "floating"

    Widgets

    Widgets may be enumerated by calling the widgetIds property on an Activity or Panel object. With a widget id in hand, a Widget object can be retrieved by calling widgetById(id) on an Activity or Panel object. New Widgets can be created with add addWidget(String) function provided by Activity and Panel objects.

    Checking if a widget is installed

    A list of all installed widget types can be retrieved the following read-only property:

    • Array[String] knownWidgetTypes (scripting version >= 2)

    This can be used most conveniently with the indexOf() method, like this:

    if (knownWidgetTypes.indexOf('someWidgetPluginName') > -1) {
        print("It is installed on this system!");
    } else {
        print("It is not installed :(");
    }
    

    Widget Object API

    A Widget object provides the following read-only properties:

    • number id: the id of the widget
    • String type: the plugin type of this widget
    • Array[String] configKeys: a list of all keys that are set in the current configuration
    • Array[String] configGroups: a list of all the groups in the current configuration
    • Array[String] globalConfigKeys: (scriptingVersion >= 2) a list of all keys that are set in the current global configuration group
    • Array[String] globalConfigGroups: (scriptingVersion >= 2) a list of all the groups in the current global configuration group
    • String version: (scriptingVersion >= 2) the version of the Activity or Panel

    as well as the following read-write properties:

    • Array[String] currentConfigGroup: the current configuration group path, with each entry in the array representing a sub-group. This allows one to access trees of groups with code such as: widget.currentConfigGroup = new Array('topGroup', 'subGroupOfTopGroup'). An empty Array means the default (top-level) configuration group for the widget
    • Array[String] currentGlobalConfigGroup: (scriptingVersion >= 2) the current global configuration group path, with each entry in the array representing a sub-group, similar to currentConfigGroup. However, global configuration is shared by all instances of widgets of the same type.
    • QRectF geometry: the geometry of the widget (settable)
    • String globalShortcut: the shortcut sequence (in the format used by QKeySequence, e.g. "Alt+F1") associated with this widget
    • number index: the layout index of the widget; in a Panel this corresponds to the order the widget appears in. Changing the value of the index will change the position of the widget in Panels and may do so in some Activities as well.

    and the following methods:

    • remove(): deletes this widget
    • readConfig(String key, any default): reads the value of key in the config with default for the default value
    • writeConfig(String key, any value): sets key to value in the config
    • readGlobalConfig(String key, any default): (scriptingVersion >= 2) reads the value of key in the global config with default for the default value
    • writeGlobalConfig(String key, any value): (scriptingVersion >= 2) sets key to value in the global config
    • reloadConfig(): causes the widget to reload its configuration; reaction to configuration changes made using readConfig are usually activated on script exit, but this can be triggered earlier on a per-widget basis using this method
    • showConfigurationInterface(): shows the configuration user interface for this widget on the screen

    Screen Geometry

    Read-only properties:

    • number screenCount: returns the number of screens connected to the computer

    Functions:

    • QRectF screenGeometry(number screen): returns a rect object representing the geometry of a screen

    Wallpaper Plugins

    • Array[String => Array[String]] knownWallpaperPlugins(): (scripting version >= 4) returns a list of all installed wallpaper plugins. The keys of the array are the wallpaper plugin names. The values are arrays containing the modes available for that wallpaper plugin. The mode array may be empty, as most wallpaper plugins only offer one mode.

    Locating Applications and Paths

    • boolean applicationExists(String name): (scripting version >= 4) searches $PATH first, then tries in the application menu system by application storage name (aka the .desktop file name), then Name= entries for apps with installed .desktop files, then GenericName= entries for same
    • mixed defaultApplication(String kind [, boolean storageId = false]): (scripting version >= 4) returns the executable (or if storageId is true, then the app menu system id, e.g. its .desktop file name) of the default app. The "kind" parameter may be a well-known application type including "browser", "mailer", "filemanager", "terminal", "imClient" and "windowmanager" (or any other entry in share/apps/kcm_componentchooser/kcm_*.desktop); it may also be a mimetype (e.g. "application/pdf"). On failure, it returns false.
    • String applicationPath(String name): (scripting version >= 4) returns the full local path to a given application or .desktop file if it exists. Example:
    var desktopfile = "firefox.desktop"
    var executable  = "firefox"
    if (applicationExists(executable)) {  
        print (executable + " exists " + " with this path:  " + applicationPath(executable))
        print (executable + " .desktop file is located here :    " + applicationPath(desktopfile))
    } else{
        print (executable + " does not exist ")
    }
    
    • String userDataPath([String type, String path]): (scripting version >= 4) returns the default path for user data. Called with no parameters, it returns the user's home directory. If only one string is passed in, the standard directory for that type of data in the user's home directory will be located; the following values are recognized:
      • documents
      • music
      • video
      • downloads
      • pictures
      • autostart
      • desktop (should be considered deprecated for Plasma workspaces)

    If a second string is passed in, it is considered a request for a specific path and the following types are recognized:

      • apps - Applications menu (.desktop files).
      • autostart - Autostart directories (both XDG and kde-specific)
      • cache - Cached information (e.g. favicons, web-pages)
      • cgi - CGIs to run from kdehelp.
      • config - Configuration files.
      • data - Where applications store data.
      • emoticons - Emoticons themes
      • exe - Executables in $prefix/bin. findExe() for a function that takes $PATH into account.
      • html - HTML documentation.
      • icon - Icons, see KIconLoader.
      • kcfg - KConfigXT config files.
      • lib - Libraries.
      • locale - Translation files for KLocale.
      • mime - Mime types defined by KDE-specific .desktop files.
      • module - Module (dynamically loaded library).
      • qtplugins - Qt plugins (dynamically loaded objects for Qt)
      • services - Services.
      • servicetypes - Service types.
      • sound - Application sounds.
      • templates - Templates for the "Create new file" functionality.
      • wallpaper - Wallpapers.
      • tmp - Temporary files (specific for both current host and current user)
      • socket - UNIX Sockets (specific for both current host and current user)
      • xdgconf-menu - Freedesktop.org standard location for menu layout (.menu) files.
      • xdgdata-apps - Freedesktop.org standard location for application desktop files.
      • xdgdata-dirs - Freedesktop.org standard location for menu descriptions (.directory files).
      • xdgdata-mime - Freedesktop.org standard location for MIME type definitions.
      • xdgdata-icon - Freedesktop.org standard location for icons.
      • xdgdata-pixmap - Gnome-compatibility location for pixmaps.

    The second parameter should be a specific resource to find the path to. An example might be userDataPath("data", "plasma-desktop").

    External Configuration Files

    Scripting version >=6

    Access to configuration files outside of the application's appletsrc file is provided by the ConfigFile object which has the following constructors:

    • ConfigFile(ConfigFile other): creates a new ConfigFile object with the first as its parent, which automatically makes all groups of this object child groups of that parent
    • ConfigFile(string file[, string group]): creates a new ConfigFile object for file and optionally set to group group

    ConfigFile has the following functions:

    • writeEntry(string key, any value): writes value for key in the current group
    • readEntry(string key): returns the value of key in the current group
    • deleteEntry(key): deletes key in the current group

    ConfigFile has the following read/write properties:

    • file: the name of the configuration file. Maybe an absolute path or just a file name to be located automatically in the system's configuration repository.
    • group: the name of the current group. To get to child groups, create a new ConfigFile with another ConfigFile as its parent.

    ConfigFile has the follow read-only properties:

    • entryList: all the keys in the current group
    • groupList: all the child groups in the current group

    Example usage:

    // open the kickoffrc file
    var config = ConfigFile('kickoffrc');
    // switch to the RecentlyUsed group
    config.group = 'RecentlyUsed';
    // write an entry into it
    config.writeEntry('MaxApplications', 25);
    
    // now put Yes=20 into RecentlyUsed/Test
    var config2 = ConfigFile(config, 'Test);
    config2.writeEntry('Yes', 20);
    

    Misc. Global Properties and Functions

    Read-write properties:

    • boolean locked: whether the desktop shell and widgets are locked or not (settable)
    • string theme: (scripting version >= 3) the name of the desktop theme to use for the interface, e.g. default, Air, Oxygen, etc.

    Read-only properties:

    • boolean hasBattery: whether or not the system has the ability to run on battery power, e.g. a laptop or mobile device
    • boolean multihead: (scripting version >= 3) true if the system is running with multiple screens in a "Xaphod" multiple display server configuration
    • int multiheadScreen: (scripting version >= 3) if multihead is true, contains the (real) screen id of the current screen

    Functions:

    • sleep(number ms): sleeps the script for the specified number of milliseconds

    QRectF

    A rectangle class is also provided for use with Widget, Panel and screen geometry properties and functions.

    Read-only properites:

    • boolean empty: true if the rectangle's width or height is less than, or equal to, 0; an empty rectangle is also invalid
    • boolean null: true if the rectangle has both the width and the height set to 0; a null rectangle is also empty and not valid
    • boolean valid: true if the rectangle has a width > 0 and height 0.

    Read-write properties:

    • number left
    • number top
    • number bottom
    • number right
    • number height
    • number width
    • number x
    • number y

    Constructors:

    • QRectF
    • QRectF(number x, number y, number width, number height): Sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.

    Functions:

    • adjust(number dx1, number dy1, number dx2, number dy2): adds dx1, dy1, dx2 and dy2 respectively to the existing coordinates of the rectangle
    • QRectF adjusted(number dx1, number dy1, number dx2, number dy2): returns a new QRectF with dx1, dy1, dx2 and dy2 added respectively to the existing coordinates of the rectangle
    • translate(number dx, number dy): translates the rect by dx, dy
    • setCoords(number x1, number y1, number x2, number y2): sets the coordinates of the rectangle's top-left corner to (x1, y1), and the coordinates of its bottom-right corner to (x2, y2).
    • setRect(number x, number y, number width, number height): sets the coordinates of the rectangle's top-left corner to (x, y), and its size to the given width and height.
    • boolean contains(number x, number y): returns true if the rect contains the point (x, y)
    • 'moveBottom(number delta): moves the bottom by delta pixels
    • moveLeft(number delta): moves the left by delta pixels
    • moveRight(number delta): moves the right by delta pixels
    • moveTo(number x, number y): moves the top left of the rect to point (x, y)
    • moveTop(number delta): moves the top by delta pixels


    Configuration Keys

    Here you find a list of commonly used configuration keys to use with the writeConfig command. Where the documentation notes that a key is in a subgroup other than General, remember to first use currentConfigGroup.

    org.kde.desktopcontainment

    General
    • icon (String, default folder) The name of the custom icon to use for the compact representation (e.g. on a small panel) of the Folder View applet. Only used if useCustomIcon is true.
    • useCustomIcon (Bool, default false) Whether to use a custom icon for the compact representation (e.g. on a small panel) of the Folder View Applet.
    • ToolBoxButtonState (String, default topleft) Position state of the toolbox button.
    • ToolBoxButtonX (int, default null) X coordinate of the toolbox.
    • ToolBoxButtonY (int, default null) Y coordinate of the toolbox.
    • url (String, default desktop:/) URL of the file system location being shown.
    • labelMode (Int, default 1) How to show the Folder View label: 0 = No label, 1 = Friendly version of path relative to closest Places entry, 2 = Full path, 3 = Custom title
    • labelText (String, default empty string) Custom text for the Folder View label. Only used if labelMode is 3.
    • arrangement (Int, default 0) How Folder View icons are arranged: 0 = Rows, 1 = Columns
    • alignment (Int, default 0) How Folder View icons are aligned: 0 = Left, 1 = Right
    • locked (Bool, default false) Whether Folder View icons are locked or not. Only used when serving as containment.
    • sortMode (Int, default 0) How Folder View icons are sorted: 0 = Unsorted, 1 = Name, 2 = Size, 3 = Type, 4 = Date
    • sortDesc (Bool, default false) Whether to sort Folder View icons descending instead of ascending.
    • sortDirsFirst (Bool, default true) Whether to sort folders before files in Folder View.
    • toolTips (Bool, default false) Whether to show info tooltips when hovering Folder View icons.
    • selectionMarkers (Bool, default true) Whether to show selection markers when hovering Folder View icons.
    • popups (Bool, default true) Whether to show a popup preview window for Folder View icons for folders.
    • previews (Bool, default true) Whether to show preview thumbnails in Folder View.
    • previewPlugins (StringList, default imagethumbnail,jpegthumbnail) List of id's of the thumbnail preview plugins to use in Folder View.
    • viewMode (Int, default 0) The Folder View view mode (used only by the widget full represntation): 0 = Grid, 1 = List
    • iconSize (Int, default 4) The icon size to use for Folder View icons. One of the list of Plasma icon sizes.
    • textLines (Int, default 2) The (maximum) number of lines of text to use below Folder View icons.
    • textColor (String, default white) The text color to use below Folder View icons. Only used when serving as containment.
    • iconHoverEffect (Bool, default true) Whether icons should change in appearance when the mouse pointer is above them.
    • filterPattern (String, default *) The pattern to filter files by. Supports wildcards.
    • filterMode (Int, default 0) The file filter mode: 0 = Show All Files, 1 = Show Files Matching, 2 = Hide Files Matching
    • filterMimeTypes (StringList, default all/all) List of MIME types to filter by.
    • showTweaks (Bool, default true) Whether to show the "Tweaks" config page. Only used when serving as containment.
    • showToolbox (Bool, default true) Whether to show the Desktop Toolbox. Only used when serving as containment.
    • pressToMove (Bool, default true) Whether to activate widget handles and widget move mode by long press. Only used when serving as containment.
    • pressToMoveHelp (Bool, default true) Whether to show an info notification about pressToMove mode after enabling it or when the containment becomes mutable (i.e. widgets are unlocked).

    org.kde.ktp-chat

    General
    • pinnedContacts (StringList, default empty list)

    org.kde.mediacentercontainment

    General
    • AppletOrder (String, default empty string) encoded order of items

    org.kde.panel

    General
    • AppletOrder (String, default empty string) encoded order of items

    org.kde.person

    General
    • personUri (String, default empty string)

    org.kde.phone.homescreen

    General
    • AppletOrder (String, default empty string) encoded order of items
    • AppOrder (StringList, default org.kde.phone.dialer.desktop) order of apps

    org.kde.phone.panel

    General
    • AppletOrder (String, default empty string) encoded order of items

    org.kde.phone.taskpanel

    General
    • PanelButtonsVisible (Bool, default true) panel chrome visible

    org.kde.plasma.analogclock

    General
    • showSecondHand (Bool, default false)
    • showTimezoneString (Bool, default false)

    org.kde.plasma.appmenu

    Appearance
    • compactView (Bool, default false) If true it only shows a button for the application menu.

    org.kde.plasma.battery

    General
    • showPercentage (bool, default false) If true, the battery will display a little charge percentage label inside.

    org.kde.plasma.binaryclock

    General
    • showGrid (Bool, default true)
    • showOffLeds (Bool, default true)
    • showSeconds (Bool, default true)
    • useCustomColorForActive (Bool, default false)
    • customColorForActive (Color, default green)
    • useCustomColorForInactive (Bool, default false)
    • customColorForInactive (Color, default red)
    • useCustomColorForGrid (Bool, default false)
    • customColorForGrid (Color, default blue)

    org.kde.plasma.calendar

    Agenda
    • startOfWorkingDay (int, default 9)
    • endOfWorkingDay (int, default 17)
    • showWeekNumbers (Bool, default false)
    • compactDisplay (String, default d)

    org.kde.plasma.colorpicker

    General
    • history (StringList, default empty list)
    • autoClipboard (Bool, default true)
    • defaultFormat (String, default #RRGGBB)
    • pickOnActivate (Bool, default true)

    org.kde.plasma.devicenotifier

    General
    • removableDevices (Bool, default true) If true it lists removable devices, such as USB thumbdrives. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    • nonRemovableDevices (Bool, default false) If true it lists non removable devices, such as internal harddrives. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    • allDevices (Bool, default false) If true it lists all kind of devices. Only one between removableDevices, nonRemovableDevices and allDevices should be set.
    • popupOnNewDevice (Bool, default true) If true it tries to open the plasmoid when a new device is inserted, as a kind of notification.

    org.kde.plasma.digitalclock

    Appearance
    • showLocalTimezone (Bool, default false) Whether the timezone should be displayed when the clock is showing the local timezone.
    • showSeconds (Bool, default false) Whether seconds should be shown in the clock.
    • showDate (Bool, default false) Whether the date should be shown next to the clock.
    • dateFormat (string, default shortDate) The date format to display. Options are: shortDate, longDate or isoDate.
    • fontFamily (string, default null) Font family. e.g "arial". The system font is used if this is not set.
    • boldText (Bool, default false) Sets the font to bold.
    • italicText (Bool, default false) Sets the font to italic.
    • timeFormat (string, default default)
    • selectedTimeZones (StringList, default Local) A list of the time zones available on mouse wheel. Requires wheelChangesTimezone to be true. Format is "Europe/London". Special entry "Local" indicates system time zone.
    • lastSelectedTimezone (String, default Local) When multiple time zones are configured, this is the one shown on widget restore.
    • wheelChangesTimezone (Bool, default false) Whether the mouse wheel switches between the timezones configured in selectedTimeZones.
    • displayTimezoneAsCode (Bool, default true) Whether the timezone is displayed as a code i.e. "GMT" or full text i.e. "London".
    • showWeekNumbers (Bool, default false) Whether the calendar should show week numbers.
    • use24hFormat (UInt, default 1) Force the clock to use 12/24 hour time, instead of following the user locale.
    • enabledCalendarPlugins (StringList, default empty list) A list of plugins where additional calendar event data can be sourced.
    • pin (Bool, default false) Whether the popup should remain open when another window is activated

    org.kde.plasma.fifteenpuzzle

    Appearance
    • imagePath (String, default empty string)
    • useImage (Bool, default false)
    • showNumerals (Bool, default true)
    • boardColor (Color, default #333333)
    • numberColor (Color, default #ffffff)
    • boardSize (Int, default 4)

    org.kde.plasma.fuzzyclock

    Appearance
    • fuzzyness (Int, default 1)
    • boldText (Bool, default false)
    • italicText (Bool, default false)

    org.kde.plasma.icon

    General
    • url (String, default empty string)
    • localPath (String, default empty string)

    org.kde.plasma.kicker

    General
    • icon (String, default start-here-kde) The name of the icon to use for the compact representation (e.g. on a small panel).
    • useCustomButtonImage (Bool, default false) Whether to use a custom image instead of an icon in the compact representation (e.g. on a small panel).
    • customButtonImage (Url, default null) The URL of the custtom image to use instead of an icon in the compact representation (e.g. on a small panel).
    • appNameFormat (Int, default 0) The format used in the display of application names: 0 = NameOnly, 1 = GenericNameOnly, 2 = NameAndGenericName, 3 = GenericNameAndName
    • limitDepth (Bool, default false) Whether to flatten top-level menu categories to a single level instead of displaying sub-categories.
    • alphaSort (Bool, default false) Whether to sort menu contents alphabetically or use manual/system sort order.
    • recentOrdering (Int, default 0) How should the previously used apps/docs/contacts be ordered: 0 = RecentFirst, 1 = PopularFirst
    • favoriteApps (StringList, default preferred://browser,kontact.desktop,systemsettings.desktop,org.kde.dolphin.desktop,ktp-contactlist.desktop,org.kde.kate.desktop,org.kde.discover) List of general favorites. Supported values are menu id's (usually .desktop file names), special URLs that expand into default applications (e.g. preferred://browser), document URLs and KPeople contact URIs.
    • favoriteSystemActions (StringList, default logout,reboot,shutdown) List of system action favorites.
    • favoritesPortedToKAstats (Bool, default false) Are the favorites ported to use KActivitiesStats to allow per-activity favorites
    • hiddenApplications (StringList, default empty list) List of menu id's (usually .desktop file names) of apps that should not be shown in the menu.
    • showRecentApps (Bool, default true) Whether to show the "Recent Applications" category.
    • showRecentDocs (Bool, default true) Whether to show the "Recent Documents" category.
    • showRecentContacts (Bool, default false) Whether to show the "Recent Contacts" category.
    • useExtraRunners (Bool, default true) Whether to use additional KRunner plugins to produce results in the search.
    • extraRunners (StringList, default shell,bookmarks,baloosearch,locations) The plugin id's of additional KRunner plugins to use. Only used if useExtraRunners is true.
    • alignResultsToBottom (Bool, default true) Whether to align search results to the bottom of the menu representation (e.g. panel popup) instead of the top.

    org.kde.plasma.kickoff

    General
    • switchTabsOnHover (Bool, default true) Whether to switch between menu tabs by hovering them.
    • showAppsByName (Bool, default false) Whether to display specific application names instead of their generic names (e.g. Dolphin instead of File Manager).
    • icon (String, default start-here-kde) The name of the icon used in the compact representation (e.g. on a small panel).
    • favorites (StringList, default preferred://browser,kontact.desktop,systemsettings.desktop,org.kde.dolphin.desktop,ktp-contactlist.desktop,org.kde.kate.desktop,org.kde.discover.desktop) List of general favorites. Supported values are menu id's (usually .desktop file names), special URLs that expand into default applications (e.g. preferred://browser), document URLs and KPeople contact URIs.
    • favoritesPortedToKAstats (Bool, default false) Are the favorites ported to use KActivitiesStats to allow per-activity favorites
    • systemApplications (StringList, default systemsettings.desktop,org.kde.kinfocenter.desktop,org.kde.discover.desktop) List of applications at the top of the "Computer" tab.
    • useExtraRunners (Bool, default true) Whether to use additional KRunner plugins to produce results in the search.
    • runners (StringList, default shell,bookmarks,recentdocuments,locations,baloosearch) The plugin id's of additional KRunner plugins to use. Only used if useExtraRunners is true.
    • menuItems (StringList, default bookmark:t,application:t,computer:t,used:t,oftenUsed:f,leave:t) The menu tabs to show.
    • alphaSort (Bool, default false) Whether to sort menu contents alphabetically or use manual/system sort order.

    org.kde.plasma.kimpanel

    Appearance
    • vertical_lookup_table (Bool, default false)
    • use_default_font (Bool, default true)
    • font (Font, default null)
    • hiddenList (StringList, default empty list)

    org.kde.plasma.lock_logout

    General
    • show_requestShutDown (Bool, default true) Show an option to shut down the system.
    • show_lockScreen (Bool, default true) Show an option to lock the system.
    • show_switchUser (Bool, default false) Show an option to switch user.
    • show_suspendToDisk (Bool, default false) Show an option to suspend the system to disk (hibernate).
    • show_suspendToRam (Bool, default false) Show an option to suspend the system suspend.

    org.kde.plasma.mediacontroller

    General
    • pauseWhenScreenLocked (Bool, default false)

    org.kde.plasma.mediaframe

    General
    • interval (Double, default 6.8)
    • randomize (Bool, default true)
    • pauseOnMouseOver (Bool, default true)
    • useBackground (Bool, default true)
    • leftClickOpenImage (Bool, default true)
    • showCountdown (Bool, default true)
    • fillMode (int, default 1)
    Paths
    • pathList (StringList, default empty list)

    org.kde.plasma.minimizeall

    General
    • icon (String, default user-desktop)

    org.kde.plasma.networkmanagement

    General
    • unlockModemOnDetection (Bool, default true) If true request PIN code as soon as modem is detected.
    • manageVirtualConnections (Bool, default false) If true plasma-nm will be able to show and configure virtual connections.

    org.kde.plasma.notes

    General
    • color (String, default yellow)
    • noteId (String, default empty string)

    org.kde.plasma.notifications

    General
    • showNotifications (Bool, default true) Show the notifications
    • showJobs (Bool, default true) Show the jobs progress
    • showHistory (Bool, default true) Show a history of notifications

    org.kde.plasma.pager

    General
    • displayedText (Enum, default 2) The text to show inside the desktop rectangles.
    • showWindowIcons (Bool, default false) Whether to show window icons inside the window rectangles.
    • showOnlyCurrentScreen (Bool, default false) Whether to limit the Pager to the set of windows and the geometry of the screen the widget resides on.
    • currentDesktopSelected (Enum, default 0) What to do on left-mouse click on a desktop rectangle.
    • pagerLayout (Enum, default 0) The layout style used for the presentation.

    org.kde.plasma.panelspacer

    General
    • expanding (bool, default true) If true, the spacer tries to take all the available space in the panel.
    • length (Int, default 0) length in pixels of the spacer. Configuration effective only if expanding is set to false.

    org.kde.plasma.printmanager

    General
    • activeJobs (Bool, default true)
    • completedJobs (Bool, default false)
    • allJobs (Bool, default false)

    org.kde.plasma.private.grouping

    General

    org.kde.plasma.private.systemtray

    General
    • applicationStatusShown (bool, default true) If true, the items of "Application status" category are shown in the systray.
    • communicationsShown (bool, default true) If true, the items of "Communications" category are shown in the systray.
    • systemServicesShown (bool, default true) If true, the items of "System services" category are shown in the systray.
    • hardwareControlShown (bool, default true) If true, the items of "Hardware Control" category are shown in the systray.
    • miscellaneousShown (bool, default true) If true, the items of "miscellaneous" category are shown in the systray.
    • extraItems (StringList, default empty list) All plasmoid items that are explicitly enabled in the systray. It's a comma-separated string list of plasmoid plugin ids.
    • hiddenItems (StringList, default empty list) All items that are hidden, forced always in the popup. It's a comma-separated string list of unique identifiers that are either plasmoid plugin ids or StatusNotifier ids.
    • shownItems (StringList, default empty list) All items that are shown. It's a comma-separated string list of unique identifiers that are either plasmoid plugin ids or StatusNotifier ids.
    • showAllItems (bool, default false) If true, all systray entries will be always in the main area, outside the popup.
    • iconSize (Int, default 1) Default icon size for the systray icons, it's an enum which values mean, Small, SmallMedium, Medium, Large, Huge, Enormous respectively. On low DPI systems they correspond to 16, 22, 32, 48, 64, 128 pixels. On high DPI systems those values would be scaled up, depending on the DPI.
    • pin (Bool, default false) Whether the popup should remain open when another window is activated

    org.kde.plasma.quicklaunch

    General
    • maxSectionCount (Int, default 1)
    • showLauncherNames (Bool, default false)
    • enablePopup (Bool, default false)
    • title (String, default empty string)
    • launcherUrls (StringList, default empty list)
    • popupUrls (StringList, default empty list)

    org.kde.plasma.quickshare

    Appearance
    • copyAutomatically (bool, default false)
    • historySize (int, default 3)

    org.kde.plasma.showdesktop

    General
    • icon (String, default user-desktop)

    org.kde.plasma.systemloadviewer

    General
    • memApplicationColor (Color, default blue)
    • memCachedColor (Color, default green)
    • memBuffersColor (Color, default yellow)
    • cacheDirtyColor (Color, default blue)
    • cacheWritebackColor (Color, default yellow)
    • swapUsedColor (Color, default turquoise)
    • cpuUserColor (Color, default blue)
    • cpuIOWaitColor (Color, default green)
    • cpuSysColor (Color, default red)
    • cpuNiceColor (Color, default yellow)
    • cpuActivated (Bool, default true)
    • cpuAllActivated (Bool, default false)
    • memoryActivated (Bool, default true)
    • swapActivated (Bool, default true)
    • cacheActivated (Bool, default false)
    • setColorsManually (Bool, default false)
    • updateInterval (Double, default 1.0)
    • monitorType (Enum, default 0)

    org.kde.plasma.systemmonitor.cpu

    General
    • sources (StringList, default empty list) Which "systemmonitor" dataengine sources this applet will take data from.

    org.kde.plasma.systemmonitor.diskactivity

    General
    • sources (StringList, default empty list) Which "systemmonitor" dataengine sources this applet will take data from.

    org.kde.plasma.systemmonitor.diskusage

    General
    • sources (StringList, default empty list) Which "systemmonitor" dataengine sources this applet will take data from.

    org.kde.plasma.systemmonitor.memory

    General
    • sources (StringList, default empty list) Which "systemmonitor" dataengine sources this applet will take data from.

    org.kde.plasma.systemmonitor.net

    General
    • sources (StringList, default empty list) Which "systemmonitor" dataengine sources this applet will take data from.

    org.kde.plasma.taskmanager

    General
    • showOnlyCurrentScreen (Bool, default false) Whether to show only window tasks that are on the same screen as the widget.
    • showOnlyCurrentDesktop (Bool, default false) Whether to only show tasks that are on the current virtual desktop.
    • showOnlyCurrentActivity (Bool, default true) Whether to show only tasks that are on the current activity.
    • showOnlyMinimized (Int, default false) Whether to show only window tasks that are minmized.
    • groupingStrategy (Enum, default 1) How tasks are grouped: 0 = Do Not Group, 1 = By Program Name
    • groupPopups (Bool, default true) Whether groups are to be reduced to a single task button and expand into a popup or task buttons are grouped on the widget itself.
    • onlyGroupWhenFull (Bool, default true) Whether to group always or only when the widget runs out of space to show additional task buttons comfortably.
    • groupingAppIdBlacklist (StringList, default empty list) The id's (usually .desktop file names) of applications that should not have their tasks grouped.
    • groupingLauncherUrlBlacklist (StringList, default empty list) The launcher URLs (usually .desktop file or executable URLs) of applications that should not have their tasks grouped.
    • sortingStrategy (Int, default 2) How to sort tasks: 0 = Do Not Sort, 1 = Manually, 2 = Alphabetically, 3 = By Desktop, 4 = By Activity
    • separateLaunchers (Bool, default true) Whether launcher tasks are sorted separately at the left side of the widget or can be mixed with other tasks.
    • maxStripes (Int, default 2) The maximum number of rows (in a horizontal-orientation containment, i.e. panel) or columns (in a vertical-orientation containment) to layout task buttons in.
    • forceStripes (Bool, default false) Whether to try and always layout task buttons in as many rows/columns as set via maxStripes.
    • showToolTips (Bool, default true) Whether to show tooltips when hovering task buttons.
    • wheelEnabled (Bool, default true) Whether using the mouse wheel with the mouse pointer above the widget should switch between tasks.
    • highlightWindows (Bool, default false) Whether to request the window manager highlight windows when hovering corresponding task buttons.
    • launchers (StringList, default empty list) The list of launcher tasks on the widget. Usually .desktop file or executable URLs. Special URLs such as preferred://browser that expand to default applications are supported.
    • middleClickAction (Enum, default 0) What to do on middle-mouse click on a task button.
    • smartLaunchersEnabled (Bool, default true) Whether to show progress and status information on task buttons.
    • indicateAudioStreams (Bool, default true) Whether to indicate applications that are playing audio including an option to mute them.
    • taskHoverEffect (Bool, default true) Whether task buttons should change in appearance when the mouse pointer is above them.
    • maxTextLines (Int, default 0) The maximum number of text lines to show in a task button. 0 means no limit.
    • iconSize (Enum, default 3) The preferred size of task button icons in a vertical task manager.

    org.kde.plasma.timer

    General
    • running (int, default 0)
    • seconds (int, default 0)
    • savedAt (DateTime, default null)
    • showTitle (Bool, default false)
    • title (String, default Timer)
    • showSeconds (Bool, default true)
    • showNotification (Bool, default true)
    • notificationText (String, default Timer finished)
    • runCommand (Bool, default false)
    • command (String, default empty string)
    • predefinedTimers (StringList, default 30,60,120,300,450,600,900,1200,1500,18𝟢0,2700,3600)

    org.kde.plasma.userswitcher

    General
    • showFace (Bool, default false)
    • showName (Bool, default true)
    • showFullName (Bool, default true)
    • showTechnicalInfo (Bool, default false)

    org.kde.plasma.volume

    General
    • maximumVolume (Int, default 100)
    • volumeStep (Int, default 5)
    • volumeFeedback (Bool, default true)

    org.kde.plasma.webbrowser

    General

    org.kde.plasma.worldclock

    General
    • projection (Enum, default Equirectangular)
    • centerMode (Enum, default Daylight)
    • fixedLongitude (double, default 0)
    • showDate (Bool, default false)