Difference between revisions of "QOrbiter"

From LinuxMCE
Jump to: navigation, search
(Where To Find It)
 
(47 intermediate revisions by 8 users not shown)
Line 1: Line 1:
 +
{{versioninfo}}
 
[[category:QML]]
 
[[category:QML]]
 
[[category:QOrbiter]]
 
[[category:QOrbiter]]
qOrbiter is a new LinuxMCE orbiter designed to run on a multitude of devices as well as provide flexible skinning options to make it truly one's own. The purpose of this document now is for documentation of the app moving forward, followed by it being a reference for creating ones own skin
+
[[Category: Programmer's Guide]]
 +
qOrbiter is a new LinuxMCE orbiter designed to run on a multitude of devices as well as provide flexible skinning options to make it truly one's own. The purpose of this document is for documenting the existing skin api of the application moving forward.
 +
 
 +
=Where To Find It=
 +
The latest version of qOrbiter can always be found on the developers  [http://langstonball.com/downloads/category/1-qorbiter-downloads site].
 +
== Installation Instructions ==
 +
qOrbiter for Android should be installed from [http://192.168.80.1/lmce-admin/index.php?section=orbitersWin the local core].
  
 
=Concept=
 
=Concept=
Line 8: Line 15:
 
So, for example lets take the context property "deviceid". This property is added to the QML engine at runtime so that it can be used to provide the current device id of the orbiter. So in effect, this is a macro or keyword if you will that enables access to the underlying LinuxMCE data. As is one of the goals, no programming is required. One of the goals of this document is to outline all of these properties for easy reference in making a new skin.
 
So, for example lets take the context property "deviceid". This property is added to the QML engine at runtime so that it can be used to provide the current device id of the orbiter. So in effect, this is a macro or keyword if you will that enables access to the underlying LinuxMCE data. As is one of the goals, no programming is required. One of the goals of this document is to outline all of these properties for easy reference in making a new skin.
  
=Context Properties=
+
=Colors & Styling=
 +
Colors such as background and button colors should be set in the style file of the qml skin. See 'Style.qml' for reference on setting up property aliases.
  
 +
Examples include:
  
The format is PropertyName: the type of data it provides.
+
  property color stageBG: "slategray"
==General==
+
*'''srouterip''' : string of the router ip. Default is "dcerouter"
+
  
*'''deviceid'''  : string representation of device number
+
Qualified color references include:
*'''style'''      : reference the the current style that is set
+
*SVG named colors [http://www.december.com/html/spec/colorsvg.html Reference]
 +
*Web color notation #112233
  
==User==
+
==Skins==
*'''currentUser''': the current orbiter user - Text name
+
skinsList: listmodel of skins found for the build
*'''userList''': listmodel of all users
+
One should always check the official doc's to see what methods are supported for setting properties.
There is also a component: UserListComponent.qml
+
This component is totally skinnable and at its core contains a listmodel of all the users. In addition, it sets the current user whenever clicked.
+
  
==Location==
 
*'''currentroom''': the current room / ea
 
*'''roomList''': list of ea's rooms
 
*'''component''': RoomSelector.qml
 
Selects and set the current room and changes listmodels accordingly
 
  
==Home Screen==
 
  
==List Models==
+
=Developing a qOrbiter skin=
These are prepared in c++ and provided to the QML. If you are creating a skin, you will use these variables to call certain arrays
+
QOrbiter utilizes QML's ease of creating themes. The current engine used for themes supports the following
of objects like  scenarios, or userlists. This makes it easier for the designer, as they information will be populated and they only need to fill in the variable.
+
*Screen Size based themes:
 +
** "small"  4" diagonal size and up
 +
** "medium" 7" diagonal size and up
 +
** "large"  10" diagonal size and up
 +
** "xlarge" 13" diagonal size and up
 +
*DPI based themes
 +
** "ldpi"    120
 +
** "mdpi"    160
 +
** "tvdpi"  213
 +
** "hdpi"    240
 +
** "xhdpi"  320
 +
** "xxhdpi"  480
 +
** "xxxhdpi" 640
 +
*Platform based themes
 +
** "linux"
 +
** "ios"
 +
** "android"
 +
** "windows"
 +
** "raspbian"
  
===currentRoomLights===
 
This provides by room scenario list for lights. you will need to use your own delegate. a default is provided. <br>
 
  
'''Populated Data Roles''' - Please note: These names are subject to change to fall in line with their specific component names <br>
+
==File Structure==
*names[NameRole] = "username";
+
With the use of the QQmlFileselector we have a file structure that allows for a very flexible approach to themes. If you note the various keys above, such as "medium" or "android", they correlate to different folders that can exist in a skin. For example: In the default skin, there are special folders for small screens that will only show up and be used in the case of small devices. There is nothing the user needs to do to enable this as the specific variant is selected automatically at runtime, if it is available.
*names[LabelRole] = "label";
+
*names[ParamRole] = "params";
+
*names[CommandRole] = "command";
+
*names[GotoRole] = "gotoscreen";
+
*names[ImageRole] = "image";
+
  
 +
In the linuxMCE source tree, the qml skins can be found at
 +
<path-to-source>/qOrbiter/qOrbiter_src/qml/skins
 +
It is important to note that this is the base folder for all skins and if you view this folder, you will see the 'default' skins folder inside.
 +
* If you provide your own path to the skins folder, please ensure that you have at least the 'default' folder.
 +
** The default qOrbiter installation does not ship with the skins folder, so you should obtain it from http://git.linuxmce.org
  
===currentRoomMedia===
+
==== Providing a path to your own skins. ====
This provides by room scenario list for media. you will need to use your own delegate <br>
+
The default qOrbiter does not ship with skins. With non mobile devices, you can provide a custom path to skins. This allows you to develop the UI without needing to re-compile the application (or needing a full development setup)
'''Populated Data Roles''' - Please note: These names are subject to change to fall in line with their specific component names<br>
+
* To set your own path, you need to pass a special command line option: -x <path/to/your/skins>
*names[NameRole] = "username";
+
*names[LabelRole] = "label";
+
*names[ParamRole] = "params";
+
*names[CommandRole] = "command";
+
*names[GotoRole] = "gotoscreen";
+
*names[ImageRole] = "image";
+
  
===currentRoomClimate===
 
provides by room scenario list for climate. you will need to use your own delegate
 
  
===currentRoomTelecom===
+
Files should be arranged in the following manner. Please note that you are not required to design your skin according to the default skin. This will be a description of how the default skin works and is organized.
provides by room scenario list for telecom. you will need to use your own delegate
+
:<folder>name of the skin, in this case 'default'
 +
::Main.qml  The main entry file
 +
::Style.qml  Contains default properties for the skin
 +
::qmldir    a file required by Qt for internal purposes.
 +
:::<folder>images
 +
:::<folder>screens
 +
:::<folder>components
 +
:::<folder>js (if used)
  
===currentRoomSecurity===
+
You will notice the presence of other folders with the special character "+" i.e "+large". These are the variant folders. When the QML directories are parsed, if a selector matches one of the specially designated folders denoted with the "+", it will select the content from that folder.
provides by room scenario list for security. you will need to use your own delegate
+
  
==Data Grids==
+
For example, in the 'screens' folder, there are also two additional directories. "+small" and "+large"  Content from these folders are used to serve up specific versions of screens for small and large screen devices, which will automatically be detected and the file selector internally.
Datagrids will encompass these specific views and more to come. Currently, they are very basic and dont accept any styling but this will change over time.
+
  
*File List
+
'''Order of selectors'''
*Device Arrays
+
With many different selectors it is important to keep in mind how they affect each other. They have a cascading effect meaning you can combine them, but the file structure must respect that order.
*Lists
+
# Screen Size
 +
# DPI
 +
# Resolution
 +
# Language
 +
# In case of linux based systems, UNIX or POSIX (?)
 +
# OS
 +
# Distribution (ubuntu, opensuse, etc)
  
==Media Grids==
+
==Images==
*'''gmediatype'''       : current grid mediatype (to show context based images or who knows )
+
Images can be loaded in multiple ways and will be discussed here in the future. All that is required is to use the indicated format for local vs remote loading of images
*'''fileformatmodel''' : fileformat listmodel connected to grid filtering mechanism
+
*Local:  '''source: "../../../img/icons/kmix.png"'''
*'''mediatypefilter''' : mediatype list model connected to grid filtering mechanims
+
** Note that the file selector will load images as if they are from the base directory
 +
** Make sure to put platform specific images in the correctly denoted folders
 +
*Datagrid:  '''source:"image://datagridimg/"+id'''  
 +
*File Details Screen Shot or Album cover: '''source: "image://filedetailsprovider/"+filedetailsclass.screenshot'''
  
==Colors==
 
Colors such as background and button colors should be set in the style file of the qml skin. See 'Style.qml' for reference on setting up property aliases.
 
  
Examples include:
+
==Adding to the filestructure==
 +
#in Qt Creator, in the source-tree, right-click on 'QML'
 +
#In the contextmenu select add new
 +
#choose the template 'QML' -> QML File
 +
#name it 'main'
 +
#for Path, click on choose, in the new window select 'new folder' give it the name of your new skin (in lower case letters, otherwise it wont work!) and click on 'choose'
 +
#click continue and then done
 +
#in Qt Creator, in the source-tree, right-click on 'QML'
 +
#In the contextmenu select add new
 +
#choose the template 'QML' -> QML File
 +
#name it 'Style'
 +
#for Path, click on choose, in the new window select the folder you created in step 5.
 +
#click continue and then done
 +
#in sources -> qorbitermanager.cpp find tskinModel->addSkin and add a new entry for your skin using the directory name.
 +
You can now fill main and style files with the content of the same files found in the QML/desktop/default directory.
 +
Or another pair of main.qml and Style.qml set.
 +
After this is done you can alter the Style.qml to you likings and your skin can be selected from the styles-menu inside qOrbiter
  
property color stageBG: "slategray"
+
NOTE: You only see the QML files of the target you selected under project. i.e. if you select for_desktop, you will see the desktop QML files. If you choose for_android, you will see the QML files for Android. What is shown for a target, is defined in the .pro file of qOrbiter.
  
Qualified color references include:
+
==Special Qml Pages==
*SVG named colors [http://www.december.com/html/spec/colorsvg.html Reference]
+
The following pages are 'special' in that they serve critical function for the qml application.
*Web color notation #112233
+
These should be located in the main directory of your skin.
 +
i.e. - <mySkin>/Main.qml
 +
 +
*Main.qml
 +
:The entire purpose of this qml page is to be the logic behind the runtime of the application. What this means
 +
:is that this is the highest level page and signals and slots should be added here. Also, the page loading
 +
:functions need to be implemented here for hiccup free operation. For example, the main.qml file thats is
 +
:part of the default skin serves as the loader for Screens, emits signals, and provides a constant object for
 +
:other logic.
 +
 +
*Splash.qml
 +
:This is the loading page that is initially shown when the application starts. It is not intended to be used by skin designers as the logic is very specific. However, acceptable replacements will be included.
  
=Skins=
+
*Style.qml
skinsList: listmodel of skins found for the build
+
:This qml file is unique because it does nothing more than serve as a static obeject that contains the description of
One should always check the official doc's to see what methods are supported for setting properties.
+
: your skin, both for users and the actual application. its where screen sizes are defined, scaling functions can be
 +
:located, and anything else relating to the visual style of the application as relating to your skin
  
==Images==
+
==Example==
 +
This is a small example on how to get started, using the existing skins.
 +
 
 +
First, you need to checkout the skin from out git repository
 +
git clone https://git.linuxmce.org/linuxmce/linuxmce.git /usr/src/linuxmce-src
 +
 
 +
Next, you try to start qOrbiter with the commandline switch to point to your downloaded stuff
 +
qOrbiter -x /usr/src/linuxmce-src/src/qOrbiter/qOrbiter_src/qml/skins
 +
 
 +
This should show the same qOrbiter layout as before. Quit qOrbiter, and we make a small change to verify that we are indeed using the QML code in /usr/src directory structure. For example, change line 82 in MainLayout.qml from
 +
buttonText: qsTr("Sleeping Menu")
 +
to
 +
buttonText: qsTr("Alarm Menu")
 +
 
 +
followed by a start of qOrbiter with the -x command line switch as specified above, ie.
 +
qOrbiter -x /usr/src/linuxmce-src/src/qOrbiter/qOrbiter_src/qml/skins
  
Images can be loaded in multiple ways and will be discussed here in the future.
+
Once you have verified that your changes indeed end up in your qOrbiter, you no longer need to exit and restart qOrbiter, but press <F5> to refresh the QML inside of qOrbiter.

Latest revision as of 05:38, 30 June 2016

Version Status Date Updated Updated By
710 Unknown N/A N/A
810 Unknown N/A N/A
1004 Unknown N/A N/A
1204 Unknown N/A N/A
1404 Unknown N/A N/A
Usage Information

qOrbiter is a new LinuxMCE orbiter designed to run on a multitude of devices as well as provide flexible skinning options to make it truly one's own. The purpose of this document is for documenting the existing skin api of the application moving forward.

Where To Find It

The latest version of qOrbiter can always be found on the developers site.

Installation Instructions

qOrbiter for Android should be installed from the local core.

Concept

The concept of this document is to provide those wishing to create new skins the needed access to LinuxMCE data through properties and context objects. While I will not be discussing what they are here, they are discussed in the scope of QML documentation which is a pre-requisite to skinning and working with Qorbiter.

So, for example lets take the context property "deviceid". This property is added to the QML engine at runtime so that it can be used to provide the current device id of the orbiter. So in effect, this is a macro or keyword if you will that enables access to the underlying LinuxMCE data. As is one of the goals, no programming is required. One of the goals of this document is to outline all of these properties for easy reference in making a new skin.

Colors & Styling

Colors such as background and button colors should be set in the style file of the qml skin. See 'Style.qml' for reference on setting up property aliases.

Examples include:

property color stageBG: "slategray"

Qualified color references include:

  • SVG named colors Reference
  • Web color notation #112233

Skins

skinsList: listmodel of skins found for the build One should always check the official doc's to see what methods are supported for setting properties.


Developing a qOrbiter skin

QOrbiter utilizes QML's ease of creating themes. The current engine used for themes supports the following

  • Screen Size based themes:
    • "small" 4" diagonal size and up
    • "medium" 7" diagonal size and up
    • "large" 10" diagonal size and up
    • "xlarge" 13" diagonal size and up
  • DPI based themes
    • "ldpi" 120
    • "mdpi" 160
    • "tvdpi" 213
    • "hdpi" 240
    • "xhdpi" 320
    • "xxhdpi" 480
    • "xxxhdpi" 640
  • Platform based themes
    • "linux"
    • "ios"
    • "android"
    • "windows"
    • "raspbian"


File Structure

With the use of the QQmlFileselector we have a file structure that allows for a very flexible approach to themes. If you note the various keys above, such as "medium" or "android", they correlate to different folders that can exist in a skin. For example: In the default skin, there are special folders for small screens that will only show up and be used in the case of small devices. There is nothing the user needs to do to enable this as the specific variant is selected automatically at runtime, if it is available.

In the linuxMCE source tree, the qml skins can be found at

<path-to-source>/qOrbiter/qOrbiter_src/qml/skins

It is important to note that this is the base folder for all skins and if you view this folder, you will see the 'default' skins folder inside.

  • If you provide your own path to the skins folder, please ensure that you have at least the 'default' folder.
    • The default qOrbiter installation does not ship with the skins folder, so you should obtain it from http://git.linuxmce.org

Providing a path to your own skins.

The default qOrbiter does not ship with skins. With non mobile devices, you can provide a custom path to skins. This allows you to develop the UI without needing to re-compile the application (or needing a full development setup)

  • To set your own path, you need to pass a special command line option: -x <path/to/your/skins>


Files should be arranged in the following manner. Please note that you are not required to design your skin according to the default skin. This will be a description of how the default skin works and is organized.

<folder>name of the skin, in this case 'default'
Main.qml The main entry file
Style.qml Contains default properties for the skin
qmldir a file required by Qt for internal purposes.
<folder>images
<folder>screens
<folder>components
<folder>js (if used)

You will notice the presence of other folders with the special character "+" i.e "+large". These are the variant folders. When the QML directories are parsed, if a selector matches one of the specially designated folders denoted with the "+", it will select the content from that folder.

For example, in the 'screens' folder, there are also two additional directories. "+small" and "+large" Content from these folders are used to serve up specific versions of screens for small and large screen devices, which will automatically be detected and the file selector internally.

Order of selectors With many different selectors it is important to keep in mind how they affect each other. They have a cascading effect meaning you can combine them, but the file structure must respect that order.

  1. Screen Size
  2. DPI
  3. Resolution
  4. Language
  5. In case of linux based systems, UNIX or POSIX (?)
  6. OS
  7. Distribution (ubuntu, opensuse, etc)

Images

Images can be loaded in multiple ways and will be discussed here in the future. All that is required is to use the indicated format for local vs remote loading of images

  • Local: source: "../../../img/icons/kmix.png"
    • Note that the file selector will load images as if they are from the base directory
    • Make sure to put platform specific images in the correctly denoted folders
  • Datagrid: source:"image://datagridimg/"+id
  • File Details Screen Shot or Album cover: source: "image://filedetailsprovider/"+filedetailsclass.screenshot


Adding to the filestructure

  1. in Qt Creator, in the source-tree, right-click on 'QML'
  2. In the contextmenu select add new
  3. choose the template 'QML' -> QML File
  4. name it 'main'
  5. for Path, click on choose, in the new window select 'new folder' give it the name of your new skin (in lower case letters, otherwise it wont work!) and click on 'choose'
  6. click continue and then done
  7. in Qt Creator, in the source-tree, right-click on 'QML'
  8. In the contextmenu select add new
  9. choose the template 'QML' -> QML File
  10. name it 'Style'
  11. for Path, click on choose, in the new window select the folder you created in step 5.
  12. click continue and then done
  13. in sources -> qorbitermanager.cpp find tskinModel->addSkin and add a new entry for your skin using the directory name.

You can now fill main and style files with the content of the same files found in the QML/desktop/default directory. Or another pair of main.qml and Style.qml set. After this is done you can alter the Style.qml to you likings and your skin can be selected from the styles-menu inside qOrbiter

NOTE: You only see the QML files of the target you selected under project. i.e. if you select for_desktop, you will see the desktop QML files. If you choose for_android, you will see the QML files for Android. What is shown for a target, is defined in the .pro file of qOrbiter.

Special Qml Pages

The following pages are 'special' in that they serve critical function for the qml application. These should be located in the main directory of your skin. i.e. - <mySkin>/Main.qml

  • Main.qml
The entire purpose of this qml page is to be the logic behind the runtime of the application. What this means
is that this is the highest level page and signals and slots should be added here. Also, the page loading
functions need to be implemented here for hiccup free operation. For example, the main.qml file thats is
part of the default skin serves as the loader for Screens, emits signals, and provides a constant object for
other logic.
  • Splash.qml
This is the loading page that is initially shown when the application starts. It is not intended to be used by skin designers as the logic is very specific. However, acceptable replacements will be included.
  • Style.qml
This qml file is unique because it does nothing more than serve as a static obeject that contains the description of
your skin, both for users and the actual application. its where screen sizes are defined, scaling functions can be
located, and anything else relating to the visual style of the application as relating to your skin

Example

This is a small example on how to get started, using the existing skins.

First, you need to checkout the skin from out git repository

git clone https://git.linuxmce.org/linuxmce/linuxmce.git /usr/src/linuxmce-src

Next, you try to start qOrbiter with the commandline switch to point to your downloaded stuff

qOrbiter -x /usr/src/linuxmce-src/src/qOrbiter/qOrbiter_src/qml/skins

This should show the same qOrbiter layout as before. Quit qOrbiter, and we make a small change to verify that we are indeed using the QML code in /usr/src directory structure. For example, change line 82 in MainLayout.qml from

buttonText: qsTr("Sleeping Menu")

to

buttonText: qsTr("Alarm Menu")

followed by a start of qOrbiter with the -x command line switch as specified above, ie.

qOrbiter -x /usr/src/linuxmce-src/src/qOrbiter/qOrbiter_src/qml/skins

Once you have verified that your changes indeed end up in your qOrbiter, you no longer need to exit and restart qOrbiter, but press <F5> to refresh the QML inside of qOrbiter.