.\

cggooglemapwidget__define.pro

Graphics

This is a compound widget object that obtains a Google static map from Google Maps and displays it in the program's draw widget window. It can be used either as a stand-alone program or to create a map image in draw widget in a larger widget program.

This program implements a subset of the Google Static Map API, which can be found in more detail here: https://developers.google.com/maps/documentation/staticmaps/. The program works by building a URL for a map image. A connection to the Internet is required to then request a map image (in JPEG or PNG format) to be returned from Goggle Maps. The returned image is then read and loaded into a draw widget window of the right size for the returned map image. The default is to delete the image file that is created, but user can also set keywords to retain the image that is downloaded from Google Maps. Users are able to control button and motion events in the resulting draw widget with their own event handler module. A cgMap coordinate object is created to establish a map reference coordinate system on top of the returned map image, allowing other map information to be drawn on top of the returned map image.

Examples

Used to put two markers on a map of Fort Collins, Colorado, in a stand-alone window:

   PRO cgGoogleMapWidget_Test
       marker1 = {cgGOOGLEMAPMARKER, 'normal', 'dodger blue', 'A', Ptr_New(40.600), Ptr_New(-105.100)}
       marker2 = {cgGOOGLEMAPMARKER, 'normal', 'purple',      'B', Ptr_New(40.605), Ptr_New(-105.105)}
       googleObject = Obj_New('cgGoogleMapWidget', MARKERS=[marker1, marker2], MAPTYPE='Terrain')
   END

Class description for cgGoogleMapWidget

Properties

Properties in cgGoogleMapWidget

EVENT_PRO set init
MOTION_EVENTS init
BOX_AXES init
MARKERS get set init
XSIZE get init
YSIZE get init
CENTER_LONGITUDE get set init
KEEP_IMAGE init
EVENT_METHOD get set init
MAPIMAGE get
IMAGETYPE get set init
VISIBLEMARKERS set init
DRAW set
WID get
FILENAME get
TEMPDIR init
MAPCOORD get
MAPTYPE get set init
MAPPOSITION get
BUTTON_EVENTS init
CENTER_LATITUDE get set init
ZOOMLEVEL get set init

Fields

Fields in cgGoogleMapWidget

CENTERLON 0.00000000D
EVENT_PRO ''
BOX_AXES 0B
MARKERS ptr_new()
XSIZE 0L
YSIZE 0L
KEEP_IMAGE 0B
EVENT_METHOD ''
MAPIMAGE ptr_new()
IMAGETYPE ''
VISIBLEMARKERS 0B
MAP_POSITION [0.000000, 0.000000, 0.000000, 0.000000]
WID 0L
DRAWID 0L
FILENAME ''
TEMPDIR ''
MAP_XSIZE 0L
MAP_YSIZE 0L
MAPCOORD obj_new()
RANDOM obj_new()
MAPTYPE ''
TLB 0L
CENTERLAT 0.00000000D
ZOOMLEVEL 0S

Author information

Author

FANNING SOFTWARE CONSULTING:

  David W. Fanning
  1645 Sheely Drive
  Fort Collins, CO 80526 USA
  Phone: 970-221-0438
  E-mail: david@idlcoyote.com
  Coyote's Guide to IDL Programming: http://www.idlcoyote.com

Copyright

History

Change History:

  Written, 25 June 2012. DWF.
  Set the RETAIN keyword on the draw widget for UNIX machines. 28 June 2012. DWF.
  Beefed up and changed error handling when failing to obtain a map from Google Maps. 28 June 2012. DWF.
  Added NoForwardFix keyword to call to cgMap to allow better drawing of markers. 29 June 2012. DWF.
  Added the ability to turn markers on or off with VisibleMarkers keyword and property. 29 June 2012. DWF.
  Added a WID keyword to the GetProperty method to all the user to obtain the Goggle Map
      window index number. 29 Aug 2012. DWF.
  Goggle appreciates lat/lon values to six decimal points, so now passing all of it. 19 Feb 2015. DWF.

Routines

