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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
       package require wdgeomap	?2?
       geomap::wdgeomap::create	mapName	pathName ?options?

DESCRIPTION
       The geomap::wdgeomap procedure creates a	frame  named  pathName,	 which
       contains	a canvas with a	geographic map and associated menus.  When the
       geomap::wdgeomap	procedure is called, pathName should  not  exist,  al-
       though its parent should.  The wdgeomap procedure packs the contents of
       frame pathName, but it does not submit it to any	geometry manager.  The
       application  that creates the wdgeomap should eventually	make the frame
       visible using Tk	geometry management commands, such as pack, place,  or
       grid.   The mapName argument identifies the widgets and associated data
       in the procedures described below.  These procedures 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.  The resulting	items receive the same -refpoint, -projection,
       -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 procedures
       that create and manage menus and	bindings that make  the	 map  interac-
       tive.

       The  geomap::wdgeomap::create procedure accepts additional option value
       pairs which initialize the map and canvas configuration.	 These	option
       value  pairs  are  passed  to the 'geomap::wdgeomap::configure mapName'
       procedure, described below.

DEFAULT	MENUS
       Unless configured otherwise, a wdgeomap widget will have	the  following
       menus in	its menu bar.  Menus can be managed with the addmenu, getmenu,
       and deletemenu procedures described below.

       File   Contains selections that affect the  map	or  application	 as  a
	      whole.  Default selections are:

	      Postscript
		     Exports  the  map	to  a  postscript  file.  A dialog box
		     prompts the user for a file name and color	mode.  The di-
		     alog  box	is  given a wdgeomap_ps_dlg bindtag for	subse-
		     quent access.

	      Quit   Exits the application.

       Projection
	      Selects the cartographic projection.

       Scale  Selects the cartographic scale.

       Top    Specifies	which compass direction	is up.

