HTML Boxes

This section documents classes that provide HTML Box functionality.

Class list

Author

G Element Germanium team

HTMLBox

Represents a 2D box that may contain HTML content.  You may use the HTMLBox for tasks such as :

  • Adding a graphical user interface (GUI) inside the plugin area,
  • Adding a dialog box,
  • To display content such as a mini-map, header or footer inside the plugin area.

The HTMLBox consists of the following elements :

  • The header bar.  This is a bar at the top of the HTMLBox, and contains the following sub-elements:
grabber barThis is a bar that users may click on and use to reposition the HTMLBox around the plugin area.  If dragging is enabled, this bar will be visible as a grey bar.  Otherwise, the bar takes on the background color of the HTMLBox and is not interactive.  However, the bar will still occupy space at the top of the HTMLBox.
close buttonThis an “x” button can users may click to hide the HTMLBox.  It appears inside the grabber bar, and is positioned to the right.  The visibility of this button is optional, and is independent of the visibility of the grabber bar.
  • The content pane.  This is the area where the content of the HTMLBox will be displayed.  It starts immediately below the header bar.

The header bar’s visibility may be toggled on or off.  This is useful if you want to add your own custom header (e.g. using a custom DOM structure) in the content pane and want the content pane to span the entire height of the HTMLBox.

Content

The follow content types may be added to the content pane of the HTMLBox :

  • a string,
  • a snippet of HTML code,
  • HTML DOM structures.

Positioning and size

A HTMLBox may be positioned and sized within the plugin area by using either absolute (in pixels) or proportional (as a percentage) values.  These values are identical to Cascading Style Sheets’ (CSS) ‘position’ and ‘top/bottom/left/right’ inputs and will trigger the corresponding behavior with the HTMLBox.  HTMLBoxes’ position and size are defined relative to the position and size of the plugin area.

Styling a HTMLBox

HTMLBoxes may be styled using basic CSS styling attributes such as margin, padding, color, background-color and overflow.  These values can be modified using the setter functions provided by the API, which takes in standard CSS-styled inputs.

Advanced uses

Users who wish to do advanced styling of HTMLBox contents should create their own DOM hierarchy and attach it to the HTMLBox’s content pane.  You may find it useful to hide the header bar of the HTMLBox should you intend to do this.

Note :

You should not instantiate the HTMLBox class using the JavaScript keyword ‘new’.  Instead, use the function WebControl.CreateHTMLBox .

See also

WebControl.CreateHTMLBox

Since Version 1.5.0.5

Summary
General properties
GetHandle Gets the Handle of this HTMLBox .
Dimensions
SetSize Sets the size of this HTMLBox .
SetWidth Sets the width of this HTMLBox .
SetHeight Sets the height of this HTMLBox .
GetWidth Returns the width property of the HTMLBox
GetHeight Returns the height property of the HTMLBox
Position
SetPosition Sets the position of this HTMLBox .
SetLeft Sets the position of the left side of the HTMLBox .
SetRight Sets the position of the right side of the HTMLBox .
SetTop Sets the position of the top of the HTMLBox .
SetBottom Sets the position of the bottom of the HTMLBox .
GetLeft Returns the left property of the HTMLBox
GetRight Returns the right property of the HTMLBox
GetTop Returns the top property of the HTMLBox
GetBottom Returns the bottom property of the HTMLBox
Interactivity
SetCloseButtonVisibility Sets whether the close button of the HTMLBox is visible.
GetCloseButtonVisibility Returns whether the close button of the HTMLBox ’s button is set to visible.
SetIsDraggable Sets whether the HTMLBox can be dragged by the user to a different position within the plugin area.
GetIsDraggable Returns whether the HTMLBox is draggable by the user.
SetHeaderBarVisibility Sets whether the header bar of the HTMLBox is visible.
GetHeaderBarVisibility Returns whether the header bar of the HTMLBox is set to visible.
Content
SetContent Sets the content of the HTMLBox .
GetContent Returns the content of the HTMLBox .
Styling
SetBorder Sets the style of the border of the HTMLBox .
GetBorder Returns the border style of the HTMLBox .
SetPadding Sets the style of the padding of the HTMLBox .
GetPadding Returns the padding style of the HTMLBox .
SetColor Sets the color of text of the HTMLBox .
GetColor Returns the color style of this HTMLBox
SetBackgroundColor Sets the background color of the HTMLBox .
GetBackgroundColor Returns the background color style of this HTMLBox
SetOverflow Sets the overflow style of the HTMLBox .
GetOverflow Returns the overflow style of this HTMLBox
SetZIndex Sets the z-index of the HTMLBox .
GetZIndex Returns the z-index of this HTMLBox
ResetStyles Resets the CSS styles of this HTMLBox to default
Visibility
Show Makes this HTMLBox visible.
Hide Hides this HTMLBox .
SetVisibility Sets the visibility state of this HTMLBox
GetVisibility Gets the visibility state of this HTMLBox

