Ovi Maps API Reference

Contents

Class ovi.mapsapi.ui.UIComponent

Class Summary

The base class for UI components. It enhances the functionalities of map components with features and tools which are usefull for adding visual appearance to map components.

Extends ovi.mapsapi.dom.EventTarget, ovi.mapsapi.map.component.Component.
new ovi.mapsapi.ui.UIComponent ([props])
Method Summary
addListener (type, listener, useCapture) : Object Registers an event listener, depending on the useCapture parameter, on the capture phase of the event flow or its target and bubbling phases.
addListenerNS (namespaceURI, type, listener, useCapture) : ovi.mapsapi.dom.EventTarget Registers an event listener, depending on the useCapture parameter, on the capture phase of the event flow or its target and bubbling phases.
addObserver (key, callback, [context]) : ovi.mapsapi.util.OObject Register an observer for a property.
attach (mapDisplay) Will be called when this component gets added to a map display.
attach (mapDisplay) Callback method that is invoked when the component is attached to a map.
build () Creates all DomElements and other entities which must created to generate a visual appearance.
collapse () Shortcut function for set("expanded", false).
detach (mapDisplay) Will be called when this component gets removed from a map display.
detach (mapDisplay) Callback method that is invoked when the component is detached from a map.
disableDrag () : ovi.mapsapi.dom.EventTarget Disable the dragging of this event target, disallowing this event target to receive dragstart, drag and dragend events.
disableUserSelect () : ovi.mapsapi.dom.EventTarget Forbids the user to select text and elements within the event target and prevents the magnifier at the iPhone or other similar mobile devices.
dispatch (evt) : Boolean Dispatches an event.
doc () : DomDocument Returns the DomDocument instance this UI component MUST use for creating DomElements at run time.
enableDrag () : ovi.mapsapi.dom.EventTarget Enable the dragging of this event target and disables the user selection, allowing this event target to receive dragstart, drag and dragend events.
enableUserSelect () : ovi.mapsapi.dom.EventTarget Allows the user to select text and elements within the event target and allows the magnifier at the iPhone or other similar mobile devices.
expand () Shortcut function for set("expanded", true).
expandedSetter (expanded) Will be called when this UI component's expansion state gets changed.
findElement (cssClassName, [node]) Returns the first element within the component's root node, that has the passed css class assigned.
static findElement (className, parent) : DomElement Finds an HTML element with a given identifier with respect either to the passed node or map display.
get (key) : Variant Returns the value of the property with the given name.
getClippingNode () : DomElement Returns the node containing all UI component's dom elements which get clipped automatically.
getId () : String Returns a unique identifier of the component.
getRootNode () : DomElement Returns the node containing all UI component's dom elements.
getSize ([node]) : Object Returns the height and width of a given node or, by default, the UIComponent system's root node.
getVersion () : String Returns the version of the component.
hide () Shortcut function for set("hidden", true).
static hideAll (display, [except]) Hides all UI components.
hitTest (pageX, pageY) : Boolean Tests if the given x/y position relative to the document lies within the outer bounding box of this node.
insertListener (type, listener, useCapture) : Object Registers an event listener as first listener in the listener chain, depending on the useCapture parameter, on the capture phase of the event flow or its target and bubbling phases.
insertListenerNS (namespaceURI, type, listener, useCapture) : ovi.mapsapi.dom.EventTarget Registers an event listener as first listener in the listener chain, depending on the useCapture parameter, on the capture phase of the event flow or its target and bubbling phases.
queryReference () : ovi.mapsapi.map.component.Component Queries a new reference to this component.
releaseReference () : Number Release a reference to this component and return the new updated reference count.
remove (key) : ovi.mapsapi.util.OObject Removes the property with the given name.
removeListener (type, listener, useCapture) : ovi.mapsapi.dom.EventTarget Removes an event listener.
removeListenerNS (namespaceURI, type, listener, useCapture) : ovi.mapsapi.dom.EventTarget Removes an event listener.
removeObserver (key, callback, context) : ovi.mapsapi.util.OObject Remove an observer from a key.
static restoreAll (display) Restores the visibility states, which were active before the #hideAll method was called.
set (nameOrObject, [value, [force]]) : ovi.mapsapi.util.OObject Set the value(s) of a property or properties of given name(s) to given value(s).
show () Shortcut function for set("hidden", false).
Field Summary
Boolean draggable True if this event target is draggable and may receive a dragstart, drag and dragend events; false otherwise.
Object eventListener Either undefined or a hashtable that contains for every event type an array with the values: (listener, useCapture, namespaceURI)(, listener, useCapture, namespaceURI)(,…)
Boolean expanded Indicates whether this component is in an expanded state
Boolean hidden Indicates whether this component is hidden
Boolean isEventTarget A property to indicate that an object implements the ovi.mapsapi.dom.EventTarget interface.
ovi.mapsapi.map.Display mapDisplay A reference to the map to which this component belongs.
ovi.mapsapi.dom.EventTarget parentNode If this property is set, it shall refer to the parent event target.
Object parentNodes If this property is set, it shall be a hash table that contains as key the "namespaceURI" for which the assigned value is the parent event target.
Direct Inheritance
Inherited from ovi.mapsapi.dom.EventTarget: addListener addListenerNS disableDrag disableUserSelect dispatch enableDrag enableUserSelect hitTest insertListener insertListenerNS removeListener removeListenerNS draggable eventListener isEventTarget parentNode parentNodes
Inherited from ovi.mapsapi.map.component.Component: attach detach getId getVersion queryReference releaseReference mapDisplay
Indirect Inheritance
Inherited from ovi.mapsapi.util.OObject: addObserver get remove removeObserver set
Constructor Detail

