tutorials/www/component-and-container.xml - pivot - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to you under the Apache License,
 Version 2.0 (the "License"); you may not use this file except in
 compliance with the License.  You may obtain a copy of the License at

     http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
 -->

 <document id="component-and-container">
     <properties>
         <title>Component &amp; Container</title>
     </properties>

     <body>
         <p>
             All Pivot components ultimately extend the base <tt>Component</tt> class. This class,
             in conjunction with the similarly abstract <tt>Container</tt> class, defines the APIs
             that specify where a component will appear on screen, what it will look like, and how a
             user will interact with it.
         </p>

         <h3>Visual and ConstrainedVisual</h3>

         <p><img src="component_and_container/visuals.png"/></p>

         <p>
             As shown in the diagram, <tt>Component</tt> implements the <tt>ConstrainedVisual</tt>
             interface. This interface extends the <tt>Visual</tt> interface, which defines methods
             common to all visual elements in Pivot. The <tt>org.apache.pivot.wtk.media.Image</tt>
             class also implements the <tt>Visual</tt> interface:
         </p>

         <p>
             <tt>public int getWidth()</tt><br/>
             <tt>public int getHeight()</tt><br/>
             <tt>public int getBaseline()</tt><br/>
             <tt>public void paint(Graphics2D graphics)</tt><br/>
         </p>

         <p>
             A visual's size (reported by the <tt>getWidth()</tt> and <tt>getHeight()</tt> methods)
             is specified in "device-independent units". Though these generally map
             one-to-one to actual pixels on an output device, they are not required to do so. This
             allows Pivot applications to be written in a resolution-independent manner, supporting
             UI scaling either for accessibility purposes or for very high resolution output devices.
         </p>

         <p>
             The <tt>getBaseline()</tt> method allows a visual to report a baseline offset, which
             is used by containers that support it to align components to a common baseline.
             The <tt>paint()</tt> method is called as needed to ensure that the visual's current
             state is correctly represented on-screen. For example, a component may need to be
             repainted when an internal value, such as a button's label, has changed, or when some
             part of the component has been exposed due to an overlapping window or other component
             having been moved or resized.
         </p>

         <p>
             <tt>ConstrainedVisual</tt> adds methods to support layout, which is discussed in more
             detail below:
         </p>

         <p>
             <tt>public void setSize(int width, int height)</tt><br/>
             <tt>public int getPreferredWidth(int height)</tt><br/>
             <tt>public int getPreferredHeight(int width)</tt><br/>
             <tt>public Dimensions getPreferredSize()</tt><br/>
             <tt>public int getBaseline(int width, int height)</tt><br/>
         </p>

         <p>
             In addition to <tt>Component</tt>, the <tt>Skin</tt> and <tt>Renderer</tt> interfaces
             also extend <tt>ConstrainedVisual</tt>. In Pivot, a component's "skin" is responsible
             for the visual representation of the component. As a result, <tt>Component</tt>
             delegates the implementation of all <tt>ConstrainedVisual</tt> methods to the skin.
             The skin may, in turn, delegate some renderering responsibility to one or more
             renderers, which are used to paint some components' content (such as a button label or
             a list item); this relationship is represented by the dotted line in the diagram.
             Renderers are often implemented as extensions of the <tt>Component</tt> class, allowing
             the component's implementation of <tt>ConstrainedVisual</tt> to be re-used (and giving
             rise to the notion of renderers as "lightweight components").
         </p>

         <p>
             Components are painted in the order in which they are defined in the parent container's
             component sequence. The component sequence thus defines the "z-order" of the components
             in the container: components are painted in ascending order, allowing higer components
             to overlap lower ones. Z-order is often only noticeable at the window level - individual
             components within an application are generally arranged such that the user can see and
             readily interact with them. This process, called "layout management", is generally
             handled automatically in a Pivot application, and is discussed next.
         </p>

         <h3>Layout</h3>

         <p>
             "Layout management" is the process of automatically determining how components should
             be arranged on screen, as opposed to requiring the the developer to explicitly set
             component size and position. Layout management is performed by all Pivot containers,
             and is the responsibility of a container's skin.
         </p>

         <p>
             <tt>ConstrainedVisual</tt>'s preferred size methods, <tt>getPreferredWidth()</tt>,
             <tt>getPreferredHeight()</tt>, and <tt>getPreferredSize()</tt>, return information
             about the size the visual "wants" to be. This is generally determined based on
             attributes such as font size and border thickness, or, in the case of containers, by
             recursively asking subcomponents about their own preferred sizes. Containers may use
             this information to determine how to arrange their subcomponents during layout.
         </p>

         <p>
             In Pivot, preferred sizes may optionally be constrained by passing a height constraint
             value to <tt>getPreferredWidth()</tt> or a width constraint value to
             <tt>getPreferredHeight()</tt>. This allows components to "wrap" their contents. For
             example, a <tt>Label</tt> component with the "wrapText" style set to <tt>true</tt> will
             report a preferred height that is tall enough to render its entire content by applying
             line break logic using the given width constraint.
         </p>

         <p>
             <tt>ConstrainedVisual</tt> defines an additional signature for <tt>getBaseline()</tt>
             that takes <tt>width</tt> and <tt>height</tt> arguments. This allows a component to
             report a constrained baseline given a possible width and height (for example, a
             label whose content is vertically aligned to bottom will report a different baseline
             than one that is vertically aligned to top when it is given more than its preferred
             height).
         </p>

         <h3>Location and Visibility</h3>

         <p>
             <tt>Component</tt> defines several additional methods that are used by containers
             during layout:
         </p>

         <p>
             <tt>public int getX()</tt><br/>
             <tt>public int getY()</tt><br/>
             <tt>public Point getLocation()</tt><br/>
             <tt>public void setLocation(int x, int y)</tt><br/>
             <tt>public final void setLocation(Point location)</tt><br/>
         </p>

         <p>
             These methods are used to manage a component's location, which is defined as an (x, y)
             coordinate pair that is relative to the origin of its parent container.
         </p>

         <p>
             <tt>public boolean isVisible()</tt><br/>
             <tt>public void setVisible(boolean visible)</tt><br/>
         </p>

         <p>
             These methods manage a component's visibility. A component that is not visible is not
             painted. Layout containers will generally also exclude non-visible components from
             layout.
         </p>

         <p>
             Container skins use the preferred size and visibility values to determine how to
             arrange their subcomponents. They first query the subcomponents for the preferred
             values, and then use these values to set the components' actual size and location. As
             a result, callers should generally not invoke the methods that set these properties
             directly, since the container is likely to override any values set by the caller
             during layout.
         </p>

         <p>
             It is important to note that containers are not required to respect a component's
             preferred size or visibility. For example, <tt>CardPane</tt> sets the size of its
             subcomponent to the maximum preferred size of all its child components, and
             <tt>TablePane</tt> sets the size of its components based on the width of its rows and
             columns. However, most respect at least one, and many respect both.
         </p>

         <h3>Disabled Components</h3>

         <p>
             A component that is "enabled" is currently capable of receiving user input. A component
             may be "disabled" to prevent it from receiving input from the user. For example,
             buttons are often disabled to prevent a user from initiating an action that would not
             be appropriate for the current state of the application. Most components display a
             disabled state to indicate to the user that interaction is currently forbidden.
         </p>

         <p>
             Note that, while a user is prevented from interacting with a disabled component,
             programmatic interaction is still allowed. For example, it is still valid to set the
             selection state of a disabled list view component in code, even though the user cannot
             click on an item in the list to change the list's selection state.
         </p>

         <p>
             Also note that disabling a container will prevent all child components of the container
             from receiving input as well. Thus, there is no need to propagate the enabled state of
             a container down to its children. When a component is either disabled or one of its
             ancestors is disabled, it is said to be "blocked".
         </p>

         <h3>Focus Management</h3>

         <p>
             A component that is eligible to receive keyboard input is said to have the "input
             focus", or simply "focus". Only one component is allowed to have the focus at any given
             time. Not all components are focusable, though many are, including text inputs, buttons,
             and list views, among others. It is up to a component's skin to decide whether or not it
             is capable of receiving focus. In order to receive the focus, a component (and its
             ancestry) must be enabled, visible, and focusable.
         </p>

         <p>
             Generally, a focusable component will paint a slightly different state when it has the
             focus as a visual cue to the user. For example, a text input may show a blinking
             cursor, while a button might draw a dotted line around its label.
         </p>

         <p>
             Clicking on a component with the mouse will usually transfer focus to that component.
             However, focus can also be transferred between using the Tab (or Shift-Tab) key. This
             is called "focus traversal". Each container provides a "focus traversal policy" that
             defines how focus management is performed within the container. By default, most
             containers use a default traversal policy that simply traverses child components in the
             order in which they appear in the container's component sequence. However, windows use
             a traversal policy that ensures that focus is never transferred out of the window
             itself; tab panes employ a similar policy. However, callers and skin developers are
             free to override these defaults and can install a custom traversal policy on any
             container.
         </p>

         <h3>Cursors</h3>

         <p>
             A component's skin will generally ensure that an appropriate cursor is displayed when
             the mouse is over the component. However, a caller may customize the component's cursor
             using the <tt>setCursor()</tt> method of <tt>Component</tt>. Valid cursor values are
             defined by the <tt>Cursor</tt> enum.
         </p>

         <h3>Styles</h3>

         <p>
             Styles are a means of customizing a component's appearance. They are implemented as
             named properties exposed by a skin via the component. For example, a label skin might
             define styles such as "font", "color", and "textDecoration", and a list view skin might
             define styles including "font", "color", "selectionColor" and
             "selectionBackgroundColor". These properties correspond directly to the Java bean
             getters and setters defined by the skin class.
         </p>

         <p>
             By design, skins are programmatically hidden from the developer; a caller interacts
             with a skin's styles via the component's style collection, an instance of
             <tt>org.apache.pivot.wtk.Component.StyleDictionary</tt> returned by
             <tt>Component#getStyles()</tt>:
         </p>

         <p>
             <tt>public Object get(String key) - returns the value of a given style</tt><br/>
             <tt>public Object put(String key, Object value) - sets a style value</tt><br/>
         </p>

         <p>
             This facilitates a loose, flexible coupling between an application and a skin: an
             application need not be tied to a particular skin implementation, and skin developers
             are free to add or remove styles without the risk of breaking existing applications.
             However, it becomes the responsibility of the caller to be aware of the styles
             supported by the current skin. Attempting to set a non-existent style value will
             simply generate a warning, but passing an invalid type for a valid style will throw
             an exception.
         </p>

         <p>
             Style values can be set in BXML using the "styles" attribute. The value of this
             attribute is a JSON-formatted string representing the style values to be applied to
             the component after it is constructed. For example, the following attribute applied to
             the Label element would produce a bold, 24-point Arial label with red text:
         </p>

         <p>
             <tt>styles="{font:'Arial bold 24', color:'#ff0000'}"</tt><br/>
         </p>

         <p>
             Styles can also be set using a <tt>&lt;styles&gt;</tt> sub-element:
         </p>

         <p>
             <tt>&lt;styles font="Arial bold 24" color="#ff0000"&gt;</tt><br/>
         </p>

         <p>
             Finally, styles can be applied via CSS-like stylesheets. Both typed and untyped
             selectors are supported. For example:
         </p>

         <source type="jscript">
         {  Button: {
                 color: "#aa0000"
             },

             RadioButton: {
                 color: "#00aa00"
             },

             "org.apache.pivot.wtk.PushButton": {
                 color: "#0000aa"
             },

             heading: {
                 font: {
                     size: "120%",
                     bold: true
                 },

                 color: "#000000"
             },

             subHeading: {
                 font: {
                     size: "110%",
                     italic: true
                 },

                 color: "#666666"
             }
         }
         </source>

         <h3>Attributes</h3>

         <p>
             Attributes are a means of attaching container-specific properties to a component.
             Attributes are typed values defined by containers that support or require them. For
             example, <tt>TabPane</tt> defines a "label" attribute that allows a caller to specify
             the text that is displayed on the tab button for the component; <tt>TablePane</tt>
             defines a "rowSpan" attribute that determines how a cell is laid out. Attributes
             effectively allow a caller to "tag" a component with values that are relevant only to
             its parent container (and the container's skin).
         </p>

         <p>
             Callers can set attribute values programmatically using a static setter method of
             the <tt>Container</tt> subclass (e.g. <tt>TabPane#setLabel(Component, String)</tt>).
             Alternatively, attributes can be specified in BXML. For example, the sub-elements of
             a <tt>TabPane</tt> can provide a <tt>TabPane.label</tt> attribute to specify the value
             that should be used as the text label for that component.
          </p>

         <h3>Events</h3>

         <p>
             In GUI programming, the term "event" generally refers to a notification sent by a
             program in response to some triggering action. The trigger may have been input from
             the user, a response from a remote server, or a change in some internal state.
         </p>

         <p>
             Pivot components rely heavily on events, both to respond to change notifications from
             data models or other components and to notify external listeners of changes to their
             own states. Each concrete component class defines a set of events specific to its own
             implementation, and all components inherit a set of common events defined by the base
             <tt>Component</tt> and <tt>Container</tt> classes.
         </p>

         <p>
             Events are often placed into groups that share some common
             characteristics. For example, <tt>Component</tt> defines a set of mouse button events
             that include "mouse down", "mouse up", and "mouse click". Components maintain a list
             of listeners who have registered interest in a particular group of events, and each
             listener is notified, in turn, as events occur.
         </p>

         <p>
             Event listeners implement a listener interface defined for a particular group. For
             example, component mouse listeners implement the ComponentMouseListener interface,
             which defines the following methods:
         </p>

         <p>
             <tt>public void mouseMove(Component component, int x, int y)</tt><br/>
             <tt>public void mouseOver(Component component)</tt><br/>
             <tt>public void mouseOut(Component component)</tt><br/>
         </p>

         <p>
             A caller that implements the <tt>ComponentMouseListener</tt> interface can add itself
             as a listener by calling <tt>Component#getComponentMouseListeners().add()</tt>.
             Conversely, a listener can remove itself via the
             <tt>Component#getComponentMouseButtonListeners().remove()</tt> method. Other event
             listeners are registered and unregistered similarly.
         </p>

         <p>
             <tt>Component</tt> defines the following event listener interfaces that are inherited
             by all component subclasses:
         </p>

         <ul>
             <li>
                 <p>
                     <b>ComponentListener</b> - defines events related to core component properties
                     including location, size, visibility, etc.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentStateListener</b> - defines events related to component enabled and
                     focus state.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentStyleListener</b> - defines events related to component
                     styles.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentDecoratorListener</b> - defines events related to component
                     decorators.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentMouseListener</b> - defines events that are fired when the mouse
                     is positioned over the component.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentMouseButtonListener</b> - defines mouse button events.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentMouseWheelListener</b> - defines mouse wheel events.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentKeyListener</b> - defines events that are fired when the component
                     has the input focus.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentTooltipListener</b> - defines events that are related to component
                     tooltips.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentDataListener</b> - defines events that are fired when component
                     user data changes.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ComponentClassListener</b> - defines events that are fired when class-level
                     component properties change.
                 </p>
             </li>
         </ul>

         <p>
             The <tt>Container</tt> class defines the following additional events that are inherited
             by its subclasses:
         </p>

         <ul>
             <li>
                 <p>
                     <b>ContainerListener</b> - defines events related to core container properties
                     including insertion/removal of components.
                 </p>
             </li>
             <li>
                 <p>
                     <b>ContainerMouseListener</b> - defines events that are fired when the mouse
                     is positioned over the container.
                 </p>
             </li>
         </ul>

         <p>
             Note that both <tt>Component</tt> and <tt>Container</tt> define interfaces related to
             mouse events. Container mouse events are "tunneling" events, and are fired as an event
             is propagated down the container hierarchy, whereas component mouse events are
             "bubbling" events, and are fired as the event moves up the container hierarchy. In
             other words, the parent of a component will receive a container mouse event before the
             component does, but the component will recieve a component mouse event before its
             parent does.
         </p>

         <p>
             Tunneling and bubbling events can be "consumed" by a listener. When a tunneling event
             is consumed, it will not be propagated further down the component hierarchy.
             Conversely, when a bubbling event is consumed, it will not be propagated further up
             the hierarchy. This allows a caller to prevent a descendant from receiving a tunneling
             event or an ancestor from receiving a bubbling event. Note, however, that it does
             not prevent other listeners at the same level in the hierarchy from receiving the event.
             Consuming an event only prevents it from progressing further up or down the hierarchy.
         </p>
     </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to you under the Apache License,
	Version 2.0 (the "License"); you may not use this file except in
	compliance with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<document id="component-and-container">
	<properties>
	<title>Component & Container</title>
	</properties>

	<body>
	<p>
	All Pivot components ultimately extend the base <tt>Component</tt> class. This class,
	in conjunction with the similarly abstract <tt>Container</tt> class, defines the APIs
	that specify where a component will appear on screen, what it will look like, and how a
	user will interact with it.
	</p>

	<h3>Visual and ConstrainedVisual</h3>

	<p><img src="component_and_container/visuals.png"/></p>

	<p>
	As shown in the diagram, <tt>Component</tt> implements the <tt>ConstrainedVisual</tt>
	interface. This interface extends the <tt>Visual</tt> interface, which defines methods
	common to all visual elements in Pivot. The <tt>org.apache.pivot.wtk.media.Image</tt>
	class also implements the <tt>Visual</tt> interface:
	</p>

	<p>
	<tt>public int getWidth()</tt><br/>
	<tt>public int getHeight()</tt><br/>
	<tt>public int getBaseline()</tt><br/>
	<tt>public void paint(Graphics2D graphics)</tt><br/>
	</p>

	<p>
	A visual's size (reported by the <tt>getWidth()</tt> and <tt>getHeight()</tt> methods)
	is specified in "device-independent units". Though these generally map
	one-to-one to actual pixels on an output device, they are not required to do so. This
	allows Pivot applications to be written in a resolution-independent manner, supporting
	UI scaling either for accessibility purposes or for very high resolution output devices.
	</p>

	<p>
	The <tt>getBaseline()</tt> method allows a visual to report a baseline offset, which
	is used by containers that support it to align components to a common baseline.
	The <tt>paint()</tt> method is called as needed to ensure that the visual's current
	state is correctly represented on-screen. For example, a component may need to be
	repainted when an internal value, such as a button's label, has changed, or when some
	part of the component has been exposed due to an overlapping window or other component
	having been moved or resized.
	</p>

	<p>
	<tt>ConstrainedVisual</tt> adds methods to support layout, which is discussed in more
	detail below:
	</p>

	<p>
	<tt>public void setSize(int width, int height)</tt><br/>
	<tt>public int getPreferredWidth(int height)</tt><br/>
	<tt>public int getPreferredHeight(int width)</tt><br/>
	<tt>public Dimensions getPreferredSize()</tt><br/>
	<tt>public int getBaseline(int width, int height)</tt><br/>
	</p>

	<p>
	In addition to <tt>Component</tt>, the <tt>Skin</tt> and <tt>Renderer</tt> interfaces
	also extend <tt>ConstrainedVisual</tt>. In Pivot, a component's "skin" is responsible
	for the visual representation of the component. As a result, <tt>Component</tt>
	delegates the implementation of all <tt>ConstrainedVisual</tt> methods to the skin.
	The skin may, in turn, delegate some renderering responsibility to one or more
	renderers, which are used to paint some components' content (such as a button label or
	a list item); this relationship is represented by the dotted line in the diagram.
	Renderers are often implemented as extensions of the <tt>Component</tt> class, allowing
	the component's implementation of <tt>ConstrainedVisual</tt> to be re-used (and giving
	rise to the notion of renderers as "lightweight components").
	</p>

	<p>
	Components are painted in the order in which they are defined in the parent container's
	component sequence. The component sequence thus defines the "z-order" of the components
	in the container: components are painted in ascending order, allowing higer components
	to overlap lower ones. Z-order is often only noticeable at the window level - individual
	components within an application are generally arranged such that the user can see and
	readily interact with them. This process, called "layout management", is generally
	handled automatically in a Pivot application, and is discussed next.
	</p>

	<h3>Layout</h3>

	<p>
	"Layout management" is the process of automatically determining how components should
	be arranged on screen, as opposed to requiring the the developer to explicitly set
	component size and position. Layout management is performed by all Pivot containers,
	and is the responsibility of a container's skin.
	</p>

	<p>
	<tt>ConstrainedVisual</tt>'s preferred size methods, <tt>getPreferredWidth()</tt>,
	<tt>getPreferredHeight()</tt>, and <tt>getPreferredSize()</tt>, return information
	about the size the visual "wants" to be. This is generally determined based on
	attributes such as font size and border thickness, or, in the case of containers, by
	recursively asking subcomponents about their own preferred sizes. Containers may use
	this information to determine how to arrange their subcomponents during layout.
	</p>

	<p>
	In Pivot, preferred sizes may optionally be constrained by passing a height constraint
	value to <tt>getPreferredWidth()</tt> or a width constraint value to
	<tt>getPreferredHeight()</tt>. This allows components to "wrap" their contents. For
	example, a <tt>Label</tt> component with the "wrapText" style set to <tt>true</tt> will
	report a preferred height that is tall enough to render its entire content by applying
	line break logic using the given width constraint.
	</p>

	<p>
	<tt>ConstrainedVisual</tt> defines an additional signature for <tt>getBaseline()</tt>
	that takes <tt>width</tt> and <tt>height</tt> arguments. This allows a component to
	report a constrained baseline given a possible width and height (for example, a
	label whose content is vertically aligned to bottom will report a different baseline
	than one that is vertically aligned to top when it is given more than its preferred
	height).
	</p>

	<h3>Location and Visibility</h3>

	<p>
	<tt>Component</tt> defines several additional methods that are used by containers
	during layout:
	</p>

	<p>
	<tt>public int getX()</tt><br/>
	<tt>public int getY()</tt><br/>
	<tt>public Point getLocation()</tt><br/>
	<tt>public void setLocation(int x, int y)</tt><br/>
	<tt>public final void setLocation(Point location)</tt><br/>
	</p>

	<p>
	These methods are used to manage a component's location, which is defined as an (x, y)
	coordinate pair that is relative to the origin of its parent container.
	</p>

	<p>
	<tt>public boolean isVisible()</tt><br/>
	<tt>public void setVisible(boolean visible)</tt><br/>
	</p>

	<p>
	These methods manage a component's visibility. A component that is not visible is not
	painted. Layout containers will generally also exclude non-visible components from
	layout.
	</p>

	<p>
	Container skins use the preferred size and visibility values to determine how to
	arrange their subcomponents. They first query the subcomponents for the preferred
	values, and then use these values to set the components' actual size and location. As
	a result, callers should generally not invoke the methods that set these properties
	directly, since the container is likely to override any values set by the caller
	during layout.
	</p>

	<p>
	It is important to note that containers are not required to respect a component's
	preferred size or visibility. For example, <tt>CardPane</tt> sets the size of its
	subcomponent to the maximum preferred size of all its child components, and
	<tt>TablePane</tt> sets the size of its components based on the width of its rows and
	columns. However, most respect at least one, and many respect both.
	</p>

	<h3>Disabled Components</h3>

	<p>
	A component that is "enabled" is currently capable of receiving user input. A component
	may be "disabled" to prevent it from receiving input from the user. For example,
	buttons are often disabled to prevent a user from initiating an action that would not
	be appropriate for the current state of the application. Most components display a
	disabled state to indicate to the user that interaction is currently forbidden.
	</p>

	<p>
	Note that, while a user is prevented from interacting with a disabled component,
	programmatic interaction is still allowed. For example, it is still valid to set the
	selection state of a disabled list view component in code, even though the user cannot
	click on an item in the list to change the list's selection state.
	</p>

	<p>
	Also note that disabling a container will prevent all child components of the container
	from receiving input as well. Thus, there is no need to propagate the enabled state of
	a container down to its children. When a component is either disabled or one of its
	ancestors is disabled, it is said to be "blocked".
	</p>

	<h3>Focus Management</h3>

	<p>
	A component that is eligible to receive keyboard input is said to have the "input
	focus", or simply "focus". Only one component is allowed to have the focus at any given
	time. Not all components are focusable, though many are, including text inputs, buttons,
	and list views, among others. It is up to a component's skin to decide whether or not it
	is capable of receiving focus. In order to receive the focus, a component (and its
	ancestry) must be enabled, visible, and focusable.
	</p>

	<p>
	Generally, a focusable component will paint a slightly different state when it has the
	focus as a visual cue to the user. For example, a text input may show a blinking
	cursor, while a button might draw a dotted line around its label.
	</p>

	<p>
	Clicking on a component with the mouse will usually transfer focus to that component.
	However, focus can also be transferred between using the Tab (or Shift-Tab) key. This
	is called "focus traversal". Each container provides a "focus traversal policy" that
	defines how focus management is performed within the container. By default, most
	containers use a default traversal policy that simply traverses child components in the
	order in which they appear in the container's component sequence. However, windows use
	a traversal policy that ensures that focus is never transferred out of the window
	itself; tab panes employ a similar policy. However, callers and skin developers are
	free to override these defaults and can install a custom traversal policy on any
	container.
	</p>

	<h3>Cursors</h3>

	<p>
	A component's skin will generally ensure that an appropriate cursor is displayed when
	the mouse is over the component. However, a caller may customize the component's cursor
	using the <tt>setCursor()</tt> method of <tt>Component</tt>. Valid cursor values are
	defined by the <tt>Cursor</tt> enum.
	</p>

	<h3>Styles</h3>

	<p>
	Styles are a means of customizing a component's appearance. They are implemented as
	named properties exposed by a skin via the component. For example, a label skin might
	define styles such as "font", "color", and "textDecoration", and a list view skin might
	define styles including "font", "color", "selectionColor" and
	"selectionBackgroundColor". These properties correspond directly to the Java bean
	getters and setters defined by the skin class.
	</p>

	<p>
	By design, skins are programmatically hidden from the developer; a caller interacts
	with a skin's styles via the component's style collection, an instance of
	<tt>org.apache.pivot.wtk.Component.StyleDictionary</tt> returned by
	<tt>Component#getStyles()</tt>:
	</p>

	<p>
	<tt>public Object get(String key) - returns the value of a given style</tt><br/>
	<tt>public Object put(String key, Object value) - sets a style value</tt><br/>
	</p>

	<p>
	This facilitates a loose, flexible coupling between an application and a skin: an
	application need not be tied to a particular skin implementation, and skin developers
	are free to add or remove styles without the risk of breaking existing applications.
	However, it becomes the responsibility of the caller to be aware of the styles
	supported by the current skin. Attempting to set a non-existent style value will
	simply generate a warning, but passing an invalid type for a valid style will throw
	an exception.
	</p>

	<p>
	Style values can be set in BXML using the "styles" attribute. The value of this
	attribute is a JSON-formatted string representing the style values to be applied to
	the component after it is constructed. For example, the following attribute applied to
	the Label element would produce a bold, 24-point Arial label with red text:
	</p>

	<p>
	<tt>styles="{font:'Arial bold 24', color:'#ff0000'}"</tt><br/>
	</p>

	<p>
	Styles can also be set using a <tt><styles></tt> sub-element:
	</p>

	<p>
	<tt><styles font="Arial bold 24" color="#ff0000"></tt><br/>
	</p>

	<p>
	Finally, styles can be applied via CSS-like stylesheets. Both typed and untyped
	selectors are supported. For example:
	</p>

	<source type="jscript">
	{ Button: {
	color: "#aa0000"
	},

	RadioButton: {
	color: "#00aa00"
	},

	"org.apache.pivot.wtk.PushButton": {
	color: "#0000aa"
	},

	heading: {
	font: {
	size: "120%",
	bold: true
	},

	color: "#000000"
	},

	subHeading: {
	font: {
	size: "110%",
	italic: true
	},

	color: "#666666"
	}
	}
	</source>

	<h3>Attributes</h3>

	<p>
	Attributes are a means of attaching container-specific properties to a component.
	Attributes are typed values defined by containers that support or require them. For
	example, <tt>TabPane</tt> defines a "label" attribute that allows a caller to specify
	the text that is displayed on the tab button for the component; <tt>TablePane</tt>
	defines a "rowSpan" attribute that determines how a cell is laid out. Attributes
	effectively allow a caller to "tag" a component with values that are relevant only to
	its parent container (and the container's skin).
	</p>

	<p>
	Callers can set attribute values programmatically using a static setter method of
	the <tt>Container</tt> subclass (e.g. <tt>TabPane#setLabel(Component, String)</tt>).
	Alternatively, attributes can be specified in BXML. For example, the sub-elements of
	a <tt>TabPane</tt> can provide a <tt>TabPane.label</tt> attribute to specify the value
	that should be used as the text label for that component.
	</p>

	<h3>Events</h3>

	<p>
	In GUI programming, the term "event" generally refers to a notification sent by a
	program in response to some triggering action. The trigger may have been input from
	the user, a response from a remote server, or a change in some internal state.
	</p>

	<p>
	Pivot components rely heavily on events, both to respond to change notifications from
	data models or other components and to notify external listeners of changes to their
	own states. Each concrete component class defines a set of events specific to its own
	implementation, and all components inherit a set of common events defined by the base
	<tt>Component</tt> and <tt>Container</tt> classes.
	</p>

	<p>
	Events are often placed into groups that share some common
	characteristics. For example, <tt>Component</tt> defines a set of mouse button events
	that include "mouse down", "mouse up", and "mouse click". Components maintain a list
	of listeners who have registered interest in a particular group of events, and each
	listener is notified, in turn, as events occur.
	</p>

	<p>
	Event listeners implement a listener interface defined for a particular group. For
	example, component mouse listeners implement the ComponentMouseListener interface,
	which defines the following methods:
	</p>

	<p>
	<tt>public void mouseMove(Component component, int x, int y)</tt><br/>
	<tt>public void mouseOver(Component component)</tt><br/>
	<tt>public void mouseOut(Component component)</tt><br/>
	</p>

	<p>
	A caller that implements the <tt>ComponentMouseListener</tt> interface can add itself
	as a listener by calling <tt>Component#getComponentMouseListeners().add()</tt>.
	Conversely, a listener can remove itself via the
	<tt>Component#getComponentMouseButtonListeners().remove()</tt> method. Other event
	listeners are registered and unregistered similarly.
	</p>

	<p>
	<tt>Component</tt> defines the following event listener interfaces that are inherited
	by all component subclasses:
	</p>

	<ul>
	<li>
	<p>
	<b>ComponentListener</b> - defines events related to core component properties
	including location, size, visibility, etc.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentStateListener</b> - defines events related to component enabled and
	focus state.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentStyleListener</b> - defines events related to component
	styles.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentDecoratorListener</b> - defines events related to component
	decorators.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentMouseListener</b> - defines events that are fired when the mouse
	is positioned over the component.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentMouseButtonListener</b> - defines mouse button events.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentMouseWheelListener</b> - defines mouse wheel events.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentKeyListener</b> - defines events that are fired when the component
	has the input focus.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentTooltipListener</b> - defines events that are related to component
	tooltips.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentDataListener</b> - defines events that are fired when component
	user data changes.
	</p>
	</li>
	<li>
	<p>
	<b>ComponentClassListener</b> - defines events that are fired when class-level
	component properties change.
	</p>
	</li>
	</ul>

	<p>
	The <tt>Container</tt> class defines the following additional events that are inherited
	by its subclasses:
	</p>

	<ul>
	<li>
	<p>
	<b>ContainerListener</b> - defines events related to core container properties
	including insertion/removal of components.
	</p>
	</li>
	<li>
	<p>
	<b>ContainerMouseListener</b> - defines events that are fired when the mouse
	is positioned over the container.
	</p>
	</li>
	</ul>

	<p>
	Note that both <tt>Component</tt> and <tt>Container</tt> define interfaces related to
	mouse events. Container mouse events are "tunneling" events, and are fired as an event
	is propagated down the container hierarchy, whereas component mouse events are
	"bubbling" events, and are fired as the event moves up the container hierarchy. In
	other words, the parent of a component will receive a container mouse event before the
	component does, but the component will recieve a component mouse event before its
	parent does.
	</p>

	<p>
	Tunneling and bubbling events can be "consumed" by a listener. When a tunneling event
	is consumed, it will not be propagated further down the component hierarchy.
	Conversely, when a bubbling event is consumed, it will not be propagated further up
	the hierarchy. This allows a caller to prevent a descendant from receiving a tunneling
	event or an ancestor from receiving a bubbling event. Note, however, that it does
	not prevent other listeners at the same level in the hierarchy from receiving the event.
	Consuming an event only prevents it from progressing further up or down the hierarchy.
	</p>
	</body>
	</document>