Lesson 5: Using the GeoCalc Dialogs

Overview

There are several dialogs included with GeoCalc that provide a graphical interface for dealing with the DataSource.  The DataSourceEditor, and ObjectEditor dialogs allow the user to view and modify the DataSource and the objects it contains.  The DataSourcePicker and DatumShiftPicker dialogs provide a graphical way to retrieve objects from the DataSource.

In order to compile the code samples contained in this lesson, it will be necessary to include the WDataSource.h, WDataSourceEditor.h, WDataSourcePicker.h, WDatumShiftPicker.h, and WObjectEditor.h header files.

The DataBrowser class is provided for backward compatibility. In previous releases, it was used to create and display old-style dialogs used to view and modify the DataSource. Those old-style dialogs have been removed from GeoCalc, and this class now simply serves as an alternate interface to the same dialog displayed by the  DataSourceEditor class. We recommend that the DataBrowser class not be used in new code, and we suggest that old code be updated to use DataSourceEditor instead.

The ObjectPicker class is provided for backward compatibility. In previous releases, it was used to create and display old-style dialogs used to view and modify the DataSource. Those old-style dialogs have been removed from GeoCalc, and this class now simply serves as an alternate interface to the same dialog displayed by the  DataSourcePicker class. We recommend that the ObjectPicker class not be used in new code, and we suggest that old code be updated to use DataSourcePicker instead.

Since all of the GeoCalc dialogs require access to a DataSource object, we will start by creating and loading a DataSource.  For more information about using the DataSource, see lesson 4.  

DataSource * dataSource = 0;

dataSource = DataSource::CreateDataSource();

dataSource->LoadFile(L"c:\\bmg\\geocalcpbw\\data\\geocalc.xml");

 

ObjectEditor Dialog

The ObjectEditor allows the user to edit a single definition within the GeoCalc DataSource.  It will not edit specific instances of objects, such as an AngularUnit that was retrieved from the DataSource with a call to GetAngularUnit; it will only edit a definition as it exists in the DataSource.

Most commonly, the user will not explicitly create and display an ObjectEditor.  The ObjectEditor dialog is used by all of the other GeoCalc dialogs to display or edit the definition of an object.  For example, when you double-click on a definition in the DataSourceEditor dialog, an ObjectEditor dialog will be displayed that shows the complete definition of the object and allows the user to edit the object.  However, it is possible for the user to manually create and display an ObjectEditor like this:

ObjectEditor * objEditor = 0;

objEditor = ObjectEditor::CreateObjectEditor(dataSource, DataSource::ProjectedCoordSysType);

objEditor->Show();

This will create an ObjectEditor that will display and allow the user to create and edit a new ProjectedCoordSys.  It is also possible to construct an ObjectEditor that will edit an existing object in the DataSource.  To do this, you would use the alternate form of the ObjectEditor constructor that allows you to specify the issuer and code of the existing object.  Here is what an ObjectEditor for a ProjectedCoordSys looks like:

At the top of the dialog, there are two tabs, "Identification", and "Definition", which is currently selected.  The "Identification" tab contains the information that is common to all Serializable objects, like Name, Remarks, and Identifiers.  The "Definition" tab contains the information that is unique to the specific kind of Serializable object.  Therefore, the "Definition" tab looks different for each type of object that can be displayed with the ObjectEditor.

All of the objects and parameters that define the ProjectedCoordSys can be viewed and edited with this dialog.  For example, one could view or edit the Envelope by clicking on the "i" button next to the "Envelope" field, or one could select a different Envelope from the DataSource by clicking on the "..." button next to the "Envelope field.  The values of the parameters that define the Projection can be edited by entering values in the "Value" fields of the table at the bottom, and the units that express these values can be changed by clicking on the button in the "Units" column of the table.

If the user clicks "OK", the dialog will be closed and any changes made in the ObjectEditor dialog will be saved to the in-memory DataSource.  When this occurs, some checks will be performed to ensure that the values in the ObjectEditor define a valid object.  If an inconsistency is found, then the user will be presented with a dialog describing the inconsistency, and the ObjectEditor will remain open.  In order to make the changes permanent, the DataSource will need to be saved to a file.  See Lesson 4 for information about saving the DataSource to file.  If the user clicks "Cancel", the dialog will be closed, but no changes will be made to the DataSource.

 

DataSourceEditor Dialog

The DataSourceEditor dialog is new for GeoCalc 6.3.  It provides much of the functionality that the dialogs in previous releases provided, but it has a different organization and provides the ability to search the DataSource.  In order to create an instance of the DataSourceEditor class, one must provide an instance of the DataSource and a list of the object types that will be edited by the dialog.  The dialog will be displayed when the Show method is called.  The following lines of code will instantiate and display a DataSourceEditor that will allow the user to browse and edit all of the definitions in the DataSource:

DataSourceEditor * editor = 0;

editor = DataSourceEditor::CreateDataSourceEditor(dataSource, GeoBase::NoType);

editor->Show();

This will display a DataSourceEditor that can be used to browse and edit any definition within the DataSource.  Here is an example of the appearance of the DataSourceEditor;

The Show method will return when the user closes the DataSourceEditor dialog.  Depending on which signature of the Show method is used, the currently selected object may be returned when the user clicks OK.

 

DataSourcePicker Dialog

The DataSourcePicker dialog is new for GeoCalc 6.3.  It provides much of the functionality that the dialogs in previous releases provided, but it has a different organization and provides the ability to search the DataSource.  In order to create an instance of the DataSourcePicker class, one must provide an instance of the DataSource and the type of the object that the dialog will be used to pick.  The dialog will then be displayed when the Show method is called.  The following lines of code will instantiate and display a DataSourcePicker that will allow the user to select from CoordSys definitions:

Serializable * dataSourcePickerSelectedObj = 0;

DataSource::ObjectType objType = (GeoBase::ObjectType)(GeoBase::GeodeticCoordSysType |

GeoBase::ProjectedCoordSysType |

GeoBase::GeocentricCoordSysType |

GeoBase::FittedCoordSysType);

DataSourcePicker * picker = 0;

picker = DataSourcePicker::CreateDataSourcePicker(dataSource, objType);

EDialogState retVal = picker->Show(&dataSourcePickerSelectedObj, &objType);

This will display a DataSourcePicker dialog that can be used to select a CoordSys from the DataSource.  Here is an example of the appearance of the DataSourcePicker dialog:

If the return value of the Show method is eDialogStateSuccess, then an object was successfully selected in the dialog, and dataSourcePickerSelectedObject now holds a pointer to that object.  If the user closes the dialog without selecting an object, then the return value from the Show method will be eDialogStateCancel.

 

DatumShiftPicker Dialog

The DatumShiftPicker dialog is new for GeoCalc 6.3.  It is similar in structure to the DataSourcePicker dialog, but it is customized to make it easy to find the DatumShifts required by a CoordTransform.  This dialog will be described in-depth in Lesson 6: Selecting DatumShifts.

 

Clean Up

Finally, we must clean up after ourselves and free the memory that we have allocated in this lesson using the Disposal::Dispose method:

if(objEditor) Disposal::Dispose(objEditor);

if(editor) Disposal::Dispose(editor);

if(picker) Disposal::Dispose(picker);

if(dataSourcePickerSelectedObj) Disposal::Dispose(dataSourcePickerSelectedObj);

if(dataSource) Disposal::Dispose(dataSource);