Projects/Marble/GeoData/GeoDataUse - Revision history

Tgridel: /* Actual Implemented Use Details */

2011-09-14T21:51:38Z

‎Actual Implemented Use Details

Tgridel at 23:06, 14 August 2010

2010-08-14T23:06:38Z

Tampakrap: fix small issues in last edit

2009-08-12T22:58:36Z

fix small issues in last edit

Tampakrap: add comment on GeoDataFeature being dependent on derived classes

2009-08-12T22:55:18Z

add comment on GeoDataFeature being dependent on derived classes

Tgridel at 22:54, 31 July 2009

2009-07-31T22:54:36Z

Tgridel: moved Projects/Marble/GeoDataUse to Projects/Marble/GeoData/GeoDataUse: moving to GeoData related pages

2009-07-31T22:27:49Z

moved Projects/Marble/GeoDataUse to Projects/Marble/GeoData/GeoDataUse: moving to GeoData related pages

Tampakrap: clarify root -> root document (not root class), hope this is correct

2009-07-31T17:45:11Z

clarify root -> root document (not root class), hope this is correct

Tampakrap: Created page with '== Using GeoData == this page tries to summarise the use of GeoData classes in marble so that its implementation details can match the use cases, and understand if any what issu...'

2009-07-31T17:35:04Z

Created page with '== Using GeoData == this page tries to summarise the use of GeoData classes in marble so that its implementation details can match the use cases, and understand if any what issu...'

New page

== Using GeoData ==

this page tries to summarise the use of GeoData classes in marble so that its implementation details can match the use cases, and understand if any what issues might arise from manipulating them otherwise.

=== Use Cases ===

The use cases identified so far are:

# use any GeoData class as a convenient data holder in APIs.
#: It is expected in that regard that classes have shared data.
#: Let's call this usecase the "ToolClass" usecase.

# use {{class|GeoDataDocument|kdeedu|4.x}} as the root of a "data file" in-memory representation, or even another grouping of information.
#: In this use case, there would exist a "tree" of data matching a logical grouping of information.
#: Let's call this usecase the "DataTree" usecase.

=== Actual Implemented Use Details ===
* GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value.

* Reading a file with {{class|GeoParser|kdeedu|4.X}} creates a tree of data.
This data is manipulated within a stack of {{class|GeoNode|kdeedu|4.x}}s and internally stored in {{qt|QVector}} of value types like QVector<GeoDataFeature>

* PlaceMarkManager creates its copy of any placemark in opened files