result = cgGoogleMapWidget::INIT( [parent] [, /BOX_AXES] [, /BUTTON_EVENTS] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, EVENT_METHOD=string] [, EVENT_PRO=string] [, IMAGETYPE=string] [, /KEEP_IMAGE] [, MAPTYPE=string] [, MARKERS=structure] [, /MOTION_EVENTS] [, TEMPDIR=string] [, /VISIBLEMARKERS] [, XSIZE=int] [, YSIZE=int] [, ZOOMLEVEL=integer]): This is the initialization method of the cgGoogleMapWidget object.
cgGoogleMapWidget::CLEANUP: The clean-up method for the object.
cgGoogleMapWidget::CreateMapCoordObject: This method creates a cgMap map coordinate object for georeferencing the map image returned by Google maps.
cgGoogleMapWidget::Draw [, /SUCCESS]: The purpose of this method is obtain the map from Google as an image and display it in the draw widget window.
cgGoogleMapWidget::DrawWidgetEvents, event: The purpose of this method is handle draw widget events.
result = cgGoogleMapWidget::GetMapCoord( [/UPDATE]): This method returns the map coordinate object that sets up the georeferencing coordinate system (in projected meter space) for drawing on top of the map image.
cgGoogleMapWidget::GetProperty [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, EVENT_METHOD=string] [, FILENAME=string] [, MAPIMAGE=bytarr] [, IMAGETYPE=string] [, MAPPOSITION=fltarr] [, MAPCOORD=object] [, /MAPTYPE], MARKERS=MARKERS, WID=WID [, XSIZE=int] [, YSIZE=int] [, ZOOMLEVEL=integer]: The properties of the object are retrieved with this method.
cgGoogleMapWidget::Map_Type, event: The purpose of this method is to display a map with a particular map type.
cgGoogleMapWidget::Notify_Realize: The purpose of this method is to draw the initial map plot in the draw widget.
cgGoogleMapWidget::SetProperty [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, /DRAW] [, EVENT_METHOD=string] [, EVENT_PRO=string] [, IMAGETYPE=string] [, MAPTYPE=string] [, MARKERS=structure] [, /VISIBLEMARKERS] [, ZOOMLEVEL=integer]: The purpose of this method is to set some of the object's properties.
cgGoogleMapWidget::SetWindow: The purpose of this method is to make the draw widget window the current window.
cgGoogleMapWidget::Zoom_In [, event]: The purpose of this method is to zoom into the map by increasing the zoom factor.
cgGoogleMapWidget::Zoom_Out [, event]: The purpose of this method is to zoom out of the map by decreasing the zoom factor.
cgGoogleMapWidget_Notify_Realize, id: This is the realize notify routine for the widget.
cgGoogleMapWidget_Cleanup, tlb: This is the cleanup routine for the widget.
cgGoogleMapWidget_Events, event: This is the main event handler for the program.
cgGoogleMapWidget__Define [, class]: The object class definition for the cgGoogleMapWidget class.

Routine details

top cgGoogleMapWidget::INIT

result = cgGoogleMapWidget::INIT( [parent] [, /BOX_AXES] [, /BUTTON_EVENTS] [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, EVENT_METHOD=string] [, EVENT_PRO=string] [, IMAGETYPE=string] [, /KEEP_IMAGE] [, MAPTYPE=string] [, MARKERS=structure] [, /MOTION_EVENTS] [, TEMPDIR=string] [, /VISIBLEMARKERS] [, XSIZE=int] [, YSIZE=int] [, ZOOMLEVEL=integer])

This is the initialization method of the cgGoogleMapWidget object.

Parameters

parent in optional type=long

The identifier of the parent widget of the draw widget that is going to be created by the program. If not provided, the program will create its own top-level base widget as the parent.

Keywords

BOX_AXES in optional type=boolean default=0

Set this keyword to draw box axes around the Google Map.

BUTTON_EVENTS in optional type=boolean default=0

Set this keyword to turn button events on for the draw widget in the program.

CENTER_LATITUDE in optional type=float default=40.60

The center latitude of the requested Google map. If not provided, the latitude of Fort Collins, Colorado, home of Coyote. Latitudes are only recognized to four decimals values of precision.

