Development

Licence

ModRana is licensed under GPLv3.

Source code repository

ModRana source code is hosted on Github:

​https://github.com/M4rtinK/modrana

Pull requests & patches are welcome ! :)

Structure

ModRana consists of the main modrana.py "kernel", which handles the core functionality, like loading modules, managing the persistent options dictionary, providing platform-independent paths to essential modRana files and folders. It also handles modRana startup and shutdown.

Rest of the functionality is provided by "modules". All modules inherit the ranaModule base class. There are three types of modules:

• device modules - provide platform/device adaptation
• GUI modules - provide the GUI layer, are independent on the device modules
• normal modules - provide various functionality independently on the platform and device modules (or more specifically should not depend on any specific GUI or device module)

Modules can be either file-modules (mod_foo.py) of folder-modules (mod_foo/mod_foo.py). Usually when a file-module grows to an unmaintainable size, it should be converted to a folder module and its functionality split to more files in its folder.

Modules

mod_location

Supports various location data providers and provides location data in a consistent format.

mod_online_services

Wraps various online services for use in modRana.

mod_messages

Handles messaging between modules.

Sending a message

All modules inherit the sendMessage(message) method from the base class.

Handling a message

If a module receives a message, its handleMessage(message, type, args) method is called

Message syntax

[prefix:]module_name:message[:optional_payload]

Plain messages

No prefix.

Example:

menu:reload

Is handled by the "menu" module (mod_menu.py).
message = "reload"
type = None
args = None

Message string

Has the ms prefix.

Example:

ms:route:reroute:fromStart

Is handled by the "reoute" module (mod_menu.py).
message = "reroute"
type = "ms"
args = "fromStart"

Message list

Has the ml prefix. Example:

ml:storePOI:storePoint:12.3;45.6;Camelot

Is handled by the "storePOI" module (mod_menu.py).
message = "storePoint"
type = "ml"
args = ["12.3","45.6","Camelot"]

Message dict

Has the md prefix.

Example:

ml:storePOI:storePoint:lat=12.3;lon=45.6;name=Camelot

Is handled by the "storePOI" module (mod_menu.py).
message = "storePoint"
type = "md"
args = {"lat":"12.3","lon":"45.6","name":"Camelot"}

mod_menu

Menu structure representation and drawing. Currently mostly used by the GTK GUI.

mod_options

GTK GUI options menu structure.

mod_map_data

Batch tile download handling.

mod_log

Debug logging. Currently mostly concerned with redirecting stdout to a file, so that seldom ocuring errors can be easily loged.

mod_cron

Handles timers in a a graphics toolkit independent way. It currently supports GTK and Qt.

Adding a timer

addTimeout(self, callback, timeout, caller, description, args=[]) callback - method that will be called by the timer
timeout - timeout in milliseconds
caller - instance of the calling module
description - a short string describing what the timer does
args - an optional list of arguments for the callback function

The addTimeout method returns an id, that can be used to manipulate the the timer during its lifetime. If the callback method returns False (must be False, not "", 0, [] or similar), the timer is automatically canceled.

mod_icons

Handles icon loading & parametric icon generation.

Most of the functionality of this module is currently used only by the GTK GUI.

Parametric icons

there are six positional parameters:

fill color,fill opacity, outline color, outline opacity, outline width (default 8) and corner radius (default 22, use 0 for right angle)

to use default value, just don't fill in the positional parameter ( len(parameter) == 0 )

EXAMPLE: generic:green;1.0;blue;0.5;10;15

Icon placement

"center" means that we have an icon which we want to center inside the button there re two parameters - icon name and border width

EXAMPLE: center:more;0.1

• icon name: more
• border width: 10% of shortest icon side

mod_

mod_

mod_

Coding style

Class and variable names are in CammelCase.

2 whitespace indentation.

Other than that, ​PEP8

Modules

All class variables should be declared in the init method, the firstTime() (if implemented) should be near the top.

Python 2.5 compatibility

In Fremantle on the N900 only Python 2.5 is available. Therefore, all modRana code needs to be Python 2.5 compatible.

Python 3 compatibility

ModRana has not yet been tested on Python 3, but forward compatibility is desired. For example, 'print' should be always used with braces, to be Python 3 compatible.

Porting

WebOS

Android

Development notes

modRana infrastructure improvements

python-clutter notes

running PyGame on the HP Touchpad

voice output localization

offline routing