General properties

GetHandle

GetHandle : function ()

Gets the Handle of this HTMLBox .  Handles are system-generated and non-persistent.  Use a handle as a fast, lightweight alternative to passing around a Placemark.

Returns

string

Since

Version 1.5.0.5

Dimensions

SetSize

SetSize : function (width,
height)

Sets the size of this HTMLBox .  This function takes in CSS-style inputs.  If width or height is set as “”, previous width/height is retained.

Parameters

{string} widthNew width of the HTMLBox, in px or %
{string} heightNew height of the HTMLBox, in px or %

Returns

void

Examples

SetSize(“640px”, “480px”);Sets the HTMLBox size to be 640x480 pixels.
SetSize(“50%”, “25%”);Sets the HTMLBox’s width and height to be 50% and 25% of the width and height of the plugin area, respectively.
SetSize(“640px”, “25%”);Sets the HTMLBox’s width to be 640pixels and height to be 25% of the width of the plugin area.

Since

Version 1.5.0.5

SetWidth

SetWidth: function (width)

Sets the width of this HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} widthNew width of the HTMLBox, in px or %

Returns

void

Examples

SetWidth(“640px”);Sets the HTMLBox’s width to be 640 pixels.
SetWidth(“50%”);Sets the HTMLBox’s width to be 50% of the width of the plugin area.

Since

Version 1.5.0.7

SetHeight

SetHeight: function (height)

Sets the height of this HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} heightNew height of the HTMLBox, in px or %

Returns

void

Examples

SetWidth(“480px”);Sets the HTMLBox’s height to be 640 pixels.
SetWidth(“25%”);Sets the HTMLBox’s height to be 50% of the height of the plugin area.

Since

Version 1.5.0.7

GetWidth

GetWidth : function ()

Returns the width property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

GetHeight

GetHeight : function ()

Returns the height property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

Position

SetPosition

SetPosition : function (left,
top)

Sets the position of this HTMLBox .  This function takes in CSS-style inputs.  If left or top is set as “”, previous left/top is retained.

Parameters

{string} leftOffset of the left side of the HTMLBox from the plugin area’s left side, in px or %
{string} topOffset of the top of the HTMLBox from the plugin area’s top, in px or %

Returns

void

Examples

SetPosition(“0px”, “0px”);Sets the HTMLBox’s position to be at the left top corner of the plugin area.
SetPosition(“50%”, “25%”);Sets the HTMLBox’s left to be 50% of the plugin area’s width away from its left; and the top to be 25% of the plugin area’s height away from its top.
SetPosition(“50px”, “25%”);Sets the HTMLBox’s left to be 50px away from the plugin area’s left; and the top to be 25% of the plugin area’s height away from its top.

See also

SetLeft , SetRight , SetTop , SetBottom

Since

Version 1.5.0.5

SetLeft

SetLeft : function (left)

Sets the position of the left side of the HTMLBox .

Parameters

{string}Offset of the left side of the HTMLBox from the plugin area’s left side, in px or %

Returns

void

Since

Version 1.5.0.5

SetRight

SetRight : function (right)

Sets the position of the right side of the HTMLBox .

Parameters

{string} rightOffset of the right side of the HTMLBox from the plugin area’s right side, in px or %

Returns

void

Since

Version 1.5.0.5

SetTop

SetTop : function (top)

Sets the position of the top of the HTMLBox .

Parameters

{string} topOffset of the top of the HTMLBox from the plugin area’s top, in px or %

Returns

void

Since

Version 1.5.0.5

SetBottom

SetBottom : function (bottom)

Sets the position of the bottom of the HTMLBox .

Parameters

{string} bottomOffset of the bottom of the HTMLBox from the plugin area’s bottom, in px or %

Returns

void

Since

Version 1.5.0.5

GetLeft

GetLeft : function ()

Returns the left property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

GetRight

GetRight : function ()

Returns the right property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

GetTop

GetTop : function ()

Returns the top property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

GetBottom

GetBottom : function ()

Returns the bottom property of the HTMLBox

Returns

string

Since

Version 1.5.0.5

Interactivity

SetCloseButtonVisibility

SetCloseButtonVisibility : function (bVal)

Sets whether the close button of the HTMLBox is visible.  If the close button is visible, users may close the HTMLBox by clicking it.  If the HTMLBox is set to be draggable, the button will appear inside the grabber bar.

Note :

The close button is contained inside the header bar.  The header bar must be set to visible (the default behavior) for the close button to be visible.

Parameters

{bool} bValboolean value to set whether the close button is shown.

Returns

void

See also

SetHeaderBarVisibility

Since

Version 1.5.0.5

