Public Member Functions | Properties
Table Class Reference

The table object is used to store information from the dbf file associated with a shapefile. More...

List of all members.

Public Member Functions

bool Calculate (string Expression, int RowIndex, out object Result, out string ErrorString)
 Calculates the the expression taking the values from the specified row of the attribute table.
void ClearCache ()
 Clears the cache (cell values already loaded in the memory).
bool Close ()
 Closes the attribute table.
bool CreateNew (string dbfFilename)
 Creates a new attribute table.
void Deserialize (string newVal)
 Restores state of joins from string.
bool Dump (string dbfFilename, ICallback cBack=null)
 Writes contents of the DBF file to disk without changing the state of in-memory DBF.
int EditAddField (string Name, FieldType Type, int Precision, int Width)
 Adds a field to the table. The table must be in editing mode.
bool EditCellValue (int FieldIndex, int RowIndex, object newVal)
 Sets the value of the cell.
bool EditClear ()
 Deletes all rows and fields from the table. Note: The table must be set to allow editing before the rows and fields can be deleted from the table.
bool EditDeleteField (int FieldIndex, ICallback cBack)
 Deletes a field from the table.
bool EditDeleteRow (int RowIndex)
 Deletes a row from the table.
bool EditInsertField (Field Field, ref int FieldIndex, ICallback cBack)
 Inserts a new field into the table.
bool EditInsertRow (ref int RowIndex)
 Inserts a new row into the table.
bool EditReplaceField (int FieldIndex, Field NewField, ICallback cBack)
 Replaces the specified field in the table with the new field.
object get_CellValue (int FieldIndex, int RowIndex)
 Gets the value of the specified cell in the table.
string get_ErrorMsg (int ErrorCode)
 Retrieves the error message associated with the specified error code.
Field get_Field (int FieldIndex)
 Gets the field object at the specified field index in the table.
int get_FieldIndexByName (string Fieldname)
 Seeks field with specified name. Comparison is case insensitive.
bool get_FieldIsJoined (int FieldIndex)
 Gets the value indicating whether the specified field is joined from external table.
int get_FieldJoinIndex (int FieldIndex)
 Returns the index of join operation by which the specified field was brought in.
string get_JoinFields (int joinIndex)
 Gets string with the names of fields which were used in join operation.
string get_JoinFilename (int joinIndex)
 Gets filename of the external datasource used in specified join.
string get_JoinFromField (int joinIndex)
 Gets name of FromField in external table for specified join operation.
string get_JoinOptions (int joinIndex)
 Gets the options of the join operation.
string get_JoinToField (int joinIndex)
 Gets name of ToField in this table for specified join operation.
object get_MaxValue (int FieldIndex)
 Returns the maximum value for the specified field of the table.
double get_MeanValue (int FieldIndex)
 Calculates the mean value for the specified field of the table.
object get_MinValue (int FieldIndex)
 Returns the minimum value for the specified field.
bool get_RowIsModified (int RowIndex)
 Gets a value indicating whether the row values have been modified.
double get_StandardDeviation (int FieldIndex)
 Calculates the standard deviation for the set of values in specified field.
bool Join (Table table2, string field1, string field2)
 Joins external table to the current one.
bool Join2 (Table table2, string field1, string field2, string filenameToReopen, string joinOptions)
 Joins external table to the current one.
bool Join3 (Table table2, string field1, string field2, string filenameToReopen, string joinOptions, Array fieldList)
 Joins external table to the current one.
bool Open (string dbfFilename, ICallback cBack)
 Opens a .dbf table from file.
bool ParseExpression (string Expression, ref string ErrorString)
 Checks if the expression is a valid one.
bool Query (string Expression, ref object Result, ref string ErrorString)
 Selects the rows in the table which agree with the specified expression.
bool Save (ICallback cBack)
 Saves in-memory version of the table to the source file.
bool SaveAs (string dbfFilename, ICallback cBack)
 Saves the table using the specified filename.
string Serialize ()
 Serializes the state of joins for table to be restored later with Table.Deserialize method.
bool StartEditingTable (ICallback cBack)
 Sets the table to allow table editing.
void StopAllJoins ()
 Stops all joins associated with table.
bool StopEditingTable (bool ApplyChanges, ICallback cBack)
 Sets the table to prevent editing.
bool StopJoin (int joinIndex)
 Stops (removes) specific join created for the table.
bool TestExpression (string Expression, tkValueType ReturnType, ref string ErrorString)
 Tests the validity of expression and determines its return type.
bool TryJoin (Table table2, string fieldTo, string fieldFrom, out int rowCount, out int joinRowCount)
 Tries to create a join and reports number of rows to be joined for the specified join fields.