The constructor of all UIComponents. It must be called by all implementing subclasses. Example of how to extend / implement a UIComponent:

new ovi.mapsapi.ui.UIComponent([props])
Parameters:
{Object} [props]: an object which can contain properties / methods which should be appended to instances of this class. It can be used to extend a component.
Method Detail
attach (mapDisplay)
Will be called when this component gets added to a map display. It shows the UIComponent by appending the root node to the UIContainer of the map display. When overridden by deriving UI components, this super method must be called before anything else is done. Note: Deriving classes should use this method to attach event handlers to their interacting DomElements. A good implementation would then remove these event handlers again in the #detach method. A possible minimal implementation would be:
Examples:
var superClass = ovi.mapsapi.ui.UIComponent.prototype;
superClass.attach.apply(this, arguments);
//Attach a click listener to the root node of this UIComponent
ovi.mapsapi.dom.EventTarget(this.node).addListener("click", this.onClick);
Parameters:
{ovi.mapsapi.map.Display} mapDisplay The map display this component gets added to.
See:
ovi.mapsapi.map.component.Component#attach
build ()
Creates all DomElements and other entities which must created to generate a visual appearance. This method must be implemented by deriving classes and it must set the UIComponent's #node property. It will be called before the first time this component gets added to a map display. When overridden by deriving UI components, this super method must be called after all steps are done. A possible minimal implementation would be:
Examples:
var superClass = ovi.mapsapi.ui.UIComponent.prototype,
	node = this.doc().createElement("div");
