MapGuide API Extensions v5.0

  

Read SHP Control

The Read SHP 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 ESRI Shapefile (SHP) data from client devices. The Control provides a set of public methods that enable the developer to:

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

An effort has been made to replicate the methods of the HgisReadSdf ActiveX Control in order to maximize flexibility in developing applications that require reading vector objects from the client's devices.

The control appears as a clickable button:

HgisReadShp

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:

HgisReadShpMenu

An option is provided for closing an SHP 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 SHP file:

HgisReadShpListFile

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

HgisReadShpListVerts

The database record of the last object read into memory may also be displayed in a dialog:

HgisReadShpListRecs

The dialog form of closing an input file and clearing the last SHP 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 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 SHP 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:

HgisReadShpWarn

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 SHP File

An ESRI Shapefile consists of a minimum of two files: an SHP file containing the vector data and an SHX file which is an indexing file. The control checks for the presence of both files, as well as for a DBase (DBF) file that contains attributes. It is not necessary to have a DBF file associated with a SHP file; however, if one is not present, then all of the DBF-related methods will return false or null values. All objects in an ESRI Shapefiles are required to be of the same shape type. The record number of objects starts at 1 and must be sequential; the first object in the SHP file is associated with the first record in the DBF file. In essence, the key of the object is its record number.

Most SHP file contains objects similar to an SDF file: Points, Polylines and Polygons, including PolyPolylines and PolyPolygons. A MultiPoint object represents a set of points. It is retrieved in the same manner as the other object types; however, it is left to the programmer to provide code that will deconstruct the MultiPoint object to a set of Point objects for use with the MapGuide Viewer API methods.

Input files are opened through the openAsFile() and openFileDlg() methods. Only one SHP 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 SHP 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", "Polygon" or "MultiPoint" to obtain the number of objects of a particular class;
  • getMinX(), getMinY(), getMaxX(), and getMinY() to retrieve for the extents of the SDF file;
  • getVersion() to pass the version of the SHP file.
  • getFileType() to determine the type of objects in the file.

The programmer can determine if a DBF file is present by issuing the isDbfFileOpen() method. If a DBF file is present, the following methods are available:

  • getNumDbfRecords() to obtain the number of records in the DBF file;
  • getNumDbfColumns() to retrieve the number of columns in the DBF file;
  • getDbfColumnName(), getDbfColumnType(), getDbfColumnLength() and getDbfColumnDecimals() to yield particulars on the DBF columns;
  • setKeyColumn(), setNameColumn() and setLinkColumn() to specify which columns in the DBF contain the object's key, name and link.
  • getKeyColumn(), getNameColumn() and getLinkColumn() to determine which columns in the DBF have been assigned as the object's key, name and link.
  • readDbfRecord() to read a specific DBF record into the component;
  • getDbfColumnValue() to retrieve the column contents of a DBF record previously read into the component.

There are basically two ways that the SHP objects may be retrieved. The first method involves reading the keys contained within the SHP file into the ActiveX component via the readObjectKeys() or readObjectKeysExtents() methods. The type of objects to process may be limited by passing "Point", "Polyline", "Polygon" and "MutliPoint". A loop may then be set up to obtain each of the keys by using the getSavedKey() method; the retrieved 'keys' are the record numbers of the objects. The SHP 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() (affected by setKeyColumn())
  • getObjectName() (affected by setNameColumn())
  • getObjectLink() (affected by setLinkColumn())
  • 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 SHP objects involves looping through the SHP 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 SHP 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.

If an entire SHP file is to be read, then the second method is most efficient. If the objects to be extracted must fall within a specified minimum bounding rectangle (MBR), then the first method must be used.

Methods

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

 © 2002, Hunter GIS