yukijoou/kwin
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
kwin/scripting/documentation-global.xml
Martin Gräßlin 2764565f9d Allow Scripts to add menus to the UserActionsMenu 
A script can register a callback through registerUserActionsMenu to be
informed when the UserActionsMenu is about to be shown. This menu calls
the Scripting component to gather actions to add to a Scripts submenu.

The Scripting component now asks all scripts for the actions, which will
invoke the registered callbacks with the Client for which the menu is to
be shown as argument.

The callback is supposed to return a JSON structure describing how the
menu should look like. The returned object can either be a menu item or
a complete menu. If multiple menu items or menus are supposed to be added
by the script it should just register multiple callbacks.

The structure for an item looks like the following:
{
    text: "My caption",
    checkable: true,
    checked: false,
    triggered: function (action) {
       print("The triggered action as parameter");
    }
}

The structure for a complete menu looks quite similar:
{
    text: "My menu caption",
    items: [
         {...}, {...} // items as described above
    ]
}

The C++ part of the script parses the returned object and generates
either QAction or QMenu from it. All objects become children of the
scripts QMenu provided by the UserActionsMenu.

Before the menu is shown again the existing menu is deleted to ensure
that no outdated values from no longer existing scripts are around. This
means the scripts are queried each time the menu is shown.

FEATURE: 303756
FIXED-IN: 4.10
REVIEW: 106285
2012-09-07 07:32:00 +02:00

125 lines
8.9 KiB
XML
Raw Blame History

<?xml version='1.0' encoding='UTF-8' standalone='no'?>
<doxygen xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="compound.xsd" version="1.7.6.1">
<!-- Documentation for global KWin scripting methods. In doxygen XML format as this can be converted to MediaWiki -->
<!-- Use script and XSLT from kde:scratch/graesslin/kwin-scripting-api-generator to generate the documentation -->
<!-- This xml is not meant to be doxygen complient -->
<compounddef>
<compoundname>Global</compoundname>
<briefdescription>Methods and properties added to the global JavaScript object.</briefdescription>
<sectiondef kind="property">
<memberdef kind="property" writable="no">
<type>KWin::Options</type>
<definition></definition>
<argsstring></argsstring>
<name>options</name>
<read></read>
<detaileddescription>Global property to all configuration values of KWin core.</detaileddescription>
</memberdef>
<memberdef kind="property" writable="no">
<type>KWin::Workspace</type>
<definition></definition>
<argsstring></argsstring>
<name>workspace</name>
<read></read>
<detaileddescription>Global property to the core wrapper of KWin.</detaileddescription>
</memberdef>
</sectiondef>
<sectiondef kind="public-func">
<memberdef kind="function">
<type>Q_SCRIPTABLE void</type>
<definition>void KWin::Scripting::print</definition>
<argsstring>(QVariant ... values)</argsstring>
<name>print</name>
<read></read>
<detaileddescription>Prints all provided values to kDebug and as a D-Bus signal</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE QVariant</type>
<definition>QVariant KWin::Scripting::readConfig</definition>
<argsstring>(QString key, QVariant defaultValue = QVariant())</argsstring>
<name>readConfig</name>
<read></read>
<detaileddescription>Reads the config value for key in the Script's configuration with the optional default value. If not providing a default value and no value stored in the configuration an undefined value is returned.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::registerScreenEdge</definition>
<argsstring>(ElectricBorder border, QScriptValue callback)</argsstring>
<name>registerScreenEdge</name>
<read></read>
<detaileddescription>Registers the callback for the screen edge. When the mouse gets pushed against the given edge the callback will be invoked.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::registerShortcut</definition>
<argsstring>(QString title, QString text, QString keySequence, QScriptValue callback)</argsstring>
<name>registerShortcut</name>
<read></read>
<detaileddescription>Registers keySequence as a global shortcut. When the shortcut is invoked the callback will be called. Title and text are used to name the shortcut and make it available to the global shortcut configuration module.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assert</definition>
<argsstring>(bool value, QString message = QString())</argsstring>
<name>assert</name>
<read></read>
<detaileddescription>Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assertTrue</definition>
<argsstring>(bool value, QString message = QString())</argsstring>
<name>assertTrue</name>
<read></read>
<detaileddescription>Aborts the execution of the script if value does not evaluate to true. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assertFalse</definition>
<argsstring>(bool value, QString message = QString())</argsstring>
<name>assertFalse</name>
<read></read>
<detaileddescription>Aborts the execution of the script if value does not evaluate to false. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assertEquals</definition>
<argsstring>(QVariant expected, QVariant actual, QString message = QString())</argsstring>
<name>assertEquals</name>
<read></read>
<detaileddescription>Aborts the execution of the script if the actual value is not equal to the expected value. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assertNull</definition>
<argsstring>(QVariant value, QString message = QString())</argsstring>
<name>assertNull</name>
<read></read>
<detaileddescription>Aborts the execution of the script if value is not null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE bool</type>
<definition>bool KWin::Scripting::assertNotNull</definition>
<argsstring>(QVariant value, QString message = QString())</argsstring>
<name>assertNotNull</name>
<read></read>
<detaileddescription>Aborts the execution of the script if value is null. If message is provided an error is thrown with the given message, if not provided an error with default message is thrown.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE void</type>
<definition>void KWin::Scripting::callDBus</definition>
<argsstring>(QString service, QString path, QString interface, QString method, QVariant arg..., QScriptValue callback = QScriptValue())</argsstring>
<name>callDBus</name>
<read></read>
<detaileddescription>Call a D-Bus method at (service, path, interface and method). A variable number of arguments can be added to the method call. The D-Bus call is always performed in an async way invoking the callback provided as the last (optional) argument. The reply values of the D-Bus method call are passed to the callback.</detaileddescription>
</memberdef>
<memberdef kind="function">
<type>Q_SCRIPTABLE void</type>
<definition>void KWin::Scripting::registerUserActionsMenu</definition>
<argsstring>QScriptValue callback</argsstring>
<read></read>
<detaileddescription>Registers the passed in callback to be invoked whenever the User actions menu (Alt+F3 or right click on window decoration) is about to be shown. The callback is invoked with a reference to the Client for which the menu is shown. The callback can return either a single menu entry to be added to the menu or an own sub menu with multiple entries. The object for a menu entry should be {title: "My Menu entry", checkable: true, checked: false, triggered: function (action) { // callback with triggered QAction}}, for a menu it should be {title: "My menu", items: [{...}, {...}, ...] /*list with entries as described*/}</detaileddescription>
</memberdef>
</sectiondef>
</compounddef>
</doxygen>
Reference in a new issue View git blame Copy permalink