this.set("node", node);
superClass.build.call(this);
See:
ovi.mapsapi.util.OObject#set
collapse ()
Shortcut function for set("expanded", false).
See:
ovi.mapsapi.ui.UIComponent#expanded
detach (mapDisplay)
Will be called when this component gets removed from a map display. It hides the UIComponent by hiding the component's node. When overridden by deriving UI components, this super method must be called after all steps are done. Note: Deriving classes should use this method to detach event handlers from their interacting DomElements. A possible minimal implementation would be:
Examples:
var superClass = ovi.mapsapi.ui.UIComponent.prototype;
//Detach a click listener (added by #attach) from the root node of this UIComponent
this.node.removeListener("click", this.onClick);
superClass.detach.apply(this, arguments);
Parameters:
{ovi.mapsapi.map.Display} mapDisplay The map display this component gets removed from.
See:
ovi.mapsapi.map.component.Component#detach
doc () : DomDocument
Returns the DomDocument instance this UI component MUST use for creating DomElements at run time.
Returns:
{DomDocument}
expand ()
Shortcut function for set("expanded", true).
See:
ovi.mapsapi.ui.UIComponent#expanded
expandedSetter (expanded)
Will be called when this UI component's expansion state gets changed. When overridden by deriving classes, the function should return the expanded flag value according to the parameter. Additionally this method must be called by the overriding one. Not all UI components need expansion behavior, so this method need not to be overridden. Note: Override this method to control your UIComponent when it should get expanded. A possible implementation would be:
Examples:
var superClass = ovi.mapsapi.ui.UIComponent.prototype;
if (expanded)
	this.node.style.width = "500px";
else
	this.node.style.width = "250px";
return superClass.expandedSetter.apply(this, arguments);
Parameters:
{Boolean} expanded A flag indicating whether this component should be expanded.
See:
ovi.mapsapi.util.OObject#set
findElement (cssClassName, [node])
Returns the first element within the component's root node, that has the passed css class assigned.
Parameters:
{String} cssClassName The css class of the element to be searched.
{DomNode} [node]: A node in which should be searched instead of the root node.
static findElement (className, parent) : DomElement
Finds an HTML element with a given identifier with respect either to the passed node or map display.
Parameters:
{String} className the nodes identifier (NOTE: The identifier is not necessarily the DOM node's ID. The current implementation finds nodes by their class names to avoid ID clashes when more than one map instance is present in the DOM).
{DomElement | ovi.mapsapi.map.Display} parent An optional node can be passed to limit the search range. Only the children of the node will be searched for the first node which matches the search criteria. If a map display is passed instead of a node, it will be searched through the whole UI system according to that map display.
Returns:
{DomElement} the first DOM node which has a matching CSS class assigned or null.
getClippingNode () : DomElement
Returns the node containing all UI component's dom elements which get clipped automatically. Use this node to change things concerning general behavior of all these nodes. (e.g. event handling, css, ...) Note: The clipping container is a special node which should be used if some nodes of a component should be clipped to the map display's viewport. This means that even if these nodes are larger than the main map node the the overlapping parts of them will be hidden.
Returns:
{DomElement} The node containing all UI component's dom elements which get clipped automatically.
getRootNode () : DomElement
Returns the node containing all UI component's dom elements. Use this node to manipulate things concerning general behavior of all nodes. (e.g. event handling, css, ...) Normally all UIComponent's nodes are added into this container. Note: This node can also be used to directly append additional DomElements at create- or even at runtime. Nodes which were appended to the root UI system's root node should be removed by the according component when the #detach component gets called.
Returns:
{DomElement} The root node.
getSize ([node]) : Object
Returns the height and width of a given node or, by default, the UIComponent system's root node.
Parameters:
{DomElement} [node]: Optional root node of a component to measure
Returns:
{Object} A size hash of the form: {width: x, height: y}
hide ()
Shortcut function for set("hidden", true).
See:
ovi.mapsapi.ui.UIComponent#hidden
static hideAll (display, [except])
Hides all UI components. Optionally, a UI component can be passed, which should be kept visible.
Parameters:
{ovi.mapsapi.map.Display} display The display of which the components should be hidden.
{ovi.mapsapi.ui.UIComponent} [except]: The UI component that should be kept visible.
static restoreAll (display)
Restores the visibility states, which were active before the #hideAll method was called.
Parameters:
{ovi.mapsapi.map.Display} display The display of which the components should be shown.
show ()
Shortcut function for set("hidden", false).
See:
ovi.mapsapi.ui.UIComponent#hidden
Field Detail
Boolean expanded
Indicates whether this component is in an expanded state
Boolean hidden
Indicates whether this component is hidden
Documentation generated on Fri Aug 19 2011 13:36:12 GMT+0200 (CEST).