DBUS API

Gnome15 has an exensive DBUS API that allows you to control and extend from any language or platform that has a DBUS binding.There are currently 6 different interfaces that are exposed over DBUS, all using the Session bus under the name org.gnome15.Gnome15. There is also a System Bus service under org.gnome15.SystemService as well, that is used by the kernel driver. This replaces lgsetled as the means of setting the brightness and colour of the various backlights.

The desktop service is provided by the g15-desktop-service application, which manages the pages displayed and provides other service to both DBUS clients and in-process plugins.

org.gnome15.Gnome15

Interface org.gnome15.Service

/org/gnome15/Service

The service manages multiple Devices, each of which may or may not have a Screen associated with it.

Signals

Name

Signature

Description

ScreenAdded

screen_name=s

A new screen has been activated.

ScreenRemoved

screen_name=s

A screen has been deactivated.

Stopping

The desktop service is stopping

Stopped

The desktop service is stopped. Note, you will probably never receive this signal

Started

The desktop service has completed starting up.

Starting

The desktop service is starting up. Note, you will probably never receive this signal.

Methods

Name

In Signature

Out Signature

Description

GetDevices

devices=as

Gets a list of paths of all the detected devices. Each object path will be of the type org.gnome15.Device.

GetScreens

screens=as

Get a list of all screens. A path for each device that is enabled and working will be returned.

GetServerInformation

app_name=s
app_vendor=s
app_version=s
protocol_version=s

Get information about the desktop service implementation.

IsStopping

shutting_down=b

Get if the service is currently stopping.

IsStarting

starting_up=b

Get if the service is currently starting up.

IsStarted

started=b

Get if the service is completely started.

Stop

Stop the desktop service.

Interface org.gnome15.Screen

/org/gnome15/Screen/[deviceUID]

Each supported device that is enabled and connected will have a Screen (any devices disabled or not connected may be enumerated using org.gnome15.Service.GetDevices instead).

The path will be /org/gnome15/Screen/[deviceUID].

The list of current screens may be retrieved use org.gnome15.Service.GetScreens.

A screen consists of many Pages, the paths of which may be retrieved using org.gnome15.Screen.GetPages.

Signals

Name

Signature

Description

Action

binding=b

A bound action has been invoked. This will be as the result of the user pressing a key or key combination.

AttentionCleared

Clears the current attention state. See AttenionRequestioned for more information

AttentionRequested

message=s

The desktop service is now in ‘Attention’ state. This is used by panel components to display some kind of indicator signaling that Gnome15 needs attention, usually when something goes wrong with the driver. The message parameter should contain text describing the problem.

KeysPressed

keys=as

One or more of the extended keys (G, L, D-Pad etc) has been pressed. Each array element will be the Gnome15 key ID. You will only receive these signals if you have requested them using ReserveKey.

KeysReleased

keys=as

One of more of the extended keys (G, L, D-Pad etc) has been released. Each array element will be the Gnome15 key ID. You will only receive these signals if you have requested them using ReserveKey.

PageChanged

page_path=t

A page has changed in some way (e.g. priority updated)

PageCreated

page_path=s
title=s

A new page has been created. page_seq is the new sequence number that may be used to locate the page object via DBUS.

PageDeleting

page_path=s

A page is about to be deleted.

PageDeleted

page_path=s

A page has been deleted and is no longer available.

PageTitleChanged

page_path=s
new_title=s

The title of a page has changed.

Disconnected

driver_name=s

The desktop service is shutting down.

Connected

driver_name=s

A connection to the device has been made.

MemoryBankChanged

new_memory_bank=t

The active memory bank for this device had changed.

Methods

Name

In Signature

Out Signature

Description

AcquireControl

control_id=s
release_after=d
value=s

control_acquisition_path=s

Acquire a backlight or other control. Once acquired, a new object will be available that may be used to change the value of the control or enable effects such as blink or fade. The control remains acquire until is is released, at which point, the original value will be reset.If release_after is non-zero, then the page will be release after that amount of seconds.

An initial value may also be supplied, this should be a string repreentation of the value depending on the type. For a single value (level), use an integer value. For RGB colours, use [R],[G],[B]. For switch controls, use True or False.

The returned path is the path of the org.gnome15.Control object

ClearAttention

Clears the current attention state, i.e. whatever error condition that caused it is now fixed.

ClearPopup

If the visible page is a popup, it will be removed.

CreatePage

id=s
title=s
priority=n

page_path=t

Creates a new page. The returned value is the path for an object of type org.gnome15.Page that can be used to manipulate this new page.The priority values are :-

0 = Invisible

20 = Low (splash screen)

50 = Normal (part of cycle)

99 = High (temporarily high priority)

