FileManager Class Reference

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

Collaboration diagram for FileManager:
Collaboration graph

Public Member Functions

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

Properties

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

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);
tkFileOpenStrategy
Possible open strategies for datasources.
Definition: Enumerations.cs:1799
Provides functionality for opening and examining different types of datasources.
Definition: FileManager.cs:158

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));
}
}
Represents an raster image of particular format which may be added to the map.
Definition: Image.cs:66
Provides a functionality for accessing and editing ESRI shapefiles.
Definition: Shapefile.cs:72
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:

  • if so and it is RGB image, fosRgbImage is chosen;
  • otherwise it is checked whether a proxy image exists for rendering this datasource, and whether its size exceeds GlobalSettings.MaxNoProxyGridSizeMb property; if either is true fosProxyForGrid will be chosen;
  • otherwise fosDirectGrid will be returned.

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";
var obj = fm.Open(filename, fm.IsGrid(filename) ? tkFileOpenStrategy.fosProxyForGrid: tkFileOpenStrategy.fosAutoDetect, null);
object Open(string Filename, tkFileOpenStrategy OpenStrategy=tkFileOpenStrategy.fosAutoDetect, ICallback cBack=null)
Tries to open datasource with specified name.
Definition: FileManager.cs:219

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

◆ BuildGdalOverviews()

bool FileManager.BuildGdalOverviews ( string  Filename)

Builds overviews for a raster datasource managed by GDAL.

Parameters
FilenameFilename of datasource.
Returns
True on success.

◆ ClearGdalOverviews()

bool FileManager.ClearGdalOverviews ( string  Filename)

Clears overviews for a raster datasource managed by GDAL.

Parameters
FilenameFilename of datasource.
Returns
True on success.

◆ get_CanOpenAs()

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.

◆ get_ErrorMsg()

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.

◆ get_HasGdalOverviews()

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.

◆ get_HasValidProxyForGrid()

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.

◆ get_IsGrid()

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.

◆ get_IsRgbImage()

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.

◆ get_IsSupported()

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.

◆ get_IsSupportedBy()

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.

◆ get_IsVectorLayer()

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.

◆ get_OpenStrategy()

tkFileOpenStrategy FileManager.get_OpenStrategy ( string  Filename)

Determines optimal open strategy for datasource.

Parameters
FilenameFilename of datasource.
Returns
The optimal strategy to open datasource.

◆ Open()

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.

◆ OpenFromDatabase()

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

◆ OpenRaster()

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.

◆ OpenShapefile()

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.

◆ OpenVectorDatasource()

OgrDatasource FileManager.OpenVectorDatasource ( string  Filename)

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

◆ OpenVectorLayer()

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

◆ RemoveProxyForGrid()

bool FileManager.RemoveProxyForGrid ( string  Filename)

Remove proxy images generated for grid rendering.

Parameters
FilenameFilename of grid datasource.
Returns

Property Documentation

◆ CdlgFilter

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

◆ CdlgRasterFilter

string FileManager.CdlgRasterFilter
get

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

◆ CdlgVectorFilter

string FileManager.CdlgVectorFilter
get

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

New API 4.9.3:
Added in version 4.9.3

◆ GlobalCallback

ICallback FileManager.GlobalCallback
getset

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

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.

◆ Key

string FileManager.Key
getset

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

◆ LastErrorCode

int FileManager.LastErrorCode
get

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

◆ LastOpenFilename

string FileManager.LastOpenFilename
get

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

◆ LastOpenIsSuccess

bool FileManager.LastOpenIsSuccess
get

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

◆ LastOpenStrategy

tkFileOpenStrategy FileManager.LastOpenStrategy
get

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

◆ SupportedGdalFormats

string FileManager.SupportedGdalFormats
get

Gets string with the list of supported GDAL formats.

New API 4.9.3:
Added in version 4.9.3