Version 35 (modified by 9 years ago) (diff) | ,
---|
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.
Folder modules also can more easily import parts of their functionality on-demand, thus shorting the modRana startup time.
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_map_layers
Map layer metadata handling. Parses the map layer configuration file, converts the data into MapLayerGroup? & MapLayer? objects and makes them available to other modules.
mod_store_tiles
Handles storage of map tiles either as individual image files or into a sqlite database.
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_route
Handles online and offline routing.
mod_turn_by_turn
Handles turn-by-turn navigation on the currently selected route. Makes sure navigation is properly started, done and shutdown.
mod_
Signals
There is a built-in signaling system, represented by the Signal class in the core.signal shared module. It is is a classic signaling implementation: signals can be declared, connected to and arguments can be passed when the signal is triggered.
Example:
from core.signal import Signal # declare the signal spamArrived = Signal() # create signal handler def handleSpam(spamType): print("delicious %d arrived!" % spamType) # connect handler to the signal spamArrived.connect(handleSpam) # trigger the signal & pass an argument spamArrived("original SPAM")
Coding style
PEP8 without the 80 character per line limitation - please still keep line length reasonable (say ~140 characters max).
Historically modRana used CammelCase in variable names are in and 2 space indentation to allow easier editing of source code on mobile devices and smaller displays, and it is still possible to encounter this in some older modules or old modRana revisions.
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 been modified to be Python 3 compatible. At the same time it still fully supports Python 2.5. Any changes therefore need to work both with Python 2.5 and Python 3. (actually 3.2).
For more info how the Python >= 2.5 & <= 3.2 see the Making an application compatible with Python 2.5 to 3.2 at the same time article.
Porting
- generic build & usage guide
- work-in-progress
Guides
PySide for Android - generic build & usage guide
Supporting multiple component sets with a single QML codebase