Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
tclgeomap(3)		     TkGeoMap C	Functions		  tclgeomap(3)

NAME
       Tclgeomap_Init,	Tclgeomap_NewGeoPtObj,	Tclgeomap_SetGeoPtObj,	Tclge-
       omap_GetGeoPtFromObj,   Tclgeomap_NewMapPtObj,	Tclgeomap_SetMapPtObj,
       Tclgeomap_GetMapPtFromObj,   Tclgeomap_JulDayToList,  Tclgeomap_Append-
       Time, Tclgeomap_GetProj,	 Tclgeomap_ProjName,  Tclgeomap_AddProjUpdate-
       Task,  Tclgeomap_CnxProjUpdateTask, Tclgeomap_AddProjDeleteTask,	Tclge-
       omap_CnxProjDeleteTask, Tclgeomap_AddLnArr, Tclgeomap_GetLnArr,	Tclge-
       omap_LnArrName, Tclgeomap_AddLnArrDeleteTask, Tclgeomap_CnxLnArrDelete-
       Task,   Tclgeomap_LnArrToMap,   Tclgeomap_AddPlaceUpdateTask,	Tclge-
       omap_CnxPlaceUpdateTask,	 Tclgeomap_AddPlaceDeleteTask,	Tclgeomap_Cnx-
       PlaceDeleteTask,	Tclgeomap_GetPlace, Tclgeomap_PlaceLoc,	Tclgeomap_Pla-
       ceName -	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 func-
       tions 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	infor-
       mation 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	inter-
       nal 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.	Tclge-
       omap_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	inter-
       nal 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_SetGeo-
       TimeObj 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.	Tclge-
       omap_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  conver-
       sion,  it  returns  TCL_ERROR and leaves	an error message in the	inter-
       preter'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  Geo-
       Time_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	Tclge-
       omap_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  geo-
       Proj.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_CnxPlaceUp-
       dateTask.  Therefore, clientData	must not be NULL.

       Tclgeomap_CnxProjUpdateTask cancels an update task created with	Tclge-
       omap_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_Cnx-
       PlaceDeleteTask.	 Therefore, clientData must not	be NULL.

       Tclgeomap_CnxProjDeleteTask  cancels  a delete task created with	Tclge-
       omap_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	Tclge-
       omap_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	Tclge-
       omapLnArr, 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 ::	names-
       pace 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.	tclGe-
       oLnArr 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 usu-
       ally 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	Tclge-
       omap_CnxLnArrDeleteTask.

       Tclgeomap_CnxLnArrDeleteTask cancels a  callback	 created  with	Tclge-
       omap_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	Tclge-
       omap_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 (Tclge-
       omap_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.	There-
       fore, 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	Tclge-
       omap_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)

NAME | SYNOPSIS | INTRODUCTION | GEOGRAPHY OBJECTS | TIME | PROJECTIONS | LINE ARRAYS | PLACES | SEE ALSO | FILES | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tclgeomap&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help