Properties

string CdlgFilter [get]
 Returns the common dialog filter containing all supported file extensions in string format.
bool EditingTable [get]
 Gets whether or not the table is in editing mode.
string Filename [get, set]
 Gets the filename of the DBF file if the table is bound to one.
ICallback GlobalCallback [get, set]
 The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications.
bool IsJoined [get]
 Gets a value indicating whether the table has any joined tables.
int JoinCount [get]
 Gets number of joins for the table.
string Key [get, set]
 The key may be used by the programmer to store any string data associated with the object.
int LastErrorCode [get]
 Retrieves the last error generated in the object.
int NumFields [get]
 Gets the number of fields in the table.
int NumRows [get]
 Gets the number of rows in the table.

Detailed Description

The table object is used to store information from the dbf file associated with a shapefile.

dot_inline_dotgraph_64.png

Graph description

Table expressions.

Table class provides a built-in expression parser which is used at the time of writing these lines by the following methods:

Expression may include:

The intermediate values during calculation and resulting values can be of one of the following types:

The parser doesn't rely on any DBMS, therefore it doesn't support standard SQL functions, both mathematic and string. Therefore for more complex expressions a column should be added, where calculations can be made using Table.get_CellValue, Table.EditCellValue API members and programming language of your choice.

Examples:

 [Area] > 100 AND [Population] < 50  -- Area and Population are field names; resulting value is boolean
 [Area] / 10000 + " ha"              -- Area is field name, " ha" - string constant, "+" - concatenation operator; 
                                     -- resulting value is string
 ([Pop1990] + [Pop2005])/2           -- Pop1990 and Pop2005 are field names; resulting value is double

Here is code sample demonstrating how to calculate a new field as an average of 2 existing fields:

 string filename = @"D:\counties.dbf";
 var tbl = new Table();
 if (!tbl.Open(filename))
 {
     MessageBox.Show("File not found: " + filename);
 }
 else
 {
     tbl.StartEditingTable();
 
     int fldIndex = tbl.FieldIndexByName["Pop1990"];
     int fldIndex2 = tbl.FieldIndexByName["Pop1997"];
     if (fldIndex == -1 && fldIndex2 == -1)
     {
         MessageBox.Show("Source fields aren't found.");
     }
     else
     {
         // adding a new field:
         // 2 - number of decimal places; 
         // 16 - total length (numbers are actually stored as strings inside DBF )
         int fldIndexNew = tbl.EditAddField("PopAvg", FieldType.DOUBLE_FIELD, 2, 16);
 
         for (int i = 0; i < tbl.NumRows; i++)
         {
             // it's assumed here that the source fields are numeric (either integer or double),
             // but if it's not known then a field type can be checked with Table.get_Field(fieldIndex).Type
             double val1 = Convert.ToDouble(tbl.get_CellValue(fldIndex, i));
             double val2 = Convert.ToDouble(tbl.get_CellValue(fldIndex2, i));
             tbl.EditCellValue(fldIndexNew, i, (val1 + val2)/2);
          }
         MessageBox.Show("New field is calculated.");
     }
 
     if( tbl.StopEditingTable(true))
         MessageBox.Show("Table is saved.");
 }
 tbl.Close();

Member Function Documentation

bool Table.Calculate ( string  Expression,
int  RowIndex,
out object  Result,
out string  ErrorString 
)

Calculates the the expression taking the values from the specified row of the attribute table.

Parameters:
ExpressionThe expression to analyse.
RowIndexThe index of the row.
ResultThe result of calculation as variant data type, either boolean, double or string.
ErrorStringAn output string with the description of error in case method failed.
Returns:
True on successful calculation and false otherwise.
New API 4.8:
Added in version 4.8
void Table.ClearCache ( )

Clears the cache (cell values already loaded in the memory).

New API 4.9.4:
Added in version 4.9.4
bool Table.Close ( )

Closes the attribute table.

Returns:
The value can be ignored.
Examples:
CalculateArea.cs.
bool Table.CreateNew ( string  dbfFilename)

Creates a new attribute table.

A new table is automatically in editing mode after it is created.

Parameters:
dbfFilenameThe filename for the new table.
Returns:
A boolean value representing the success or failure of creating the new table.
void Table.Deserialize ( string  newVal)

Restores state of joins from string.

Parameters:
newValString generated by Table.Serialize method.
New API 4.9.0:
Added in version 4.9.0
bool Table.Dump ( string  dbfFilename,
ICallback  cBack = null 
)

Writes contents of the DBF file to disk without changing the state of in-memory DBF.

