See the file man.macros.

NAME

Tclgeomap_Init, Tclgeomap_NewGeoPtObj, Tclgeomap_SetGeoPtObj, Tclgeomap_GetGeoPtFromObj, Tclgeomap_NewMapPtObj, Tclgeomap_SetMapPtObj, Tclgeomap_GetMapPtFromObj, Tclgeomap_JulDayToList, Tclgeomap_AppendTime, Tclgeomap_GetProj, Tclgeomap_ProjName, Tclgeomap_AddProjUpdateTask, Tclgeomap_CnxProjUpdateTask, Tclgeomap_AddProjDeleteTask, Tclgeomap_CnxProjDeleteTask, Tclgeomap_AddLnArr, Tclgeomap_GetLnArr, Tclgeomap_LnArrName, Tclgeomap_AddLnArrDeleteTask, Tclgeomap_CnxLnArrDeleteTask, Tclgeomap_LnArrToMap, Tclgeomap_AddPlaceUpdateTask, Tclgeomap_CnxPlaceUpdateTask, Tclgeomap_AddPlaceDeleteTask, Tclgeomap_CnxPlaceDeleteTask, Tclgeomap_GetPlace, Tclgeomap_PlaceLoc, Tclgeomap_PlaceName - C API for manipulating geographic data in Tcl.

SYNOPSIS

#include <tclgeomap.h>

int Tclgeomap_Init(Tcl_Interp *interp);
Tcl_Obj * Tclgeomap_NewGeoPtObj(GeoPt geoPt);
void Tclgeomap_SetGeoPtObj(Tcl_Obj *objPtr, GeoPt geoPt);
int Tclgeomap_GetGeoPtFromObj(Tcl_Inter *interp, Tcl_Obj *objPtr, GeoPt *geoPtPtr);
Tcl_Obj * Tclgeomap_NewMapPtObj(MapPt mapPt);
void Tclgeomap_SetMapPtObj(Tcl_Obj *objPtr, MapPt mapPt);
int Tclgeomap_GetMapPtFromObj(Tcl_Inter *interp, Tcl_Obj *objPtr, MapPt *mapPtPtr);

Tcl_Obj *Tclgeomap_NewGeoTimeObj(struct GeoTime_Jul jul);
void Tclgeomap_SetGeoTimeObj(Tcl_Obj *ptr, struct GeoTime_Jul jul);
int Tclgeomap_GetGeoTimeFromObj(Tcl_Interp *interp, Tcl_Obj *objPtr, struct GeoTime_Jul *julPtr);
Tcl_Obj *Tclgeomap_JulDayToList(struct GeoTime_Jul jul);
void Tclgeomap_AppendTime(Tcl_Obj *list, struct GeoTime_Jul jul);

TclgeomapProj Tclgeomap_GetProj(Tcl_Inter *interp, char *projName);
const char * Tclgeomap_ProjName(Tclgeomap_Proj proj);
void Tclgeomap_AddProjUpdateTask(Tclgeomap_Proj proj, Tclgeomap_ProjUpdateProc proc, ClientData clientData);
void Tclgeomap_CnxProjUpdateTask(Tclgeomap_Proj proj, ClientData clientData);
void Tclgeomap_AddProjDeleteTask(Tclgeomap_Proj proj, Tclgeomap_ProjDeleteProc proc, ClientData clientData);
void Tclgeomap_CnxProjDeleteTask(Tclgeomap_Proj proj, ClientData clientData);

TclgeomapLnArr Tclgeomap_AddLnArr(Tcl_Inter *interp, char *arrNm, GeoLnArr geoLnArr);
void Tclgeomap_AddLnArrDeleteTask(Tclgeomap_LnArr tclGeoLnArr, Tclgeomap_LnArrDeleteProc proc, ClientData clientData);
void Tclgeomap_CnxLnArrDeleteTask(Tclgeomap_LnArr tclGeoLnArr, ClientData clientData);
TclgeomapLnArr Tclgeomap_GetLnArr(Tcl_Inter *interp, char * arrNm);
char * Tclgeomap_LnArrName(Tclgeomap_LnArr tclGeoLnArr);
MapLnArr Tclgeomap_LnArrToMap(struct Tclgeomap_LnArr *lnArrPtr, Tclgeomap_Proj proj)

