From kwrite-devel  Tue Jan 17 20:19:36 2012
From: Dominik Haumann <dhdev () gmx ! de>
Date: Tue, 17 Jan 2012 20:19:36 +0000
To: kwrite-devel
Subject: Scripting in Kile
Message-Id: <201201172119.37115.dhdev () gmx ! de>
X-MARC-Message: https://marc.info/?l=kwrite-devel&m=132683180304692

Hi Kile developers,

CC: kile mailing list, kate mailing list

I stumbled over the extended-scripting branch you have in your git
repository [1]. Basically, it is awesome that Kile gets scripting support,
just the way like we do it in Kate Part, but it seems there is a lot of
code duplication:
- [2] is a copy of our Cursor & Range API. And ideally, improvements of
  these classes should be included in the Kate API as well.
- view and document objects: Functions like insertText(...) or cursor
  movements are basic document/view opertions, and are provided by Kate
  Part's scripting as well (and if not, it should be added).
- api documentation is copied to a large extent as well.

Now, the obvious reason why Kile copies the code is that the scripting is
entirely internal to Kate Part.

In order to share code, I quickly talked with Christoph and we came up with
the following solution: Since KTextEditor::View/Document derive from QObject,
we suggest to
- add a property to KTextEditor::View (e.g. scriptObject), that creates an
  instance of KateScriptView [3] and returns this pointer as QVariant.
- add a property to KTextEditor::Document (e.g. scriptObject), that creates
  an instance of KateScriptDocument [4] and returns this pointer as QVariant.

Kile can then query the KTE::View/Document for this property to get the
scripting object, and put it into the QScriptEngine (newQObject(...)), just
like you do right now with your own implementations (KileScriptView,
KileScriptDocument).

Now, since Kile certainly wants to provide its own additional functions to
the "view" and "document" object, we have to check how Kile can extend these
objects with own functions. Right now, I do not know how this works. So
this is something that needs to be investigated! (*)


Next, as said, Kile's interface is based on the Cursor & Range api [2]. Since
KateScriptView and KateScriptDocument depend on the Cursor & Range api, Kile
would need to make sure this api is loaded beforehand.
A solution to this is to add a property to KTextEditor::Editor (e.g. scriptingApi),
which is a QStringList of the _content_ of 05_cursor.js and 10_range.js [5, 6].
Kile then can iterate through the QStringList and evaluate each item in the
script engine. And after that add the view and document classes.

Again, Kile might have need of additional functions in the Cursor & Range
classes. This can be done by modifying the prototype, i.e. by evaluating
javascript code like "Cursor.insertSection = function() {...};" (bad example).
So this should not be an issue.


To wrap up: The property system allows Kate Part to deliver all the stuff Kile
needs without braking binary compatibility (KTextEditor interfaces are frozen
in KDE 4.x.).
A benefit would be, that Kate Part internal scripting code can be use by Kile,
Kate, KDevelop etc... And another huge advantage is, that our document
scripting already provides functions that are not publically available via the
KTextEditor interfaces.

We as "the Kate team" want to have a stable scripting interface anyway, so we
would guarantee compatibility across releases.

Given that (*) can be solved, would that be an option for Kile together with
KDE 4.9 (it's too late for KDE 4.8.0)? Would that fit into Kile's release and
feature plans?

For KDE 5.0, we can use "real" KTextEditor interfaces again, providing a better
api to add scripting support...

[1] https://projects.kde.org/projects/extragear/office/kile/repository/revisions/extended-scripting/show/src/scripting
[2] https://projects.kde.org/projects/extragear/office/kile/repository/revisions/extended-scripting/show/src/data/script-plugins
[3] https://projects.kde.org/projects/kde/kde-baseapps/kate/repository/revisions/master/entry/part/script/katescriptview.h
[4] https://projects.kde.org/projects/kde/kde-baseapps/kate/repository/revisions/master/entry/part/script/katescriptdocument.h
[5] https://projects.kde.org/projects/kde/kde-baseapps/kate/repository/revisions/master/show/part/script/data
[6] http://docs.kde.org/stable/en/kdebase-runtime/kate/advanced-editing-tools-scripting.html#advanced-editing-tools-scripting-api

Greetings,
Dominik
_______________________________________________
KWrite-Devel mailing list
KWrite-Devel@kde.org
https://mail.kde.org/mailman/listinfo/kwrite-devel