* Model classes (implementing Qt's model-view framework that is) serve as interface to GeoData classes, passing them through {{qt|QVariant}}s

TODO others??

=== Common Issues and Pitfalls ===
In the past or present, some issues have appeared and need to be remembered/adressed:

* memory ownership is an issue to be determined depending on use case.

* Compliance with KML spec is a priority, limiting differing needs.

* Parsing code is full of casts.

* storing e.g. an GeoDataPlacemark item in a QVector<GeoDataFeature> looks like a hairy solution, as QVector<T>::append will internally create a new T. In the shared data context this implies that we end up with an element of vector being a GeoDataFeature with a private member being a GeoDataPlacemarkPrivate.

=== Proposals ===
TODO

@@ Line 15: / Line 15: @@
 === Actual Implemented Use Details ===
-* GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value. This is all for the "ToolClass", and not much useful for the "DataTree".
+* GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value. This is all for the "ToolClass", and not much useful for the "DataTree". Pure parameter passing benefits from shallow copy.
 * {{class|FileManager|kdeedu|4.x}} uses {{class|FileLoader|kdeedu|4.x}} which build a {{class|GeoDataDocument|kdeedu|4.x}} from files it opens. It internally uses the {{class|GeoParser|kdeedu|4.x}} classes and framework for xml files. Those files then provided through the {{class|GeoDataTreeModel|kdeedu|4.x}} model.
 * {{class|PositionTracker|kdeedu|4.x}} keeps a document with past positions retrieved from {{class|PositionProviderPlugin|kdeedu|4.x}} plugins.

@@ Line 1: / Line 1: @@
 == Using GeoData ==
-this page tries to summarise the use of GeoData classes in marble so that its implementation details can match the use cases, and understand if any what issues might arise from manipulating them otherwise.
+This page tries to summarise the use of GeoData classes in marble so that its implementation details can match the use cases, and understand if any what issues might arise from manipulating them otherwise.
 === Use Cases ===
@@ Line 17: / Line 17: @@
 * GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value. This is all for the "ToolClass", and not much useful for the "DataTree".
-* Reading a file with {{class|GeoParser|kdeedu|4.X}} creates a tree of data.
+* {{class|FileManager|kdeedu|4.x}} uses {{class|FileLoader|kdeedu|4.x}} which build a {{class|GeoDataDocument|kdeedu|4.x}} from files it opens. It internally uses the {{class|GeoParser|kdeedu|4.x}} classes and framework for xml files. Those files then provided through the {{class|GeoDataTreeModel|kdeedu|4.x}} model.
-This data is manipulated within a stack of {{class|GeoNode|kdeedu|4.x}}s and internally stored in {{qt|QVector}} of value types like QVector<GeoDataFeature>. This is the canonical way to generate a "DataTree".
-* {{class|PlacemarkLoader|kdeedu|4.x}} as used by {{class|PlacemarkManager|kdeedu|4.x}} appends all placemark from files it opens in a {{class|PlacemarkContainer|kdeedu|4.x}} (which is a {{qt|QVector}} of {{class|GeoDataPlacemark|kdeedu|4.x}}). This is another way to create a sort of "DataTree", relying on some "ToolClasses"
+* {{class|PlacemarkManager|kdeedu|4.x}} uses placemarks retrieved from the FileManager, and provides a {{class|PlacemarkModel|kdeedu|4.x}} model which contains them.
-* Model classes (implementing Qt's model-view framework that is) serve as interface to GeoData classes, passing them through {{qt|QVariant}}s
+* {{class|PositionTracker|kdeedu|4.x}} keeps a document with past positions retrieved from {{class|PositionProviderPlugin|kdeedu|4.x}} plugins.
 TODO others??
@@ Line 31: / Line 32: @@
 # memory ownership is an issue to be determined depending on use case.
 # Compliance with KML spec is a priority, limiting differing needs.

@@ Line 34: / Line 34: @@
 # storing e.g. an GeoDataPlacemark item in a QVector<GeoDataFeature> looks like a hairy solution, as QVector<T>::append will internally create a new T. In the shared data context this implies that we end up with an element of vector being a GeoDataFeature with a private member being a GeoDataPlacemarkPrivate.
 # data which may be useful in the context of the "DataTree" use case are completely useless in the context of the "ToolClass" use case. This is true for featureId and other type defining attributes.
-# GeoDataFeature needs a copy constructor per derived class and each derived class has to be a friend of GeoDataFeature. This make the base class dependent on each derived class which is bad design.
+# GeoDataFeature needs a constructor per derived class and each derived class has to be a friend of GeoDataFeature. This makes the base class dependent on each derived class which is bad design.
 === Proposals ===

@@ Line 34: / Line 34: @@
 # storing e.g. an GeoDataPlacemark item in a QVector<GeoDataFeature> looks like a hairy solution, as QVector<T>::append will internally create a new T. In the shared data context this implies that we end up with an element of vector being a GeoDataFeature with a private member being a GeoDataPlacemarkPrivate.
 # data which may be useful in the context of the "DataTree" use case are completely useless in the context of the "ToolClass" use case. This is true for featureId and other type defining attributes.
 === Proposals ===

@@ Line 10: / Line 10: @@
 #: It is expected in that regard that classes have shared data.
 #: Let's call this usecase the "ToolClass" usecase.
 # use {{class|GeoDataDocument|kdeedu|4.x}} as the root document of a "data file" in-memory representation, or even another grouping of information.
 #: In this use case, there would exist a "tree" of data matching a logical grouping of information.
@@ Line 16: / Line 15: @@
 === Actual Implemented Use Details ===
-* GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value.
+* GeoData classes have shared data, in the sense that e.g. copying a GeoDataFeature is a shallow copy, with deep copy happening when one of the instances need to modify a value. This is all for the "ToolClass", and not much useful for the "DataTree".
 * Reading a file with {{class|GeoParser|kdeedu|4.X}} creates a tree of data.
-This data is manipulated within a stack of {{class|GeoNode|kdeedu|4.x}}s and internally stored in {{qt|QVector}} of value types like QVector<GeoDataFeature>
+This data is manipulated within a stack of {{class|GeoNode|kdeedu|4.x}}s and internally stored in {{qt|QVector}} of value types like QVector<GeoDataFeature>. This is the canonical way to generate a "DataTree".
-* PlaceMarkManager creates its copy of any placemark in opened files
+* {{class|PlacemarkLoader|kdeedu|4.x}} as used by {{class|PlacemarkManager|kdeedu|4.x}} appends all placemark from files it opens in a {{class|PlacemarkContainer|kdeedu|4.x}} (which is a {{qt|QVector}} of {{class|GeoDataPlacemark|kdeedu|4.x}}). This is another way to create a sort of "DataTree", relying on some "ToolClasses"
 * Model classes (implementing Qt's model-view framework that is) serve as interface to GeoData classes, passing them through {{qt|QVariant}}s
@@ Line 30: / Line 29: @@
 In the past or present, some issues have appeared and need to be remembered/adressed:
-* memory ownership is an issue to be determined depending on use case.
+# memory ownership is an issue to be determined depending on use case.
-* Compliance with KML spec is a priority, limiting differing needs.
+=== Proposals ===
-* Parsing code is full of casts.
+* Using internally QVectors of pointers may limit the problem of inheritance. This does not limit the ability to use QVectors of Data types when needed elsewhere.
-* storing e.g. an GeoDataPlacemark item in a QVector<GeoDataFeature> looks like a hairy solution, as QVector<T>::append will internally create a new T. In the shared data context this implies that we end up with an element of vector being a GeoDataFeature with a private member being a GeoDataPlacemarkPrivate.
+* Providing some specialised "ToolClasses" like {{class|GeoDataCoordinates|kdeedu|4.x}} would limit the interference between the use cases.
-−
-=== Proposals ===
-TODO