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

FreeBSD Manual Pages


home | help
geomap::igeomap(n)	    Tk Extensions tkgeomap	    geomap::igeomap(n)

       igeomap - create	and manipulate a geographic map	with interactive menus
       and bindings.

       package require tkgeomap_procs ?2?
       geomap::igeomap namespaceName pathName ?options?

       The geomap::igeomap procedure creates a	frame  named  pathName,	 which
       contains	 a canvas with a geographic map	and associated menus.  It also
       creates or modifies a namespace	named  namespaceName.	When  the  ge-
       omap::igeomap  procedure	is called, pathName should not exist, although
       its parent should.  Namespace namespaceName may already exist.  If not,
       it  will	be created.  The igeomap procedure packs the contents of frame
       pathName, but it	does not submit	it to any geometry manager.   The  ap-
       plication  that	creates	 the  igeomap should eventually	make the frame
       visible using Tk	geometry management commands, such as pack, place,  or

       Namespace procedures described below create and manage geomap_lnarr and
       geomap_place items in the canvas. These items  display  information  at
       geographic locations, as	described in the tkgeomap (n) man page.	 Items
       created with the	namespace procedures receive the same -refpoint, -pro-
       jection,	 -scale, and -rotation configuration options so	that the items
       are on the same map in the canvas, and they are	updated	 automatically
       when the	map's cartographic properties change.  This is more convenient
       than configuring	each canvas item separately.  There  are  also	proce-
       dures  that  create and manage menus and	bindings that make the map in-

       Tasks not done by the namespace procedures can be done with widget com-
       mands,  whose  names  are  stored  in namespace variables.  namespaceN-
       mae::frame is the path name of the frame	the holds the map  canvas  and
       menus,  which was given as pathName in the initial call to geomap::ige-
       omap.  namespaceName::canvas is the path	name of	 the  canvas.	names-
       paceName::mbar  is the path name	of the menu bar	(a frame).  namespace-
       Name::toplevel is the path name of the toplevel	widget	that  contains
       everything.   Array  member  ::geomap::map_ns(toplevel_path)  maps  the
       toplevel	widget name to the name	of the map namespace.

       The geomap::igeomap procedure accepts  additional  option  value	 pairs
       which  initialize the map and canvas configuration.  These option value
       pairs are passed	to the namespaceName::configure	 procedure,  described

       namespaceName::configure	option value ?option value ...?
	      This  procedure  sets namespace variables	that define the	carto-
	      graphic properties of the	map and	configures associated items in
	      the  canvas.   If	 a  given option is not	in the list below, the
	      procedure	applies	it to the canvas configuration.	 If option  is
	      not  a  valid  canvas configuration option either, the procedure
	      raises an	error.	The following options are recognized.

	      -refpoint	{lat lon}
		     Sets the map center to point {lat lon}.  Default value is
		     {0.0 0.0}.

	      -projname	name
		     Specifies	the type of map	projection.  name should iden-
		     tify a projection from  the  list	returned  by  the  ge-
		     omap::projections command.	 Unlike	the geomap::projection
		     command, this option does not require any projection  pa-
		     rameters.	 If the	projection requires a reference	point,
		     such as Orthographic and  Lambert	Conformal  Conic,  the
		     lat-lon at	the center of the map is used.	If the projec-
		     tion requires a reference longitude,  such	 as  Mercator,
		     the  longitude at the center of the map is	used.  Projec-
		     tions that	require	a hemisphere  specification,  such  as
		     Polar  Stereographic,  use	 whichever hemisphere contains
		     the map center.  Array ::geomap::ProjRef maps  projection
		     names  to projection reference, which is either longitude
		     or	point.	The default value for the -projname option  is

	      -scale scale
		     Specifies	the  cartographic scale	of the map.  The value
		     can be a floating point number or	a  cartographic	 scale
		     (e.g. 1:30000000).	 Default value is 1.0e-7.

	      -rotation	rotation
		     Specifies	the map's orientation.	The rotation should be
		     a value known to the -rotation option  described  in  the
		     tkgeomap (n) man page.  Default value is 0.0.

	      -update script
		     Specifies	a  script  to evaluate whenever	the -refpoint,
		     -projection, -scale,  or  -rotation  option  is  changed.
		     This  makes  it  possible	to  update  labels and legends
		     around the	map, add or remove items as the	scale changes,
		     and perform any other tasks that depend on	the map's car-
		     tographic characteristics.	 script	is evaluated at	global
		     scope.  Default value is {}.

	      -boundcirclecolor	color
		     Specifies	the  color  of	the  bounding circle for hemi-
		     spheric projections.  Default value is Black.

	      -lazy boolean
		     Deletes certain bindings associated  with	the  -projname
		     option.   This option should be set to true if the	widget
		     appears to	be wasting time	modifying the  map  projection
		     without  changing the map appearance.  This often happens
		     when the map is zoomed in most of the time.  Value	should
		     be	a Boolean.  Default value is 0 (false).

	      -colormenu boolean
		     Determines	 whether  the File menu	will have a Colors se-
		     lection.  This selection creates a	dialog	in  which  the
		     user  interactively  selects  colors for various map ele-
		     ments in the display.  It assumes that map	colors are set
		     with two arrays in	the map	namespace: namespaceName::col-
		     orval and namespaceName::colorscript.  These  two	arrays
		     use  the  same  set of indeces, which should identify map
		     elements that share a color, e.g.	water,	land,  places,
		     etc.   Array  values in the namespaceName::colorval array
		     are color values to use when displaying the map elements.
		     They should be intelligible to Tk_GetColor.  Array	values
		     in	the namespaceName::colorscript array  are  scripts  to
		     run  when	the corresponding color	changes.  Usually they
		     draw or configure the affected map	elements.  The	dialog
		     box  will	have a button for each map element represented
		     in	the colorval and colorscript arrays.   When  the  user
		     presses  one  of  these buttons, a	color selection	dialog
		     will appear.  If the user selects a color and  clicks  OK
		     in	 the  color selection dialog, the corresponding	script
		     from the colorscript array	will be	called.	  This	script
		     should  redraw affected items with	the chosen color.  The
		     Save button saves color values currently in the dialog to
		     a	file  identified  by  the user.	 It adds or modifies a
		     line in the selected file that starts with	"Colors:" fol-
		     lowed  by the contents of the namespaceName::colorval ar-
		     ray.  The Load button retrieves values from a  file  cre-
		     ated  with	 the  Save  button.  The Undo button retrieves
		     previous color configurations.   The  path	 name  of  the
		     color  dialog will	be stored in the color_dlg variable in
		     the map namespace.	 If the	-colormenu  configuration  op-
		     tion  is  set to true, the	application should use the the
		     colorval and colorscript arrays to	manage all  colors  in
		     the  map.	This will allow	the user to modify colors con-
		     veniently in one place.  The specific indeces and	values
		     in	 these	arrays,	 and the manner	in which they are set,
		     will depend on what data the map displays and how	it  is

	      -layermenu boolean
		     Determines	 whether  the File menu	will have a Layers se-
		     lection.  This selection creates a	dialog	in  which  the
		     user  can	adjust	the  stacking  order of	certain	canvas
		     items by dragging rectangles  representing	 canvas	 tags.
		     Items  without tags listed	in the dialog move to the bot-
		     tom of the	stacking order.	 Tags can be added to and  re-
		     moved  from  this	dialog	with  the  map	namespace  in-
		     sert_layer	and rm_layer procedures, described below.  The
		     path  name	 of  the  layer	 dialog	 will be stored	in the
		     layer_dlg variable	in the map namespace.

	      -projections projectionList
		     Lists the projection names	in the Projections menu.   Se-
		     lecting a projection from the menu	sets the -projname op-
		     tion to that projection.	Default	 value	is  {CylEqDist
		     Mercator CylEqArea	LambertConfConic LambertEqArea Stereo-
		     graphic PolarStereographic	Orthographic}.	 If  value  is
		     {}, the Projections menu is not displayed.

	      -scales scaleList
		     Lists  the	 scales	 in  the Scales	menu at	the top	of the
		     map.  Selecting a scale from the menu sets	the -scale op-
		     tion   to	that  scale.   Default	value  is  {1:10000000
		     1:20000000	1:30000000  1:45000000	1:60000000  1:90000000
		     1:120000000}.   If	 value	is  {},	the Scales menu	is not

	      -rotationmenu boolean
		     Specifies whether or not the  Top	menu  should  be  dis-
		     played.   Selecting  a  direction	from the menu sets the
		     -rotation option so that the chosen direction is  at  the
		     top  of  the  map.	  Value	 should	be a Boolean.  Default
		     value is 1.

       namespaceName::cget option
	      Retrieves	a value	from the map configuration.  option can	be one
	      of the options known to the configure procedure, or a canvas op-

       namespaceName::draw type	name ?option value ...?
	      This procedure creates or	modifies a map	item  in  the  canvas.
	      type identifies the item type, which must	be either geomap_lnarr
	      or geomap_place.	name identifies	the linearray  or  place  dis-
	      played  in  the  item.   It should be the	name of	a linearray or
	      place command returned by	 the  geomap::lnarr  or	 geomap::place
	      command.	See the	tclgeomap (n) man page for more	information on
	      linearrays and places.  If the  command  for  the	 linearray  or
	      place  is	 in  a non-global namespace, name MUST BE FULLY	QUALI-
	      FIED.  If	type and name refer to an already existing  item,  the
	      item  is	modified.  Otherwise, a	new item is created.  Item op-
	      tions that define	the geographic	map,  specifically  -refpoint,
	      -projection,  -rotation,	and  -scale, will be obtained from the
	      namespace.  Other	options	that affect the	item's appearance  can
	      be  given	 in  the option	value list.  See tkgeomap (n) man page
	      for discussion of	recognized options.  Any options in the	option
	      value  list  that	define the geographic map will be ignored.  In
	      addition to any tags specified in	the option list, the item will
	      have  the	 following  tags:  name,  and geomap.  These tags help
	      identify the item	in other procedures and	 configuration	tasks.
	      This  procedure returns the item identifier for the new or modi-
	      fied item.

       namespaceName::erase type name
	      Deletes an item created by the  draw  command.   type  and  name
	      should be	as given to the	draw command.

       namespaceName::insert_layer layer ?index?
	      Allows  the File->Layers dialog to manipulate the	stacking order
	      of map canvas items with tag layer.  Layers can be arranged in a
	      hierarchy.  A : in layer denotes a separate level	in the map hi-
	      erarchy.	Text to	the left of a :	identifies a parent.  Text  to
	      the  right identifies a child or hierarchy of children.  If sev-
	      eral hierarchical	levels of layers are present, the dialog  will
	      show  them in a tree diagram.  Each path through the tree	is one
	      layer.  All children of an item move with	the item.  An item can
	      only  be	moved  relative	to its siblings	(other children	of its
	      parent).	If present, index specifies where to put  these	 items
	      in the stacking order.  index should specify a list index	intel-
	      ligible to the linsert command.  A smaller value means the items
	      are  lower  in  the  stacking order.  Default is end (items with
	      layer tag	go on top).

       namespaceName::rm_layer layer
	      Removes tag layer	 from  the  list  of  layers  managed  by  the
	      File->Layers dialog.  Canvas items with tag layer	will still ex-
	      ist, but the File->Layers	dialog will no	longer	control	 their
	      stacking order.

	      Puts  items  with	 layer related tags into their stacking	order.
	      This procedure should be called whenever an item	with  a	 layer
	      tag  is  created or drawn.  The set_layers call does not have to
	      be immediate.  For example, it may be more efficient to create a
	      set of items in a	loop and then stack them with a	single call to
	      set_layers after	the  loop.   insert_layer  and	rm_layer  call
	      set_layers implicitly.

       namespaceName::xytolatlon ?-catch? x y ?x y ...?
	      Returns  the geographic coordinates corresponding	to one or more
	      pairs of canvas coordinates in the canvas.  If the -catch	option
	      is  present,  points for which the conversion is not defined are
	      skipped.	Otherwise, an attempt to make an undefined  conversion
	      results  in  an  error.	Return	value is a list	of form	{{lat1
	      lon1} {lat2 lon2}	...}, in which each {lat lon}  corresponds  to
	      an "x y" pair in the input list.

       namespaceName::latlontoxy ?-catch? {lat1	lon1} ?{lat2 lon2} ...?
	      Returns a	list of	canvas coordinates in the canvas corresponding
	      to one or	more pairs of geographic coordinates.  If  the	-catch
	      option  is  present,  points for which the conversion is not de-
	      fined are	skipped.  Otherwise, an	attempt	to make	 an  undefined
	      conversion  results in an	error.	Return value is	a list of form
	      {x1 y1 x2	y2 ...}	in which each "x y" pair corresponds to	a {lat
	      lon} in the input	list.

       pathName	addmenu	name
	      Adds  a  menu to pathName's menu bar.  This method will create a
	      menu button named	name and associated menu.  Return value	is the
	      path  name of the	associated menu, which user can	then modify as
	      described	in the menu (n)	man page.

       deletemenu deletemenu name
	      Deletes a	menu created with the addmenu method.  The menu	button
	      and associated menu will be destroyed.

	      Deletes  the  namespace,	canvas,	and all	associated data.  This
	      procedure	should be used instead of namespace delete or Tk's de-
	      stroy  command  to  delete  a map	created	by the geomap::igeomap

       geomap::set_motion_bindings modifier button
	      This procedure applies bindings that allow the user  to  move  a
	      map  with	 the mouse.  The type of mouse motion required to move
	      the map depends on the projection.  If  the  projection  uses  a
	      reference	 point,	 like  Lamber Conformal	Conic, double-clicking
	      selects a	new projection reference point and map center.	If the
	      projection  uses	a reference longitude, the map can be moved by
	      dragging.	 When the mouse	is released after dragging, the	 final
	      longitude	at the center of the map becomes the projection	refer-
	      ence longitude, unless the -lazy option is set.  modifier	speci-
	      fies  an	additional  key	to press while moving the map with the
	      mouse.  It should	be one of "", Alt, Control, or Shift.  A  non-
	      empty  modifier  can  help  prevent spurious map motion.	button
	      specifies	the mouse button to push while	moving	the  map.   It
	      should be	1, 2, or 3.

	      This  query  procedure returns a list of bindings	that move maps
	      created with the geomap command.

       The geomap::igeomap command is  part  of	 the  tkgeomap_procs  package,
       which  is  defined in file tkgeomap_procs.tcl of	the tkgeomap installa-

       tkgeomap	(n)

       Gordon Carrie,

Tk				       2		    geomap::igeomap(n)


Want to link to this manual page? Use this URL:

home | help