= Development =

[[PageOutline]]

== Licence ==
!ModRana is licensed under GPLv3.

== Source code repository ==
!ModRana source code is hosted on Github:

[https://github.com/M4rtinK/modrana 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).[[br]]
message = "reload"[[br]]
type = None[[br]]
args = None

====== Message string ======
Has the '''ms''' prefix.

''Example:''

{{{
ms:route:reroute:fromStart
}}}
Is handled by the "reoute" module (mod_menu.py).[[br]]
message = "reroute"[[br]]
type = "ms"[[br]]
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).[[br]]
message = "storePoint"[[br]]
type = "ml"[[br]]
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).[[br]]
message = "storePoint"[[br]]
type = "md"[[br]]
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[[br]]
''timeout'' - timeout in milliseconds[[br]]
''caller'' - instance of the calling module[[br]]
''description'' - a short string describing what the timer does[[br]]
''args'' - an optional list of arguments for the callback function[[br]]

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:
{{{
#!python

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 ==
Class and variable names are in !CammelCase.

2 whitespace indentation.

Other than that, [http://www.python.org/dev/peps/pep-0008/ 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 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 [wiki:python2and3CompatiblityEN Making an application compatible with Python 2.5 to 3.2 at the same time] article.


== Porting ==

[wiki:nemoMobile Nemo Mobile]

[wiki:webos WebOS]

[wiki:android Android]

* [wiki:PyOtherSideForAndroid PyOtherSide for Android]

[wiki:BB10 BlackBerry 10]

[wiki:tizen Tizen]

== Guides ==
[wiki:PySideForAndroid PySide for Android] - generic build & usage guide

[wiki:SingleQMLCodebase Supporting multiple component sets with a single QML codebase]

== Development notes ==

 [wiki:modranaIfrastructureImprovemetsEN modRana infrastructure improvements]

 [wiki:pyclutter_notes python-clutter notes]

 [wiki:pygame_touchpad running PyGame on the HP Touchpad]

 [wiki:voiceOutputLocalizationEN voice output localization]

 [wiki:offlineRouting offline routing]

 [wiki:vectorMapRendering vector map rendering]

 [wiki:dataRepositoryManager modRana data repository manager - design document]

 [wiki:alarmLists alarm lists]

 [wiki:maemo5Mapnik testing Mapnik port for Maemo 5 from Marmistrz]

 [wiki:martin_kolman activity overview]