Table Class Reference

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

Collaboration diagram for Table:
Collaboration graph

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

Properties

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

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:

  • field names (in square brackets);
  • arithmetic operators (+ (also works for concatenation of strings), -, *, /, \ (interger division), ^ (raising to power));
  • comparison operators (>, <, <=, >=, <>, =);
  • logical operators (AND, OR, XOR, NOT);
  • logical constants (TRUE, FALSE);
  • string constants (e.g. "my_string_constant");
  • round brackets (to control order of evaluation);

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

  • double (integers are treated as doubles as well);
  • string;
  • boolean.

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

◆ Calculate()

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

◆ ClearCache()

void Table.ClearCache ( )

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

New API 4.9.4:
Added in version 4.9.4

◆ Close()

bool Table.Close ( )

Closes the attribute table.

Returns
The value can be ignored.
Examples:
CalculateArea.cs.

◆ CreateNew()

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.

◆ Deserialize()

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

◆ Dump()

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

◆ EditAddField()

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

◆ EditCellValue()

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.

◆ EditClear()

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.

◆ EditDeleteField()

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

◆ EditDeleteRow()

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.

◆ EditInsertField()

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.

◆ EditInsertRow()

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.

◆ EditReplaceField()

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.

◆ get_CellValue()

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.

◆ get_ErrorMsg()

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.

◆ get_Field()

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.

◆ get_FieldIndexByName()

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.

◆ get_FieldIsJoined()

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

◆ get_FieldJoinIndex()

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

◆ get_JoinFields()

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

◆ get_JoinFilename()

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

◆ get_JoinFromField()

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

◆ get_JoinOptions()

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

◆ get_JoinToField()

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

◆ get_MaxValue()

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

◆ get_MeanValue()

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

◆ get_MinValue()

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

◆ get_RowIsModified()

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

◆ get_StandardDeviation()

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

◆ Join()

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

◆ Join2()

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

◆ Join3()

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

◆ Open()

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.

◆ ParseExpression()

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

◆ Query()

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

◆ Save()

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

◆ SaveAs()

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.

◆ Serialize()

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

◆ StartEditingTable()

bool Table.StartEditingTable ( ICallback  cBack)

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.

◆ StopAllJoins()

void Table.StopAllJoins ( )

Stops all joins associated with table.

New API 4.9.0:
Added in version 4.9.0

◆ StopEditingTable()

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.

◆ StopJoin()

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

◆ TestExpression()

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

◆ TryJoin()

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

◆ CdlgFilter

string Table.CdlgFilter
get

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

◆ EditingTable

bool Table.EditingTable
get

Gets whether or not the table is in editing mode.

◆ Filename

string Table.Filename
get

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

◆ GlobalCallback

ICallback Table.GlobalCallback
getset

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.

◆ IsJoined

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

◆ JoinCount

int Table.JoinCount
get

Gets number of joins for the table.

New API 4.9.0:
Added in version 4.9.0

◆ Key

string Table.Key
getset

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

◆ LastErrorCode

int Table.LastErrorCode
get

Retrieves the last error generated in the object.

◆ NumFields

int Table.NumFields
get

Gets the number of fields in the table.

◆ NumRows

int Table.NumRows
get

Gets the number of rows in the table.

Examples:
PointIcons.cs.