GSoC Application Review

[Matěj Laitl]

On 2. 5. 2013 Anmol Ahuja wrote:
> Short description: My
> proposal aims at revamping the Amarok scripting interface, and adding an
> intuitive Script Creator graphical application allowing easy script
> creation by non-coders and coders alike. (...)

Please update the short description to match the proposal as it develops.


> Project Goals:
> 
>    Part I : Setting up Automating Documentation
>
>    Setup Doxygen for automatically generating the Scripting API
>    Documentation wiki content from in-source documentation.

I don't think that wiki will keep to be the hosting for the generated 
documentation. Much rather http://api.kde.org/extragear-api/multimedia-apidocs/amarok/html/ will be the target.

>             Bug 245647 <https://bugs.kde.org/show_bug.cgi?id=245647> -
>             Programmatic access to data objects in QtScript

Oh nice, this is actually the same idea I had with QueryMaker (simplified) 
interface.

> Implementation Details
> **
> QObjects can easily be accessed in QtScript, an ECMAScript based language,
> thanks to the Qt meta-object system. This can be achieved by passing them
> to QScriptEngine::newQObject(), resulting in a QtScript accessible
> QScriptValue with all of the QObject's public slots and signals, functions
> with the Q_INVOKABLE macro, named child objects, and Q_PROPERTY parameters
> (with SCRIPTABLE true) accessible in the script environment.
> **
> In Amarok script, only selected methods are exposed to the QtScript
> environment by creating QObject( and for prototypes, QScriptable ) -
> derived wrappers for the classes to be accessed via Amarok script, to avoid
> cluttering the scripting API and customizing behavior of Amarok classes to
> be script friendly. This gives complete control over functionality made
> available via the scripting API. These wrappers simply call the functions
> of the actual class they link to, which do the real work. So, instead of
> having to design Javascript equivalents of every class, only the wrapper
> QObjects must be made and exported.
> **
> I will be using the following QtScript classes in this GSoC project:
> **
>    -
>    QScriptable - For exposing Amarok classes like Collection,
>    CollectionLocation to the scripting environment. They will be exposed
> using QScriptable and QObject derived classes registered as protoypes via
> QScriptEngine::setDefaultPrototype(). The QScriptable derivation allows
> accessing the scriptable environment's context from within the C++ code,
> allowing access to the calling object and more.
>    -
>    QScriptEngine - Provides the environment for QtScript evaluation. Used
>    for setting custom protoypes of objects, setting global objects in the
>    scripting environment, etc.
> ***
>    -
>    Other basic classes, like:
>    -
>       QScriptContext for Javascript to C++ interaction, like accessing
>       function arguments, accessing the this pointer, etc.
>    -
>       QScriptValue : for translating objects back and forth between
>       QtScript and Qt/ C++.
> **
> Qt Script uses garbage collection to reclaim memory used by script objects
> when they are no longer needed, with this need being determined on the
> basis of the ownership parameter passed as the second argument to
> QScriptEngine::newQObject():
> 
> 1. Qt Ownership (default) - QObject owned by the C++ code, not the script
> engine. That is, it managed according to Qt's object ownership.
> 
> 2. Script ownership - Script engine fully owns the QObject, deleting it
> when there are no references to it in the script code.
> 
> 3. Auto-Ownership - Behaves like Script ownership when no parent, Qt
> Ownership otherwise.

Very, very nice (the whole section above). Although I'm not a QtScript expert, 
this clearly shows that you have a very good understanding of how it works.

> Here are class diagrams for some of the classes I plan on implementing, as
> detailed in the project goals:
> 
> 1. Collection Management and Manipulation
> (...)
> **
> The QueryMaker will be exposed in a simplified form via the QueryFilter
> class, which will use Collections::addTextualFilter and addDateFilter to
> allow the CollectionBrowser search widget like queries. For example:
> 
> title:"carry" AND artist:"Fun."

Well, I think you'll need the code to "decode" the query and I think you can 
just reuse the same exact code used in Collection Browser. (perhaps moving it 
to some shared place)

Otherwise nice.

> 2. AmarokScript::EngineController

I'd prefix the new methods relating to track with "current", e.g. 
currentTrackLength() so that it is clearer.

In summary a very good proposal, Anmol! It is clearly visible that you've put 
a lot of work into it and I think it pays off. :-)

	Matěj