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
KConfigGroup is not the least thread safe and unfortunately
the KServiceTypeTrader::self()->query() will in doubt create
one if the sycoca database was damaged.
BUG: 303713
REVIEW: 105608
(cherry picked from commit e3edcbcf66b324febcc2014ca4c1fbfa383d8972)
A new global method is exported to perform a remote method call
through D-Bus. The call is always performed async invoking a
callback once the call completed passing through the arguments
received from D-Bus.
Possible code looks like the following:
callDBus("org.kde.kwin", "/KWin", "org.kde.KWin", "currentDesktop", function (desktop) {
print("Current Desktop through D-Bus: ", desktop);
});
REVIEW: 105396
New properties for the current activity and the available
activities plus related signals in scripts. Signals added to
effects.
BUG: 302060
FIXED-IN: 4.9.0
ScreenEdge is changed to emit a signal whenever a screen edge
got activated without an action or effect taking care of it.
A Script can reserve one to many callbacks for an edge and the
callback get's triggered whenever the signal is emitted. On
deconstruction of the Script the edge is unreserved again.
FEATURE: 299275
FIXED-IN: 4.9.0
REVIEW: 104904
A CMake variable is used to specify the name of the binary.
By default this is "kwin" but building for PA changes the
name to "kwinactive". The variable adjusts all names, e.g.
kwinnvidiahack becomes kwinactivenvidiahack.
The remaining usage of kwinrc in core and libs is replaced
by a cmakedefine for the configuration name and all data
installations are moved to the defined name. Dynamic loading
for scripts & co is adjusted for loading based on defined name.
This change allows the side-by-side installation of both kwin
for desktop and kwin for Plasma Desktop without the known
issues like conflicts in config files or missing build options
if kwin desktop is used for Plasma Active.
Likewise the KCMs are not adjusted as they are not intended to
be used for kwinactive.
REVIEW: 104299
BUG: 296084
FIXED-IN: 4.9.0
CCMAIL: active@kde.org
Further debugging functionality for KWin scripts. Added assert
methods validate the to be tested parameter and throw a script
error if the value is not valid.
Following methods are available:
* assert(value)
* assertTrue(boolean)
* assertFalse(boolean)
* assertEquals(expected, actual)
* assertNull(nullValue)
* assertNotNull(notNullValue)
All methods take an additional optional parameter which is used
as the error message if provided.
Methods to validate the number of arguments and types of the
parameters are added and throw syntax or type errors.
REVIEW: 104870
A ScriptEngineAgent is added to monitor the execution of a
script. If it ends it stops the script to free resources.
The same is done in case of an exception, just that in this
case the script takes care of unloading itself.
REVIEW: 104871
The I/O intensive reading of the complete KWin Script
file into a QByteArray is moved into a thread.
Evaluating and setting up the script engine is still
performed in the main thread.
REVIEW: 104782
Searching for the scripts to load is performed in an own
thread including unloading of already loaded scripts which
no longer should be loaded.
To ensure that two threads are not trying to load/unload
at the same time a mutex is added to protect the list of
loaded scripts.
REVIEW: 104768
Workspace emits a signal when the initialization finished and
interested parties can connect to this signal to perform post
init actions. That is everything that does not have to be
performed to have a completely working Window Manager.
As an example loading the scripts is moved into this post init
phase.
REVIEW: 104580
This enables the script wrapper objects to automatically create new
dynamic properties for Client objects so that scripts can register custom
properties.
REVIEW: 104697
If workspace is exported as a context property there seem to be
issues with the signals which are not bound to a property of
WorkspaceWrapper.
This problems seems to be fixable by exporting the workspace
property as a global property on the script engine.
As a side-effect this also resolves the issue with the clientList,
so we can drop the hack again.
REVIEW: 104682
TabGroup is not (and should not be) a QObject which
makes it rather useless in scripting. In order to use
window tabs in KWin scripts the methods to interact
with tabs from Client should be used.
REVIEW: 104685
The documentation is in an XML file which mimics the
XML output of doxygen, which can be converted to
MediaWiki syntax with the tools found in
kde:scratch/graesslin/kwin-scripting-api-generator git
repository.
BUG: 297640
FIXED-IN: 4.9.0
A global method "registerShortcut" is exported to the scripts which
can be used to register a callback to be called when the global
shortcut is triggered.
The shared code between Scripts and Effects is moved into template
functions defined in a new file scriptingutils.h.
REVIEW: 104400
Sometimes Qt is surprising. Apparently QML has problems with a
QList<KWin::Client*> and wants to have a QList<QObject*> which
cannot be used in QtScript.
There ends my dream of having one API for both JavaScript and QML.
So with QtScript it is:
workspace.clientList()
and in QML it is:
workspace.getClientList()
Objects of AnimationData can be instantiated by scripts and expose
all relevant data as properties, so that the ScriptedEffect can
construct the meta value out of it.
This is probably something that could be done a little bit better.
Still need to think about it, so API not yet final.
REVIEW: 103823
The Plasma package structure contains a subdirectory "contents".
Furthermore we have to use locate instead of locateLocal to find
system wide installed packages and adding some debug output for
the case that the script cannot be found.
The scripted effects can define their configuration through a
KConfigXT file in the same way as a packaged Plasmoid. Because of
that the ScriptedEffect also uses the Plasma::ConfigLoader to load
and manage the configuration. The config group used for the scripted
effect is like any other effect the "Effect-name" group.
In difference to the Plasmoid JavaScript API effects are not allowed
to change their configuration.
Simplifies the API. An FPx2 can be defined as a single real value
or a complex object with two real values:
{
value1: 1.0,
value2: 2.0
}
For a default ctor a null value can be used.
Scripted effects follow the Plamsoid package structure and the effect
loader recognizes a scripted effect at the according line in the desktop
file. If it is a scripted effect a different loader is used which
instantiates an object of the ScriptedEffect class. This class inherits
the AnimationEffect and exports the animate method and the EffectsHandler.
Client has a property for demands attention and Workspace
is emitting a signal whenever the demands attention state
of any Client changes.
REVIEW: 104204
This adds extensive support information about the running instance
by printing out all used options, the compositing information
including GL platform, loaded effects and active effects.
The debug output can be retrieved through D-Bus:
qdbus org.kde.kwin /KWin supportInformation
or through a KWin Script (use desktop console):
print(workspace.supportInformation())
REVIEW: 104142
Whenever the KWin configuration is changed, scripting has to unload
scripts no longer loaded and load the scripts which have been added.
For this new methods are introduced to check whether the script is
loaded.
REVIEW: 104037
This is useful for scripts controlled from other KCMs, like e.g.
DesktopChangeOSD which is controlled by the virtual desktop KCM
and should not be listed in the scripts section.
New global method readConfig is exported to QtScript and declarative scripts.
Config is read from a config group stored in kwinrc called "Script-<pluginname>".
For this the ctors of the AbstractScript and derived classes are changed to also
take the pluginname.
For this the Script class is slightly refactored to have a common
base for JavaScript and QML based scripts.
Why QML bindings? This allows to use QML for example for the
desktop change OSD or for fullscreen effects like Present Windows.
Scripts are found by the KServiceTypeTrader and can now be
enabled/disabled. Loading of config is currently disabled. Will
be made available again after scripted effects are merged.
All slots not requiring to be triggered from a QAction are exported.
This means that switchToDesktop is not exported but also not required,
as we have this through the properties.
Needs documentation...
For this a new MetaObject "KWin" is exported to have the
enum ClientAreaOption available in scripts. Unfortunately this
requires duplicating the enum from kwinglobals.h.
Properties are already available thanks to QObject: no need to
export them again. Dropping the toString method allows to remove
the plasma-backportglobal.h file for which Krazy had many complains.
The idea is to extend the wrapper to have it wrapping even more
functions provided by Workspace. Of course it would be possible to
just add the properties to Workspace itself and export this. But I
think complete Workspace is just too powerful to fully expose to
scripts. So a small wrapper around the parts which are usefull for
scripts might make more sense.
This breaks now also the API for Workspace and again it is already
more powerful with less code than before.
Unlike stated at several places in the code it is not difficult to
setup the connections to all Clients.
It would have been nice if the failed attempts to connect the Clients
would not have made it into the code as emitted signals which are
nowhere used. Not to mention that like in all places the signals to
inform that a state changed were emitted before the state changed was
performed.
For this properties are defined in ClientGroup and several methods
are changed to be slots (to be invokable from scripts). On Client
the clientGroup is exported as a property.
The existing wrapper around ClientGroup is dropped as it is no
longer needed. Interestingly it was wrong anyway as it allowed to
construct a new ClientGroup, which has to be done internally.
At the same time the meta declarations get cleaned up a little bit.
Whatever it was, we cannot need a "Lazy Logic (TM)" which is not
documented. And even if it were useful, KWin is not the right place
to develop language extensions to ECMAScript.
Each KWin Script is also exported as a D-Bus object and can be
stopped (destroyed) and started through D-Bus. Output and errors
are emitted as D-Bus signals. That allows external applications
(e.g. Plasma desktop scripting console) to load a script and print
out the output.
The general interface is exported as /Scripting and allows to load
a new script by file. The script is not directly executed but only
loaded. To execute it the run method on the script object has to be
invoked.
Dropping the wrapper around Client and just exporting the Client's
properties. This breaks all existing scripts as it's now e.g.:
client.caption
instead of
client.caption()
But the first one is the more natural one for JavaScript and also
for everyone writing QML as well.
Setters and signals are mostly still missing in client. Other parts
like ClientGroup must be converted to properties, too.
It is possible that adding this build option broke the Scripting
component. This is something that should not happen. Unfortunately
by just ifdefing everything scripting related with scripting enabled
we have build errors. These are caused by the fact that the scripting
code includes e.g. client.h through "./../client.h". At one offending
place I changed that to "client.h", but there is also a client.h in
the scripting directory.
The includes and naming of the scripting files clearly have to be fixed!
workspace.clientSetKeepAbove
client.onSetKeepAbove
Documentation updated. Please refer to kwsapi.html for more details.
svn path=/trunk/KDE/kdebase/workspace/; revision=1191158
client.keepAbove
client.keepBelow
client.setKeepAbove
client.setKeepBelow
For more information on the abovementioned methods, please refer to
scripting/apidocs.xml.
These were added in a response to a feature suggestion from Eike Hein.
Thanks a lot Eike :)
svn path=/trunk/KDE/kdebase/workspace/; revision=1180319
also a small conversion program (it's not small and it's horribly ugly,
but it works under 5ms :) ).
svn path=/trunk/KDE/kdebase/workspace/; revision=1180045
A non-void function, Chelate::equivGen was reaching the end of function
without a return value, which could cause a segmentation fault. FIXED.
svn path=/trunk/KDE/kdebase/workspace/; revision=1177875
Every disorder causes every duration, which ensures the one that stays.
reality is relative. natural is disorder.
[R]obinhood[P]andey
Merging scripting from
^/branches/work/kwin_scripting TO
^/trunk
svn path=/trunk/KDE/kdebase/workspace/; revision=1177865