GetCloseButtonVisibility

GetCloseButtonVisibility : function ()

Returns whether the close button of the HTMLBox ’s button is set to visible.

Returns

booltrue if the close button is visible; false if the close button is hidden.

Since

Version 1.5.0.5

SetIsDraggable

SetIsDraggable : function (bVal)

Sets whether the HTMLBox can be dragged by the user to a different position within the plugin area.  If set to true, a grabber bar will appear at the top of the HTMLBox.  If the close button is also set to be visible, the button will appear inside the grabber bar.

Note :

The grabber bar is contained inside the header bar.  The header bar must be set to visible (the default behavior) for the grabber bar to be visible.

Parameters

{bool} bValboolean value to set whether the HTMLBox is draggable.

Returns

void

See also

SetHeaderBarVisibility

Since

Version 1.5.0.5

GetIsDraggable

GetIsDraggable : function ()

Returns whether the HTMLBox is draggable by the user.

Returns

booltrue if the HTMLBox is draggable; false if it is not draggable.

Since

Version 1.5.0.5

SetHeaderBarVisibility

SetHeaderBarVisibility : function (bVal)

Sets whether the header bar of the HTMLBox is visible.

The header bar consists of the grabber bar and the close button.  Setting header bar to not be visible will hide the grabber bar and the close button even if the HTMLBox is set to be draggable and the close button is set to be visible.

Parameters

{bool} bValboolean value to set whether the header bar is visible.

Returns

void

See also

SetCloseButtonVisibility , SetIsDraggable

Since

Version 1.5.1.2

GetHeaderBarVisibility

GetHeaderBarVisibility : function ()

Returns whether the header bar of the HTMLBox is set to visible.

Returns

booltrue if the header bar is visible; false if the header bar is hidden

See also

GetCloseButtonVisibility , GetIsDraggable

Since

Version 1.5.1.2

Content

SetContent

SetContent : function (htmlString)

Sets the content of the HTMLBox .  If the content is set while the HTMLBox is visible on screen, any existing content inside the HTMLBox will be replaced by the new content immediately.

The content may consist of :

  • a string
  • a snippet of HTML code
  • HTML DOM structures

Parameters

{mixed} htmlStringa line of text (string)/ a snippet of HTML (string)/ a DOM element (object)

Returns

void

Examples

SetContent(“My HTMLBox”);sets the content to be the string “My HTMLBox”.
SetContent(“<p>My HTMLBox</p>”);sets the content to be the string “My HTMLBox” enclosed in paragraph tags.
SetContent( document.createElement(“div”) );creates a new “div” DOM structure and sets it as the content.

Since

Version 1.5.0.5

GetContent

GetContent : function ()

Returns the content of the HTMLBox .

Returns

{mixed}string or DOM object.

Since

Version 1.5.0.5

Styling

SetBorder

SetBorder : function (strBorder)

Sets the style of the border of the HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} strBorderborder style

Returns

void

Examples

SetBorder(“1px solid black”);Sets solid black border around the HTMLBox of 1 pixel width.

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetBorder

GetBorder : function ()

Returns the border style of the HTMLBox .

Returns

string

Since

Version 1.5.0.5

SetPadding

SetPadding : function (strPadding)

Sets the style of the padding of the HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} strPaddingpadding style

Returns

void

Examples

SetPadding(“3px”);Sets a padding of 3 pixels between the border and the contents of the HTMLBox.

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetPadding

GetPadding : function ()

Returns the padding style of the HTMLBox .

Returns

string

Since

Version 1.5.0.5

SetColor

SetColor : function (strColor)

Sets the color of text of the HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} strColorcolor style

Returns

void

Examples

SetColor(“red”);Sets the color using a color name.
SetColor(“#FF0000”);Sets the color using a hex value.
SetColor(“rgb(255,0,0)”);Sets the color using an RGB value.

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetColor

GetColor : function ()

Returns the color style of this HTMLBox

Returns

string

Since

Version 1.5.0.5

SetBackgroundColor

SetBackgroundColor : function (strColor)

Sets the background color of the HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} strColorbackground color style

Returns

void

Examples