Parameters:
dbfFilenameFilename to write the data to.
cBackCallback interface.
Returns:
True on success and false otherwise.

The methods may be used for in-memory, when the content should be saved without switching to disk mode.

New API 4.9.0:
Added in version 4.9.0
int Table.EditAddField ( string  Name,
FieldType  Type,
int  Precision,
int  Width 
)

Adds a field to the table. The table must be in editing mode.

Parameters:
NameThe name of field.
TypeThe type of field.
PrecisionThe precision of field.
WidthThe width of field.
Returns:
The index of the new field or -1 on failure.
New API 4.9.0:
Added in version 4.9.0
bool Table.EditCellValue ( int  FieldIndex,
int  RowIndex,
object  newVal 
)

Sets the value of the cell.

The table must be set to allow editing before a cell's value may be edited.

Parameters:
FieldIndexThe field index of the cell to be edited.
RowIndexThe row index of the cell to be edited.
newValThe new value to be used to set the specified cell's value.
Returns:
A boolean value representing the success or failure of setting the value of the specified cell in the table.
bool Table.EditClear ( )

Deletes all rows and fields from the table. Note: The table must be set to allow editing before the rows and fields can be deleted from the table.

Returns:
A boolean value representing the success or failure of deleting all rows and fields from the table.
bool Table.EditDeleteField ( int  FieldIndex,
ICallback  cBack 
)

Deletes a field from the table.

The table must be set to allow editing before a field can be deleted from the table.

Parameters:
FieldIndexThe index of the field to be deleted from the table.
cBackThe ICallback object which will receive progress and error messages while the field is being deleted from the table.
Returns:
bool Table.EditDeleteRow ( int  RowIndex)

Deletes a row from the table.

The table must be set to allow editing before a row can be deleted from the table.

Parameters:
RowIndexThe index of the row to be deleted from the table.
Returns:
A boolean value representing the success or failure of deleting the specified row from the table.
bool Table.EditInsertField ( Field  Field,
ref int  FieldIndex,
ICallback  cBack 
)

Inserts a new field into the table.

The table must be set to allow editing before a field can be inserted into the table.

Parameters:
FieldThe new field to be inserted into the table.
FieldIndexThe desired index to be used for the new field being inserted into the table. If the desired index is invalid or unavailable, the actual index used for the new field will be returned.
cBackThe ICallback object which will receive progress and error messages while the new field is being inserted into the table.
Returns:
A boolean value representing the success or failure of inserting the new field into the table.
bool Table.EditInsertRow ( ref int  RowIndex)

Inserts a new row into the table.

The table must be set to allow editing before a row can be inserted into the table.

Parameters:
RowIndexThe desired index to use when inserting the new row into the table. If the desired index is invalid or unavailable, the actual index used to insert the new row will be returned.
Returns:
A boolean value representing the success or failure of inserting the new row into the table.
bool Table.EditReplaceField ( int  FieldIndex,
Field  NewField,
ICallback  cBack 
)

Replaces the specified field in the table with the new field.

The table must be set to allow editing before a field can be replaced in the table.

Parameters:
FieldIndexThe index of the field to be replaced.
NewFieldThe field to be used to replace the specified field in the table.
cBackThe ICallback object which will receive progress and error messages while the specified field is being replced by the new field.
Returns:
A boolean value representing the success or failure of replacing the specified field.
object Table.get_CellValue ( int  FieldIndex,
int  RowIndex 
)

Gets the value of the specified cell in the table.

Parameters:
FieldIndexThe field index of the cell for which the value is required.
RowIndexThe row index of the cell for which the value is required.
Returns:
The value of the specified cell in the table.
string Table.get_ErrorMsg ( int  ErrorCode)

Retrieves the error message associated with the specified error code.

Parameters:
ErrorCodeThe error code for which the error message is required.
Returns:
The error message description for the specified error code.
Field Table.get_Field ( int  FieldIndex)

Gets the field object at the specified field index in the table.

Parameters:
FieldIndexThe index of the field in the table to be returned.
Returns:
The field object specified by the field index.
int Table.get_FieldIndexByName ( string  Fieldname)

Seeks field with specified name. Comparison is case insensitive.

Parameters:
FieldnameThe name of field to search.
Returns:
The index of field if it exists and -1 otherwise.
bool Table.get_FieldIsJoined ( int  FieldIndex)

Gets the value indicating whether the specified field is joined from external table.

Parameters:
FieldIndexField index.
Returns:
True if the field is brought from external table.
New API 4.9.0:
Added in version 4.9.0
int Table.get_FieldJoinIndex ( int  FieldIndex)

Returns the index of join operation by which the specified field was brought in.

