Echo.Component

Echo
Component

Class Hierarchy:

Object
Echo.Component

Direct Known Subclasses:: Echo.AbstractButton, Echo.AbstractListComponent, Echo.Arc.ChildContainer, Echo.Column, Echo.Composite, Echo.ContentPane, Echo.Grid, Echo.Label, Echo.Row, Echo.SplitPane, Echo.TextComponent, Echo.WindowPane, Extras.AccordionPane, Extras.BorderPane, Extras.CalendarSelect, Extras.ColorSelect, Extras.ContextMenu, Extras.DropDownMenu, Extras.Group, Extras.MenuBarPane, Extras.RichTextArea, Extras.TabPane, Extras.ToolTipContainer, Extras.TransitionPane

Base class for components. Derived classes should wishing to support hierarchal construction should provide constructors with a first parameter name of 'properties' which is passed to the super-constructor. In any case, the super-constructor must be invoked. A component MUST have its componentType property set before it is used in a hierarchy. Failing to do so will throw an exception and/or result in indeterminate behavior.

Constructor Summary
Public	`Echo.Component()` Creates a new Component.

Class Field Summary
Internal	`_nextRenderId` The next automatically assigned client render id.

Instance Field Summary
Public, Virtual	`componentType` Component type.
Public, Virtual	`focusable` Flag indicating whether or not the component is focusable.

