.\"
.\" Copyright (c) 2004 Gordon D. Carrie.  All rights reserved.
.\" 
.\" Licensed under the Open Software License version 2.1
.\" 
.\" Please address questions and feedback to user0@tkgeomap.org
.\" 
.\" @(#) $Id: tclgeomap.3,v 1.25 2007/06/29 16:07:54 tkgeomap Exp $
.so man.macros
.TH tclgeomap 3 2 Tcl "TkGeoMap C Functions"
.SH 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.
.SH SYNOPSIS
.nf
\fB#include <tclgeomap.h>\fR
.sp
\fBint Tclgeomap_Init(Tcl_Interp *\fIinterp\fB);\fR
\fBTcl_Obj * Tclgeomap_NewGeoPtObj(GeoPt \fIgeoPt\fB);\fR
\fBvoid Tclgeomap_SetGeoPtObj(Tcl_Obj *\fIobjPtr\fB, GeoPt \fIgeoPt\fB);\fR
\fBint Tclgeomap_GetGeoPtFromObj(Tcl_Inter *\fIinterp\fB, Tcl_Obj *\fIobjPtr\fB, GeoPt *\fIgeoPtPtr\fB);\fR
\fBTcl_Obj * Tclgeomap_NewMapPtObj(MapPt \fImapPt\fB);\fR
\fBvoid Tclgeomap_SetMapPtObj(Tcl_Obj *\fIobjPtr\fB, MapPt \fImapPt\fB);\fR
\fBint Tclgeomap_GetMapPtFromObj(Tcl_Inter *\fIinterp\fB, Tcl_Obj *\fIobjPtr\fB, MapPt *\fImapPtPtr\fB);\fR
.sp
\fBTcl_Obj\fR *\fBTclgeomap_NewGeoTimeObj\fR(\fBstruct GeoTime_Jul\fR \fIjul\fR);
\fBvoid\fR \fBTclgeomap_SetGeoTimeObj\fR(\fBTcl_Obj\fR *\fIptr\fR, \fBstruct GeoTime_Jul\fR \fIjul);
\fBint\fR \fBTclgeomap_GetGeoTimeFromObj\fR(\fBTcl_Interp\fR *\fIinterp\fR, \fBTcl_Obj\fR *\fIobjPtr\fR, \fBstruct GeoTime_Jul\fR *\fIjulPtr\fR);
\fBTcl_Obj\fR *\fBTclgeomap_JulDayToList\fR(\fBstruct GeoTime_Jul\fR \fIjul\fR);
\fBvoid\fR \fBTclgeomap_AppendTime\fR(\fBTcl_Obj\fR *\fIlist\fR, \fBstruct GeoTime_Jul\fR \fIjul\fR);
.sp
\fBTclgeomapProj Tclgeomap_GetProj(Tcl_Inter *\fIinterp\fB, char *\fIprojName\fB);\fR
\fBconst char * Tclgeomap_ProjName(Tclgeomap_Proj \fIproj\fB);\fR
\fBvoid Tclgeomap_AddProjUpdateTask(Tclgeomap_Proj \fIproj\fB, Tclgeomap_ProjUpdateProc \fIproc\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_CnxProjUpdateTask(Tclgeomap_Proj \fIproj\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_AddProjDeleteTask(Tclgeomap_Proj \fIproj\fB, Tclgeomap_ProjDeleteProc \fIproc\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_CnxProjDeleteTask(Tclgeomap_Proj \fIproj\fB, ClientData \fIclientData\fB);\fR
.sp
\fBTclgeomapLnArr Tclgeomap_AddLnArr(Tcl_Inter *\fIinterp\fB, char *\fIarrNm\fB, GeoLnArr \fIgeoLnArr\fB);\fR
\fBvoid Tclgeomap_AddLnArrDeleteTask(Tclgeomap_LnArr \fItclGeoLnArr\fB, Tclgeomap_LnArrDeleteProc \fIproc\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_CnxLnArrDeleteTask(Tclgeomap_LnArr \fItclGeoLnArr\fB, ClientData \fIclientData\fB);\fR
\fBTclgeomapLnArr Tclgeomap_GetLnArr(Tcl_Inter *\fIinterp\fB, char * \fIarrNm\fB);\fR
\fBchar * Tclgeomap_LnArrName(Tclgeomap_LnArr \fItclGeoLnArr\fB);\fR
\fBMapLnArr\fR \fBTclgeomap_LnArrToMap\fR(\fBstruct Tclgeomap_LnArr\fR *\fIlnArrPtr\fR, \fBTclgeomap_Proj\fR \fIproj\fR)\fR
.sp
\fBvoid Tclgeomap_AddPlaceUpdateTask(Tclgeomap_Place \fIplace\fB, Tclgeomap_PlaceUpdateProc \fIproc\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_CnxPlaceUpdateTask(Tclgeomap_Place \fIplace\fB, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_AddPlaceDeleteTask(Tclgeomap_Place \fIplace\fB,Tclgeomap_PlaceDeleteProc \fIproc, ClientData \fIclientData\fB);\fR
\fBvoid Tclgeomap_CnxPlaceDeleteTask(Tclgeomap_Place \fIplace\fB, ClientData \fIclientData\fB);\fR
\fBTclgeomapPlace Tclgeomap_GetPlace(Tcl_Inter *\fIinterp\fB,char * \fIplaceName\fB);\fR
\fBGeoPt Tclgeomap_PlaceLoc(Tclgeomap_Place \fIplace\fB);\fR
\fBchar *Tclgeomap_PlaceName(Tclgeomap_Place \fIplace\fB);\fR
.fi
.SH INTRODUCTION
This document describes the exported data types, structures, and functions used
by the the tclgeomap package.  The the \fBtclgeomap\fR (n) man page for
information on the Tcl commands added by this package.
.SH 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 \fBgeography\fR (3) man page for information about GeoPt's and MapPt's.
.PP
\fBTclgeomap_Init\fR initializes the \fBtclgeomap\fR package in \fIinterp\fR.
See the \fBtclgeomap\fR (n) man page for a list of commands this package
adds.
.PP
\fBTclgeomap_NewGeoPtObj\fR and \fBTclgeomap_SetGeoPtObj\fR
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 \fIgeoPt\fR;
\fBTclgeomap_NewGeoPtObj\fR 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 \fIgeoPt\fR.
\fBTclgeomap_SetGeoPtObj\fR invalidates any old string representation in
\fIobjPtr\fR and, if the object is not already a GeoPt object,
frees any old internal representation.
.PP
\fBTclgeomap_GetGeoPtFromObj\fR attempts to return a GeoPt value
from the Tcl object \fIobjPtr\fR.
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 \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR and stores the GeoPt value
in the address given by \fIgeoPtPtr\fR.
If the object is not already a GeoPt object,
the conversion will free any old internal representation.
.PP
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 \fBGeography\fR man page for information about
MapPt's.
\fBTclgeomap_NewMapPtObj\fR and \fBTclgeomap_SetMapPtObj\fR
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 \fImapPt\fR;
\fBTclgeomap_NewMapPtObj\fR 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 \fImapPt\fR.
\fBTclgeomap_SetMapPtObj\fR invalidates any old string representation in
\fIobjPtr\fR and, if the object is not already a MapPt object,
frees any old internal representation.
.PP
\fBTclgeomap_GetMapPtFromObj\fR attempts to return a MapPt value
from the Tcl object \fIobjPtr\fR.
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 \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR and stores the MapPt value
in the address given by \fImapPtPtr\fR.
If the object is not already a MapPt object,
the conversion will free any old internal representation.
.SH 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 \fBGeoTime_Jul\fR structures, as described in the
\fBgeography\fR (3) man page.
\fBTclgeomap_NewGeoTimeObj\fR and \fBTclgeomap_SetGeoTimeObj\fR
will create a new object of \fBGeoTime\fR type
or modify an existing object to have \fBGeoTime\fR type. 
Both of these procedures set the object's value to a \fBGeoTime_Jul\fR structure
given by \fIjul\fR;
\fBTclgeomap_NewGeoTimeObj\fR returns a pointer to a newly created object
with reference count zero.
Both procedures set the object to \fBGeoTime\fR type 
and assign the the object's internal representation
to a pointer containing \fIjul\fR.
\fBTclgeomap_SetGeoTimeObj\fR invalidates any old string representation in
\fIobjPtr\fR and, if the object is not already a \fBGeoTime\fR object,
frees any old internal representation.
.PP
\fBTclgeomap_GetGeoTimeFromObj\fR attempts to return a \fRGeoTime\fR value
from the Tcl object \fIobjPtr\fR.
If the object is not already a \fBGeoTime\fR object,
it will attempt to convert it to one.
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
and leaves an error message in the interpreter's result object
unless \fIinterp\fR is NULL.
Otherwise, it returns \fBTCL_OK\fR and stores the \fBGeoTime\fR value
in the address given by \fIjulPtr\fR.
If the object is not already a \fBGeoTime\fR object,
the conversion will free any old internal representation.
.PP
\fBTclgeomap_JulDayToList\fR returns a Tcl list object whose elements are
.CS
{year month day hour minute second}
.CE
corresponding to the time in \fBGeoTime_Jul\fR struct \fIjul\fR.  The return
value is a Tcl object with a reference count
of \fB0\fR.  The user should eventually free it by decrementing its reference
count.
.PP
\fBTclgeomap_AppendTime\fR appends a list object with the
.CS
{year month day hour minute second}
.CE
corresponding to the time in \fIjul\fR to list object \fIlist\fR.
.SH PROJECTIONS
The tclgeomap package accesses projections using the interface described
in the \fBGeoProj\fR (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
\fBTclgeomap_LnArr\fR, which can also be used as values of type \fBGeoLnArr\fR
in the functions described in the \fBGeoLnArr\fR man page.
.PP
\fBTclgeomap_GetProj\fR returns a token for a projection created with a call to
\fBgeomap::projection new\fR
in Tcl.  \fIname\fR 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 \fBGeoProj\fR
argument in functions declared in \fBgeoProj.h\fR and described in the
\fBgeoProj\fR(3) man page.
.PP
\fBTclgeomap_AddProjUpdateTask\fR arranges for \fIproc\fR to be called
whenever the projection identified as \fIproj\fR changes.  \fIproc\fR
must be a function of form:
.CS
typedef void (Tclgeomap_ProjUpdateProc)(ClientData clientData);
.CE
\fIclientData\fR will be given as one of the arguments to \fIproc\fR,
and is also used to identify the task in a subsequent call to
\fBTclgeomap_CnxPlaceUpdateTask\fR.  Therefore, \fIclientData\fR must not be
\fBNULL\fR.
.PP
\fBTclgeomap_CnxProjUpdateTask\fR cancels an update task created with
\fBTclgeomap_AddProjUpdateTask\fR.  \fIproj\fR and \fIclientData\fR are the
values given in the previous call to \fBTclgeomap_AddProjUpdateTask\fR.
.PP
\fBTclgeomap_AddProjDeleteTask\fR arranges for \fIproc\fR to be called
when the projection identified as \fIproj\fR disappears.  \fIproc\fR
must be a function of form:
.CS
typedef void (Tclgeomap_ProjDeleteProc)(ClientData clientData);
.CE
\fIclientData\fR will be given as one of the arguments to \fIproc\fR,
and is also used to identify the task in a subsequent call to
\fBTclgeomap_CnxPlaceDeleteTask\fR.  Therefore, \fIclientData\fR must not be
\fBNULL\fR.
.PP
\fBTclgeomap_CnxProjDeleteTask\fR cancels a delete task created with
\fBTclgeomap_AddProjDeleteTask\fR.  \fIproj\fR and \fIclientData\fR are the
values given in the previous call to \fBTclgeomap_AddProjDeleteTask\fR.
.SH LINE ARRAYS
The tclgeomap package maintains a database of geolinearrays, which are
containers for geographic points.  See the \fBGeoLnArr\fR (3) man page for
geolinearrays and the C functions required to create and access them.
The package interface accesses geolinearrays as values of type
\fBTclgeomap_LnArr\fR, which can also be used as values of type \fBGeoLnArr\fR
in the functions described in the \fBGeoLnArr\fR man page.
.PP
\fBTclgeomap_AddLnArr\fR adds \fIgeoLnArr\fR to the linearray database.
If \fIarrNm\fR 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 \fBTclgeomapLnArr\fR,
which is returned.  It will contain \fIgeoLnArr\fR along with additional
information needed by the Tcl interpreter.  Any previous command with the same
name is deleted.  The Tclgeomap_LnArr structure and \fIgeoLnArr\fR should be freed
by destroying the linearray's command.
.PP
\fBTclgeomap_GetLnArr\fR returns the Tclgeomap_LnArr object for the linearray
named \fIarrNm\fR.  If \fIarrNm\fR is not fully qualified the array must be
in the current namespace or global.  \fBTclgeomap_GetLnArr\fR returns NULL
if there is no array named \fIarrNm\fR.
.PP
\fBTclgeomap_LnArrName\fR returns the name of linearray \fItclGeoLnArr\fR,
which is also the name of its command.  The name does not include any
\fB::\fR namespace qualifiers.  The return value should not be modified by the
user.
.PP
\fBTclgeomap_AddLnArrDeleteTask\fR 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.
\fItclGeoLnArr\fR identifies the array of interest.  It should be the return
value of a previous call to \fBTclgeomap_AddLnArr\fR or
\fBTclgeomap_GetLnArr\fR.  \fIproc\fR is the procedure to call when
the linearray is deleted.  It should be of form:
.CS
typedef void (Tclgeomap_LnArr)(ClientData clientData);
.CE
The \fIclientData\fR argument to \fBTclgeomap_AddLnArrDeleteTask\fR 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, \fIclientData\fR is used to refer to the deletion task later.
Therefore, it must uniquely identify the deletion task, and cannot be
\fBNULL\fR.  The callback should eventually be canceled with a call to
\fBTclgeomap_CnxLnArrDeleteTask\fR.
.PP
\fBTclgeomap_CnxLnArrDeleteTask\fR cancels a callback created with
\fBTclgeomap_AddLnArrDeleteTask\fR.  This procedure should be called
when the object that was interested in the existence of the linearray
disappears or no longer needs the array.  \fItclGeoLnArr\fR identifies the
array.  \fIclientData\fR should be the clientData argument that was given to
\fBTclgeomap_AddLnArrDeleteTask\fR.
.PP
\fBTclgeomap_LnArrToMap\fR returns an array of map points corresponding to
the geographic points in \fIlnArrPtr\fR.  The transformation is performed with
projection \fIproj\fR.  The returned array belongs to the geolinearray and
should not be destroyed or modified by the user.
.SH PLACES
These functions access the Tcl place database.  A place is a character
string name associated with a geographic point (see \fBGeography\fR (3)).
Geoplaces are accessed through objects of type \fBTclgeomapPlace\fR.  They are
created with various subcommands of the \fBgeomap::place\fR command, as
described in the \fBtclgeomap\fR (n) man page.
.PP
\fBTclgeomap_PlaceName\fR returns the name of a place, which is also the name
of its command.  The name does not include any \fB::\fR namespace qualifiers.
The return value should not be modified by the user.
.PP
\fBTclgeomap_AddPlaceUpdateTask\fR arranges for function \fIproc\fR
to be called when the place identified as \fIplace\fR moves.  This allows other
objects to take appropriate action, such as updating a map display.
\fIproc\fR must be of type \fITclgeomap_PlaceUpdateProc\fR,
declared as
.CS
typedef void (Tclgeomap_PlaceUpdateProc)(ClientData);
.CE
\fIclientData\fR will be given as one of
the arguments to \fIproc\fR when called, and is also used to identify
the task in a subsequent call to \fBTclgeomap_CnxPlaceUpdateTask\fR.  Therefore,
\fIclientData\fR must uniquely identify the update task and must not be
\fBNULL\fR.  It is usually the address of an object.
.PP
\fBTclgeomap_CnxPlaceUpdateTask\fR cancels an update task given to \fIplace\fR
by a call to \fBTclgeomap_AddPlaceUpdateTask\fR.  \fIclientData\fR is the value
given in the previous call to \fBTclgeomap_AddPlaceUpdateTask\fR.
.PP
\fBTclgeomap_AddPlaceDeleteTask\fR arranges for function \fBproc\fR to be called
when the place identified as \fIplace\fR is deleted.  This allows other
objects to take appropriate action, such as updating a map display.
\fIplaceDeleteroc\fR must be of type \fITclgeomap_PlaceDeleteProc\fR, declared
as:
.CS
typedef void (Tclgeomap_PlaceDeleteProc)(ClientData);
.CE
\fIclientData\fR will be given as one of the arguments to \fIproc\fR,
and is also used to identify the task in a subsequent call to
\fBTclgeomap_CnxPlaceDeleteTask\fR.  Therefore, \fIclientData\fR must not be
\fBNULL\fR.
.PP
\fBTclgeomap_CnxPlaceDeleteTask\fR cancels an delete task given to \fIplace\fR
by a call to \fBTclgeomap_AddPlaceDeleteTask\fR.  \fIclientData\fR is the value
given in the previous call to \fBTclgeomap_AddPlaceDeleteTask\fR.
.PP
\fBTclgeomap_GetPlace\fR returns the place named \fIname\fR.
\fIname\fR may include \fB::\fR namespace qualifiers to identify a place
in a particular namespace.  If no place is found, \fBTclgeomap_GetPlace\fR
returns \fBNULL\fR.
.PP
\fBTclgeomap_PlaceLoc\fR returns the GeoPt struct associated with
Tclgeomap_Place place
.SH "SEE ALSO"
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
.SH FILES
libtclgeomap2.11.4.a
libtclgeomap2.11.4.so
.SH 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