[andy/viking.git] / HACKING

This file is meant to summarize the Viking development policies.


Clean commits
=============

Commits/patches should be as fine-grained as possible (and no finer). Every
distinct change should be in its own commit and every commit should be a
meaningful change on its own.

Coding style
============

Naming:
A "module" is a .c file.

Functions starting with "vik_" operate on an object/structure with the module name (see layer.c for an example).
Functions starting with "a_" do not, these modules may have static variables.
Both are followed by the module name. Unless of course the function is static, in which case it may be called anything.

All (well, practically all) global constants and macros start with "VIK_" and then the module name.

Technical notices
=================

In order to activate reference documentation, you have to specify the following configure command line:
$ ./configure --enable-gtk-doc --enable-gtk-doc-html

Then, cd to doc/reference and launch make command.

---

The layers panel holds all the layers. Layers connect to the layers panel via what I call "interfaces" which are really just a 
structure of function pointers and pointers to other bits such as icons. viklayer.c switches between the layers like 
polymorhpism. Anything specific to the layer should (in theory) be found solely in that layer's source file.

There are some ugly hacks in here, like the layers panel holding the viewport and each layer holding the viewport and a 
GtkTreeIter. Unfortunately it was the only way I could figure out to do some things. It would be _much_ easier with a 
object-oriented language.

---

"xmpp" and "ympp" are really misnomers, as they only represent the Meters Per Pixel in UTM mode. Otherwise they are an artificial
zooming system. In expedia mode it represents the "Alti", in Google mode it represents 2^(scale), e.g. 2^0 = 1, 2^8 = 256.

---
Implementing a MapSource

VikMapSource is the "interface", the really base class of the MapSource tree.
In order to implement a MapSource, you have to prefer to derive from VikMapSourceDefault, a less abstract class, adding a property based implementation for some aspects of the VikMapSource interface.
Then, you have to provide implementation for coord_to_mapcoord, mapcoord_to_center_coord and download methods.
Commit	Line	Data
240d1fc8 GB	1	This file is meant to summarize the Viking development policies.
	2
	3
	4	Clean commits
	5	=============
	6
	7	Commits/patches should be as fine-grained as possible (and no finer). Every
	8	distinct change should be in its own commit and every commit should be a
	9	meaningful change on its own.
	10
	11	Coding style
	12	============
	13
50a14534 EB	14	Naming:
	15	A "module" is a .c file.
	16
	17	Functions starting with "vik_" operate on an object/structure with the module name (see layer.c for an example).
	18	Functions starting with "a_" do not, these modules may have static variables.
	19	Both are followed by the module name. Unless of course the function is static, in which case it may be called anything.
	20
	21	All (well, practically all) global constants and macros start with "VIK_" and then the module name.
	22
240d1fc8 GB	23	Technical notices
240d1fc8 GB	24	=================
50a14534	25
e5c58469 GB	26	In order to activate reference documentation, you have to specify the following configure command line:
	27	$ ./configure --enable-gtk-doc --enable-gtk-doc-html
	28
	29	Then, cd to doc/reference and launch make command.
	30
	31	---
	32
50a14534 EB	33	The layers panel holds all the layers. Layers connect to the layers panel via what I call "interfaces" which are really just a
	34	structure of function pointers and pointers to other bits such as icons. viklayer.c switches between the layers like
	35	polymorhpism. Anything specific to the layer should (in theory) be found solely in that layer's source file.
	36
	37	There are some ugly hacks in here, like the layers panel holding the viewport and each layer holding the viewport and a
	38	GtkTreeIter. Unfortunately it was the only way I could figure out to do some things. It would be _much_ easier with a
	39	object-oriented language.
	40
	41	---
	42
	43	"xmpp" and "ympp" are really misnomers, as they only represent the Meters Per Pixel in UTM mode. Otherwise they are an artificial
	44	zooming system. In expedia mode it represents the "Alti", in Google mode it represents 2^(scale), e.g. 2^0 = 1, 2^8 = 256.
2a035b62 GB	45
	46	---
	47	Implementing a MapSource
	48
	49	VikMapSource is the "interface", the really base class of the MapSource tree.
	50	In order to implement a MapSource, you have to prefer to derive from VikMapSourceDefault, a less abstract class, adding a property based implementation for some aspects of the VikMapSource interface.
	51	Then, you have to provide implementation for coord_to_mapcoord, mapcoord_to_center_coord and download methods.