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.

See here for explanation of signature data types.

org.gnome15.Gnome15

Interface org.gnome15.Service

/org/gnome15/Service

  • Represents the desktop service and is the top level object.
  • May be used to query and set general information about the 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].
  • Switch - Such as invert. A boolean string, i.e. True or False.

Methods

Name In Signature Out Signature Description
GetValue
value=s Get the current value.
GetHint
hint=s Gets the control's hint mask. This will be made up of : 
			
HINT_DIMMABLE = 1 << 0
HINT_SHADEABLE = 1 << 1
HINT_FOREGROUND = 1 << 2
HINT_BACKGROUND = 1 << 3
HINT_HIGHLIGHT = 1 << 4
HINT_SWITCH = 1 << 5
HINT_MKEYS = 1 << 6
HINT_VIRTUAL = 1 << 7
SetValue
value=s
reset_after=d		 Set the current value.
Fade
percentage=d
duration=d
release=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 :-

  • left - align horizontally on the left (within bounds)
  • right - align horizontally on the right (within bounds)
  • center - align central horizontally/vertically (within bounds, depends if 1st or 2nd occurrence)
  • top - align vertically on the top (within bounds)
  • bottom - align vertically on the bottom (within bounds)
  • wrapword - wrap on word boundary
  • wrapchar - wrap on character boundary
  • wrapwordchar - wrap on word/character boundary

For example center,center,wrapword.
UnreserveKey

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

Interface: org.gnome15.Debug

/org/gnome15/Debug

  • Used for debugging Gnome15 (was added to track down memory leaks).
  • Will be removed at some point.

Methods

Name In Signature Out Signature Description
GC

Force garbage collection.
MostCommonTypes

Dumps objects with most instances onto stdout.
Objects type_name=s
Dumps of the specified type onto console.
Referents type_name=s
Dumps referents of the specified type onto console.
Referrers type_name=s
Dumps referrers of the specified type onto console.
ShowGraph

Dump an object graph into the current working directory of the process.