From kwrite-devel Sat Nov 16 21:06:23 2013 From: Alex Turbov Date: Sat, 16 Nov 2013 21:06:23 +0000 To: kwrite-devel Subject: About recent changes in kate/pate Message-Id: X-MARC-Message: https://marc.info/?l=kwrite-devel&m=138463599529772 MIME-Version: 1 Content-Type: multipart/mixed; boundary="--===============0228036065152506503==" --===============0228036065152506503== Content-Type: multipart/alternative; boundary=20cf301cbee0f57fb504eb51af10 --20cf301cbee0f57fb504eb51af10 Content-Type: text/plain; charset=ISO-8859-1 Hi all, and especially Python plugin developers I'd like to share a brief info about (even more) recent changes in Python plugins, so others get know thats going on and be able to fix if smth wrong (still unfixed). 0) as you may know plugins now searched via trader client and described by a corresponding .desktop file w/ 'Kate/PythonPlugin' service type 1) default Python supposed to be version 3, so if your plugin is binilgual a property 'X-Python-2-Compatible=true' must be added to a .desktop file 2) if your plugin is Python2 only you have add also a 'X-Python-2-Only=true' 3) to make some simple dependency checks (from other python modules you plugin may use) add 'X-Python-Dependencies=', where the is a string in format: "python-module-2-import [ | version-info ]". 'version-info' is quite informal text to be displayed as a tooltip over "broken" plugin in the manager's view. To add Python2 only dependencies (i.e. will not be checked if embedded Python is version 3), add the 'X-Python-2-Dependencies' property w/ the same format. Examples could be found at pate/src/plugins/python_console_ipython/katepate_python_console_ipython.desktop (and some other files) It is why 'need_packages' from libkatepate.error module was removed. 4) to avoid .desktop file names clash, all of them have a prefix 'katepate_' 5) pate engine has refactored to be able to load individual plugins (not all at once as it was before). so checking/unchecking a plugin name in the manager will load/unload it immediately (just like C++ plugins manager do). It is why 'Reload plugins' button is not needed anymore and removed. 6) plugins w/ actions now use KXMLGUIClient and "inject" their actions into UI smoothly. Particular place where an action will be injected in UI completely defined by *_ui.rc file. It can be a main menu (maybe w/ submenus), context menu, or a toolbar. You can even control an approximate place to merge your action w/ kate menu using groups (see cmake_utils_ui.rc for example). Every entry of the *_ui.rc may contain attributes to specify action's text, tooltip, whatsthis, icon, shortcut, & etc. It is why @kate.action decorator do not need any parameters :) For advanced usage: also via *_ui.rc file you may control what actions should be disabled/enabled depending on various circumstances. See `commentar.py` plugin for example. This feature can be used instead of some libkatepate.decorators. 7) pate defines an its own menu (named Pate) w/ 3 groups (top, mid, bottom) to merge your actions into (see block_ui.rc, format_ui.rc or commentar_ui.rc for usage examples) 8) the plugin also adds a simple about dialog (About Pate). the main reason I've added it is to show some Python info... authors/credits and other stuff still needs (?) to be added. 9) kate.gui removed completely 10) as you probably know the engine do not add a plugin's directory to the python paths. so the only path is the root of plugins! now plugin may use relative imports to avoid potential namespace (module names) clash. (Philipp can give more details about other benefits of this :) and finally 11) Shaheed, I'm really sorry, but documentation tab was completely removed. The reasons to do that: * code to make a GUI from C++ (where the part of data laid in a Python namespace) is far from clean, obvious and maintainable * it would be much more simple to implement the same, using pure python plugin and add some action to the Help menu * especially taking in account that documentation needed only to python plugin devs and not for end users * honestly, that generated docs are far from being usable (anyway). Partly cuz plugins itself do not provide a good enough docs. Partly cuz read it in a configuration dialog is far from convenient (I'd prefer read docs in a browser... or at least in a slightly bigger window than it was) * and finally it is quite strange (unexpected) to read some API docs in a configuration dialog :) Just assume if someone going to write a brand new Python plugin... and in the middle of typing he wants to recall some details... He must to choose configure kate (!) which will open a modal (!!!) dialog, so he will unable to type while reading and vise versa :))) Some further ideas: * make some more decorators to turn a python function into a signal handler for some popular events of the view/document class. Particularly, to be able to enable/disable actions depending on a selection in a current document, I need to track 'selectionChanged'... & etc. comments? ideas? --20cf301cbee0f57fb504eb51af10 Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable
Hi all, and especially = Python plugin developers