COMMANDS
       geomap::wdgeomap::map_canvas mapName
	      Returns the path of canvas in which the map is drawn.

       geomap::wdgeomap::mbar mapName
	      Returns the path of menu bar.

       geomap::wdgeomap::configure mapName option value	?option	value ...?
	      This procedure specifies the cartographic	properties of the  map
	      and  configures  associated items	in the canvas.	If a given op-
	      tion is not in the list below, the procedure applies it  to  the
	      canvas  configuration.  If option	is not a valid canvas configu-
	      ration option either, the	procedure raises an error.   The  fol-
	      lowing 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.	Use the	geomap::proj_info procedure in
		     tclgeomap_procs package to	identify the  type  of	refer-
		     ence,  either  longitude  or  point, for each projection.
		     The default value for the -projname option	is Mercator.

	      -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 map elements	 whose
		     colors  have been specified by the	setcolor procedure de-
		     scribed below.  The dialog	box will  have	a  button  for
		     each  such	 map  element.	 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 se-
		     lection dialog, the application will update the  elements
		     color  with  a call to setcolor.  The actual update tasks
		     should be performed by a script assigned to  the  element
		     with  a  call  to the setcolorscript procedure.  The Save
		     button saves color	values currently in the	 dialog	 to  a
		     file  identified  by the user.  The Load button retrieves
		     values from a file	created	with  the  Save	 button.   The
		     Undo  button retrieves previous color configurations.  If
		     the -colormenu configuration option is set	to  true,  the
		     application  should  use  the setcolor and	setcolorscript
		     procedures	to manage all colors in	the  map.   This  will
		     allow  the	 user  to  modify  colors  conveniently	in one
		     place.  The color values and scripts that use  them  will
		     depend  on	 what  data the	map displays and how it	is im-
		     ported.  When the the dialog box is created,  a  call  to
		     bindtags  adds  a	tag  named  wdgeomap_color_dlg	to its
		     toplevel.	This allows applications to  add  bindings  to
		     it, such as context sensitive help.

	      -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	add_layer  and
		     rm_layer procedures, described below.  When the the  dia-
		     log  box  is created, a call to bindtags adds a tag named
		     wdgeomap_layer_dlg	to its toplevel.  This allows applica-
		     tions  to	add  bindings to it, such as context sensitive
		     help.

	      -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
		     displayed.

	      -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.

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

       geomap::wdgeomap::draw mapName 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
	      map object.  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.
	      If  the map manages layers, the application should call set_lay-
	      ers after	drawing	a new line or place.  See below	for discussion
	      of layer management.  This procedure returns the item identifier
	      for the new or modified item.

       geomap::wdgeomap::erase mapName type name
	      Deletes an item created by the draw procedure.   type  and  name
	      should be	as given to the	draw procedure.

       geomap::wdgeomap::setcolor mapName element color
	      Associates a color with a	map element.  The element should iden-
	      tify map items that share	a color,  e.g.	water,	land,  places,
	      etc.   The  color	 should	be intelligible	to Tk_GetColor.	 After
	      the color	for the	element	is set,	a script specified with	a call
	      to  setcolorscript  is invoked.  This script should draw or con-
	      figure the affected map elements using color.

       geomap::wdgeomap::setcolorscript	mapName	element	script
	      Specifies	a script to run	when the color associated with element
	      is changed with a	call to	setcolor.

       geomap::wdgeomap::getcolor mapName element
	      Returns  the  color value	specified in the last call to setcolor
	      for element, or "" if their is no	color for the element.

       geomap::wdgeomap::add_layer mapName layer
	      Adds a layer to the map layer hierarchy, if the layer is not al-
	      ready  present.  If layer	is already in the hierarchy, due to an
	      earlier call to add_layer, this procedure	 does  nothing.	  Once
	      layer has	been added, the	File->Layers dialog can	manipulate the
	      stacking order of	map canvas items with tag layer.   Layers  can
	      be  arranged  in a hierarchy.  A list element in layer denotes a
	      separate level in	the map	hierarchy.  The	element	before a  list
	      element identifies a parent.  Subsequent elements	denote a child
	      or hierarchy of children.	 If  several  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).   An  application
	      should  call  set_layers	after calling add_layer	and before the
	      display is updated for the new stacking order to take effect  in
	      the display.

       geomap::wdgeomap::rm_layer mapName 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.  An application  should  call  set_layers	 after
	      calling  rm_layer	 and before the	display	is updated for the new
	      stacking order to	take effect in the display.

       geomap::wdgeomap::set_layers mapName
	      Puts items with layer related tags into  their  stacking	order.
	      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.
	      Applications should call set_layers after	creating canvas	 items
	      with  the	 canvas	create subcommand, drawing geomap_lnarr	or ge-
	      omap_place items with the	wdgeomap draw subcommand, or modifying
	      the  layer sequence with the wdgeomap add_layer or rm_layer sub-
	      commands.

       geomap::wdgeomap::xytolatlon mapName ?-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.

       geomap::wdgeomap::latlontoxy mapName ?-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.

       geomap::wdgeomap::addmenu mapName name
	      Adds  a  menu  to	mapName'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.

       geomap::wdgeomap::getmenu mapName name
	      Retrieves	the path name of the menu button  created  by  addmenu
	      for name.

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

       geomap::wdgeomap::delete	mapName
	      Deletes the map widget, and all associated data.

       geomap::wdgeomap::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.

       geomap::wdgeomap::get_motion_bindings
	      This  query  procedure  returns a	list of	bindings that move map
	      items created with the draw procedure.

FILES
       wdgeomap.tcl

SEE ALSO
       tclgeomap (n)
       tkgeomap	(n)

AUTHOR
       Gordon Carrie, user0@tkgeomap.org

Tk				       2		   geomap::wdgeomap(n)

NAME | SYNOPSIS | DESCRIPTION | DEFAULT MENUS | COMMANDS | FILES | SEE ALSO | AUTHOR

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

home | help