DragonFly On-Line Manual Pages
tclgeomap(3) TkGeoMap C Functions tclgeomap(3)
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
SEE ALSO
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
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
Tcl 2 tclgeomap(3)