MapGuide API Extensions v5.0

  

Read SDF Control

The Read SDF Control is an ActiveX component that extends the capability of the MapGuide Viewer API by enabling the development of applications that require the import of SDF data from client devices. The Control provides a set of public methods that enable the developer to:

  • open and close an SDF file,
  • obtain the SDF's header information, including the number of objects and extents,
  • read the keys of the objects in the SDF file into the memory, and then to retrieve the keys in order for processing,
  • read an object from the SDF into the component, either by its key value or by its sequence in the SDF file,
  • obtain the key, name, URL, type and vertices of an object read into the component
  • enter a password in order to obtain access to a layer's Geometry or Setup,
  • pause the MapGuide Viewer Control to avoid isBusy() conflicts.

This control requires the MapGuide SDF Component Toolkit DLL (sdfcomtk.dll) to be registered on the client's computer. The client must download the Toolkit from the Autodesk website (www.mapguide.com), install the Toolkit, and register the DLL by entering the following command in the Windows Run menu: 

 C:\Windows\System\Regsvr32.exe  C:\Program Files\Autodesk\SdfComTk4\Bin\sdfcomtk.dll

Alternatively, you could permit the user to download the DLL from your website. Version 4.0 of the control uses SDF Component Toolkit v4.0; Version 5.0 requires SDF Component Toolkit v5.0.

The control appears as a clickable button:

HgisReadSdf

The button may be sized through the BoxWidth and BoxHeight parameters while the label is set through the ButtonLabel parameter. Clicking on the button pulls up the Read SDF About Dialog:

HgisReadSdfMenu

An option is provided for closing an SDF file that has been opened; a warning is issued indicating that behaviour of the application may become unpredictable if a file is closed. The control allows display of header information obtained from an open SDF file:

HgisReadSdfListFile

The parameters of the last object that was read into memory may also be displayed in a dialog:

HgisReadSdfListVerts

The dialog form of closing an input file and clearing the last SDF object read into the control are features that are provided for debugging purposes. These options may also be used for those applications that require the user to close the file, or when an error has occurred and the application is unable to close the file.

The control provides two methods to open input files on the client's devices. The first method (openFileDlg) calls presents the standard Windows File Selection dialog box, enabling the client to define the output filename. The second method (openAsFile) allows an application to open a file without requesting a user-supplied filename, allowing the programmer to develop applications that open layer-specific files. The client is provided with an option to be notified when a file is opened if the file was not specified by the user through the standard Windows File Selection dialog. This option, which can only be set by the client, allows the user to determine which SDF files that the application may access, regardless of the application's coding. If the client has requested to be notified and a openAsFile call is made, then the following window is presented, defining the file that is about to be opened:

HgisReadSdfWarn

Loading the Control

Instructions for implementing the control on web pages are provided with the Toolkit documentation.

Parameters

Name Description
AboutDlgStatus Toggles the ability to display the About Dialog Box by clicking on the Control. A value of "0" prevents the display of the Dialog, while a value of "1" enables display (Default: "1" )
ButtonLabel The label to appear on the button (Default: "Hgis Read Sdf" )
BoxWidth The width of the control in Twips (Default: 1500 Minimum: 200 )
BoxHeight The height of the control in Twips (Default: 500 Minimum: 50 )

Loading Data from an SDF File

Input files are opened through the openAsFile() and openFileDlg() methods. Only one SDF file may be opened at time. The isFileOpen() method may be used to determine whether an input file has been opened, while the getOpenFileName() retrieves the full pathname of the opened file. A file remains open until it is closed by the closeFile() method.

Once an SDF file has been opened, the following methods may be used to examine header information:

  • getTotalObjects() to obtain the total number of objects. Pass "Point", "Polyline" or "Polygon" to obtain the number of objects of a particular class;
  • getMinX(), getMinY(), getMaxX(), and getMinY() to retrieve for the extents of the SDF file;
  • getProjection() to yield the projection system
  • getPrecision() to obtain the precision of the data (32 or 64);
  • getDescription() to get the description;
  • getMaxKeyLength() to obtain the maximum length of keys;
  • getVersion() to pass the version of the SDF file.

There are basically two ways that the SDF objects may be retrieved. The first method involves reading the keys contained within the SDF file into the ActiveX component via the readObjectKeys() or readObjectKeysExtents() methods. The type of objects to process may be limited by passing "Point", "Polyline" or "Polygon". A loop may then be set up to obtain each of the keys by using the getSavedKey() method. The SDF object with a particular key may then be read into the Control by the readObjectWithKey() method. Once an object has been read into the control, the following commands may be issued to transfer the information from the Control to the application:

  • getObjectKey()
  • getObjectName()
  • getObjectLink()
  • getObjectType()
  • getObjectMinX()
  • getObjectMinY()
  • getObjectMaxX()
  • getObjectMaxY()
  • getObjectNumObjects()
  • getObjectNumVerts()
  • getObjectVertices()
Keys are retained by the component until a new set of object keys are read or the method freeObjectKeys() is called.

The second method to retrieve SDF objects involves looping through the SDF file sequentially. First, obtain the total number of objects, or the number of objects in a particular class. Then use the readObjectWithPosition() method to read the Nth object in the SDF file into the Component. Once the object has been successfully read, you may use the previously listed methods to transfer data from the Component to the application.

The first method of object retrieval requires that a KIF file accompany the opened SDF file, while the second method does not require a KIF file. If a KIF file does exists, the first method is recommended as it searches through the SDF file much faster. To determine whether an opened SDF file has a KIF, use the isKifFileOpen() method.

Methods

A complete list of the public methods is provided with the Toolkit documentation.

 © 2002, Hunter GIS