Public Member Functions | Properties
FileManager Class Reference

Provides functionality for opening and examining different types of datasources. More...

List of all members.

Public Member Functions

bool BuildGdalOverviews (string Filename)
 Builds overviews for a raster datasource managed by GDAL.
bool ClearGdalOverviews (string Filename)
 Clears overviews for a raster datasource managed by GDAL.
bool get_CanOpenAs (string Filename, tkFileOpenStrategy OpenStrategy)
 Checks whether specific open strategy is applicable for a given datasource.
string get_ErrorMsg (int ErrorCode)
 Gets the description of the specific error code.
bool get_HasGdalOverviews (string Filename)
 Returns true if specified raster datasource managed by GDAL has overviews.
bool get_HasValidProxyForGrid (string Filename)
 Returns true if specified grid datasource has proxy images for its rendering.
bool get_IsGrid (string Filename)
 Checks whether specified datasource is grid, i.e. non-RGB raster datasource which require synthetic colour scheme for rendering.
bool get_IsRgbImage (string Filename)
 Checks whether datasource is RGB image.
bool get_IsSupported (string Filename)
 Checks whether the datasource is supported (can be opened) by MapWinGis.
bool get_IsSupportedBy (string Filename, tkSupportType supportType)
 Checks whether datasource is supported by specified subsystem of MapWinGIS.
bool get_IsVectorLayer (string Filename)
 Checks whether specified datasource is vector layer that can be opened by MapWinGIS.
tkFileOpenStrategy get_OpenStrategy (string Filename)
 Determines optimal open strategy for datasource.
object Open (string Filename, tkFileOpenStrategy OpenStrategy=tkFileOpenStrategy.fosAutoDetect, ICallback cBack=null)
 Tries to open datasource with specified name.
OgrLayer OpenFromDatabase (string connectionString, string layerNameOrQuery)
 Opens a layer or runs a query against OGR spatial database.
Image OpenRaster (string Filename, tkFileOpenStrategy OpenStrategy, ICallback cBack=null)
 Tries to open raster datasource (either RGB image or grid) with specified name.
Shapefile OpenShapefile (string Filename, ICallback cBack=null)
 Tries to open shapefile with specified name.
OgrDatasource OpenVectorDatasource (string Filename)
 Tries to open specified file as OGR datasource.
OgrLayer OpenVectorLayer (string Filename, ShpfileType preferedShapeType=ShpfileType.SHP_NULLSHAPE, bool forUpdate=false)
 Tries to open specified file as OGR layer.
bool RemoveProxyForGrid (string Filename)
 Remove proxy images generated for grid rendering.

Properties

string CdlgFilter [get]
 Gets expression to be set for OpenFileDialog.Filter property to select supported datasources.
string CdlgRasterFilter [get]
 Gets expression to be set for OpenFileDialog.Filter property to select raster datasources (both RGB images and grids).
string CdlgVectorFilter [get]
 Gets expression to be set for OpenFileDialog.Filter property to select vector datasources.
ICallback GlobalCallback [get, set]
 Gets or sets a Callback object which handles progress and error messages.
string Key [get, set]
 A text string associated with object. Any value can be stored by developer in this property.
int LastErrorCode [get]
 Gets the code of last error which took place inside this object.
string LastOpenFilename [get]
 Gets filename of the last datasource that was attempted to be opened.
bool LastOpenIsSuccess [get]
 Gets a value indicating whether the last attempt to open a datasource was successful.
tkFileOpenStrategy LastOpenStrategy [get]
 Gets a strategy that was used on last attempt to open datasource.
string SupportedGdalFormats [get]
 Gets string with the list of supported GDAL formats.

Detailed Description

Provides functionality for opening and examining different types of datasources.