100 = Exclusive (only 1 at a time allowed)

999 = Popup (overrides everything)

Only these priority numbers should be used. A page should also provide its own ID string that may be used to lookup the page sequence number using something other than the sequence number.

Cycle

times=n

Cycle the screen a number of times. Negative values cycle backwards which will be reflected by the special if supported.

CycleKeyboard

times=n

Cycle either the level or the colour of the keyboard backlight.

GetControlIds

ds=as

Get a list of valid control IDs that may be acquired.

GetDeviceInformation

uid=s
model_id=s
usb_id=s
model_full_name=s

Get information about the device this screen is attached to.

GetDriverInformation

driver_name=s
model_id=s
width=s
height=s
bpp=s

Get information about the driver used for this screen.

GetDeviceUID

uid=s

Get the unique ID of the device this screen is attached to.

GetLastError

message=s

Gets what the last error message was. Used when the service goes into attention state. Used by panel components.

GetMessage

message=s

Gets the current desktop service status message to display. Used by panel components.

GetPageForID

id=s

page_path=s

Gets the path of the object for the page with the given ID (ID is the internal ID used by Gnome15).

GetPages

page_paths=as

Returns an array of object paths for every page this screen is managing.

GetPagesBelowPriority

priority=t

page_paths=as

Returns an array of objects paths for all pages below the provided priority.

GetVisiblePage

page_path=s

Returns the object path of the visible page

IsAttentionRequested

requested=b

Get if the screen is currently in attention state, i.e. an error occured with the driver.

IsConnected

connected=b

Get if the driver is connected.

IsReceiveActions

receive_actions=b

Get if the action events will be received

SetReceiveActions

receive_actions=b

Set if action events will be received.

RequestAttention

message=s

Request that the service go into attention state. The practical effect of this is that panel components will indicate there is a problem with the service.

ReserveKey

key_name=s

Reserve a particular key. You will then be able to receive KeysPressed and KeysReleased signals.

UnreserveKey

key_name=s

Unreserve a previously reserved key. Events for that key will no longer been sent.

Interface: org.gnome15.Device

/org/gnome15/Device/[deviceUID]

Each supported device that is detected will have an instance of this object, regardless of whether it is enabled or disabled, connected or disconnected.

The path will be /org/gnome15/Device/[deviceUID].

The list of current devices may be retrieved use org.gnome15.Service.GetDevices.

Methods

Name

In Signature

Out Signature

Description

Enable

Enable this device if it is disabled. If the drivers connects OK, then a new org.gnome15.Screen object will be created.

Disable

Disable this device if it is enabled. When the driver disconnects, the associated org.gnome15.Screen object and all of it’s pages will be removed.

GetBPP

bpp=t

Get the number of bits per pixel (i.e. the colour depth) for this device.

GetModelFullName

name=s

Get the full name of the model.

GetScreen

screen_path=s

Get the object path of the screen this device is associated with. If the device is disabled or disconnected, this will be empty.

GetSize

width=t
height=t

Gets size of the display

GetUID

uid=s

Get the unique identifier of the device.

GetUsbId

usb_id=s

Get the USB identifier for this device.

Interface: org.gnome15.Control

/org/gnome15/Control/[acquisitionID]

One object will exists for each acquired control.

Controls may be acquired using org.gnome15.Screen.AcquireControl.

The path returned when acquiring will be /org/gnome15/Control/[acquisitionID].

Release controls when you have finished with them.

Control values are handled as strings. Depending on the type of control, the format of this string will be different. The type of control may be determined by using GetHint.

Levels – Single value controls, such as brightness values are strings containing an integer number.

Color – Such as backlight colours are strings in the format [R],[G],[B].

Fade the control to the specified percentage (of the current value). The duration specifies how long the fade should take. If release is true, the control will be release automatically when the fade is complete.

Blink

off_val=s
delay=d
duration=b

Blink the control, swapping between the current value and the new specified value. The delay argument controls how the time between each blink. The duration argument specifies how long the effect should last, use 0 to blink forever.

Reset

Set the control back to the value it was when it was first acquired.

CancelReset

Cancel any any automatic reset that may have been set during SetValue.

Release

Release the control. This object will then be removed, and the control will be returned to the value of the previously acquisition.

Interface org.gnome15.Page

/org/gnome15/PageX

Represents an individual page on one Screen.

Create new pages using org.gnome15.Screen.CreatePage.

All pages created by a connection will be removed when the client disconnects.

Drawing Using Functions

Before using any drawing functions, you must call NewSurface() once. This clears the surface and prepares the page for being to. Then you should call the various drawing functions, such as Arc(), Circle(), Text(). After all shapes have been drawn, commit the surface to the page’s buffer using DrawSurface(). Finally call RedrawPage() to send the screen to the LCD.