CENTER_LONGITUDE in optional type=float default=-105.10

The center longitude of the requested Google map. If not provided, the longitude of Fort Collins, Colorado, home of Coyote. Longitude are only recognized to four decimals values of precision.

EVENT_METHOD in optional type=string

The name of the event handler method (a procedure) for the draw widget. If you use this keyword, you will also need to write this event handler module. It gets sent one positional parameter, the event structure created by the draw widget.

EVENT_PRO in optional type=string

The name of an external event handler procedure for the draw widget. The event handler procedure gets sent one positional parameter, the event structure created by the draw widget.

IMAGETYPE in optional type=string default=png32

The type of image format the Google map should be returned in. The default is a 32-bit full color PNG file. The image types are given in the Google Static Map API documentation and are as follows: png or png8, png32, gif, jpg, and jpg-baseline.

KEEP_IMAGE in optional type=boolean default=0

Set this keyword if you wish to save the Google map as an image when the object is destroyed.

MAPTYPE in optional type=string default=terrain

Set this keyword to the type of map you wish to retrieve from Google Maps. The choices are listed in the Google Static Map API documentation and are: "roadmap", "terrain", "satellite", and "hybrid".

MARKERS in optional type=structure

A scalar or array of cgGoogleMapMarker structures. If present, the markers will be requested with the map from Google. The cgGoogleMapMarker structure is defined like this:

  struct = { cgGOOGLEMAPMARKER, $
     size: "", $         ; The marker size ("tiny", "small", "mid" or "normal")
     color: "", $        ; A color name as provided by cgColor.
     label: "", $        ; A single uppercase character label from the set {A-Z,0-9}.
     lats: Ptr_New(), $  ; A pointer to one or more latitude values.
     lons: Ptr_New() }   ; A pointer to one or more longitude values.

Note that the user will be responsible for freeing the pointers in the MARKERS structure. This program will not do that.

MOTION_EVENTS in optional type=boolean default=0

Set this keyword to turn motion events on for the draw widget in the program.

TEMPDIR in optional type=string

The directory where the image containing the Google map is written. By default, it is obtained from the environment like this: tempdir = GetEnv('IDL_TMPDIR').

VISIBLEMARKERS in optional type=boolean default=1

Set this keyword to 0 to temporarily turn off the display of the markers. Normally, markers are drawn (if present), unless this flag is set to 0.

XSIZE in optional type=int default=600

The X size of the program's draw widget. A maximum of 690 if box axes are requested and a maximum of 640 if no box axes are requested. Box axes require a 25 pixel border and the maximum size of a Google Map is 640 pixels.

YSIZE in optional type=int default=600

The Y size of the program's draw widget. A maximum of 690 if box axes are requested and a maximum of 640 if no box axes are requested. Box axes require a 25 pixel border and the maximum size of a Google Map is 640 pixels.

ZOOMLEVEL in optional type=integer default=12

The zoom level of the requested Google map. Should be an integer between 0 and 21.

top cgGoogleMapWidget::CLEANUP

cgGoogleMapWidget::CLEANUP

The clean-up method for the object. When the object is destroyed, this method will free the object's pointers and objects. If you wanted to save the map image file, this is where you do it.

top cgGoogleMapWidget::CreateMapCoordObject

cgGoogleMapWidget::CreateMapCoordObject

This method creates a cgMap map coordinate object for georeferencing the map image returned by Google maps. Use this object to establish a geocoordinate reference rectangle for drawing on top of the map image.

top cgGoogleMapWidget::Draw

cgGoogleMapWidget::Draw [, /SUCCESS]

The purpose of this method is obtain the map from Google as an image and display it in the draw widget window.

Keywords

SUCCESS out optional type=boolean: On return, if set to 1 a map image was successfully obtained from Google. Otherwise, 0.

top cgGoogleMapWidget::DrawWidgetEvents

cgGoogleMapWidget::DrawWidgetEvents, event

The purpose of this method is handle draw widget events.

Parameters

event

top cgGoogleMapWidget::GetMapCoord

result = cgGoogleMapWidget::GetMapCoord( [/UPDATE])

