ScreenOverlay Functions

The following functions provide various routines for adding, removing, and updating ScreenOverlays in Google Earth. More...

Functions

int GE_GetScreenOverlayCount ()
 Returns the current number of ScreenOverlays added to the Google Earth map by the GE SDK.
BOOL GE_RefreshScreenOverlay (STRING overlay_name)
 Forces an update to the ScreenOverlay with the given ScreenOverlay name.
BOOL GE_AddScreenOverlay (STRING overlay_name, STRING image_url)
 Adds a new ScreenOverlay to Google Earth.
BOOL GE_AddScreenOverlayEx (STRING overlay_name, STRING image_url, double overlayXY_x, double overlayXY_y, int overlayXY_xunits, int overlayXY_yunits, double screenXY_x, double screenXY_y, int screenXY_xunits, int screenXY_yunits, double rotationXY_x, double rotationXY_y, int rotationXY_xunits, int rotationXY_yunits, double size_x, double size_y, int size_xunits, int size_yunits)
 Adds a new ScreenOverlay to Google Earth with additional settings.
BOOL GE_DeleteScreenOverlay (STRING overlay_name)
 Removes the ScreenOverlay with the given name from the Google Earth map.
BOOL GE_ScreenOverlayExists (STRING overlay_name, int *index)
 Determines if a ScreenOverlay with the given name has been added to Google Earth by the GE SDK.
BOOL GE_ScreenOverlayVisible (STRING overlay_name)
 Determines if the ScreenOverlay with the given name is currently visible in Google Earth.
BOOL GE_ShowScreenOverlay (STRING overlay_name)
 Sets the ScreenOverlay with the given name to visible.
BOOL GE_HideScreenOverlay (STRING overlay_name)
 Sets the ScreenOverlay with the given name to invisible.
STRING GE_GetScreenOverlayName (int index)
 Retrieves the name of the ScreenOverlay at the given index.
BOOL GE_SetScreenOverlayName (STRING overlay_name, STRING new_name)
 Changes the name of a ScreenOverlay.
STRING GE_GetScreenOverlaySnippet (STRING overlay_name)
 Retrieves a ScreenOverlay's snippet.
BOOL GE_SetScreenOverlaySnippet (STRING overlay_name, STRING snippet)
 Changes the snippet of the given ScreenOverlay.
int GE_GetScreenOverlaySnippetMaxLines (STRING overlay_name)
 Retrieves the given ScreenOverlay's snippet maxLines attribute value.
BOOL GE_SetScreenOverlaySnippetMaxLines (STRING overlay_name, int max_lines)
 Changes the snippet maxLines attribute value for the given ScreenOverlay.
STRING GE_GetScreenOverlayKML (STRING overlay_name)
 Retrieves the KML content that makes up the given ScreenOverlay.
STRING GE_GetScreenOverlayDescription (STRING overlay_name)
 Retrieves the description of the given ScreenOverlay.
BOOL GE_SetScreenOverlayDescription (STRING overlay_name, STRING description)
 Sets the description of the given ScreenOverlay.
STRING GE_GetScreenOverlayColor (STRING overlay_name)
 Retrieves the given ScreenOverlay's current color.
BOOL GE_SetScreenOverlayColor (STRING overlay_name, STRING color)
 Sets the given ScreenOverlay's color.
STRING GE_GetScreenOverlayImageUrl (STRING overlay_name)
 Retrieves the full path to the image file of the given ScreenOverlay.
BOOL GE_SetScreenOverlayImageUrl (STRING overlay_name, STRING url)
 Sets the overlay image for the given ScreenOverlay.
int GE_GetScreenOverlayDrawOrder (STRING overlay_name)
 Retrieves the draw order of the given ScreenOverlay.
BOOL GE_SetScreenOverlayDrawOrder (STRING overlay_name, int order)
 Sets the draw order for the given ScreenOverlay.
double GE_GetScreenOverlayRotation (STRING overlay_name)
 Retrieves the current rotation angle of the given ScreenOverlay.
BOOL GE_SetScreenOverlayRotation (STRING overlay_name, double rotation_angle)
 Sets the rotation angle of the given ScreenOverlay.
double * GE_GetScreenOverlayOverlayXYPoint (STRING overlay_name)
 Retrieves the overlay-relative (x,y) point of the given ScreenOverlay.
int * GE_GetScreenOverlayOverlayXYUnits (STRING overlay_name)
 Retrieves the units of the overlay-relative (x,y) point of the given ScreenOverlay.
BOOL GE_SetScreenOverlayOverlayXY (STRING overlay_name, double x, double y, int xunits, int yunits)
 Sets the overlay-relative (x,y) point of the given ScreenOverlay.
