View source for Kexi/Junior Jobs/Map Browser Form Widget

'''Status: done'''[[Image:Gsoc_2011.jpg|right]]
{{Note|This task was available within sponsored [http://community.kde.org/GSoC/2011/Ideas#Project:_Add_Maps_Support_to_Kexi Google Summer of Code 2011 program]. See [http://community.kde.org/GSoC details].}}

{{Note|This task is a base for [http://www.google-melange.com/gsoc/project/google/gsoc2011/rwicik/15001 Google Summer of Code 2011] by Radek Wicik}}

Map browser widget is a GUI element that displays globe and map for given location.

Proposed and mentored by [[User:Jstaniek|Jstaniek]] 22:37, 17 February 2011 (UTC)

==Definitions==
*'''Kexi Forms:''' one of Kexi core plugins, provided for handling form-based data entry and browsing. A form is consisted of widgets, possibly nested. The implementation of Kexi froms is independent of the Qt Designer forms but similar in many regards. The differences most visible to the user are:
**definitions of kexi forms are stored in the kexi project, i.e. databaseeven if in the future, exporting to separate file could be provided);
**kexi forms offer data-aware widgets, e.g. text boxes, that can be bound to database table or query fields.
*'''Kexi form widgets and factories:''' building blocks of kexi forms, e.g. buttons, text boxes. Technically, kexi widgets can be instantiated through Kexi widget plugins, so called factories. Each widget is of a given class, named using identifier (unique within the whole kexi session). One widget factory can be capable of creating widget instances of one or more classes. Kexi has currently two built-in factories: standard factory and container factory (these would be finally merged into one since there is no point in separation). Built-in factory means that it is always available in the default kexi build and should be thus present in properly packaged kexi application.

==The Goal==
*Deliver extra "Map Browser" widget compatible with Kexi Forms.
*Deliver extra "Map Browser" report element compatible with Kexi Report.
*Deliver "map" element as a flake shape for any Flake-capable app.

==Requirements==
===Kexi Form Widget===
*Design and implement widget and provide it through separate factory using the kexi widget factory API
*All the code should be stored in this tree in calligra/:
 kexi/formeditor/factories/mapbrowser/CMakeLists.txt
 kexi/formeditor/factories/mapbrowser/MapBrowserFactory.h
 kexi/formeditor/factories/mapbrowser/MapBrowserFactory.cpp
 kexi/formeditor/factories/mapbrowser/MapBrowserWidget.h
 kexi/formeditor/factories/mapbrowser/MapBrowserWidget.cpp

*To implement the widget derive from [http://techbase.kde.org/Projects/Marble/MarbleDesigner Marble::MarbleWidget] class
*Do not export the any class, just export the plugin using K_EXPORT_KEXI_FORM_WIDGET_FACTORY_PLUGIN(MapWidgetFactory, mapbrowser) in MapBrowserFactory.cpp
*Class name of the widget should be KexiMapBrowser 
*User-visible name of the widget should be "Map Browser"
*Name prefix of the widget should be "map"
*User-visible description of the widget should be "Map browser"
*class name of the factory should be MapBrowserFactory, and the name passed to the KFormDesigner::WidgetFactory constructor should be "mapbrowser"
*provide translations (i18n()) for all user-visible property names in the factory constructor (see StdWidgetFactory for reference), e.g.
 m_propDesc["longitude"] = i18n("Longitude");
**hide properties "presistentTileCacheLimit", "volatileTileCacheLimit", "mapThemeId" for users (these are too technical)
*the build should be allowed for mapbrowser/CMakeLists.txt only if the marble library, try to copy appropriate FindMarble.cmake file to calligra/cmake/modules
*Testing: proper implementation should after installing provide map browser widget within the widget palette of "Form Design" tab. Inserting the map browser widget should show it, changing properties through the property editor should work, switching to data view mode should display the browser properly and the browser's contents (map) should be available for zooming (using the wheel) and panning (using the mouse move). All these mouse actions should be disabled on the widget in design mode, so the user is able to drag and drop the widget within the form.

====Extensions====
*Data binding: ideally, any data properties should be provided for read/write binding to the database source; however to do this, custom binding GUI in the form designer should be delivered; this is not yet supported by Kexi API
**(Projection, longitude, latitude) tuple could be combined in a single data structure and supported natively in kexi as extra data type for easier binding

====Hints====
*The directory of the forms framework is kexi/kformeditor/, standard factory is implemented in kexi/formeditor/
*The widget factory API is provided by the KFormDesigner::WidgetFactory base class. Inherit it as StdWidgetFactory does. 
*The MarbeWidget is exposed in Qt Designer if you compile it or install appropriate 'devel' package. Trying the MarbleWidget in the Qt Designer can be useful to get accustomed with the features. Similarly, it is suggested to try the Marble application.

===Kexi Report Element===
*Expose the maps to Kexi Reports via the KoReports official API for elements
*The element should inserted into a separate report plugin

TODO

===Flake Shape===
*Expose the maps as a flake shape (for any Flake-capable app)
**Note: Much of this has been already implemented: http://websvn.kde.org/trunk/playground/office/kofficeplugins/geoshape/
**Hint: vector-based maps would be good for printouts
*add support for so called Replacement Images, compare:
 "The OpenDocument Format contains a great idea: so called Replacement Images. 
  The idea is that when you have an embedded object in an ODF file, perhaps not 
  all applications can handle that particular kind of embedded object.
  
  So in addition to the object itself, a saving application has the option to save 
  an extra image of the object alongside of the object itself. That way, the loading 
  application can at least show the contents of the object to the user even if he 
  or she cannot edit the object. " [http://ingwa2.blogspot.com/2011/05/starview-metafiles-in-calligra.html more]

==After implementation==
TODO: we have to update [http://quickgit.kde.org/index.php?p=calligra.git&a=blob_plain&f=README.PACKAGERS calligra/README.PACKAGERS] document to indicate that the plugin must be packaged separately to avoid hard dependency on Marble libraries

[[Category:Kexi Junior Jobs]]



==Development==
This is a notepad for development

===Coding standards===
*[http://techbase.kde.org/Policies/Kdelibs_Coding_Style]

===Assigned Developers===
*Radek Wicik (radoslaw at wicik.pl) within [http://community.kde.org/GSoC GSoC for KDE]

===Source Code Location===
The development happens in the '''calligra''' repository: [http://community.kde.org/Calligra/Building/Building_Calligra#Getting_the_source_code], branch '''kexi-maps-wicik'''. Once it's ready for review, it will be provided for review at http://git.reviewboard.kde.org. Then the code will find its wat to the master branch of calligra.

===Discussions===
*[[/Log-2011-04-08/|(2011-04-28) Log from discussion with Marble team]] -- jstaniek asked about zooming in marble view, from reports and flake perspective it's important; in QWidget world it's different compared to QGraphicsView; probably asking for 2000 pixels or so big rendering scene and setting proper zoom in QPainter would deliver appropriate DPI; Radek will test this idea; also asked about vector support -- they'll have openstreetmap vectors but do not have now; annotations are vector of course (e.g. pathways or names); some testing will show how nice the content looks on print.

*List of proposed properties [[/Properties/|Properties]]

===TODOs===
====Common====
# Select properties to be available in kexi
# Add theme ID selection.
# Marker with Latitude/Longitude variables.
# Serialize Latitude;Longitude and store in db as string.

====Forms====
# connect to db (data source in db)

====Reports====
# connect to db (data source in db)

====Flake====

==Extensions/New Ideas==
This section is for storing ideas that could be added for maps.
===Separate Fields for Longitude Latitude and zoom===
currently coordinates are serialized to text, and stored as text
# store each field in separated real value field
# add new field type Point/Coordinate
===Multiple points on one map===
Currently only one point (map is centred on it) may be displayed, we would like to have multiple points displayed on one map in reports.
point properties:
# coordinates
# custom point icon
# custom point label
===Areas on maps===
# new data type (POLYGON)
# zone/area editor
# multiple zones on one map in reports view.
===KML import/export===
[https://developers.google.com/kml/ https://developers.google.com/kml/]
[https://developers.google.com/kml/documentation/ https://developers.google.com/kml/documentation/]