There are several dialogs included with GeoCalc that provide a graphical interface for dealing with the DataSource. The DataBrowser, DataSourceEditor, and ObjectEditor dialogs allow the user to view and modify the DataSource and the objects it contains. The DataSourcePicker, DatumShiftPicker, and ObjectPicker dialogs provide a graphical way to retrieve objects from the DataSource.
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.
Dim gcDataSource As New DataSource
gcDataSource.LoadFile ("c:\bmg\GeoCalcCOM\data\geocalc.xml")
var
gcDataSource : DataSource;
begin
gcDataSource := CoDataSource.Create;
gcDataSource.LoadFile('c:\bmg\GeoCalcCOM\data\geocalc.xml');
The DataBrowser dialog provides a graphical interface for browsing through and editing the entire DataSource. It allows the user to view, add, remove, modify, and reorganize definitions within the DataSource. In order to display the DataBrowser dialog, one must first create an instance of the DataBrowser class, give it an instance of the DataSource, and then call the DataBrowser.Show method, like this:
Dim browser As New DataBrowser
browser.DataSource = gcDataSource
browser.Show
var
browser : DataBrowser;
begin
browser := CoDataBrowser.Create;
browser.DataSource := gcDataSource;
browser.Show;
The dialog will be shown when the Show method is called, and when the dialog is closed, the Show method will return. The DataBrowser dialog looks like this:
The user can right-click on any of the elements in the DataBrowser, and a context menu will be shown that provides access to the operations that can be performed on that element. For example, if the user right-clicks on the "Ellipsoids" folder, the user will be provided with the options "New Ellipsoid", which will create a new Ellipsoid definition, "New Folder", which will create a new folder under "Ellipsoids", "Delete Folder", which will delete the "Ellipsoids" folder and all of it's contents, and "Delete Contents", which will delete all of the definitions under the "Ellipsoids" folder and leave the folder intact. Furthermore, if the user right-clicks on the "Degrees (deg)" AngularUnit definition, the user will be presented with the options "Delete", which will delete the definition, and "Edit...", which will open an ObjectEditor dialog to view and edit that definition. The ObjectEditor dialog will be discussed below.
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:
Dim objEditor As New ObjectEditor
objEditor.DataSource = gcDataSource
objEditor.ClassType = gcProjectedCoordSys
objEditor.Issuer = "BMG"
objEditor.Code = "UTM-19N"
objEditor.Show
var
objEditor : ObjectEditor;
begin
objEditor := CoObjectEditor.Create;
objEditor.DataSource := gcDataSource;
objEditor.ClassType := gcProjectedCoordSys;
objEditor.Issuer := 'BMG';
objEditor.Code := 'UTM-19N';
objEditor.Show;
This will create an ObjectEditor that will display and allow the user to edit the definition for the UTM 19N ProjectedCoordSys. It is also possible to construct an ObjectEditor that will edit a new object that is not yet defined in the DataSource. To do this, you would just set the Issuer and Code properties to the empty string ("" or ''). Here is what an ObjectEditor for the UTM 19N system 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 ISerializable objects, like Name, Remarks, and Identifiers. The "Definition" tab contains the information that is unique to the specific kind of ISerializable 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 UTM 19N 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. 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.
The ObjectPicker dialog provides a graphical way to retrieve definitions from the DataSource. If the user selects an object with the ObjectPicker, the object will be returned by the Show method. Retrieving a definition with the ObjectPicker is equivalent to retrieving the definition with the appropriate DataSource::Get method. Here is an example of how to create and display an ObjectPicker that will select a ProjectedCoordSys:
Dim objPicker As New ObjectPicker
objPicker.DataSource = gcDataSource
objPicker.ClassFilter = gcProjectedCoordSys
Dim selectedObj As ISerializable
Dim objType As ObjectType
Set selectedObj = objPicker.Show("Select the Projected Coordinate System to use:", objType)
var
objPicker : ObjectPicker;
selectedObj : ISerializable;
selectedObjType : ObjectType;
begin
objPicker := CoObjectPicker.Create;
objPicker.DataSource := gcDataSource;
objPicker.ClassFilter := gcProjectedCoordSys;
selectedObj := objPicker.Show('Select the Projected Coordinate System to use:', selectedObjType);
This will display an ObjectPicker that will allow the user to select from any of the ProjectedCoordSys definitions in the DataSource. Here is an example of what the dialog would look like:
If the user selects an object, then a pointer to that object will be returned by the Show method. If the user selects "Cancel" in the dialog, then the Show method will return NULL.
The DataSourceEditor dialog is new for GeoCalc 6.3. It provides much of the functionality that the DataBrowser dialog provides, but it has a different organization and it has 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 or the ShowWithoutSelection method is called. If the Show method is used, then the object that is selected when the user clicks OK will be returned. The ShowWithoutSelection method will not return any object. 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:
Dim editor As New DataSourceEditor
editor.DataSource = gcDataSource
editor.Caption = "Hello, my name is DataSourceEditor"
editor.ClassType = gcNoType
editor.ShowWithoutSelection
var
editor : DataSourceEditor;
begin
editor := CoDataSourceEditor.Create;
editor.DataSource := gcDataSource;
editor.Caption := 'Hello, my name is DataSourceEditor';
editor.ClassType := gcNoType;
editor.ShowWithoutSelection;
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 or ShowWithoutSelection method will return when the user clicks OK in the DataSourceEditor dialog.
The DataSourcePicker dialog is new for GeoCalc 6.3. It provides much of the functionality that the ObjectPicker dialog provides, but it has a different organization and it has 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 ICoordSys definitions:
Dim picker As New DataSourcePicker
picker.DataSource = gcDataSource
picker.Caption = "Hello, my name is DataSourcePicker"
picker.ClassType = gcGeodeticCoordSys Or gcFittedCoordSys Or gcGeocentricCoordSys Or gcProjectedCoordSys
Dim retVal As DialogState
Dim selectedObj As ISerializable
Dim objType As ObjectType
retVal = picker.Show(selectedObj, objType)
var
selectedObj : ISerializable;
selectedObjType : ObjectType;
picker : DataSourcePicker;
retVal : DialogState;
begin
picker := CoDataSourcePicker.Create;
picker.DataSource := gcDataSource;
picker.Caption := 'Hello, my name is DataSourcePicker';
picker.ClassType := gcFittedCoordSys or gcGeocentricCoordSys or gcGeodeticCoordSys or gcProjectedCoordSys;
retVal := picker.Show(selectedObj, selectedObjType);
This will display a DataSourcePicker dialog that can be used to select an ICoordSys from the DataSource. Here is an example of the appearance of the DataSourcePicker dialog:
If the return value of the Show method is drsSuccess, then an object was successfully selected in the dialog, and s 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 drsCancel.
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.