This method returns the map coordinate object that sets up the georeferencing coordinate system (in projected meter space) for drawing on top of the map image.

Keywords

UPDATE in optional type=boolean default=0: Set this keyword to make sure a new map coordinate object is created.

top cgGoogleMapWidget::GetProperty

cgGoogleMapWidget::GetProperty [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, EVENT_METHOD=string] [, FILENAME=string] [, MAPIMAGE=bytarr] [, IMAGETYPE=string] [, MAPPOSITION=fltarr] [, MAPCOORD=object] [, /MAPTYPE], MARKERS=MARKERS, WID=WID [, XSIZE=int] [, YSIZE=int] [, ZOOMLEVEL=integer]

The properties of the object are retrieved with this method.

Keywords

CENTER_LATITUDE out optional type=float: The center latitude of the requested Google map.
CENTER_LONGITUDE out optional type=float: The center longitude of the requested Google map.
EVENT_METHOD out optional type=string: The name of the event handler method for the draw widget.
FILENAME out optional type=string: The name of the file where the map image is stored.
MAPIMAGE out optional type=bytarr: The image variable containing the Goggle map. The size and dimensions of the image depend upon what was retrieved from Google.
IMAGETYPE out optional type=string: The type of image format the Google map should be returned in.
MAPPOSITION out optional type=fltarr: The position of the map in the display window.
MAPCOORD out optional type=object: The map coordinate object. Another way to obtain the map coordinate object is to use the GetMapCoord method.
MAPTYPE out optional type=boolean: The type of Google map requested by the program.
MARKERS
WID
XSIZE out optional type=int: The X size of the program's draw widget.
YSIZE out optional type=int: The Y size of the program's draw widget.
ZOOMLEVEL out optional type=integer: The zoom level of the requested Google map.

top cgGoogleMapWidget::Map_Type

cgGoogleMapWidget::Map_Type, event

The purpose of this method is to display a map with a particular map type.

Parameters

event in required type=varies: The event structure passed to this event handler method from which the map type can be obtained. Or, the map type itself, passed as a string.

top cgGoogleMapWidget::Notify_Realize

cgGoogleMapWidget::Notify_Realize

The purpose of this method is to draw the initial map plot in the draw widget.

top cgGoogleMapWidget::SetProperty

cgGoogleMapWidget::SetProperty [, CENTER_LATITUDE=float] [, CENTER_LONGITUDE=float] [, /DRAW] [, EVENT_METHOD=string] [, EVENT_PRO=string] [, IMAGETYPE=string] [, MAPTYPE=string] [, MARKERS=structure] [, /VISIBLEMARKERS] [, ZOOMLEVEL=integer]

The purpose of this method is to set some of the object's properties. If you wish to retrive a new map after updating the object properties, be sure to set the DRAW keyword.

Keywords

CENTER_LATITUDE in optional type=float default=40.60

The center latitude of the requested Google map. If not provided, the latitude of Fort Collins, Colorado, home of Coyote. Latitudes are only recognized to four decimals values of precision.

CENTER_LONGITUDE in optional type=float default=-105.10

The center longitude of the requested Google map. If not provided, the longitude of Fort Collins, Colorado, home of Coyote. Longitude are only recognized to four decimals values of precision.

DRAW in optional type=boolean default=0

Set this keyword if you want to immediate retrieve and display a new map with the updated properties.

EVENT_METHOD in optional type=string

The name of the event handler method for the draw widget. If you use this keyword, you will also need to write this event handler module. It gets sent one positional parameter, the event structure created by the draw widget.

EVENT_PRO in optional type=string

The name of an external event handler procedure for the draw widget. The event handler procedure gets sent one positional parameter, the event structure created by the draw widget.

IMAGETYPE in optional type=string default=png32

MAPTYPE in optional type=string default=terrain

Set this keyword to the type of map you wish to retrieve from Google Maps. The choices are listed in the Google Static Map API documentation and are: "roadmap", "terrain", "satellite", and "hybrid".

MARKERS in optional type=structure