void Tclgeomap_AddPlaceUpdateTask(Tclgeomap_Place place, Tclgeomap_PlaceUpdateProc proc, ClientData clientData);
void Tclgeomap_CnxPlaceUpdateTask(Tclgeomap_Place place, ClientData clientData);
void Tclgeomap_AddPlaceDeleteTask(Tclgeomap_Place place,Tclgeomap_PlaceDeleteProc proc, ClientData clientData);
void Tclgeomap_CnxPlaceDeleteTask(Tclgeomap_Place place, ClientData clientData);
TclgeomapPlace Tclgeomap_GetPlace(Tcl_Inter *interp,char * placeName);
GeoPt Tclgeomap_PlaceLoc(Tclgeomap_Place place);
char *Tclgeomap_PlaceName(Tclgeomap_Place place);

INTRODUCTION

This document describes the exported data types, structures, and functions used by the the tclgeomap package. The the tclgeomap (n) man page for information on the Tcl commands added by this package.

GEOGRAPHY OBJECTS

These procedures are used to create, modify, and read GeoPt and MapPt Tcl objects from C code. A GeoPt object stores a GeoPt value. A MapPt object stores a MapPt value. See the geography (3) man page for information about GeoPt's and MapPt's.

Tclgeomap_Init initializes the tclgeomap package in interp. See the tclgeomap (n) man page for a list of commands this package adds.

Tclgeomap_NewGeoPtObj and Tclgeomap_SetGeoPtObj will create a new object of GeoPt type or modify an existing object to have GeoPt type. Both of these procedures set the object to have the GeoPt value given by geoPt; Tclgeomap_NewGeoPtObj returns a pointer to a newly created object with reference count zero. Both procedures set the object to GeoPt type and assign the the object's internal representation to a pointer containing geoPt. Tclgeomap_SetGeoPtObj invalidates any old string representation in objPtr and, if the object is not already a GeoPt object, frees any old internal representation.

Tclgeomap_GetGeoPtFromObj attempts to return a GeoPt value from the Tcl object objPtr. If the object is not already a GeoPt object, it will attempt to convert it to one. If an error occurs during conversion, it returns TCL_ERROR and leaves an error message in the interpreter's result object unless interp is NULL. Otherwise, it returns TCL_OK and stores the GeoPt value in the address given by geoPtPtr. If the object is not already a GeoPt object, the conversion will free any old internal representation.

These procedures are used to create, modify, and read mapPt Tcl objects from C code. A MapPt object is one that stores a MapPt value, which is an {abscissa ordinate} pair identifying a location on a 2D map. See the Geography man page for information about MapPt's. Tclgeomap_NewMapPtObj and Tclgeomap_SetMapPtObj will create a new object of MapPt type or modify an existing object to have MapPt type. Both of these procedures set the object to have the MapPt value given by mapPt; Tclgeomap_NewMapPtObj returns a pointer to a newly created object with reference count zero. Both procedures set the object to MapPt type and assign the the object's internal representation to a pointer containing mapPt. Tclgeomap_SetMapPtObj invalidates any old string representation in objPtr and, if the object is not already a MapPt object, frees any old internal representation.

Tclgeomap_GetMapPtFromObj attempts to return a MapPt value from the Tcl object objPtr. If the object is not already a MapPt object, it will attempt to convert it to one. If an error occurs during conversion, it returns TCL_ERROR and leaves an error message in the interpreter's result object unless interp is NULL. Otherwise, it returns TCL_OK and stores the MapPt value in the address given by mapPtPtr. If the object is not already a MapPt object, the conversion will free any old internal representation.

TIME

