Revision as of 00:16, 29 November 2011

This page is intended to serve as an ongoing development guide in relation to using QML as the engine for LinuxMCE's user interface. We shall outline relevant documents relating to QML as well as specifics for designing a skin. Please note, if you are reading this, then this is in fact an ongoing guide and as such information is apt to change. Personal notes are to be kept in the discussion area of this page, please post only code, links, or other relevant data to UI development. This message will self-destruct in 10 seconds.

QML KnowledgeBase

An Overview of what QML is http://labs.qt.nokia.com/2009/05/13/qt-declarative-ui/ A document on styling and whats important, skinning - http://developer.qt.nokia.com/wiki/QmlStyling

• http://developer.qt.nokia.com/wiki/JavaScript_programmer
• http://doc.qt.nokia.com/4.7-snapshot/qdeclarativeintroduction.html
• http://doc.qt.nokia.com/4.7-snapshot/qdeclarativeelements.html

Stay tuned to this development space

Downloads & Initial setup

• http://qt.nokia.com/downloads The SDK you will need. Previous releases will NOT work

Setting it up

I installed qt creator into home, although the default location is opt. Installing it into home will allow you get up and running right away but if installed into opt you will need to export some paths as described below.

• SVN Checkout of the current /src tree from the svn
• you need to install subversion

sudo apt-get install subversion

• you then check out the source tree by entering this:

svn co http://svn.linuxmce.org/svn/branches/LinuxMCE-1004/src

and the web part like this

svn co http://svn.linuxmce.org/svn/branches/LinuxMCE-1004/web

Next, we install the QTSDK you downloaded.

• Install QT SDK as outlined

You need a qtorbiter- do this by selecting "Orbiters" from within the webadmin pages and select "qOrbiter" from the drop down menu at the bottom. A router reload is probably required. Afterwards, run the qOrbiterGenerator script from a browser:

 http://dcerouter/lmce-admin/qOrbiterGenerator.php?d=+iPK_Device

where +iPK_Device is the device id of the orbiter you just generated.

After you've started QT SDK, some configuration is required to load the orbiter. First, you need to load the project itself. Navigate through your source tree to QOrbiter/Qorbiter_src. In this directory, you will find a .pro file named QOrbiter_src.pro. Open this and it will load the project into qt Creator. It should go without saying, but read the README!

Next, open the qOrbiter project and setup the Build Settings. Do this by clicking the "Projects" button from the left side menu. You need to add to the "Additional arguments:" line for qmake under Build Steps. Do this by clicking the "Details" button to the right of qmake: and additional arguments. These are the current options:

"CONFIG+=for_desktop"    :: windows*, mac,linux desktop
"CONFIG+=for_freemantle" :: maemeo5 devices
"CONFIG+=for_harmattan"  :: harmattan based meego
"CONFIG+=ANDROID"        :: android

Please ensure you include the quotes for the "CONFIG+= whatever"

For example, after adding the above arguments, my "Effective qmake call:" box looks like this, where [username] is my ubuntu login name:

 qmake /home/[username]/src/qOrbiter/qObiter_src/qObiter_src.pro -r -spec linux-g++ "CONFIG+=for_desktop"

Next, ensure 'shadow build' is checked in this same menu. Then you need to set the path to '../build-output'

Next, add the PK_Device of your qOrbiter to the "Run Settings". After clicking on "Projects", near the top will be options for the particular simulators you are using. You will see a "Build" and a "Run" button. Clicking on the "Run" button will display the "Run Settings" page. In the "Arguments:" box, enter:

 -d iPK_Device

Where iPK_Device is the device id of your qOrbiter.

Setting up for android development

Download Necessitas from http://sourceforge.net/p/necessitas/home/necessitas/

Open the project and set it up as above, using

 "CONFIG+=ANDROID"        :: android

There is a bug in necessitas at present. Starting the app as is will give an error - "can't find read elf information".

To fix, click Projects -> Android -> Run

Open the Package configurations section and choose the Application tab. View/ slightly alter the Application Name. This will fix the error.

Lastly, choose 'Use devices qt libs' and use a real device for preference. If you must use the SDK simulator, click 'Install Ministro System Wide...' and download the APK from http://sourceforge.net/projects/ministro.necessitas.p/files/

Special Notes

via irc and TSCHAKeee Note, this was for bootstrapping an Archos 9 tablet. Desktops should not need to do this.

i literally just copy -ax /opt/QtSDK/Desktop/* to the core
either tarballing it up or otherwise
then export PATH=/opt/QtSDK/Desktop/Qt/473/gcc/bin:$PATH
then export LD_LIBRARY_PATH=/opt/QtSDK/Desktop/Qt/473/gcc/lib:$PATH
this can be placed in your .bash_profile
and you can then run qOrbiter

NOTE --Langstonius 08:13, 8 July 2011 (CEST) You shouldnt have to manually tweak the connection parameters at all

You will also need to do a few things to make it interact with your LinuxMCE installation.

• If your installation is up to date, you can add it via the Orbiters page in the webadmin. Otherwise, go to the device tree and add it as a child of the core.
• Quick reload the router. Orbiter Generation is not done the normal way as explained in the next step
• Orbiter Generation is done by qOrbiterGen.php. You need to:

1. copy qOrbiterGenerator.php from the web/lmce-admin/ directory in your svn checkout to the core (in /var/www/lmce-admin) you will be working with.
2. visit this page http://dcerouter/lmce-admin/qOrbiterGenerator.php?d=deviceno (where deviceno should be replaced with the devicenumber of the orbiter in webadmin you want to use)
3. if your device number is found and you entered everything properly, you will see a confirmation.
4. you can regenerate the orbiter in the future from inside the orbiter, no need to visit the page after configuration.

• it should now run

You should then be able to compile / run / hack on qOrbiter

Initial Findings

All research is being done against the current branch of code in the svn. The Big Idea(tm) is do the following: Create a new orbiter using qml as our ui both for its portability and skinning ease of use.

Initial experiments http://wiki.linuxmce.org/index.php/Qml http://forum.linuxmce.org/index.php?topic=11722.0

If you are interested in playing with skinning only you can find the skinning document QOrbiter Development Page.

UI

• Determine to what level we want QML to control the UI vs the c++ code.
• Provide a set of constant objects for UI designers to connect to for data
• Provide basic qml elements for some design objects. Think buttons specifically. These would be referred to as custom qml 'components'
• Develop a base template for styles to follow. This would allow changes to be made globally that would affect all qml objects loaded.
• determine animations sets for our custom qml objects

Following this idea further, its been decided to attempt to define the orbiter varables and data as a complex Data model. While the disadvantage is the complexity of the model, it will expose essentially a simple api to skin designers to access linuxMCE data in their skin, further removing programmatic responsibilities from the ui.

The initial work in this area includes

• creating the needed subclassed models from QAbstractListModel
• creating a purpose specific orbiter generator as the current orbiter gen does more than is needed and is too tightly coupled to the concept of deign_obj's something we wish to get away from.

C++

There will need be be considerable time invested into understanding and picking apart certain functions of the existing orbiter to determine relevance in any new orbiter. These include not just the orbiter itself, but datagrids and how it interacts with other plugins. We will need to translate the functionality to new methods because of the inherent difference in the two ui toolkits. Things such as screen handlers and the callback system will be replaced with the signal and slots mechanisms of Qt and so must be understood to be replaced.

• Datagrids - Custom DataModel has been implemented.
• Screen Handlers - Handled by native qt functions
• Mouse Handlers - Not needed as of yet

=