A scalar or array of cgGoogleMapMarker structures. If present, the markers will be requested with the map from Google. The GoogleMapMarker structure is defined like this:

  struct = { cgGOOGLEMAPMARKER, $
     size: "", $         ; The marker size ("tiny", "small", "mid" or "normal")
     color: "", $        ; A color name as provided by cgColor.
     label: "", $        ; A single uppercase character label from the set {A-Z,0-9}.
     lats: Ptr_New(), $  ; A pointer to one or more latitude values.
     lons: Ptr_New() }   ; A pointer to one or more longitude values.

Note that the user will be responsible for freeing the pointers in the MARKERS structure. This program will not do that.

VISIBLEMARKERS in optional type=boolean default=1

Set this keyword to 0 to temporarily turn off the display of the markers. Normally, markers are drawn (if present), unless this flag is set to 0.

ZOOMLEVEL in optional type=integer default=12

The zoom level of the requested Google map. Should be an integer between 0 and 21.

top cgGoogleMapWidget::SetWindow

cgGoogleMapWidget::SetWindow

The purpose of this method is to make the draw widget window the current window.

top cgGoogleMapWidget::Zoom_In

cgGoogleMapWidget::Zoom_In [, event]

The purpose of this method is to zoom into the map by increasing the zoom factor.

Parameters

event in optional type=structure: The event structure passed to this event handler method. Not used currently.

top cgGoogleMapWidget::Zoom_Out

cgGoogleMapWidget::Zoom_Out [, event]

The purpose of this method is to zoom out of the map by decreasing the zoom factor.

Parameters

event in optional type=structure: The event structure passed to this event handler method. Not used currently.

top cgGoogleMapWidget_Notify_Realize

cgGoogleMapWidget_Notify_Realize, id

This is the realize notify routine for the widget. Its function call the Realize_Notify method to draw the initial plot in the display window.

Parameters

id in required type=int: The widget identifier of the widget that has been realized.

top cgGoogleMapWidget_Cleanup

cgGoogleMapWidget_Cleanup, tlb

This is the cleanup routine for the widget. Its function is to destroy the underlying program object.

Parameters

tlb in required type=int: The widget identifier of the parent base widget that just died.

top cgGoogleMapWidget_Events

cgGoogleMapWidget_Events, event

This is the main event handler for the program. All events come here to be distributed to the appropriate event handler method according to instructions packed into the UVALUE of any widget generating an event.

Parameters

event in required type=structure: The event structure passed by the window manager.

top cgGoogleMapWidget__Define

cgGoogleMapWidget__Define [, class]

The object class definition for the cgGoogleMapWidget class.

Parameters

class out optional type=structure: The object class definition as a structure. Occasionally, comes in handy.

File attributes

Modification date:	Fri Mar 27 11:07:41 2015
Lines:	931
Docformat:	rst rst

Coyote Graphics Routines

Date: Fri Mar 27 12:14:20 2015

.\

cggooglemapwidget__define.pro

Examples

Class description for cgGoogleMapWidget

Properties

Properties in cgGoogleMapWidget

Fields

Fields in cgGoogleMapWidget

Author information

Routines

Routine details

top cgGoogleMapWidget::INIT

Parameters

Keywords

top cgGoogleMapWidget::CLEANUP

top cgGoogleMapWidget::CreateMapCoordObject

top cgGoogleMapWidget::Draw

Keywords

top cgGoogleMapWidget::DrawWidgetEvents

Parameters

top cgGoogleMapWidget::GetMapCoord

Keywords

top cgGoogleMapWidget::GetProperty

Keywords

top cgGoogleMapWidget::Map_Type

Parameters

top cgGoogleMapWidget::Notify_Realize

top cgGoogleMapWidget::SetProperty

Keywords

top cgGoogleMapWidget::SetWindow

top cgGoogleMapWidget::Zoom_In

Parameters

top cgGoogleMapWidget::Zoom_Out

Parameters

top cgGoogleMapWidget_Notify_Realize

Parameters

top cgGoogleMapWidget_Cleanup

Parameters

top cgGoogleMapWidget_Events

Parameters

top cgGoogleMapWidget__Define

Parameters

File attributes