I'd like to share a brief info ab= out (even more) recent changes in Python plugins, so others get know thats = going on and be able to fix if smth wrong (still unfixed).

0) as you may know plugins now searched via trader client and des= cribed by a corresponding .desktop file w/ 'Kate/PythonPlugin' serv= ice type

1) default Python supposed to be version 3, so if you= r plugin is binilgual a property 'X-Python-2-Compatible=3Dtrue' mus= t be added to a .desktop file

2) if your plugin is Python2 only you have add also a 'X-Pyth= on-2-Only=3Dtrue'

3) to make some simple dependency checks= (from other python modules you plugin may use) add 'X-Python-Dependenc= ies=3D<dep>', where the <dep> is a string in format:
=A0 "python-module-2-import [ | version-info ]".
= =A0 'version-info' is quite informal text to be displayed as a tool= tip over "broken" plugin in the manager's view.
=A0 = To add Python2 only dependencies (i.e. will not be checked if embedded Pyth= on is version 3), add the 'X-Python-2-Dependencies' property w/ the= same format.
=A0 Examples could be found at pate/src/plugins/python_console_ipytho= n/katepate_python_console_ipython.desktop (and some other files)
<= div>=A0 It is why 'need_packages' from libkatepate.error module was= removed.

4) to avoid .desktop file names clash, all of them have a prefix = 'katepate_'

5) pate engine has refactored to be able t= o load individual plugins (not all at once as it was before). so checking/u= nchecking a plugin name in the manager will load/unload it immediately (jus= t like C++ plugins manager do). It is why 'Reload plugins' button i= s not needed anymore and removed.

6) plugins w/ actions now use KXMLGUIClient and "inject"= ; their actions into UI smoothly. Particular place where an action will be = injected in UI completely defined by *_ui.rc file. It can be a main menu (m= aybe w/ submenus), context menu, or a toolbar. You can even control an appr= oximate place to merge your action w/ kate menu using groups (see cmake_uti= ls_ui.rc for example). Every <Action> entry of the *_ui.rc may contai= n attributes to specify action's text, tooltip, whatsthis, icon, shortc= ut, & etc. It is why @kate.action decorator do not need any parameters = :)
For advanced usage: also via *_ui.rc file you may control what actions shou= ld be disabled/enabled depending on various circumstances. See `commentar.p= y` plugin for example.
This feature can be used instead of some li= bkatepate.decorators.

7) pate defines an its own menu (named Pate) w/ 3 groups (to= p, mid, bottom) to merge your actions into (see block_ui.rc, format_ui.rc o= r commentar_ui.rc for usage examples)

8) the plugin also = adds a simple about dialog (About Pate). the main reason I've added it = is to show some Python info... authors/credits and other stuff still needs = (?) to be added.

9) kate.gui removed completely

10) as you probably k= now the engine do not add a plugin's directory to the python paths. so = the only path is the root of plugins! now plugin may use relative imports t= o avoid potential namespace (module names) clash. (Philipp can give more de= tails about other benefits of this :)

and finally

11) Shaheed, I'm really sorry, but d= ocumentation tab was completely removed. The reasons to do that:
= =A0 * code to make a GUI from C++ (where the part of data laid in a Python = namespace) is far from clean, obvious and maintainable
=A0 * it would be much more simple to implement the same, using pure = python plugin and add some action to the Help menu
=A0 * especiall= y taking in account that documentation needed only to python plugin devs an= d not for end users
=A0 * honestly, that generated docs are far from being usable (anyway= ). Partly cuz plugins itself do not provide a good enough docs.
=A0=A0= =A0 Partly cuz read it in a configuration dialog is far from convenient (I&= #39;d prefer read docs in a browser... or at least in a slightly bigger win= dow than it was)
=A0 * and finally it is quite strange (unexpected) to read some = API docs in a configuration dialog :) Just assume if someone going to write= a brand new Python plugin...
=A0=A0=A0 and in the middle of = typing he wants to recall some details... He must to choose configure kate = (!) which will open a modal (!!!) dialog, so he will unable to type while r= eading and vise versa :)))


Some further ideas:
* make some more decor= ators to turn a python function into a signal handler for some popular even= ts of the view/document class. Particularly, to be able to enable/disable a= ctions depending on a selection in a current document, I need to track '= ;selectionChanged'... & etc.

comments? ideas?

--20cf301cbee0f57fb504eb51af10-- --===============0228036065152506503== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ KWrite-Devel mailing list KWrite-Devel@kde.org https://mail.kde.org/mailman/listinfo/kwrite-devel --===============0228036065152506503==--