MapGuide API Extensions v5.0

Clip API Control The Clip API Control is an ActiveX component that extends the capability of the MapGuide Viewer API by enabling the development of applications that download vector and attribute data to the client's devices. The Control provides a set of public methods that enable the developer to: open and close an SDF, SHP or text file, write a single MapGuide object to the output file, write all objects of a specific layer, within a map window, or a selection set, write coordinates in latitude/longitude or mapping coordinate system, save the keys of output objects so that their attributes may be retrieved from the server, output attributes to text file, including CSV and SQL format, obtain the number of records output, enter a password in order to obtain access to a layer's Geometry or Setup, pause the MapGuide Viewer Control to avoid isBusy() conflicts. When authoring maps, general or password access must be granted to the vertices of the layers which are to be eligible for output; refer to the layer's Security tab. If password access is granted, then the user will be prompted to enter the appropriate password when an object from the layer is selected for evaluation. 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. Ensure that the version of the control that you use matches the version of the SDF Component Toolkit. The control appears as a clickable button: 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 Clip Api About Dialog: The names of files that are currently opened are displayed in the dialog; this feature is commonly used for debugging purposes. An option is provided for closing a file; however, a warning is issued indicating that behaviour of the application may become unpredictable if a file is closed. The closing of files is provided 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 output files on the client's devices. The first method (saveFileDlg) calls presents the standard Windows File Selection dialog box, enabling the client to define the output filename. The second method (saveAsFile) 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, helps to prevent potential malicious damage through unauthorized file modification. If the client has requested to be notified and a saveAsFile call is made, then the following window is presented, defining the file that is about to be opened: 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 Clip Api" ) BoxWidth The width of the control in Twips (Default: 1500 Minimum: 200 ) BoxHeight The height of the control in Twips (Default: 500 Minimum: 50 ) Downloading Data to Files Output files are opened through the saveAsFile() and saveFileDlg() methods by designating a File Number: 0 - ASCII text file 1 - AutoDesk SDF (and SIF file) 2 - ESRI Shapefile (SHP, SHX and DBF) Only one file of each type may be opened at a time. An option is provided for opening text and SDF files in 'create' or 'append' mode, while SHP files may only be opened in 'create' mode. A file remains open until it is closed by the closeFile() method. When an SDF file is opened, an SIF file is also opened as well as an optional KIF file. After the SDF file has been opened, its header must be output with the writeSdfFileHeader() method before any objects can be written to it; this applies to files opened in either 'create' and 'append' modes. When an SHP file is opened for output, corresponding SHX and DBF files are opened as well. The header of SHP files, output via writeShpFileHeader(), requires specification of the type of objects to place in the file, as well as the extents of the file. Shapefiles may only contain one type of object; attempting to write an object not of the type specified in the SHP file's header will lead to unpredictable results and possible system lockup. For SDF and SHP files, it is important to bear in mind the types of coordinates that are being sent to the Control's methods. The application must always send coordinates to the Control in a consistent fashion, either in Mapping Coordinate System (MCS) units or in latitude/longitude. The application may be set up to output the coordinates in either MCS or latitude/longitude by setting the CoordConv parameter when the file header is output: 0 - do not perform coordinate conversion. The coordinates that are sent to the control are output to the SDF or SHP file.   1 - convert from MCS to latitude/longitude (MCStoLL). MCS coordinates are sent to the Control and converted to latitude/longitude prior to output to the SDF or SHP file.   2 - convert from latitude/longitude to MCS (LLtoMCS). Latitude/longitude coordinates are sent to the Control and converted to MCS units prior to output to the SDF or SHP file. The getVertices() method of the MGMapObject class of the MapGuide Viewer API returns coordinates in MCS units, while the getExtents() method and the digitizing methods, return coordinates in latitude/longitude. All coordiates passed to the Control must either be in MCS units or latitude/longitude. A variety of methods are provided for writing objects to SDF and SHP files: writeMapObject() to output a specific MGMapObject   writeMapObjectParams() to output user-supplied parameters of an object, including a collection of vertices   writeMapObjectsAll() to output all objects, or all objects on a specific layer   writeMapObjectsSelected() to output all selected objects, or all selected objects on a specific layer   writeMapObjectsExtents() to output all objects within a specific window, or all objects within a specific window on a specific layer   The number of objects written to an SDF or SHP file may be obtained via a call to getNumberOfObjectsOutput prior to closing the file. The saving of the keys of objects that are written to the output file may be toggled on/off via setSaveKeys(). The switch should be toggled on prior to opening the output file, and toggeled off after closing the output file. The number of keys may be retrieved by getSavedKeyCount() in order to establish a loop so that the individual keys may be obtained through getSavedKey. The keys may then be passed to the server in order to download selected attributes from a database, which may then be written out to a text file. The keys remain saved until they are released through a call to freeSavedKeys(). The output of ASCII files is rather straightforward: the method writeTextRecord() outputs a user-supplied string to the text file, followed by a carriage return (x0D) and line feed (x0A). Before closing the text file, the number of objects output to the file may be obtained via a call to getNumberOfObjectsOutput(). Methods A complete list of the public methods is provided with the Toolkit documentation.

© 2002, Hunter GIS