Skip to content

Improve KWin scripting tutorial

Natalie Clarius requested to merge (removed):nclarius-master-patch-32585 into master

I made a number of additions and corrections to the KWin scripting tutorial with things that either tripped me up when I first got into it or which I saw asked about by others.

Main points:

  • where to find the output from the console or installed scripts
  • warn that the console output window will not show any output and how to retrieve it instead
  • warn that configuration button will not be visible without manual intervention on older Plasma version and how to fix it
  • clearer depiction of package structure
  • use metadata.json instead of deprecated metadata.desktop
  • add info that installed scripts must be enabled after installation
  • more info about where to find installed scripts and how to publish them
  • new section with basic tutorial on how to set up a user configuration (declaration + UI)

To do (in MRs in the future):

  • more thorough explanation and example of a configuration menu (in progress)
  • once the merging of the abstract client and toplevel classes and the renaming of 'client' to 'window' is reflected in the API, change the section on clients
  • the actual API documentation! It’s bad. Unfortunately I don’t understand enough about how the interiors of the scripting module work to act on this myself (yet), but:
    • Many elements that actually are exposed to the API are just completely missing from the documentation - most notably the pretty important workspace.clientList(). And just print out a client object and look at all the available but undocumented keys, e.g. stacking order.
    • Half of the elements don’t have any description at all.
    • Some entries could use more thorough explanation and usage examples, in particular the global objects and functions such as options, registerShortcut and callDBus.
    • Some of the documented functionality is broken.
    • Some information appears to be outright incorrect, e.g. workspace.activateClient(client) doesn’t seem to work, but workspace.activeClient = client does?
    • Not as a matter of the documentation but the API itself, there are a few functions and properties that would useful to have exposed to the API but currently aren’t (e.g. a client list sorted in stacking order and a client maximized property would be useful).

Suggestions for changes and further additions are welcome.

Edited by Natalie Clarius

Merge request reports