Traditionally MapWinGIS uses at least 3 classes to open different types of datasources: Shapefile, Image and Grid. There are different ways to open GDAL-based raster datasources: they can be opened for editing by Grid class or for rendering by Image class. Also rendering of grids can be performed directly or by creating temporary proxy image. FileManager was designed to hide all these details from user providing a mechanism to open and display any type of datasource with least amount of code.

A. Opening datasources.

To open any supported datasource the following code can be used:

 var fm = new FileManager();
 var obj = fm.Open("some_filename", tkFileOpenStrategy.fosAutoDetect, null);

Perhaps receiving an object of unknown type isn't very impressive, here is more practical example which adds open datasource to the map:

  var fm = new FileManager();
  var obj = fm.Open("some_filename", tkFileOpenStrategy.fosAutoDetect, null);
  if (obj != null && fm.LastOpenIsSuccess)
  {
     int handle = axMap1.AddLayer(obj, true);
     if (handle != -1)
     {
         MessageBox.Show("Layer was added to the map. Open strategy: " + fm.LastOpenStrategy.ToString());
     }
     else
     {
         MessageBox.Show("Failed to add layer to the map: " + axMap1.get_ErrorMsg(axMap1.LastErrorCode));
     }
  }
  else
  {
     MessageBox.Show("Failed to open datasource: " + fm.get_ErrorMsg(fm.LastErrorCode));
  }

FileManager.Open returns instance of Shapefile class for shapefile datasources and instance of Image class for any raster datasources both RGB images and grids. In case of grids it may temporarily open a Grid object to create proxy image for it but then closes it. To exclude casting of opened object to known type use: FileManager.OpenRaster and FileManager.OpenShapefile. The code below shows how to cast opened object to appropriate type.

 string filename = "some_filename.ext";
 var fm = new FileManager();
 if (!fm.get_IsSupported(filename))
 {
     MessageBox.Show("Datasource isn't supported by MapWinGIS");
 }
 else
 {
     var obj = fm.Open(filename, tkFileOpenStrategy.fosAutoDetect, null);
     if (fm.LastOpenIsSuccess)
     {
         if (fm.LastOpenStrategy == tkFileOpenStrategy.fosVectorLayer)
         {
             var shapefile = obj as Shapefile;
             if (shapefile != null)
                 MessageBox.Show("Shapefile was opened.");
         }
         else
         {
             var image = obj as Image;
             if (image != null)
                 MessageBox.Show("Image was opened.");
         }
     }
     else
     {
         MessageBox.Show("Failed to open datasource: " + fm.get_ErrorMsg(fm.LastErrorCode));
     }
 }
Note:
Look for additional examples on opening raster datasources in description of Grid class.

B. Open strategies.

The following strategies are available through tkFileOpenStrategy enumeration:

dot_inline_dotgraph_40.png

See details on distinction between available open strategies for grids in description of Grid class.

The default tkFileOpenStrategy.fosAutoDetect strategy works like this:

1) Shapefiles are checked by (.shp) extension and fosVectorLayer is chosen.

2) It is analyzed whether datasource can be opened with GDAL:

3) A check is made whether it can be handled by MapWinGIS own grid drivers - if so fosProxyForGrid will be returned.

4) If all previous methods have failed fosNotSupported will be returned.

In most cases fosAutoDetect strategy is the best choice. However as grids have 2 strategies it may be needed to choose on of them explicitly:

 string filename = "some_filename.ext";
 FileManager fm = new FileManager();
 var obj = fm.Open(filename, fm.IsGrid(filename) ? tkFileOpenStrategy.fosProxyForGrid: tkFileOpenStrategy.fosAutoDetect, null);

C. Built-in file manager for map control.

An instance of FileManager class is also used by AxMap.AddLayerFromFilename method, which require only filename and open strategy to add layer to the map. Here is example of its usage:

 int handle = axMap1.AddLayerFromFilename(filename, tkFileOpenStrategy.fosAutoDetect, true);
 if (handle != -1 && axMap1.FileManager.LastOpenIsSuccess) 
 {
     MessageBox.Show("Layer was added to the map. Open strategy: " + axMap1.FileManager.LastOpenStrategy.ToString());
 }
 else
 {
     MessageBox.Show("Failed to open grid: " + axMap1.FileManager.ErrorMsgFromObject(axMap1.FileManager.LastErrorCode));
 }