Instance Method Summary
Public, Virtual	`getFocusComponent()` Returns the child component at the specified index after sorting the children in the order which they should be focused.
Public	`add()` Adds a component as a child.
Public	`addListener()` Adds an arbitrary event listener.
Public	`fireEvent()` Provides notification of an arbitrary event.
Public	`get()` Returns an arbitrary property value.
Public	`getComponent()` Retrieves the child component at the specified index.
Public	`getComponentCount()` Returns the number of child components.
Public	`getIndex()` Returns an arbitrary indexed property value.
Public	`getLayoutDirection()` Returns the component layout direction.
Public	`getLocale()` Returns the component locale.
Public	`getLocalStyleData()` Retrieves local style property map associations.
Public	`getRenderLayoutDirection()` Returns the layout direction with which the component should be rendered, based on analyzing the component's layout direction, its parent's, and/or the application's.
Public	`getRenderLocale()` Returns the locale with which the component should be rendered, based on analyzing the component's locale, its parent's, and/or the application's.
Public	`getStyle()` Returns the style assigned to this component, if any.
Public	`getStyleName()` Returns the name of the style (from the application's style sheet) assigned to this component.
Public	`indexOf()` Returns the index of a child component, or -1 if the component is not a child.
Public	`isActive()` Determines if the component is active, that is, within the current modal context and ready to receive input.
Public	`isAncestorOf()` Determines if this component is or is an ancestor of another component.
Public	`isEnabled()` Determines the enabled state of this component.
Public	`isRenderEnabled()` Determines whether this `Component` should be rendered with an enabled state.
Public	`register()` Registers / unregisters a component that has been added/removed to/from a registered hierarchy (a hierarchy that is registered to an application).
Public	`render()` Returns the value of a property that should be rendered, based on the value set on this component, in the component's specified style, and/or in the application's stylesheet.
Public	`renderIndex()` Returns the value of an indexed property that should be rendered, based on the value set on this component, in the component's specified style, and/or in the application's stylesheet.
Public	`remove()` Removes a child component.
Public	`removeAll()` Removes all child components.
Public	`removeListener()` Removes an arbitrary event listener.
Public	`set()` Sets the value of a property in the internal style.
Public	`setEnabled()` Sets the enabled state of the component.
Public	`setIndex()` Sets the value of an indexed property in the internal style.
Public	`setLayoutDirection()` Sets a component-specific layout direction.
Public	`setLocale()` Sets a component-specific locale.
Public	`setStyle()` Sets the style of the component.
Public	`setStyleName()` Sets the name of the style (from the application's style sheet) assigned to this component.
Public	`toString()` Returns a string representation of the component (default implementation).

Style Properties
`background`	Color (`String`)	the background color
`font`	Font (`Object`)	the component font
`foreground`	Color (`String`)	the foreground color
`layoutData`		layout data information, describing how the component should be rendered by its container

Events
`property`	An event fired when the a property of the component changes. The `propertyName` property will specify the name of the changed property. The `oldValue` and `newValue` properties (may) describe the previous and current states of the property, respectively.
`init`	An event which is fired when the Component is added to a component hierarchy which is registered to an application. The "application" property of the Component will be available when the event is fired.
`dispose`	An event which is fired when the Component is about to be removed from a component hierarchy which is registered to an application. The "application" property of the Component will be available when the event is fired.
`parent`	An event which is fired when the Component's parent is changed.
`children`	An event which is fired when a child is added to or removed from the Component.

Echo.Component()

Creates a new Component. The parent constructor MUST be invoked if it is overridden. This is accomplished by including the statement "BaseComponent.call(this, properties)" in any derivative constructor, where "BaseComponent" is class from which the component is immediately derived (which may or may not be Echo.Component itself).

Parameters:

properties - (Optional) associative mapping of initial property values (may be null) By default, all properties will be placed into the local style, except for the following:

styleName specifies the component stylesheet style name
style specifies the referenced component style
renderId specifies the render id
children an array specifying the initial children of the component
events an associative mapping between event names and listener methods

getFocusComponent

Returns the child component at the specified index after sorting the children in the order which they should be focused. The default implementation simply returns the same value as getComponent(). Implementations should override this method when the natural order to focus child components is different than their normal ordering (e.g., when the component at index 1 is positioned above the component at index 0).

Parameters:: index (Number) - the index of the child (in focus order)

Returns:: (Echo.Component) the child component

add

Adds a component as a child.

Parameters:: component (Echo.Component) - the component to add; index (Number) - the (integer) index at which to add it (optional, omission will cause component to be appended to end)

addListener

Adds an arbitrary event listener.

Parameters:: eventType (String) - the event type name; eventTarget (Function) - the method to invoke when the event occurs (the event will be passed as the single argument)

fireEvent

Provides notification of an arbitrary event. Listeners will be notified based on the event's type property.

Parameters:: event - the event to fire

get

Returns an arbitrary property value.

Parameters:: name (String) - the name of the property

Returns:: the property value

getComponent

Retrieves the child component at the specified index.

Parameters:: index (Number) - the (integer) index

Returns:: (Echo.Component) the child component

getComponentCount

Returns the number of child components.

Returns:: (Number) the number of child components

getIndex

Returns an arbitrary indexed property value.

Parameters:: name (String) - the name of the property; index (Number) - the index to return

Returns:: the property value

getLayoutDirection

Returns the component layout direction. Note that in most cases it is preferable to set the layout direction of the Application, rather than individual components.

Returns:: (Echo.LayoutDirection) the component layout direction

getLocale

Returns the component locale. Note that in most cases it is preferable to set the locale of the Application, rather than individual components.

Returns:: (String) the component locale

getLocalStyleData

Retrieves local style property map associations. This method should only be used by a de-serialized for the purpose of rapidly loading properties into a new component.

Returns:: the internal style property map associations

getRenderLayoutDirection

Returns the layout direction with which the component should be rendered, based on analyzing the component's layout direction, its parent's, and/or the application's.

Returns:: (Echo.LayoutDirection) the rendering layout direction

getRenderLocale

Returns the locale with which the component should be rendered, based on analyzing the component's locale, its parent's, and/or the application's.

Returns:: (String) the rendering locale

getStyle

Returns the style assigned to this component, if any.

Returns:: the assigned style

getStyleName

Returns the name of the style (from the application's style sheet) assigned to this component.

Returns:: (String) the style name

indexOf

Returns the index of a child component, or -1 if the component is not a child.

Parameters:: component (Echo.Component) - the component

Returns:: (Number) the index

isActive

Determines if the component is active, that is, within the current modal context and ready to receive input.

Returns:: (Boolean) the active state

isAncestorOf

Determines if this component is or is an ancestor of another component.

Parameters:: c (Echo.Component) - the component to test

Returns:: (Boolean) true if an ancestor relationship exists

isEnabled

Determines the enabled state of this component. Use isRenderEnabled() to determine whether a component should be rendered as enabled.

Returns:: the enabled state of this specific component

isRenderEnabled

Determines whether this Component should be rendered with an enabled state. Disabled Components are not eligible to receive user input.

Returns:: (Boolean) true if the component should be rendered enabled

Registers / unregisters a component that has been added/removed to/from a registered hierarchy (a hierarchy that is registered to an application).

Parameters:: application (Echo.Application) - the application (null to unregister the component)

render

Returns the value of a property that should be rendered, based on the value set on this component, in the component's specified style, and/or in the application's stylesheet.

Parameters:: name (String) - the name of the property; defaultValue - the default value to return if no value is specified in an internal property, style, or stylesheet

Returns:: the property value

renderIndex

Returns the value of an indexed property that should be rendered, based on the value set on this component, in the component's specified style, and/or in the application's stylesheet.

Parameters:: name (String) - the name of the property; index (Number) - the (integer) index of the property; defaultValue - the default value to return if no value is specified in an internal property, style, or stylesheet

Returns:: the property value

remove

Removes a child component.

Parameters:: componentOrIndex - the index of the component to remove, or the component to remove (values may be of type Echo.Component or Number)

removeAll

Removes all child components.

removeListener

Removes an arbitrary event listener.

Parameters:: eventType (String) - the event type name; eventTarget (Function) - the method to invoke when the event occurs (the event will be passed as the single argument)

set

Sets the value of a property in the internal style.

Parameters:: name (String) - the name of the property; value - the new value of the property

setEnabled

Sets the enabled state of the component.

Parameters:: newValue - the new enabled state

setIndex

Sets the value of an indexed property in the internal style.

Parameters:: name (String) - the name of the property; index (Number) - the index of the property; newValue - the new value of the property

setLayoutDirection

Sets a component-specific layout direction. Note that in most cases it is preferable to set the layout direction of the Application, rather than individual components.

Parameters:: newValue (Echo.LayoutDirection) - the new layout direction

setLocale

Sets a component-specific locale. Note that in most cases it is preferable to set the locale of the Application, rather than individual components.

Parameters:: newValue (String) - the new layout direction

setStyle

Sets the style of the component.

Parameters:: newValue - the new style

setStyleName

Sets the name of the style (from the application's style sheet) assigned to this component.

Parameters:: newValue (String) - the style name

toString

Returns a string representation of the component (default implementation).

Parameters:: longFormat (Boolean) - an optional flag specifying whether all information about the component should be displayed (e.g., property values)

Returns:: (String) a string representation of the component