The Tclgeomap package includes functions that store and manipulate time instants stored in Tcl objects. Times are written and read as lists of form {year month day hour minute second}, although they are internally stored and manipulated as GeoTime_Jul structures, as described in the geography (3) man page. Tclgeomap_NewGeoTimeObj and Tclgeomap_SetGeoTimeObj will create a new object of GeoTime type or modify an existing object to have GeoTime type. Both of these procedures set the object's value to a GeoTime_Jul structure given by jul; Tclgeomap_NewGeoTimeObj returns a pointer to a newly created object with reference count zero. Both procedures set the object to GeoTime type and assign the the object's internal representation to a pointer containing jul. Tclgeomap_SetGeoTimeObj invalidates any old string representation in objPtr and, if the object is not already a GeoTime object, frees any old internal representation.

Tclgeomap_GetGeoTimeFromObj attempts to return a GeoTime value from the Tcl object objPtr. If the object is not already a GeoTime object, it will attempt to convert it to one. If an error occurs during conversion, it returns TCL_ERROR and leaves an error message in the interpreter's result object unless interp is NULL. Otherwise, it returns TCL_OK and stores the GeoTime value in the address given by julPtr. If the object is not already a GeoTime object, the conversion will free any old internal representation.

Tclgeomap_JulDayToList returns a Tcl list object whose elements are {year month day hour minute second} corresponding to the time in GeoTime_Jul struct jul. The return value is a Tcl object with a reference count of 0. The user should eventually free it by decrementing its reference count.

Tclgeomap_AppendTime appends a list object with the {year month day hour minute second} corresponding to the time in jul to list object list.

PROJECTIONS

The tclgeomap package accesses projections using the interface described in the GeoProj (3) man page. The following functions make the functions and structures of the geoProj interface available to Tcl. The package interface accesses geolinearrays as values of type Tclgeomap_LnArr, which can also be used as values of type GeoLnArr in the functions described in the GeoLnArr man page.

Tclgeomap_GetProj returns a token for a projection created with a call to geomap::projection new in Tcl. name is the name of the projection, which is also the name of the Tcl command that accesses the projection. The return value is also the clientData value of the Tcl command. It can also be used as the GeoProj argument in functions declared in geoProj.h and described in the geoProj(3) man page.

Tclgeomap_AddProjUpdateTask arranges for proc to be called whenever the projection identified as proj changes. proc must be a function of form: typedef void (Tclgeomap_ProjUpdateProc)(ClientData clientData); clientData will be given as one of the arguments to proc, and is also used to identify the task in a subsequent call to Tclgeomap_CnxPlaceUpdateTask. Therefore, clientData must not be NULL.

Tclgeomap_CnxProjUpdateTask cancels an update task created with Tclgeomap_AddProjUpdateTask. proj and clientData are the values given in the previous call to Tclgeomap_AddProjUpdateTask.

Tclgeomap_AddProjDeleteTask arranges for proc to be called when the projection identified as proj disappears. proc must be a function of form: typedef void (Tclgeomap_ProjDeleteProc)(ClientData clientData); clientData will be given as one of the arguments to proc, and is also used to identify the task in a subsequent call to Tclgeomap_CnxPlaceDeleteTask. Therefore, clientData must not be NULL.

Tclgeomap_CnxProjDeleteTask cancels a delete task created with Tclgeomap_AddProjDeleteTask. proj and clientData are the values given in the previous call to Tclgeomap_AddProjDeleteTask.

LINE ARRAYS

The tclgeomap package maintains a database of geolinearrays, which are containers for geographic points. See the GeoLnArr (3) man page for geolinearrays and the C functions required to create and access them. The package interface accesses geolinearrays as values of type Tclgeomap_LnArr, which can also be used as values of type GeoLnArr in the functions described in the GeoLnArr man page.

Tclgeomap_AddLnArr adds geoLnArr to the linearray database. If arrNm contains namespace qualifiers, the linearray's command is added to the specified namespace; otherwise it is added to the global namespace. The clientData for this command is set to a struct of type TclgeomapLnArr, which is returned. It will contain geoLnArr along with additional information needed by the Tcl interpreter. Any previous command with the same name is deleted. The Tclgeomap_LnArr structure and geoLnArr should be freed by destroying the linearray's command.

Tclgeomap_GetLnArr returns the Tclgeomap_LnArr object for the linearray named arrNm. If arrNm is not fully qualified the array must be in the current namespace or global. Tclgeomap_GetLnArr returns NULL if there is no array named arrNm.