New API 4.9.1:
Added in version 4.9.1

Member Function Documentation

bool FileManager.BuildGdalOverviews ( string  Filename)

Builds overviews for a raster datasource managed by GDAL.

Parameters:
FilenameFilename of datasource.
Returns:
True on success.
bool FileManager.ClearGdalOverviews ( string  Filename)

Clears overviews for a raster datasource managed by GDAL.

Parameters:
FilenameFilename of datasource.
Returns:
True on success.
bool FileManager.get_CanOpenAs ( string  Filename,
tkFileOpenStrategy  OpenStrategy 
)

Checks whether specific open strategy is applicable for a given datasource.

Parameters:
FilenameFilename of datasource to open.
OpenStrategyOpen strategy to check.

Inconsistent behaviour, i.e. return value is false while datasource is still can be opened with a given strategy, should be reported as bugs. The opposite case, i.e. return value is true while datasource fails to open with given strategy, may occur by design, but it may also be an indication of bugs in some other parts of MapWinGIS.

Returns:
True in case strategy is applicable.
string FileManager.get_ErrorMsg ( int  ErrorCode)

Gets the description of the specific error code.

Parameters:
ErrorCodeThe error code returned by LastErrorCode property.
Returns:
String with the description.
bool FileManager.get_HasGdalOverviews ( string  Filename)

Returns true if specified raster datasource managed by GDAL has overviews.

Parameters:
FilenameFilename of datasource.
Returns:
True if overviews are exist.
bool FileManager.get_HasValidProxyForGrid ( string  Filename)

Returns true if specified grid datasource has proxy images for its rendering.

Parameters:
FilenameFilename of grid datasource.
Returns:
True if proxy images exist.
bool FileManager.get_IsGrid ( string  Filename)

Checks whether specified datasource is grid, i.e. non-RGB raster datasource which require synthetic colour scheme for rendering.

Parameters:
FilenameFilename of datasource to be checked.
Returns:
True in case datasource is grid.
bool FileManager.get_IsRgbImage ( string  Filename)

Checks whether datasource is RGB image.

Parameters:
Filename

Attempt is made to open datasource with GDAL. If it succeeds, a check is made whether bands with Red, Green, Blue colour interpretation are present in it.

Returns:
True if datasource is RGB image.
bool FileManager.get_IsSupported ( string  Filename)

Checks whether the datasource is supported (can be opened) by MapWinGis.

Parameters:
FilenameFilename of datasource

Under the hood open strategy will be determined with FileManager.get_OpenStrategy and then FileManager.get_CanOpenAs(strategy) is called.

Returns:
True in case datasource can be opened.
bool FileManager.get_IsSupportedBy ( string  Filename,
tkSupportType  supportType 
)

Checks whether datasource is supported by specified subsystem of MapWinGIS.

Parameters:
FilenameFilename of datasource
supportTypeThe subsystem to choose (the list may be extended later on).
Returns:
True in case the datasource is supported, i.e. can be opened.
bool FileManager.get_IsVectorLayer ( string  Filename)

Checks whether specified datasource is vector layer that can be opened by MapWinGIS.

Parameters:
FilenameFilename of datasource.

Currently only shapefile format can be opened directly.

Returns:
True in case datasource is vector one and is supported by MapWinGIS.

Determines optimal open strategy for datasource.

Parameters:
FilenameFilename of datasource.
Returns:
The optimal strategy to open datasource.
object FileManager.Open ( string  Filename,
tkFileOpenStrategy  OpenStrategy = tkFileOpenStrategy.fosAutoDetect,
ICallback  cBack = null 
)