Parameters:
FieldIndexField index.
Returns:
The index of join.
New API 4.9.0:
Added in version 4.9.0
string Table.get_JoinFields ( int  joinIndex)

Gets string with the names of fields which were used in join operation.

Parameters:
joinIndexIndex of the join.
Returns:
The string with names.
New API 4.9.4:
Added in version 4.9.4
string Table.get_JoinFilename ( int  joinIndex)

Gets filename of the external datasource used in specified join.

Parameters:
joinIndexIndex of join operation.
Returns:
Filename of external datasource.
New API 4.9.0:
Added in version 4.9.0
string Table.get_JoinFromField ( int  joinIndex)

Gets name of FromField in external table for specified join operation.

Parameters:
joinIndexIndex of join operation.
Returns:
Name of FromField in external table.
New API 4.9.0:
Added in version 4.9.0
string Table.get_JoinOptions ( int  joinIndex)

Gets the options of the join operation.

Parameters:
joinIndexIndex of the join.
Returns:
The string with join options.
New API 4.9.4:
Added in version 4.9.4
string Table.get_JoinToField ( int  joinIndex)

Gets name of ToField in this table for specified join operation.

Parameters:
joinIndexIndex of join operation.
Returns:
Name of ToField in this table.
New API 4.9.0:
Added in version 4.9.0
object Table.get_MaxValue ( int  FieldIndex)

Returns the maximum value for the specified field of the table.

NULL will be returned in case of invalid index.

Parameters:
FieldIndexThe index of the field.
Returns:
The maximum value, either integer, double or string data type.
New API 4.8:
Added in version 4.8
double Table.get_MeanValue ( int  FieldIndex)

Calculates the mean value for the specified field of the table.

NULL will be returned in case of invalid index.

Parameters:
FieldIndexThe index of the field.
Returns:
The mean value, either integer, double or string data type.
New API 4.8:
Added in version 4.8
object Table.get_MinValue ( int  FieldIndex)

Returns the minimum value for the specified field.

NULL will be returned in case of invalid index.

Parameters:
FieldIndexThe index of the field.
Returns:
The minimum value, either integer, double or string data type.
New API 4.8:
Added in version 4.8
bool Table.get_RowIsModified ( int  RowIndex)

Gets a value indicating whether the row values have been modified.

Parameters:
RowIndexIndex of the row.
Returns:
True if the row is modified.
New API 4.9.4:
Added in version 4.9.4
double Table.get_StandardDeviation ( int  FieldIndex)

Calculates the standard deviation for the set of values in specified field.

NULL will be returned in case of invalid index.

Parameters:
FieldIndexThe index of the field.
Returns:
The minimum value, either integer, double or string data type.
New API 4.8:
Added in version 4.8
bool Table.Join ( Table  table2,
string  field1,
string  field2 
)

Joins external table to the current one.

Parameters:
table2External table.
field1Join field of this table.
field2Join filed of external table.
Returns:
True on success.

If formats other than DBF are needed, in-memory dbf table should be populated first.

New API 4.9.0:
Added in version 4.9.0
bool Table.Join2 ( Table  table2,
string  field1,
string  field2,
string  filenameToReopen,
string  joinOptions 
)

Joins external table to the current one.

Parameters:
table2>External table.
field1Join field of this table.
field2Join filed of external table.
filenameToReopenFilename to be opened to restore join on deserialization of table state.
joinOptionsArbitrary join options to help restore join on deserialization.
Returns:
True on success.

If filename specify formats other than dbf (extension is checked), Table.OnUpdateJoin event will be raised. Client can handle this event by populating joinSource table parameter using filename, fieldList and options parameters.

New API 4.9.0:
Added in version 4.9.0
bool Table.Join3 ( Table  table2,
string  field1,
string  field2,
string  filenameToReopen,
string  joinOptions,
Array  fieldList 
)

Joins external table to the current one.

Parameters:
table2>External table.
field1Join field of this table.
field2Join filed of external table.
filenameToReopenFilename to be opened to restore join on deserialization of table state.
joinOptionsArbitrary join options to help restore join on deserialization.
fieldListComma separated list of fields to be displayed from external table.
Returns:
True on success.

If filename specify formats other than dbf (extension is checked), Table.OnUpdateJoin event will be raised. Client can handle this event by populating joinSource table parameter using filename, fieldList and options parameters.

New API 4.9.0:
Added in version 4.9.0
bool Table.Open ( string  dbfFilename,
ICallback  cBack 
)

Opens a .dbf table from file.

