[HOME][CONTENTS][DOWNLOAD][PREV][NEXT]


GTABLE DATA PROCESSING

In addition to shape object, XBit provides gtable object to handle shape object related attribute data.  An XBit table object is an encapsulation of code and data with both C and Tcl API.  A table object can receive data from either scripts or files.  Currently, a gtable object can read data from and write data to a table (.dbf) file.

Create A GTable Object.  A gtable object is created using Tcl command 

gtable.create gtableObject ?options?
where gtableObject is a new Tcl command to identify and interface to an instantiated table object via Tcl scripts. Options for creating a table object include -file and -update.  Option -file specifies a table (.dbf) file to initialize the table object.  Option -update can be configured to either 0 or 1.  When a client opens a gtable object via its C API, it can add a call back function for the updating event.  When option -update is set to 1, a gtable object will invoke call back functions of its clients whenever its contents have been changed. 

Define A GTable Object. To define a newly created table object, use the following command,

gtableObject define fieldDefinition ?filedDefinition?...
where fieldDefinition is a field definition list consisting of four elements {fieldName type width decimal}, where fieldName speicfies the name of the field and must be a string with no space, type specifies the data type of the field and must be one of the following characters: (for numerical data type), C (for character string), L (for logical data type), D (for date data type), M (for memo text), width is an integer to specify the size of the data element, decimal is an integer to specify the number of decimals of a numerical data type and must be 0 for data types C, L, D or M.

To add new data fields into a gtable object, use the following command,

gtableObject addfields fieldDefinitionList ?fieldList?
where fileDefinitionList is a list of field definition, fieldList is a list of initial values for the newly added fields.  The added fields are always appended at the end of the current field list.

To insert new data fields into a gtable object, use the following command,

gtableObject insertfields position fieldDefinitionList ?fieldList?
where position specifies the index of the current field list to insert the new fields.

To delete a field, use the following command,

gtableObject delete fieldName
Edit A GTable Object.  To add records into a gtable object, use the following command,
gtableObject addrecord ?record?
where record specifies a list of data items of a record to be appended at the end of the gtable object.

To insert records into a gtable object, use the following command,

gtableObject insertrecords position ?nRecords? ?recordList?
where position specifies the position to insert the records, nRecords specifies the number of records to insert and recordList specifies a list of records to intialize the newly inserted records.  If nRecords and recordList are not specified, one empty record will be inserted. If recordList is not specified, nRecords of empty records will be inserted.

To delete records, use the following command,

gtableObject deleterecords ?index?...
The deleted records are only marked as deleted and can be undeleted by the following command,
gtableObject undeleterecords ?index?...
To erase deleted records permanently, use the following command,
gtableObject purge
To set a record's field value, use the following command,
gtableObject setfield recordIndex fieldIndex value
To set a whole record, use the following command,
gtableObject setrecord index record
To save a gtable object into a file, use the following command,
gtableObject save fileName
GTable Data Analysis.  For a gtable object analysis, the first thing to do is to retrieve primative information of a gtable object using the following command,
set info [gtableObject info]
The returned info is a list of field definitions.  Each field definition is a list of {name type length decimal}, where name is the field name, type is the field data type, length is the size of the field in bytes and decimal is the number of decimals if the field is of type N (i.e., numerical type). 

A tabular data anaylysis involves both data retrieval and comparison.  To retrieve a gtable record, use the following command,

set record [gtableObjectgetrecord index]
The returned record is a list of field values of the specified record. 

To retrieve a field value of a gtable record, use the following command,

set filedvalue [gtableObject getfield recordIndex fieldIndex]
Tcl procedures may be developed to process the retrieved data against interested attribute values and selection can be performed based on the processing result.

To select/unselect records, use the following commands,

gtableObject aselect ?index?...
gtableObject select ?index?...
gtableObject selectonly ?index?...
gtableObject unselect ?index?...
gtableObject unselectonly ?index?...
The aselect command reverses the selection status of selected records to unselected and unselected records to selected.  The select command adds the selected records into the already selected record pools.  The selectonly command selects the specified records and unselects others; the unselect command adds the unselected records into the already unselected record pool.  The unselectonly command unselects the specified records and selects others.

To combine data retrieval, process and selection together, use the following command,

gtableObject match predicateScript action
where predicateScript is a Tcl scriptic predicate with field values of a record and action is a build-in command and must be one of select, unselect, selectonly, unselectonly, aselect, and list.  A predicateScript returns 1 if its evaluation is true or 0 otherwise. The match command evaluates every records of a gtable object with perdicateScript and fires action against the record if an evaluation result of predicateScript is 1.  A field value may be specifed in a predicate script by its name following a "%".  For example, "expr %AREA < 500.0" is a predicate script expression that returns 1 if the value of the field AREA is less than 500. A record may be specified by %{RECORD} and a record index %{INDEX}.  A select action selects the record if evaluation of predicateScript is true.  An unselect action unselects the record if evaluation of predicateScript is true.  An aselect action reverse the selected records to unselected and vise verser if evaluation of predicateScript is true.  A selectonly action selects the record if evaluation of predicateScript is true and unselect it otherwise.  An unselectonly action unselects the record if evaluation of predicateScript is true and selets it otherwise.  A list action adds the index of a record into a return list if evaluation of predicateScript is true.

Using GTable Object in Map Processing.  A gtable object may be used with a shape object for map display with a gcanvas widget.  A gtable object created from a shape .dbf file provides additional attributes for the shape object.  A user may use these attributes for additional text annotations and graphic labels in map display.  In addition, a user may select records with predicate scripts and use the result to directly match the shape object in display.  In the following example, we first create a world map with a shape data set. 

# create a shape object and its associate gtable object
shape.create countries -file cntry94.shp
gtable.create countries.tb -file cntry94.dbf

# create a gcanvas widget and display the shape object
gcanvas .map -mx 1.5 -my -1.5 -viewx -180 -viewy 90 -highlightthickness 0 -update 1 -bg darkblue
.map create object 0 0 -object countries -outline red -fill darkgreen
pack .map -expand 1 -fill both

Then we highlight regions with areas greater than 1000000 square miles and draw proper text labels:
# In the gtable object, find indices of the regions with areas greater than 1000000 square miles
set selectedIndices [countries.tb match "expr %AREA > 1000000" list]

# match the shape object selection with its associated gtable selection
countries match countries.tb

# clone a shape object of the selected shape records
countries clone bigregions selected

# reselect the original shape object and display the cloned shape object
countries select 
.map create object 0 0 -object bigregions -outline green -fill brown

# find the field index of the NAME field
set fieldIndex 0
foreach {name type length decimal} [countries.tb info] {
     if {$name == "NAME"} break
     incr fieldIndex
}

# annotate the areas with proper text label
foreach index $selectedIndices {
    set name  [countries.tb getfield $index $fieldIndex]
    set centroid [lindex [countries centroid $index average] 0]
    set x [lindex $centroid 0]
    set y [lindex $centroid 1]
    .map create text $x $y -text $name -anchor center -fill yellow
}


[HOME][CONTENTS][DOWNLOAD]