Tries to open datasource with specified name.

Parameters:
FilenameFilename of datasource.
OpenStrategyStrategy to be used with default recommended value fosAutoDetect.
cBackCallback interface.

Return value may be either Shapefile or Image object. The latter is used for rendering both RGB images and grids. Under the hood the function uses OpenShapefile and OpenRaster methods, so their behaviour will be consistent.

Returns:
Opened datasource or null on failure.
OgrLayer FileManager.OpenFromDatabase ( string  connectionString,
string  layerNameOrQuery 
)

Opens a layer or runs a query against OGR spatial database.

This method will search if there is a layer with specified name in the datasource, and if so will open it. Otherwise it will run OgrDatasource.RunQuery method with provided layerNameOrQuery argument.

Parameters:
connectionStringConnection string. See details for particular formats here.
layerNameOrQueryName of the layer (i.e. database table) or SQL query.
Returns:
Opened layer or null on failure.
New API 4.9.3:
Added in version 4.9.3
Image FileManager.OpenRaster ( string  Filename,
tkFileOpenStrategy  OpenStrategy,
ICallback  cBack = null 
)

Tries to open raster datasource (either RGB image or grid) with specified name.

Parameters:
FilenameFilename of datasource.
OpenStrategyStrategy to be used with default recommended value fosAutoDetect. Three more strategies are applicable here: fosRgbImage, fosDirectGrid, fosProxyForGrid.
cBackCallback interface.
Returns:
Image object or null on failure.
Shapefile FileManager.OpenShapefile ( string  Filename,
ICallback  cBack = null 
)

Tries to open shapefile with specified name.

Parameters:
FilenameFilename of shapefile to open.
cBackCallback interface.
Returns:
Shapefile object or null on failure.

Tries to open specified file as OGR datasource.

Parameters:
FilenameFilename of the datasource to be opened.
Returns:
Instance of OgrDatasource or null on failure.
New API 4.9.3:
Added in version 4.9.3
OgrLayer FileManager.OpenVectorLayer ( string  Filename,
ShpfileType  preferedShapeType = ShpfileType.SHP_NULLSHAPE,
bool  forUpdate = false 
)

Tries to open specified file as OGR layer.

When preferedShapeType is set to default ShpfileType.SHP_NULLSHAPE value or there is no layer with preferedShapeType, then the first layer in datasource will be returned.

Parameters:
FilenameFilename of the datasource to be opened.
preferedShapeTypeSets type of layer to be returned from datasource in case there are multiple layers available.
forUpdateTrue in case layer should be open in read/write mode.
Returns:
Instance of OgrLayer or null on failure.
New API 4.9.3:
Added in version 4.9.3
bool FileManager.RemoveProxyForGrid ( string  Filename)

Remove proxy images generated for grid rendering.

Parameters:
FilenameFilename of grid datasource.
Returns:

Property Documentation

string FileManager.CdlgFilter [get]

Gets expression to be set for OpenFileDialog.Filter property to select supported datasources.

New API 4.9.3:
Added in version 4.9.3

Gets expression to be set for OpenFileDialog.Filter property to select raster datasources (both RGB images and grids).

New API 4.9.3:
Added in version 4.9.3

Gets expression to be set for OpenFileDialog.Filter property to select vector datasources.

New API 4.9.3:
Added in version 4.9.3

Gets or sets a Callback object which handles progress and error messages.

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.
string FileManager.Key [get, set]

A text string associated with object. Any value can be stored by developer in this property.

Gets the code of last error which took place inside this object.

Gets filename of the last datasource that was attempted to be opened.

Gets a value indicating whether the last attempt to open a datasource was successful.

Gets a strategy that was used on last attempt to open datasource.

Gets string with the list of supported GDAL formats.

New API 4.9.3:
Added in version 4.9.3
 All Classes Files Functions Enumerations Properties Events