Parameters:
dbfFilenameThe filename of the table to be opened.
cBackThe ICallback object which will receive progress and error messages while the table is being opened.
Returns:
The boolean value representing success or failure of the opening table.
bool Table.ParseExpression ( string  Expression,
ref string  ErrorString 
)

Checks if the expression is a valid one.

Parameters:
ExpressionThe expression to analyse.
ErrorStringAn output string with the description of error in case expression is not valid.
Returns:
True if expression is valid and false otherwise.
New API 4.8:
Added in version 4.8
bool Table.Query ( string  Expression,
ref object  Result,
ref string  ErrorString 
)

Selects the rows in the table which agree with the specified expression.

Parameters:
ExpressionThe query expression.
ResultAn array of integer type with the indices of rows which were selected.
ErrorStringAn output string with the description of error on failure.
Returns:
True in case at least one row was selected and false otherwise.
New API 4.8:
Added in version 4.8
bool Table.Save ( ICallback  cBack)

Saves in-memory version of the table to the source file.

This method should be called while the table is in editing mode. The editing mode will not be closed.

Parameters:
cBackA callback object to report information about progress and errors.
Returns:
True on success and false otherwise.
New API 4.8:
Added in version 4.8
bool Table.SaveAs ( string  dbfFilename,
ICallback  cBack 
)

Saves the table using the specified filename.

Parameters:
dbfFilenameThe filename to be used to save the table.
cBackThe ICallback object which will receive progress and error messages while the table is being saved.
Returns:
A boolean value representing the success or failure of saving the table.
string Table.Serialize ( )

Serializes the state of joins for table to be restored later with Table.Deserialize method.

Returns:
String with serialized state.
New API 4.9.0:
Added in version 4.9.0

Sets the table to allow table editing.

Parameters:
cBackOptional. The ICallback object which will receive progress and error events while the table is being set to allow editing.
Returns:
A boolean value representing the success or failure of setting the table to allow editing.

Stops all joins associated with table.

New API 4.9.0:
Added in version 4.9.0
bool Table.StopEditingTable ( bool  ApplyChanges,
ICallback  cBack 
)

Sets the table to prevent editing.

Parameters:
ApplyChangesOptional. A boolean value representing whether or not to save changes to the table. The default is True, to save the changes.
cBackOptional. The ICallback object which will receive progress and error messages while the table is being set to prevent editing.
Returns:
A boolean value representing the success or failure of setting the table to prevent editing.
bool Table.StopJoin ( int  joinIndex)

Stops (removes) specific join created for the table.

Parameters:
joinIndexIndex of join to be removed.
Returns:
True on success.
New API 4.9.0:
Added in version 4.9.0
bool Table.TestExpression ( string  Expression,
tkValueType  ReturnType,
ref string  ErrorString 
)

Tests the validity of expression and determines its return type.

Parameters:
ExpressionThe expression to test.
ReturnTypeAn output value with the return type, either double, string or boolean.
ErrorStringAn output string with the description of error.
Returns:
True if the expression is valid and false otherwise.
New API 4.8:
Added in version 4.8
bool Table.TryJoin ( Table  table2,
string  fieldTo,
string  fieldFrom,
out int  rowCount,
out int  joinRowCount 
)

Tries to create a join and reports number of rows to be joined for the specified join fields.

Parameters:
table2External table to join.
fieldToJoin field of this table.
fieldFromJoin field of external table.
rowCountNumber of rows in this table for which a join is found in external table.
joinRowCountNumber of unique values from external table, joined to this table.
Returns:
True on success.

The method can be used to determine, if the join fields for table are chosen correctly, i.e. their values match.

New API 4.9.0:
Added in version 4.9.0

Property Documentation

string Table.CdlgFilter [get]

Returns the common dialog filter containing all supported file extensions in string format.

bool Table.EditingTable [get]

Gets whether or not the table is in editing mode.

string Table.Filename [get, set]

Gets the filename of the DBF file if the table is bound to one.

New API 4.9.4:
Added in version 4.9.4

The global callback is the interface used by MapWinGIS to pass progress and error events to interested applications.

Deprecated:
v4.9.3 Use GlobalSettings.ApplicationCallback instead.
bool Table.IsJoined [get]

Gets a value indicating whether the table has any joined tables.

New API 4.9.0:
Added in version 4.9.0
int Table.JoinCount [get]

Gets number of joins for the table.

New API 4.9.0:
Added in version 4.9.0
string Table.Key [get, set]

The key may be used by the programmer to store any string data associated with the object.

Retrieves the last error generated in the object.

int Table.NumFields [get]

Gets the number of fields in the table.

int Table.NumRows [get]

Gets the number of rows in the table.

Examples:
PointIcons.cs.
 All Classes Files Functions Enumerations Properties Events