double * GE_GetScreenOverlayScreenXYPoint (STRING overlay_name)
 Retrieves the screen-relative (x,y) point of the given ScreenOverlay.
int * GE_GetScreenOverlayScreenXYUnits (STRING overlay_name)
 Retrieves the units of the screen-relative (x,y) point of the given ScreenOverlay.
BOOL GE_SetScreenOverlayScreenXY (STRING overlay_name, double x, double y, int xunits, int yunits)
 Sets the screen-relative (x,y) point of the given ScreenOverlay.
double * GE_GetScreenOverlayRotationXYPoint (STRING overlay_name)
 Retrieves the screen-relative (x,y) rotation point of the given ScreenOverlay.
int * GE_GetScreenOverlayRotationXYUnits (STRING overlay_name)
 Retrieves the units of the screen-relative (x,y) rotation point of the given ScreenOverlay.
BOOL GE_SetScreenOverlayRotationXY (STRING overlay_name, double x, double y, int xunits, int yunits)
 Sets the screen-relative (x,y) rotation point of the given ScreenOverlay.
double * GE_GetScreenOverlaySize (STRING overlay_name)
 Retrieves the horizontal and vertical (x,y) size of the given ScreenOverlay.
int * GE_GetScreenOverlaySizeUnits (STRING overlay_name)
 Retrieves the units of the horizontal and vertial (x,y) size values of the given ScreenOverlay.
BOOL GE_SetScreenOverlaySize (STRING overlay_name, double x, double y, int xunits, int yunits)
 Sets the the horizontal and vertical (x,y) size of the given ScreenOverlay.

Detailed Description

The following functions provide various routines for adding, removing, and updating ScreenOverlays in Google Earth.

ScreenOverlays are images that are drawn fixed to the current Google Earth viewport. ScreenOverlays are useful for displaying legends, symbology, or other various forms of up-front indicators.

Function Documentation

int GE_GetScreenOverlayCount (  ) 

Returns the current number of ScreenOverlays added to the Google Earth map by the GE SDK.

Returns:
The current number of ScreenOverlays added to Google Earth; -1 otherwise
BOOL GE_RefreshScreenOverlay ( STRING  overlay_name  ) 

Forces an update to the ScreenOverlay with the given ScreenOverlay name.

Parameters:
overlay_name The name of the ScreenOverlay to update
Returns:
TRUE if the function executed properly; FALSE otherwise
BOOL GE_AddScreenOverlay ( STRING  overlay_name,
STRING  image_url 
)

Adds a new ScreenOverlay to Google Earth.

The overlay position is defaulted to the center of the screen.

Parameters:
overlay_name The unique name for the ScreenOverlay
image_url The full path to the image file representing this ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
BOOL GE_AddScreenOverlayEx ( STRING  overlay_name,
STRING  image_url,
double  overlayXY_x,
double  overlayXY_y,
int  overlayXY_xunits,
int  overlayXY_yunits,
double  screenXY_x,
double  screenXY_y,
int  screenXY_xunits,
int  screenXY_yunits,
double  rotationXY_x,
double  rotationXY_y,
int  rotationXY_xunits,
int  rotationXY_yunits,
double  size_x,
double  size_y,
int  size_xunits,
int  size_yunits 
)

Adds a new ScreenOverlay to Google Earth with additional settings.

