HTMLBoxConcepts - GermaniumWeb

HTML Boxes

1 Introduction
2 Creating a HTMLBox
3 Interactivity options
4 Changing visual appearance
- 4.1 Advanced styling
5 Removing a HTMLBox
6 Multiple HTMLBoxes and Placemarks
- 6.1 Z-Index
- 6.2 Placemark callouts
7 References

Introduction

The HTMLBox enables you to create a 2D box on top of the 3D scene that can contain HTML content. You may use it for tasks such as:

adding a graphical user interface (GUI) inside the plugin area,
displaying a dialog box,
displaying 2D content such as a mini-map, header or footer inside the plugin area.

Creating a HTMLBox

You create a HTMLBox using the following steps:

Create a HTMLBox
Set the HTMLBox's properties
Customize its visual appearance (optional),
Show the HTMLBox.

Source: HTMLBox example, function CreateHTMLBox()

// Create a htmlbox
myHTMLBox = germ.CreateHTMLBox(); // myHTMLBox is a global variable
 
// Set dimensions
myHTMLBox.SetSize("125px", "160px");
 
// Set position
myHTMLBox.SetPosition("20px", "20px");
 
// Set content
myHTMLBox.SetContent("<div style='text-align: center'>This is my HTMLBox</div>");
 
// Make the box visible
myHTMLBox.SetVisibility(true);

Note: HTMLBoxes are automatically added to the WebControl after creation, unlike placemarks which need to be explicitly added.

Note: Please be reminded not to cover the status message area or the GermaniumWeb logo when creating HTMLBoxes.

Interactivity options

By default, a HTMLBox is set to be immovable, and can be closed by the user using the close button. Additionally, you have the option of allowing the user to reposition the HTMLBox by dragging it. You may do so by enabling the grabber bar.

HTMLBox interactive options. Clockwise from top-left: Not draggable and not closeable; Closeable only; Draggable and closeable; Draggable only.

Source: HTMLBox example, function SetDraggable()

myHTMLBox.SetHeaderBarVisibility(true); // show the header bar if it is not visible already
myHTMLBox.SetIsDraggable(true); // show the grabber bar in the header bar

If you do not want to allow the user to close the HTMLBox, you may hide the close button.

Source: HTMLBox example, function HideCloseButton()

myHTMLBox.SetCloseButtonVisibility(false);

Changing visual appearance

The visual appearance of HTMLBoxes are controlled through basic Cascading Style Sheets (CSS) properties, and can be customized using standard CSS input values.

By default, the HTMLBox appears as a border-less white box with black text. You may customize its appearance by changing its:

Source: HTMLBox example, function ChangeVisualAppearance()

myHTMLBox.SetBackgroundColor("#33DDFF"); // Background color
myHTMLBox.SetColor("#000000");           // Text color
myHTMLBox.SetBorder("4px solid black");  // Border width and color
myHTMLBox.SetPadding("4px");     // Padding
myHTMLBox.SetOverflow("Auto");   // Scrolling

Advanced styling

If you wish to customize the visual appearance of a HTMLBox beyond what is provided by the GermaniumWeb API, you may create and style a HTML container element (e.g. a div) and attach that as the contents of the HTMLBox.

Source: HTMLBox example, function ApplyAdvancedStyles()

// Style sheet
<style type="text/css">
div.contentContainer {
   position: absolute;
   width: 100%;
   height: 100%;
   left: 0px;
   top: 0px;
   margin: 0px;
}
div.content {
   position: absolute;
   left: 0px;
   right: 0px;
   top: 0px;
   bottom: 0px;
   border-top: 2px solid black;
   border-bottom: 2px solid black; 
   border-left: 4px solid black;
   border-right: 4px solid black;
   margin: 0px;
   text-align: center;
}
</style>
 
...
 
// Create a div hierarchy with style defined in style sheet
// and set as HTMLBox content. 
var myContainerDiv = document.createElement("div");
myContainerDiv.className = "contentContainer";
var myContentDiv = document.createElement("div");
myContentDiv.className = "content";
myContainerDiv.appendChild(myContentDiv);
 
myContentDiv.innerHTML = "This is my HTMLBox with different border widths";
 
myHTMLBox.SetHeaderBarVisibility(false);  // Removes the header bar
myHTMLBox.ResetStyles();                  // Resets all styles to default
myHTMLBox.SetContent(myContainerDiv);

Note: You should reset a HTMLBox's styles and hide the header bar before applying custom visual styles.

Warning: When setting an advanced visual style this way, a HTMLBox's header bar may clash visually with the content and style of the HTMLBox if it is not disabled.

Removing a HTMLBox

You can remove a HTMLBox from WebControl by calling RemoveHTMLBox().

Source: HTMLBox example, function RemoveFirstHTMLBox()

if (germ.GetNumberOfHTMLBoxes() > 0) {
    var box = germ.GetHTMLBoxByIndex(0);
    germ.RemoveHTMLBox(box);
} else {
    alert("There no HTMLBox in the plugin area.");
}

For convenience, you can remove all HTMLBoxes using RemoveAllHTMLBoxes().

Source: HTMLBox example, function RemoveAllHTMLBoxes()

germ.RemoveAllHTMLBoxes();

Multiple HTMLBoxes and Placemarks

Z-Index

You may have multiple HTMLBoxes visible on screen at once.

Depending on the position and size of the HTMLBoxes, the boxes may overlap each other. You can make a HTMLBox appear on top of another HTMLBox by setting its z-index to a larger value.

Placemark's callout balloon avoiding overlapping HTMLBoxes arranged using z-indices.

Source: HTMLBox example, function UncoverTopHTMLBox()

// Make myTopBox appear above myBottomBox:
// Set myTopBox's z-index 1 greater than myBottomBox's
myTopBox.SetZIndex( myBottomBox.GetZIndex() + 1 );

Placemark callouts

HTMLBoxes and Placemark callout balloons may co-exist on screen. The callout balloons will avoid opening at locations occupied by HTMLBoxes, and will reposition itself if a HTMLBox is moved on top of it.

If there is no space on screen for the callout to open, the callout will not open.

References

HTMLBox

Retrieved from "http://www.germanium3d.com/code/HTMLBoxConcepts"

This page has been accessed 212 times. This page was last modified on 16 June 2011, at 03:50.

Contents