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.

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.

Context Objects

Context objects are basically specialized variables that hold functions and information. The are seperated from other context properties for various reasons outside the scope of this document. Here you will find a major list of the properties and what they provide.

dcerouter

This object represents things that are immediately sent to the router. These normally consist of simple quick commands that will not slow down the user interface in any fashion. You can use these variables and functions knowing that.

moveDirection(String direction) - Moves the cursor on dvd / menu screen in direction "left" ,"right", "up", "down". will be changed to a numerical enum.

dcerouter.moveDirection("left")

jogStream(String jump) - jumps forward in the media in seconds. Contained in quotes with a "-" for back

dcerouter.jogStream("30") or dcerouter.jogStream("-30")

saveCurrentPlaylist(String name, bool saveAsNew) - Save the current playlist. Currently only the public option works. you must enter the playlist name. If you enter an existing playlist name, that playlist will be updated. API subject to change.

dcerouter.saveCurrentPlaylist(textEdit.text, true)

movePlaylistEntry(String , int) - moves the current playlist entry.

dcerouter.movePlaylistEntry("up", index)

manager

This represents the central management, or 'core' of qorbiter. It is responsible for dealing with skins and controlling important parts of the interaction between other components and the ui.

ex: onClicked: manager.setActiveSkin(ponies)

manager.setActiveSkin(name) -sets the active skin to the name passed to it. if the name is invalid, it will return the default skin for the platform
manager.regenOrbiter() - regenerates the current orbiter
manager.setActiveRoom(int room, int ea) - set the current room and entertain area. These variables are in the room list
manager.playMedia(string mediaIdentified) - plays media passed to it with the proper variable. this is available in filedetailsclass.file

dcenowplaying

This object provides now playing data for the current ea. This means it can potentially be different for each room based on the media playing there. It provides a granular set of attributes

ex: text: text: dcenowplaying.qs_mainTitle

Variable List

May not be all inclusive!

qs_mainTitle - long explanation as this can change depending on the type of media.
qs_mainTitle2- passed in the case of certain media that could have a subtitle, or tv shows
b_mediaPlaying - a simple boolean that notifies of current media status
timecode - string representation of the current timecode
duration - string representation of the current duration
qs_subtitle - yet another title. i did say granular didnt i?
qs_screen - the current media screen
filepath - current media path according to linuxmce
qs_playbackSpeed - string of current playback speed
m_iplaylistPosition - int of the current index of the media playing on a playlist. Also, for chapter in a dvd.
mediatitle - another title for cases of something i encountered.
genre - string representation of genre separated by a "|"
tvProgram - string of the current media program, livetv or myth
channel - string of the current channel number
channelID - string of the current channel id, ie knbc, or wkrp
episode - the current episode of the program
album - the album
track
performerlist - list of the performers separated by "|"
synop - the synops of the media. this can be long, plan accordingly
director - list of directors separated by "|"
releasedate
aspect - the aspect ration of the screenshot

filedetailsclass

Context Properties

Context properties are things that allow the skin designer access to underlying information and functions. This can be anything from the current user you want to show up in the box, to complex lists with multiple fields of information.

The format is PropertyName: the type of data it provides.

General

srouterip : string of the router ip. Default is "dcerouter"

deviceid : string representation of device number
style : reference the the current style that is set

User

currentUser: the current orbiter user - Initially set from the configuration file 'config.xml' but changes as the user is changed.
userList: listmodel of all users. Can be dropped into a component to use to select rooms. 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

This specific section covers the home screen. It is unique in that it contains most of the ui elements used to access the rest of the home automation system. for that reason, the concept has not been abandoned and instead made more dynamic. This section will attempt to explain the underlying models and functions for UI designers.

List Models

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 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.

currentRoomLights

This provides by room scenario list for lights. you will need to use your own delegate. a default is provided.

Populated Data Roles - Please note: These names are subject to change to fall in line with their specific component names

names[NameRole] = "username";
names[LabelRole] = "label";
names[ParamRole] = "params";
names[CommandRole] = "command";
names[GotoRole] = "gotoscreen";
names[ImageRole] = "image";

currentRoomMedia

This provides by room scenario list for media. you will need to use your own delegate
Populated Data Roles - Please note: These names are subject to change to fall in line with their specific component names

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

provides by room scenario list for telecom. you will need to use your own delegate

currentRoomSecurity

provides by room scenario list for security. you will need to use your own delegate

Data Grids

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
Device Arrays
Lists

Media Grids

The media grids are folded into the scenarios. Their command groups are subject to change,and thusly you should assume that they are only available with your 'media' list model.

gmediatype : current grid mediatype (to show context based images or who knows )
fileformatmodel : fileformat listmodel connected to grid filtering mechanism
mediatypefilter : mediatype list model connected to grid filtering mechanims

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.

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"
Datagrid: source:"image://datagridimg/"+id
File Details Screen Shot or Album cover: source: "image://filedetailsprovider/"+filedetailsclass.screenshot

Please note more will become available as they are connected to QML.

Developing a qOrbiter skin

File Structure

Files should be arranged in the following manner

<folder>name of the skin

Main.qml

Style.qml

qmldir

Splash.qml

<folder>images

<folder>screens

<folder>components

<folder>js (if used)

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

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

Variables

DEPRECIATE, USE ABOVE SECTIONS

ref dcerouter - used as a reference object to call functions
QString dcemessage - orbiter messaging output for display in string format
srouterip - string of the routerip
ref manager - reference object for qorbitermanager
QObject filedetailsclass - QObject used for holding file information from the router for use in the UI
bool connectedState - represents the current connected state of the device
int iPK_Device - the orbiter device number
QTime screen1time - clock. will display in
QTime currentDateTime - current date and time
---need to outline 'role' data for member data-----
DataModel currentRoomLights - list model of the current room lighting scenarios.
DataModel currentRoomMedia - list model of the current room media scenarios
DataModel currentRoomClimate - list model of current room climate scenarios
DataModel currentRoomTelecom - list model of the current room telecom scenarios
DataModel currentRoomSecurity - list model of the current room security scenarios
DataModel userList - list of the users in the linuxmce system
DataModel roomList - list of the rooms in this home.
DataModel mediaplaylist - the current playlist in list model form
DataModel simpleepg - simple epg model, can sometimes cause router crash.
DataModel playlistModel - list model of the playlist??
DataModel skinsList - list model containing the list of availible and ready skins
ListModel screenshotAttributes - listmodel of attributes correlating to thumbnail/screenshot selection
--------------------------------------------------------------------------------
QObject dcenowplaying - QObject containing the properties of the now playing object for this ea
QColor nowPlayingColor - color of now playing button
int currentcommandgrp - int of the current command group being executed
int gmediaType - int correlating to the mediatype the grid is navigating.
int currentroom - int representing the current EA of the orbiter
QString currentuser - string of the current user

Functions

This will be broken down by section with certain parts relating directly to the screens where they are used

HomeScreen

Special Screen that doesnt have to be implemented, but since it can be considered the start page, certain data is provided to make life easier for everyone.

QOrbiter

Contents