Drawing Using Themes

First set the theme SVG using either LoadTheme() to load a file resource, or SetThemeSVG() to set using a string (you must strip the XML declaration if you use this method). Once the theme is loaded, using either SetThemeProperty() to set single properties, or SetThemeProperties() if you want to update more than property at a time. Finally call RedrawPage() to send the screen to the LCD.

Signals

Name

Signature

Description

KeysPressed

keys=as

One or more of the extended keys (G, L, D-Pad etc) has been pressed while this page is visible. Each array element will be the Gnome15 key ID. You will only receive these signals if you have requested them using ReserveKey.

KeysReleased

keys=as

One of more of the extended keys (G, L, D-Pad etc) has been released while this page is visible. Each array element will be the Gnome15 key ID. You will only receive these signals if you have requested them using ReserveKey.

Methods

Name

In Signature

Out Signature

Description

Arc

x=d
y=d
radius=d
startAngle=d
endAngle=d
fill=b

Draw an arc or circle. Angle is in degrees.

CancelTimer

Cancels any timers currently running on this page. For example, timers are created when temporarily changing the priority using SetPriority.

Circle

x=d
y=d
radius=d
fill=b

Draw a circle. Same can be achieved by using Arc with a start angle of 0 and end angle of 360.

CycleTo

Cycle to this page.

Delete

Delete this page. It will be completely removed.

DrawSurface

Draws the current canvas onto the page’s buffer. This must be used before the results of drawing functions are visible.

Foreground

r=n
g=n
b=n
a=n

Sets the foreground color for all drawing operations. Each element is an integer between 0 and 255. The final value is the alpha value, or opacity.

GetId

id=s

Get the page ID (this is not the page sequence number).

GetPriority

priority=n

Get the page’s current priority. See /org/gnome15/Service/CreatePage for an explanation of the priority codes.

GetTitle

title=s

Get the page title. This is the text displayed in plugins such as the Menu plugin.

Image

path=s
x=d
y=d
width=d
height=d

Draw an image from a file at the specified location. If width or height is greater than zero, the image will be resized. No attempt is made to maintain aspect ration on resizing.

ImageData

image_data=ab
x=d
y=d

Draw an image from raw image data at the specified location.

IsVisible

visible=b

Get if this page is the one that is currently visible.

Line

x1=d
y1=d
x2=d
y2=d

Draw a line between two points.

LoadTheme

dir=s
variant=s

Load SVG theme files from the specified directory. See the Plugin Tutorial for more details on how theme files work.

NewSurface

Create a new surface for drawing operations. This method must be called before using Arc,Circle, Text or any other drawing functions.

Raise

Raise the page amongst those that are of the same priority. This will make this page visible only if no other pages of higher priority are visible.

Rectangle

x=d
y=d
width=d
height=d
fill=b

Draw a rectangle.

Redraw

Send the contents of this page to the LCD. This is the final stage after either drawing to the surface or changing theme properties.

ReserveKey

keyname=s

Reserve a particular key. You will then be able to receive KeysPressed and KeysReleased signals.

Restore

Restores drawing attributes to that state they were in when Save() was used.

Save

Save current drawing attributes for restoration using Restore(). This currently includes font, foreground color and line width.

SetFont

font_size=d
font_family=s
font_style=s
font_weight=s

Set the currently active font, as used by Text(). Size should size in approximate points.font_family is the family name, e.g. Sans.

font_style may be one of normal, oblique or italic.

font_weight may be one of normal,ultralight,light,semibold,bold,ultrabold,heavy

Sets the current stroke line width, as used by Line(), Rectangle() etc.

SetPriority

priority=n
revert_after=d
hide_after=d

Change the priority of a page, optionally requesting that it either be reset to it’s previous priority after a set amount of time, or hidden after a set amount of time. This is useful for popup messages. The timer used for reverting may be cancelled using CancelTimers().

SetThemeProperties

properties=a{s,s}

Set a number of theme properties at one time. See the Plugin tutorial for a description of how theme properties work.

SetThemeProperty

name=s
value=s

Set a single theme property. See the Plugin tutorial for a description of how theme properties work.

SetThemeSVG

svg_text=s

Load an SVG theme from a string. Note, this may not include an XML declaration at the top of the content.

Text

text=s
x=d
y=d
width=d
height=d
align/constraint=s

Draw some text at the specified location x,y. If width and height are supplied (both are non-zero), then the text will be clipped within those bounds, and aligned according to align parameter (which may be left,right or center)As from version 0.8.2 (DBUS API version 2.1), the align parameter becomes the contraint parameter. This is a comma separated list of contraints. Current constraints include :-