Represents a single layer in GDAL/OGR datasource or result of SQL query against such datasource. More...
Public Member Functions | |
bool | ClearStyles () |
Clears all the styles stored for current layer in datasource. More... | |
void | Close () |
Closes current layer and releases resources associated with it. More... | |
bool | Deserialize (string newVal) |
Restores the state of layer from string generated with OgrLayer.Serialize method. More... | |
bool | ExtendFromQuery (string extendSql) |
Extends the ogr featureset by running the given query against the datasource. More... | |
bool | GenerateCategories (string Fieldname, tkClassificationType ClassificationType, int numClasses, tkMapColor colorStart, tkMapColor colorEnd, tkColorSchemeType schemeType) |
Generates visualization categories for OGR layer. More... | |
string | get_ErrorMsg (int ErrorCode) |
Gets the description of the specific error code. More... | |
bool | get_Extents (out Extents layerExtents, bool forceLoading=false) |
Gets extents of the layer. More... | |
int | get_FeatureCount (bool forceLoading=false) |
Returns number of features in the layer. More... | |
string | get_StyleName (int styleIndex) |
Gets name of the style with particular index. More... | |
bool | get_SupportsEditing (tkOgrSaveType editingType) |
Gets a value indicating whether the layer supports editing. More... | |
string | get_UpdateSourceErrorMsg (int errorIndex) |
Gets a specified error message from the log registered during OgrLayer.SaveChanges call. More... | |
int | get_UpdateSourceErrorShapeIndex (int errorIndex) |
Gets shape index associated with specified error message from the log registered during OgrLayer.SaveChanges call. More... | |
Shapefile | GetBuffer () |
Gets layer data represented as in-memory shapefile. More... | |
string | GetConnectionString () |
Returns connection string which was used to open this layer. More... | |
int | GetNumStyles () |
Gets number of styles stored for the layer in datasource. More... | |
string | GetSourceQuery () |
Gets layer name or SQL query which was used to open this layer. More... | |
bool | OpenFromDatabase (string connectionString, string layerName, bool forUpdate) |
Opens layer with specified name from the OGR datasource. More... | |
bool | OpenFromFile (string Filename, bool forUpdate) |
Opens OGR layer from specified file. If the datasource holds several layers only the first one will be opened. More... | |
bool | OpenFromQuery (string connectionString, string sql) |
Runs SQL query against datasource and returns results as a temporary layer. More... | |
bool | RedefineQuery (string newSql) |
Runs a new query against the datasource. More... | |
bool | ReloadFromSource () |
Discards all the local changes and reloads layer from the source. More... | |
bool | RemoveStyle (string StyleName) |
Removes style with particular name from the datasource. More... | |
tkOgrSaveResult | SaveChanges (out int savedCount, tkOgrSaveType saveType=tkOgrSaveType.ostSaveAll, bool validateShapes=true) |
Saves local changes to the datasource. More... | |
string | Serialize () |
Serializes the state of layer to a string, which can be later restored with OgrLayer.Deserialize. More... | |
bool | TestCapability (tkOgrLayerCapability capability) |
Test whether current layer supports certain functionality. More... | |
Properties | |
ShpfileType | ActiveShapeType [get, set] |
Gets or sets the type of the active shape type for the layer (is used in OgrLayer.GetBuffer for example). More... | |
object | AvailableShapeTypes [get] |
Gets the array of available shape types inside OGR layer (should be cast to ShpfileType[]). More... | |
bool | DataIsReprojected [get] |
Gets a value indicating whether underlying data ( OgrLayer.GetBuffer ) was reprojected. More... | |
string | DriverName [get] |
Gets name of the driver which is used to access layer datasource. More... | |
bool | DynamicLoading [get, set] |
Gets or sets a value indicating whether features for large layers are to be loaded dynamically when moving to the new portions of map. More... | |
string | FIDColumnName [get] |
Gets name of feature ID column. More... | |
string | GdalLastErrorMsg [get] |
Extracts the last error message reported by GDAL library. More... | |
string | GeometryColumnName [get] |
Gets the name of geometry column which was used to fetch geometry for current layer. More... | |
GeoProjection | GeoProjection [get] |
Gets GeoProjection associated with current layer. More... | |
ICallback | GlobalCallback [get, set] |
Gets or sets a Callback object which handles progress and error messages. More... | |
bool | IsExternalDatasource [get] |
string | Key [get, set] |
A text string associated with object. Any value can be stored by developer in this property. More... | |
string | LabelExpression [get, set] |
Gets or sets an expression for label generation for the layer. More... | |
tkLineLabelOrientation | LabelOrientation [get, set] |
Gets or sets label orientation for polyline layers. More... | |
tkLabelPositioning | LabelPosition [get, set] |
Gets or sets position of labels relative to their parent features. More... | |
int | LastErrorCode [get] |
Gets code of the last error which took place inside this object. More... | |
int | MaxFeatureCount [get, set] |
Gets or sets maximum number of features to be loaded in the memory. More... | |
string | Name [get] |
Gets name of the layer. More... | |
ShpfileType | ShapeType [get] |
Gets shape type of the current layer. More... | |
ShpfileType | ShapeType2D [get] |
Gets "flattened" type of the current layer, i.e. Z and M components will be ignored. More... | |
tkOgrSourceType | SourceType [get] |
Gets source type of the layer. More... | |
bool | SupportsStyles [get] |
Checks whether the layers supports saving of styles to the datasource. More... | |
int | UpdateSourceErrorCount [get] |
Gets the number of errors registered in the log during OgrLayer.SaveChanges call. More... | |
Represents a single layer in GDAL/OGR datasource or result of SQL query against such datasource.
A. How to open.
There are 2 main ways to open a layer from OGR datasource:
1) open one of exiting layers:
2) return temporary layer by a query:
3) the same using datasource:
4) using FileManager class:
For spatial databases layer name corresponds to the name of underlying table with some driver specifics, like including name of database schema as a prefix or the name of the geometry column. Use OgrDatasource class to get the names of available layers.
B. How to add to the map.
Instances of OgrLayer class can be added to the map directly using AxMap.AddLayer method or opened internally using AxMap.OpenFromDatabase method. In each case OgrLayer.GetBuffer method will be called automatically which triggers the loading of data from datasource. Afterwards underlying in-memory shapefile will be used for all rendering purposes.
OgrLayer added to the map can be accessed using AxMap.get_OgrLayer property.
AxMap.AddLayerFromDatabase provides a short-cut for both 2 operations: opening a layer and adding it to the map.
OGR layers support built reprojection of layers (GlobalSettings.ReprojectLayersOnAdding) and AxMap.GrabProjectionFromData properties. Depending on their values underlying shapefile data may be reprojected on adding it to the map. Use OgrLayer.DataIsReprojected property to test whether it happened.
OGR layers support map state serialization with AxMap.SerializeMapState. Their data will be reloaded after AxMap.DeserializeMapState is called.
C. How to access the data.
OgrLayer uses in-memory shapefile to provide its data to clients.
This shapefile is populated on the first call to OgrLayer.GetBuffer method. On subsequent calls cached values will be used (lazy loading pattern).
OgrLayer.GetBuffer method maps:
OgrLayer may support database tables without geometry column. For example, all tables in PostGreSQL database will be listed as layers if no PostGIS support was added to the database. In such case table records will be converted to rows of attribute table, while shapefile will contain empty shapes with Shape.ShapeType = SHP_NULLSHAPE.
AxMap.get_GetObject and AxMap.get_Shapefile will return underlying in-memory shapefile. This allows to use
unified code for processing both regular shapefile layers and OGR layers and ensures compatibility of OGR layers with previously written client code.
OgrLayer encapsulates an instance of GDAL's OGRLayer C++ class. Check its documentation to better understand what's going on under the hood.
Here is a diagram for the OgrLayer class.
bool OgrLayer.ClearStyles | ( | ) |
Clears all the styles stored for current layer in datasource.
void OgrLayer.Close | ( | ) |
Closes current layer and releases resources associated with it.
It's recommended to call this method as soon as the layer is no longer needed.
bool OgrLayer.Deserialize | ( | string | newVal | ) |
Restores the state of layer from string generated with OgrLayer.Serialize method.
Deserialization includes:
a) reconnection to the datasource;
b) grabbing data from it;
c) restoring of visualization options set for underlying shapefile.
Particular set of actions depends on the state of the object before serialization.
Any data currently stored in this instance will be discarded.
newVal | String generated with OgrLayer.Serialize method. |
bool OgrLayer.ExtendFromQuery | ( | string | extendSql | ) |
Extends the ogr featureset by running the given query against the datasource.
The layer must be opened with OgrLayer.OpenFromQuery or OgrDatasource.RunQuery (OgrLayer.SourceType = ogrQuery) in order for this method to work. The new feature set replaces features with identical OGR feature id's.
extendSql |
bool OgrLayer.GenerateCategories | ( | string | Fieldname, |
tkClassificationType | ClassificationType, | ||
int | numClasses, | ||
tkMapColor | colorStart, | ||
tkMapColor | colorEnd, | ||
tkColorSchemeType | schemeType | ||
) |
Generates visualization categories for OGR layer.
Fieldname | Field name to use as a base for classification. |
ClassificationType | Type of classification. |
numClasses | Number of classes (is not used with unique values classification type). |
colorStart | Starting color for the color scheme. |
colorEnd | End color for the color scheme. |
schemeType | Type of color scheme. |
The whole set of features will be used during classification, not only those currently loaded into memory. Therefore the method has definite advantage over calling OgrLayer.GetBuffer.Categories.Generate directly for large layers.
Categories will be added to underlying shapefile (OgrLayer.GetBuffer). This method will trigger the population of this shapefile if it's not yet in memory.
The following code opens "buildings" layer, generates categories based on "population" field and then saves them as a "new_style" to the datasource.
string OgrLayer.get_ErrorMsg | ( | int | ErrorCode | ) |
Gets the description of the specific error code.
ErrorCode | The error code returned by LastErrorCode property. |
bool OgrLayer.get_Extents | ( | out Extents | layerExtents, |
bool | forceLoading = false |
||
) |
Gets extents of the layer.
Depending on driver implementation this method may retrieve this information directly from underlying datasource without loading the data, which provides performance benefits.
layerExtents | Retrieved extents. |
forceLoading | True to instruct driver to load the data locally if information can't be retrieved from underlying datasource otherwise. |
int OgrLayer.get_FeatureCount | ( | bool | forceLoading = false | ) |
Returns number of features in the layer.
Depending on driver implementation this method may retrieve this information directly from underlying datasource without loading the data, which provides performance benefits.
forceLoading | True to instruct driver to load the data locally if information can't be retrieved from underlying datasource otherwise. |
string OgrLayer.get_StyleName | ( | int | styleIndex | ) |
Gets name of the style with particular index.
styleIndex | Index of style. |
Shapefile OgrLayer.GetBuffer | ( | ) |
Gets layer data represented as in-memory shapefile.
Implements lazy loading pattern, i.e. data will be grabbed from underlying datasource on the first call and will be used for all subsequent calls. To force re-read of the data from datasource use OgrLayer.ReloadFromSource.
This method will automatically be called after adding the layer to the map via AxMap.AddLayer or AxMap.AddLayerFromDatabase.
string OgrLayer.GetConnectionString | ( | ) |
Returns connection string which was used to open this layer.
int OgrLayer.GetNumStyles | ( | ) |
Gets number of styles stored for the layer in datasource.
MapWinGIS provides its own functionality to store visualization styles for OGR layers. Each style hold serialized state of underlying shapefile and is stored in mw_styles table of database. The table will be created on the first call of OgrLayer.SaveStyle or on the first call of OgrDatasource.ImportShapefile when GlobalSettings.UseOgrStyles is set to true.
The default style has empty string name (""). When GlobalSettings.UseOgrStyles is set to true, this style will be automatically created during shapefile import and then will be applied for the layer on further loadings. Alternative styles can be saved and applied with OgrLayer.SaveStyle and OgrLayer.ApplyStyle respectively.
The style table has following definition for PostGIS datasource:
string OgrLayer.GetSourceQuery | ( | ) |
Gets layer name or SQL query which was used to open this layer.
bool OgrLayer.OpenFromDatabase | ( | string | connectionString, |
string | layerName, | ||
bool | forUpdate | ||
) |
Opens layer with specified name from the OGR datasource.
This method is called internally by OgrDatasource.GetLayerByName.
connectionString | Connection string or filename. |
layerName | Layer name. |
forUpdate | Indicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver). |
bool OgrLayer.OpenFromFile | ( | string | Filename, |
bool | forUpdate | ||
) |
Opens OGR layer from specified file. If the datasource holds several layers only the first one will be opened.
Filename | Filename of the datasource to open. |
forUpdate | Indicates whether the returned layer will support saving of changes back to source (the functionality should be supported by particular driver). |
bool OgrLayer.OpenFromQuery | ( | string | connectionString, |
string | sql | ||
) |
Runs SQL query against datasource and returns results as a temporary layer.
This method is called internally by OgrDatasource.RunQuery.
connectionString | Connection string or filename. |
sql | SQL query. |
bool OgrLayer.RedefineQuery | ( | string | newSql | ) |
Runs a new query against the datasource.
The layer must be opened with OgrLayer.OpenFromQuery or OgrDatasource.RunQuery (OgrLayer.SourceType = ogrQuery) in order for this method to work.
newSql | New SQL command. |
bool OgrLayer.ReloadFromSource | ( | ) |
Discards all the local changes and reloads layer from the source.
Starting with version 5.2.0, this function will also attempt to maintain the current set of Hidden and Selected shapes within the associated Shapefile.
bool OgrLayer.RemoveStyle | ( | string | StyleName | ) |
Removes style with particular name from the datasource.
StyleName | The name of the style. |
string OgrLayer.Serialize | ( | ) |
Serializes the state of layer to a string, which can be later restored with OgrLayer.Deserialize.
State information includes connection string, layer name (or query string) and visualization options for underlying shapefile (in case it is already populated when the method was called.)
bool OgrLayer.TestCapability | ( | tkOgrLayerCapability | capability | ) |
Test whether current layer supports certain functionality.
In most cases no actual attempts to perform requested operation is made.
capability | A capability to test. |
The following code opens a layer from datasource and display which capabilities are supported for it.
|
getset |
Gets or sets the type of the active shape type for the layer (is used in OgrLayer.GetBuffer for example).
|
get |
Gets the array of available shape types inside OGR layer (should be cast to ShpfileType[]).
|
get |
Gets name of the driver which is used to access layer datasource.
|
getset |
Gets or sets a value indicating whether features for large layers are to be loaded dynamically when moving to the new portions of map.
When set to false only the number of features set by OgrLayer.MaxFeatureCount is loaded into memory. No further attempts to load additional features will be done.
In dynamic loading mode after map extents change a check is made whether features for the requested extents are already in memory. If not the data loading is started in the background thread. When the loading is over all the features currently stored in memory will be discarded. If the amount of features in new map extents exceeds OgrLayer.MaxFeatureCount no background loading will be done.
The mode is chosen automatically when the layer is opened depending on the number of features. But afterwards it's possible possible to change the value.
|
get |
Extracts the last error message reported by GDAL library.
|
get |
Gets the name of geometry column which was used to fetch geometry for current layer.
Depending on data format, a layer may support several geometry columns but only one will be used to provide shape data via OgrLayer.GetBuffer(). By default the first column with geometry/geography type will be used. To access other columns temporary layers can be opened via OgrDatasource.RunQuery.
|
get |
Gets GeoProjection associated with current layer.
Corresponds to SRID set for the layer in underlying datasource. When SRID isn't specified (i.e. equals 0), empty GeoProjection instance will be returned.
|
getset |
Gets or sets a Callback object which handles progress and error messages.
|
get |
|
getset |
A text string associated with object. Any value can be stored by developer in this property.
|
getset |
Gets or sets an expression for label generation for the layer.
The syntax of expression is the same as for Shapefile.Labels.Generate method. To generate labels based on single field use "[FieldName]" syntax. The property is supported for dynamic loading mode, where labels will be generated on the fly after each zooming operation.
|
getset |
Gets or sets label orientation for polyline layers.
|
getset |
Gets or sets position of labels relative to their parent features.
|
get |
Gets code of the last error which took place inside this object.
|
getset |
Gets or sets maximum number of features to be loaded in the memory.
If total number of features exceeds this number the layer will be rendered in dynamic loading mode (see OgrLayer.DynamicLoading). During dynamic loading if number of features for the new map extents exceeds this number they won't be loaded. The default value of property can be changed with GlobalSettings.OgrLayerMaxFeatureCount.
|
get |
Gets name of the layer.
The name may correspond to table name in underlying database or store some generic string like "sql_statement" for temporary layers opened by OgrDatasource.RunQuery.
|
get |
Gets shape type of the current layer.
The property automatically maps underlying OGRwkbGeometryType to corresponding shape type.
|
get |
Gets "flattened" type of the current layer, i.e. Z and M components will be ignored.
|
get |
Gets source type of the layer.
Any new instance of class starts with ogrUninitialized. Successful call of OgrLayer.OpenFromDatabase method will set it to ogrDbTable, OgrLayer.OpenFromQuery - to ogrQuery.
|
get |
Checks whether the layers supports saving of styles to the datasource.
This property will check the presence of mw_styles table in the datasource and then will try to create one if it's missing. If neither succeeds, false will be returned.