SetBackgroundColor(“red”);Sets the background color using a color name.
SetBackgroundColor(“#FF0000”);Sets the background color using a hex value.
SetBackgroundColor(“rgb(255,0,0)”);Sets the background color using an RGB value.

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetBackgroundColor

GetBackgroundColor : function ()

Returns the background color style of this HTMLBox

Returns

string

Since

Version 1.5.0.5

SetOverflow

SetOverflow : function (strOverflow)

Sets the overflow style of the HTMLBox .  This function takes in CSS-style inputs.

Parameters

{string} strOverflowoverflow style; accepts either “auto”, “hidden” (default), or “scroll”

Returns

void

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetOverflow

GetOverflow : function ()

Returns the overflow style of this HTMLBox

Returns

string

Since

Version 1.5.0.5

SetZIndex

SetZIndex : function (zindex)

Sets the z-index of the HTMLBox .  This function takes in CSS-style inputs.

If there are multiple HTMLBoxes shown simultaneously, you may use this function to set how the HTMLBoxes overlap with one another.  A HTMLBox with a higher z-index with appear on top of another HTMLBox with a lower z-index.  Note that the z-indices of any HTMLBox should be higher than 0.

Parameters

{string} zindexz-index to set the HTMLBox.

Returns

void

Note

This function does not return an error on invalid CSS input.

Since

Version 1.5.0.5

GetZIndex

GetZIndex : function ()

Returns the z-index of this HTMLBox

Returns

string

Since

Version 1.5.0.5

ResetStyles

ResetStyles : function ()

Resets the CSS styles of this HTMLBox to default

Returns

void

Since

Version 1.5.5.5

Visibility

Show

Show : function ()

Makes this HTMLBox visible.  Equivalent to SetVisibility(true).

Returns

void

See also

SetVisibility

Since

Version 1.5.0.5

Hide

Hide : function ()

Hides this HTMLBox .  Equivalent to SetVisibility(false).

Returns

void

See also

SetVisibility

Since

Version 1.5.0.5

SetVisibility

SetVisibility : function (bVal)

Sets the visibility state of this HTMLBox

Parameter

{bool}bVal

Returns

void

Since

1.5.0.7

GetVisibility

GetVisibility : function ()

Gets the visibility state of this HTMLBox

Returns

booltrue if the HTMLBox is visible; false if it is hidden

Since

1.5.0.7

GetHandle : function ()
Gets the Handle of this HTMLBox.
Represents a 2D box that may contain HTML content.
SetSize : function (width,
height)
Sets the size of this HTMLBox.
SetWidth: function (width)
Sets the width of this HTMLBox.
SetHeight: function (height)
Sets the height of this HTMLBox.
GetWidth : function ()
Returns the width property of the HTMLBox
GetHeight : function ()
Returns the height property of the HTMLBox
SetPosition : function (left,
top)
Sets the position of this HTMLBox.
SetLeft : function (left)
Sets the position of the left side of the HTMLBox.
SetRight : function (right)
Sets the position of the right side of the HTMLBox.
SetTop : function (top)
Sets the position of the top of the HTMLBox.
SetBottom : function (bottom)
Sets the position of the bottom of the HTMLBox.
GetLeft : function ()
Returns the left property of the HTMLBox
GetRight : function ()
Returns the right property of the HTMLBox
GetTop : function ()
Returns the top property of the HTMLBox
GetBottom : function ()
Returns the bottom property of the HTMLBox
SetCloseButtonVisibility : function (bVal)
Sets whether the close button of the HTMLBox is visible.
GetCloseButtonVisibility : function ()
Returns whether the close button of the HTMLBox’s button is set to visible.
SetIsDraggable : function (bVal)
Sets whether the HTMLBox can be dragged by the user to a different position within the plugin area.
GetIsDraggable : function ()
Returns whether the HTMLBox is draggable by the user.
SetHeaderBarVisibility : function (bVal)
Sets whether the header bar of the HTMLBox is visible.
GetHeaderBarVisibility : function ()
Returns whether the header bar of the HTMLBox is set to visible.
SetContent : function (htmlString)
Sets the content of the HTMLBox.
GetContent : function ()
Returns the content of the HTMLBox.
SetBorder : function (strBorder)
Sets the style of the border of the HTMLBox.
GetBorder : function ()
Returns the border style of the HTMLBox.
SetPadding : function (strPadding)
Sets the style of the padding of the HTMLBox.
GetPadding : function ()
Returns the padding style of the HTMLBox.
SetColor : function (strColor)
Sets the color of text of the HTMLBox.
GetColor : function ()
Returns the color style of this HTMLBox
SetBackgroundColor : function (strColor)
Sets the background color of the HTMLBox.
GetBackgroundColor : function ()
Returns the background color style of this HTMLBox
SetOverflow : function (strOverflow)
Sets the overflow style of the HTMLBox.
GetOverflow : function ()
Returns the overflow style of this HTMLBox
SetZIndex : function (zindex)
Sets the z-index of the HTMLBox.
GetZIndex : function ()
Returns the z-index of this HTMLBox
ResetStyles : function ()
Resets the CSS styles of this HTMLBox to default
Show : function ()
Makes this HTMLBox visible.
Hide : function ()
Hides this HTMLBox.
SetVisibility : function (bVal)
Sets the visibility state of this HTMLBox
GetVisibility : function ()
Gets the visibility state of this HTMLBox
this.CreateHTMLBox = function()
Creates a HTMLBox and adds it to the WebControl.