Tclgeomap_LnArrName returns the name of linearray tclGeoLnArr, which is also the name of its command. The name does not include any :: namespace qualifiers. The return value should not be modified by the user.

Tclgeomap_AddLnArrDeleteTask arranges for a function to be called when a linearray is deleted. This makes it possible for objects concerned with the existence of the linearray to take appropriate action if/when the linearray is deleted, such as erasing the lines from a map. tclGeoLnArr identifies the array of interest. It should be the return value of a previous call to Tclgeomap_AddLnArr or Tclgeomap_GetLnArr. proc is the procedure to call when the linearray is deleted. It should be of form: typedef void (Tclgeomap_LnArr)(ClientData clientData); The clientData argument to Tclgeomap_AddLnArrDeleteTask is given as the clientData argument to the deletion procedure when called. It is usually the address of the object that interacts with the linearray. In addition, clientData is used to refer to the deletion task later. Therefore, it must uniquely identify the deletion task, and cannot be NULL. The callback should eventually be canceled with a call to Tclgeomap_CnxLnArrDeleteTask.

Tclgeomap_CnxLnArrDeleteTask cancels a callback created with Tclgeomap_AddLnArrDeleteTask. This procedure should be called when the object that was interested in the existence of the linearray disappears or no longer needs the array. tclGeoLnArr identifies the array. clientData should be the clientData argument that was given to Tclgeomap_AddLnArrDeleteTask.

Tclgeomap_LnArrToMap returns an array of map points corresponding to the geographic points in lnArrPtr. The transformation is performed with projection proj. The returned array belongs to the geolinearray and should not be destroyed or modified by the user.

PLACES

These functions access the Tcl place database. A place is a character string name associated with a geographic point (see Geography (3)). Geoplaces are accessed through objects of type TclgeomapPlace. They are created with various subcommands of the geomap::place command, as described in the tclgeomap (n) man page.

Tclgeomap_PlaceName returns the name of a place, which is also the name of its command. The name does not include any :: namespace qualifiers. The return value should not be modified by the user.

Tclgeomap_AddPlaceUpdateTask arranges for function proc to be called when the place identified as place moves. This allows other objects to take appropriate action, such as updating a map display. proc must be of type Tclgeomap_PlaceUpdateProc, declared as typedef void (Tclgeomap_PlaceUpdateProc)(ClientData); clientData will be given as one of the arguments to proc when called, and is also used to identify the task in a subsequent call to Tclgeomap_CnxPlaceUpdateTask. Therefore, clientData must uniquely identify the update task and must not be NULL. It is usually the address of an object.

Tclgeomap_CnxPlaceUpdateTask cancels an update task given to place by a call to Tclgeomap_AddPlaceUpdateTask. clientData is the value given in the previous call to Tclgeomap_AddPlaceUpdateTask.

Tclgeomap_AddPlaceDeleteTask arranges for function proc to be called when the place identified as place is deleted. This allows other objects to take appropriate action, such as updating a map display. placeDeleteroc must be of type Tclgeomap_PlaceDeleteProc, declared as: typedef void (Tclgeomap_PlaceDeleteProc)(ClientData); clientData will be given as one of the arguments to proc, and is also used to identify the task in a subsequent call to Tclgeomap_CnxPlaceDeleteTask. Therefore, clientData must not be NULL.

Tclgeomap_CnxPlaceDeleteTask cancels an delete task given to place by a call to Tclgeomap_AddPlaceDeleteTask. clientData is the value given in the previous call to Tclgeomap_AddPlaceDeleteTask.

Tclgeomap_GetPlace returns the place named name. name may include :: namespace qualifiers to identify a place in a particular namespace. If no place is found, Tclgeomap_GetPlace returns NULL.

Tclgeomap_PlaceLoc returns the GeoPt struct associated with Tclgeomap_Place place

FILES

libtclgeomap2.11.6.a libtclgeomap2.11.6.so

KEYWORDS

latitude, longitude, GeoPt object, GeoPt type, abscissa, ordinate, MapPt object, MapPt type, internal representation, object, object type, string representation, geoproj, projection, geography, geolinearray, GeoLnArr, geography, geoplace, geography