Parameters:
overlay_name The unique name for the ScreenOverlay
image_url The full path to the image file representing this ScreenOverlay
overlayXY_x The x-component relative to the given ScreenOverlay that is mapped to the screen's x-axis
overlayXY_y The y-component relative to the given ScreenOverlay that is mapped to the screen's y-axis
overlayXY_xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the overlayXY_x component is specified
overlayXY_yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the overlayXY_y component is specified
screenXY_x The x-component relative to the screen that is mapped to the given ScreenOverlay's x-axis
screenXY_y The y-component relative to the screen that is mapped to the given ScreenOverlay's y-axis
screenXY_xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the screenXY_x component is specified
screenXY_yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the screenXY_y component is specified
rotationXY_x The x-component relative to the screen that the given ScreenOverlay is rotated about
rotationXY_y The y-component relative to the screen that the given ScreenOverlay is rotated about
rotationXY_xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the rotationXY_x component is specified
rotationXY_yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the rotationXY_y component is specified
size_x The horizontal size of the given ScreenOverlay where [-1 uses image's native dimensions; 0 maintains the aspect ratio; n sets the value in the specified units]
size_y The vertical size of the given ScreenOverlay where [-1 uses image's native dimensions; 0 maintains the aspect ratio; n sets the value in the specified units]
size_xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the size_x component is specified
size_yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the size_y component is specified
Returns:
TRUE if the function executed properly; FALSE otherwise
BOOL GE_DeleteScreenOverlay ( STRING  overlay_name  ) 

Removes the ScreenOverlay with the given name from the Google Earth map.

Parameters:
overlay_name The name of the ScreenOverlay to remove
Returns:
TRUE if the function executed properly; FALSE otherwise
BOOL GE_ScreenOverlayExists ( STRING  overlay_name,
int *  index 
)

Determines if a ScreenOverlay with the given name has been added to Google Earth by the GE SDK.

If the function returns TRUE, then the index parameter will contain a value that represents the index into the GE SDK internal ScreenOverlay collection.

Parameters:
overlay_name The name of the ScreenOverlay
index The index into the internal ScreenOverlay collection where overlay_name exists if found
Returns:
TRUE if a ScreenOverlay with name overlay_name exists in the internal ScreenOverlay collection; FALSE otherwise
BOOL GE_ScreenOverlayVisible ( STRING  overlay_name  ) 

Determines if the ScreenOverlay with the given name is currently visible in Google Earth.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
TRUE if the given ScreenOverlay is visible; FALSE if not visible
BOOL GE_ShowScreenOverlay ( STRING  overlay_name  ) 

Sets the ScreenOverlay with the given name to visible.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
BOOL GE_HideScreenOverlay ( STRING  overlay_name  ) 

Sets the ScreenOverlay with the given name to invisible.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
STRING GE_GetScreenOverlayName ( int  index  ) 

Retrieves the name of the ScreenOverlay at the given index.

Parameters:
index The index into the internal ScreenOverlay collection
Returns:
The name of the ScreenOverlay at the given index; otherwise the empty string ("") is returned
BOOL GE_SetScreenOverlayName ( STRING  overlay_name,
STRING  new_name 
)

Changes the name of a ScreenOverlay.

Parameters:
overlay_name The name of an existing ScreenOverlay to be renamed
new_name The new name to be given to the ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
STRING GE_GetScreenOverlaySnippet ( STRING  overlay_name  ) 

Retrieves a ScreenOverlay's snippet.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The snippet of the given ScreenOverlay; otherwise the empty string ("") is returned
BOOL GE_SetScreenOverlaySnippet ( STRING  overlay_name,
STRING  snippet 
)

Changes the snippet of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
snippet The snippet to be applied to the given ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
int GE_GetScreenOverlaySnippetMaxLines ( STRING  overlay_name  ) 

Retrieves the given ScreenOverlay's snippet maxLines attribute value.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The snippet maxLines attribute value; -1 otherwise
BOOL GE_SetScreenOverlaySnippetMaxLines ( STRING  overlay_name,
int  max_lines 
)

Changes the snippet maxLines attribute value for the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
max_lines The value to be applied to the maxLines attribute
Returns:
TRUE if the function executed properly; FALSE otherwise
STRING GE_GetScreenOverlayKML ( STRING  overlay_name  ) 

Retrieves the KML content that makes up the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A string containing the KML data of the given ScreenOverlay; otherwise the empty string ("") is returned
STRING GE_GetScreenOverlayDescription ( STRING  overlay_name  ) 

Retrieves the description of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The current description for the given ScreenOverlay; otherwise the empty string ("") is returned
BOOL GE_SetScreenOverlayDescription ( STRING  overlay_name,
STRING  description 
)

Sets the description of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
description The description to apply to the ScreenOverlay
Returns:
TRUE if the function executed properly; FALSE otherwise
STRING GE_GetScreenOverlayColor ( STRING  overlay_name  ) 

Retrieves the given ScreenOverlay's current color.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A string representation of the given ScreenOverlay's color formatted as aabbggrr, where aa is opacity, bb is blue, gg is green, and rr is red; otherwise the empty string ("") is returned
BOOL GE_SetScreenOverlayColor ( STRING  overlay_name,
STRING  color 
)

Sets the given ScreenOverlay's color.

Parameters:
overlay_name The name of the ScreenOverlay
color A string representing the color formatted as aabbggrr, where aa is opacity, bb is blue, gg is green, and rr is red.
Returns:
TRUE if the function executed properly; FALSE otherwise
STRING GE_GetScreenOverlayImageUrl ( STRING  overlay_name  ) 

Retrieves the full path to the image file of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The full path to the overlay image file; otherwise the empty string ("") is returned
BOOL GE_SetScreenOverlayImageUrl ( STRING  overlay_name,
STRING  url 
)

Sets the overlay image for the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
url The full path to the overlay image file
Returns:
TRUE if the function executed properly; FALSE otherwise
int GE_GetScreenOverlayDrawOrder ( STRING  overlay_name  ) 

Retrieves the draw order of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The draw order of the overlay; -1 otherwise
BOOL GE_SetScreenOverlayDrawOrder ( STRING  overlay_name,
int  order 
)

Sets the draw order for the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
order The draw order to apply to the given overlay
Returns:
TRUE if the function executed properly; FALSE otherwise
double GE_GetScreenOverlayRotation ( STRING  overlay_name  ) 

Retrieves the current rotation angle of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
The rotation angle in degrees of the ScreenOverlay; BAD_DOUBLE otherwise
BOOL GE_SetScreenOverlayRotation ( STRING  overlay_name,
double  rotation_angle 
)

Sets the rotation angle of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
rotation_angle The rotation angle of the ScreenOverlay in degrees
Returns:
TRUE if the function executed properly; FALSE otherwise
double* GE_GetScreenOverlayOverlayXYPoint ( STRING  overlay_name  ) 

Retrieves the overlay-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's overlay-relative (x,y) point values
int* GE_GetScreenOverlayOverlayXYUnits ( STRING  overlay_name  ) 

Retrieves the units of the overlay-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's overlay-relative (x,y) point units (fraction (0), pixels (1), or insetPixels (2))
BOOL GE_SetScreenOverlayOverlayXY ( STRING  overlay_name,
double  x,
double  y,
int  xunits,
int  yunits 
)

Sets the overlay-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
x The x-component relative to the given ScreenOverlay that is mapped to the screen's x-axis
y The y-component relative to the given ScreenOverlay that is mapped to the screen's y-axis
xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the overlay x-component is specified
yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the overlay y-component is specified
Returns:
TRUE if the function executed properly; FALSE otherwise
double* GE_GetScreenOverlayScreenXYPoint ( STRING  overlay_name  ) 

Retrieves the screen-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's screen-relative (x,y) point values
int* GE_GetScreenOverlayScreenXYUnits ( STRING  overlay_name  ) 

Retrieves the units of the screen-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's screen-relative (x,y) point units (fraction (0), pixels (1), or insetPixels (2))
BOOL GE_SetScreenOverlayScreenXY ( STRING  overlay_name,
double  x,
double  y,
int  xunits,
int  yunits 
)

Sets the screen-relative (x,y) point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
x The x-component relative to the screen that is mapped to the given ScreenOverlay's x-axis
y The y-component relative to the screen that is mapped to the given ScreenOverlay's y-axis
xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the screen x-component is specified
yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the screen y-component is specified
Returns:
TRUE if the function executed properly; FALSE otherwise
double* GE_GetScreenOverlayRotationXYPoint ( STRING  overlay_name  ) 

Retrieves the screen-relative (x,y) rotation point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's screen-relative (x,y) rotation point values
int* GE_GetScreenOverlayRotationXYUnits ( STRING  overlay_name  ) 

Retrieves the units of the screen-relative (x,y) rotation point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's screen-relative (x,y) rotation point units (fraction (0), pixels (1), or insetPixels (2))
BOOL GE_SetScreenOverlayRotationXY ( STRING  overlay_name,
double  x,
double  y,
int  xunits,
int  yunits 
)

Sets the screen-relative (x,y) rotation point of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
x The x-component relative to the screen that the given ScreenOverlay is rotated about
y The y-component relative to the screen that the given ScreenOverlay is rotated about
xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the rotation x-component is specified
yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the rotation y-component is specified
Returns:
TRUE if the function executed properly; FALSE otherwise
double* GE_GetScreenOverlaySize ( STRING  overlay_name  ) 

Retrieves the horizontal and vertical (x,y) size of the given ScreenOverlay.

[-1 uses image's native dimensions; 0 maintains the aspect ratio; n sets the value in the specified units] .

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's horizontal and vertical (x,y) size values
int* GE_GetScreenOverlaySizeUnits ( STRING  overlay_name  ) 

Retrieves the units of the horizontal and vertial (x,y) size values of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
Returns:
A 2-element array with the overlay's size (x,y) units (fraction (0), pixels (1), or insetPixels (2))
BOOL GE_SetScreenOverlaySize ( STRING  overlay_name,
double  x,
double  y,
int  xunits,
int  yunits 
)

Sets the the horizontal and vertical (x,y) size of the given ScreenOverlay.

Parameters:
overlay_name The name of the ScreenOverlay
x The horizontal size of the given ScreenOverlay where [-1 uses image's native dimensions; 0 maintains the aspect ratio; n sets the value in the specified units]
y The vertical size of the given ScreenOverlay where [-1 uses image's native dimensions; 0 maintains the aspect ratio; n sets the value in the specified units]
xunits The units (fraction (0), pixels (1), or insetPixels (2)) which the size x-component is specified
yunits The units (fraction (0), pixels (1), or insetPixels (2)) which the size y-component is specified
Returns:
TRUE if the function executed properly; FALSE otherwise
Generated on Wed Sep 16 23:50:34 2009 for Google Earth SDK by  doxygen 1.6.1