You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pivot.apache.org by gb...@apache.org on 2009/12/10 20:48:14 UTC
svn commit: r889388 - in /incubator/pivot/trunk/tutorials:
src/org/apache/pivot/tutorials/navigation/ www/
Author: gbrown
Date: Thu Dec 10 19:48:13 2009
New Revision: 889388
URL: http://svn.apache.org/viewvc?rev=889388&view=rev
Log:
Continue migrating tutorial content to XML.
Removed:
incubator/pivot/trunk/tutorials/src/org/apache/pivot/tutorials/navigation/Panoramas.java
incubator/pivot/trunk/tutorials/www/meters.html
incubator/pivot/trunk/tutorials/www/navigation_containers.html
incubator/pivot/trunk/tutorials/www/panoramas.html
incubator/pivot/trunk/tutorials/www/platform_overview.html
Modified:
incubator/pivot/trunk/tutorials/www/meters.xml
incubator/pivot/trunk/tutorials/www/navigation-containers.xml
incubator/pivot/trunk/tutorials/www/panels.xml
incubator/pivot/trunk/tutorials/www/panoramas.xml
incubator/pivot/trunk/tutorials/www/platform-overview.xml
Modified: incubator/pivot/trunk/tutorials/www/meters.xml
URL: http://svn.apache.org/viewvc/incubator/pivot/trunk/tutorials/www/meters.xml?rev=889388&r1=889387&r2=889388&view=diff
==============================================================================
--- incubator/pivot/trunk/tutorials/www/meters.xml (original)
+++ incubator/pivot/trunk/tutorials/www/meters.xml Thu Dec 10 19:48:13 2009
@@ -22,5 +22,205 @@
</properties>
<body>
+ <p>
+ Meters are used to report progress to the user, generally the completion percentage of
+ a background task such as a file load operation. An example is shown below. Clicking
+ the Start button initiates a background task that simulates a long-running operation.
+ Periodically, the task updates the meter to reflect its progress:
+ </p>
+
+ <application class="org.apache.pivot.tutorials.progress.Meters"
+ width="300" height="100">
+ <libraries>
+ <library>core</library>
+ <library>wtk</library>
+ <library>wtk-terra</library>
+ <library>tutorials</library>
+ </libraries>
+ </application>
+
+ <p>
+ The WTKX source for the example is shown below:
+ </p>
+
+ <source type="xml" location="org/apache/pivot/tutorials/progress/meters.wtkx">
+ <![CDATA[
+ <Window title="Meters" maximized="true"
+ xmlns:wtkx="http://pivot.apache.org/wtkx"
+ xmlns="org.apache.pivot.wtk">
+ <content>
+ <TablePane>
+ <columns>
+ <TablePane.Column width="1*"/>
+ </columns>
+ <rows>
+ <TablePane.Row height="1*">
+ <Border styles="{padding:2}">
+ <content>
+ <BoxPane styles="{horizontalAlignment:'center', verticalAlignment:'center'}">
+ <Label text="Progress:"/>
+ <Meter wtkx:id="meter" preferredWidth="200" preferredHeight="16"/>
+ </BoxPane>
+ </content>
+ </Border>
+ </TablePane.Row>
+ <TablePane.Row height="-1">
+ <BoxPane styles="{horizontalAlignment:'center', padding:6}">
+ <PushButton wtkx:id="progressButton" styles="{minimumAspectRatio:3}"/>
+ </BoxPane>
+ </TablePane.Row>
+ </rows>
+ </TablePane>
+ </content>
+ </Window>
+ ]]>
+ </source>
+
+ <p>
+ The Java source is as follows. The main application class defines an inner class that
+ extends the <tt>pivot.util.concurrent.Task</tt> class to simulate a background
+ operation. This task simply sleeps for 100ms at a time and updates the meter when it
+ wakes up to reflect the current count. Since all UI updates must be performed on the
+ UI thread, the task queues a callback to set the meter's percent complete; a
+ <tt>pivot.wtk.TaskAdapter</tt> is used to process the task notifications for the same
+ reason:
+ </p>
+
+ <source type="java" location="org/apache/pivot/tutorials/progress/Meters.java">
+ <![CDATA[
+ package org.apache.pivot.tutorials.progress;
+
+ import org.apache.pivot.collections.Map;
+ import org.apache.pivot.util.concurrent.Task;
+ import org.apache.pivot.util.concurrent.TaskExecutionException;
+ import org.apache.pivot.util.concurrent.TaskListener;
+ import org.apache.pivot.wtk.Application;
+ import org.apache.pivot.wtk.ApplicationContext;
+ import org.apache.pivot.wtk.Button;
+ import org.apache.pivot.wtk.ButtonPressListener;
+ import org.apache.pivot.wtk.DesktopApplicationContext;
+ import org.apache.pivot.wtk.Display;
+ import org.apache.pivot.wtk.Meter;
+ import org.apache.pivot.wtk.PushButton;
+ import org.apache.pivot.wtk.TaskAdapter;
+ import org.apache.pivot.wtk.Window;
+ import org.apache.pivot.wtkx.WTKXSerializer;
+
+ public class Meters implements Application {
+ public class SampleTask extends Task<Void> {
+ private int percentage = 0;
+
+ @Override
+ public Void execute() throws TaskExecutionException {
+ // Simulate a long-running operation
+ percentage = 0;
+
+ while (percentage < 100
+ && !abort) {
+ try {
+ Thread.sleep(100);
+ percentage++;
+
+ // Update the meter on the UI thread
+ ApplicationContext.queueCallback(new Runnable() {
+ @Override
+ public void run() {
+ meter.setPercentage((double)percentage / 100);
+ }
+ });
+ } catch(InterruptedException exception) {
+ throw new TaskExecutionException(exception);
+ }
+ }
+
+ return null;
+ }
+ }
+
+ private Window window = null;
+ private Meter meter = null;
+ private PushButton progressButton = null;
+
+ private SampleTask sampleTask = null;
+
+ @Override
+ public void startup(Display display, Map<String, String> properties)
+ throws Exception {
+ WTKXSerializer wtkxSerializer = new WTKXSerializer();
+ window = (Window)wtkxSerializer.readObject(this, "meters.wtkx");
+ meter = (Meter)wtkxSerializer.get("meter");
+ progressButton = (PushButton)wtkxSerializer.get("progressButton");
+
+ progressButton.getButtonPressListeners().add(new ButtonPressListener() {
+ @Override
+ public void buttonPressed(Button button) {
+ if (sampleTask == null) {
+ // Create and start the simulated task; wrap it in a
+ // task adapter so the result handlers are called on the
+ // UI thread
+ sampleTask = new SampleTask();
+ sampleTask.execute(new TaskAdapter<Void>(new TaskListener<Void>() {
+ @Override
+ public void taskExecuted(Task<Void> task) {
+ reset();
+ }
+
+ @Override
+ public void executeFailed(Task<Void> task) {
+ reset();
+ }
+
+ private void reset() {
+ // Reset the meter and button
+ sampleTask = null;
+ meter.setPercentage(0);
+ updateProgressButton();
+ }
+ }));
+ } else {
+ // Cancel the task
+ sampleTask.abort();
+ }
+
+ updateProgressButton();
+ }
+ });
+
+ updateProgressButton();
+
+ window.open(display);
+ }
+
+ @Override
+ public boolean shutdown(boolean optional) {
+ if (window != null) {
+ window.close();
+ }
+
+ return false;
+ }
+
+ @Override
+ public void suspend() {
+ }
+
+ @Override
+ public void resume() {
+ }
+
+ private void updateProgressButton() {
+ if (sampleTask == null) {
+ progressButton.setButtonData("Start");
+ } else {
+ progressButton.setButtonData("Cancel");
+ }
+ }
+
+ public static void main(String[] args) {
+ DesktopApplicationContext.main(Meters.class, args);
+ }
+ }
+ ]]>
+ </source>
</body>
</document>
Modified: incubator/pivot/trunk/tutorials/www/navigation-containers.xml
URL: http://svn.apache.org/viewvc/incubator/pivot/trunk/tutorials/www/navigation-containers.xml?rev=889388&r1=889387&r2=889388&view=diff
==============================================================================
--- incubator/pivot/trunk/tutorials/www/navigation-containers.xml (original)
+++ incubator/pivot/trunk/tutorials/www/navigation-containers.xml Thu Dec 10 19:48:13 2009
@@ -22,5 +22,66 @@
</properties>
<body>
+ <p>
+ Navigation containers are used to maximize screen real estate, showing or hiding their
+ children as needed. Navigation containers include:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <a href="card-panes.html"><b>CardPane</b></a> - A simple "card stack" of
+ components, only one of which is visible at a time.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="tab-panes.html"><b>TabPane</b></a> - Similar to <tt>CardPane</tt> but
+ with built-in "tabs" for navigation; may optionally be "collapsed" such that
+ only the tab buttons show.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="accordions.html"><b>Accordion</b></a> - Similar to <tt>TabPane</tt>,
+ but subcomponents are presented like the folds of an accordion, with headers
+ for navigating between panels.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="expanders.html"><b>Expander</b></a> - Similar to a border but
+ collapsible such that only the title shows.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="rollups.html"><b>Rollup</b></a> - Similar to <tt>Expander</tt> but
+ supports a configurable "header" component; when collapsed, only the header is
+ visible. Can be nested to create the appearance of a "tree" structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ <a href="viewports.html"><b><i>Viewport</i></b></a> - Abstract base class for a
+ scrollable region. Sublcasses of <tt>Viewport</tt> include:
+ <ul>
+ <li>
+ <a href="scroll_panes.html"><b>ScrollPane</b></a> - A scrollable area
+ with optional vertical and horizontal scroll bars as well as row and
+ column headers.
+ </li>
+ <li>
+ <a href="panoramas.html"><b>Panorama</b></a> - A scrollable area with
+ optional up/down/left/right arrows.
+ </li>
+ </ul>
+ </p>
+ </li>
+ </ul>
+
+ <p>
+ Each of these are discussed in detail in the following sections.
+ </p>
</body>
</document>
Modified: incubator/pivot/trunk/tutorials/www/panels.xml
URL: http://svn.apache.org/viewvc/incubator/pivot/trunk/tutorials/www/panels.xml?rev=889388&r1=889387&r2=889388&view=diff
==============================================================================
--- incubator/pivot/trunk/tutorials/www/panels.xml (original)
+++ incubator/pivot/trunk/tutorials/www/panels.xml Thu Dec 10 19:48:13 2009
@@ -22,5 +22,85 @@
</properties>
<body>
+ <p>
+ Although Pivot's automatic layout management features are convenient, sometimes it is
+ preferable to perform layout manually (for example, when aligning components to an
+ existing graphical asset being used as a background image). The <tt>Panel</tt>
+ container can be used for this purpose. <tt>Panel</tt> performs no layout or preferred
+ size calculations itself, giving the application complete control over components' size
+ and position.
+ </p>
+
+ <p>
+ The following example demonstrates use of the <tt>Panel</tt> container. It defines a
+ stack pane that contains an <tt>ImageView</tt> and a <tt>Panel</tt>. The image view
+ contains a drawing that defines an absolutely positioned rectangle. The buttons in
+ the <tt>Panel</tt>, which sits on top of the <tt>ImageView</tt>, are absolutely
+ positioned such that they appear within the bounds of the rectangle:
+ </p>
+
+ <application class="org.apache.pivot.wtk.ScriptApplication"
+ width="400" height="320">
+ <libraries>
+ <library>core</library>
+ <library>wtk</library>
+ <library>wtk-terra</library>
+ <library>tutorials</library>
+ </libraries>
+ <startup-properties>
+ <src>org/apache/pivot/tutorials/layout/panels.wtkx</src>
+ </startup-properties>
+ </application>
+
+ <p>
+ The WTKX source code for this example is as follows. The <tt>Drawing</tt> and
+ <tt>Rectangle</tt> classes are discussed in more detail in the
+ <a href="drawings.html">Drawing</a> section:
+ </p>
+
+ <source type="xml" location="org/apache/pivot/tutorials/layout/panels.wtkx">
+ <![CDATA[
+ <Window title="Panels" maximized="true"
+ xmlns:wtkx="http://pivot.apache.org/wtkx"
+ xmlns:media="org.apache.pivot.wtk.media"
+ xmlns:drawing="org.apache.pivot.wtk.media.drawing"
+ xmlns="org.apache.pivot.wtk">
+ <content>
+ <StackPane>
+ <ImageView styles="{horizontalAlignment:'left', verticalAlignment:'top'}">
+ <image>
+ <media:Drawing>
+ <canvas>
+ <drawing:Canvas>
+ <drawing:Rectangle x="20" y="20" width="320" height="240"
+ fill="{paintType:'gradient', startX:0, startY:0, startColor:'#4444ff',
+ endX:320, endY:240, endColor:'#000044'}"
+ stroke="#0000aa" strokeThickness="4"
+ cornerRadius="10"/>
+ </drawing:Canvas>
+ </canvas>
+ </media:Drawing>
+ </image>
+ </ImageView>
+ <Panel>
+ <PushButton buttonData="Button 1"
+ styles="{color:'#ffffff', backgroundColor:'#000066', borderColor:'#0000dd'}"
+ x="30" y="30" width="120" height="24"/>
+ <PushButton buttonData="Button 2"
+ styles="{color:'#ffffff', backgroundColor:'#000066', borderColor:'#0000dd'}"
+ x="30" y="60" width="120" height="24"/>
+ <PushButton buttonData="Button 3"
+ styles="{color:'#ffffff', backgroundColor:'#000066', borderColor:'#0000dd'}"
+ x="30" y="90" width="120" height="24"/>
+ </Panel>
+ </StackPane>
+ </content>
+ </Window>
+ ]]>
+ </source>
+
+ <p>
+ Since this example contains no logic, there is no associated Java source.
+ </p>
</body>
</document>
Modified: incubator/pivot/trunk/tutorials/www/panoramas.xml
URL: http://svn.apache.org/viewvc/incubator/pivot/trunk/tutorials/www/panoramas.xml?rev=889388&r1=889387&r2=889388&view=diff
==============================================================================
--- incubator/pivot/trunk/tutorials/www/panoramas.xml (original)
+++ incubator/pivot/trunk/tutorials/www/panoramas.xml Thu Dec 10 19:48:13 2009
@@ -22,5 +22,55 @@
</properties>
<body>
+ <p>
+ Panoramas scroll via four directional scroll arrows shown at the top, left, bottom, or
+ right as needed. They are not as common as scroll panes in application development, but
+ are used by other components such as <tt>ListButton</tt> and <tt>MenuPopup</tt> to
+ present long lists of items.
+ </p>
+
+ <p>
+ The following example demonstrates the <tt>Panorama</tt> component. It is identical to
+ the previous example except that it uses a panorama instead of a scroll pane:
+ </p>
+
+ <application class="org.apache.pivot.wtk.ScriptApplication"
+ width="400" height="320">
+ <libraries>
+ <library>core</library>
+ <library>wtk</library>
+ <library>wtk-terra</library>
+ <library>tutorials</library>
+ </libraries>
+ <startup-properties>
+ <src>org/apache/pivot/tutorials/navigation/panoramas.wtkx</src>
+ </startup-properties>
+ </application>
+
+
+ <source type="xml" location="org/apache/pivot/tutorials/navigation/panoramas.wtkx">
+ <![CDATA[
+ <Window title="Panoramas" maximized="true"
+ xmlns:wtkx="http://pivot.apache.org/wtkx"
+ xmlns="org.apache.pivot.wtk">
+ <content>
+ <Border styles="{color:10}">
+ <content>
+ <Panorama styles="{buttonColor:'0xffffffff', buttonBackgroundColor:'0x00000044'}">
+ <view>
+ <ImageView image="org/apache/pivot/tutorials/IMG_1147.jpg"
+ tooltipText="Pemaquid Point Lighthouse, Bristol ME"/>
+ </view>
+ </Panorama>
+ </content>
+ </Border>
+ </content>
+ </Window>
+ ]]>
+ </source>
+
+ <p>
+ Since this example contains no logic, there is no associated Java source.
+ </p>
</body>
</document>
Modified: incubator/pivot/trunk/tutorials/www/platform-overview.xml
URL: http://svn.apache.org/viewvc/incubator/pivot/trunk/tutorials/www/platform-overview.xml?rev=889388&r1=889387&r2=889388&view=diff
==============================================================================
--- incubator/pivot/trunk/tutorials/www/platform-overview.xml (original)
+++ incubator/pivot/trunk/tutorials/www/platform-overview.xml Thu Dec 10 19:48:13 2009
@@ -19,8 +19,846 @@
<document id="platform-overview">
<properties>
<title>Platform Overview</title>
+ <style>
+ table {
+ border:solid 1px #999999;
+ border-collapse:collapse;
+ }
+
+ td {
+ border:solid 1px #999999;
+ padding:3px;
+ }
+
+ td.heading {
+ font-weight:bold;
+ }
+ </style>
</properties>
<body>
+ <p>
+ Like most modern development platforms, Pivot provides a comprehensive set of
+ foundation classes that together comprise a "framework". These classes form the
+ building blocks upon which more complex and sophisticated applications can be built.
+ </p>
+
+ <p>
+ Pivot classes are grouped into the following primary categories:
+ </p>
+
+ <ul>
+ <li>
+ <b>Core</b> - A set of common, non-UI classes.
+ </li>
+ <li>
+ <b>WTK</b> - Classes for user interface development, including windows, dialogs,
+ buttons, lists, text input, layout, drag and drop, XML markup, etc.
+ </li>
+ <li>
+ <b>Web</b> - Classes to facilitate communicate with remote data services.
+ </li>
+ <li>
+ <b>Charts</b> - Classes for adding interactive charting capabilities to Pivot
+ applications.
+ </li>
+ <li>
+ <b>Tools</b> - Development tools and utility applications.
+ </li>
+ </ul>
+
+ <p>
+ The classes in each category are packaged and distributed in a corresponding library or
+ set of libraries:
+ </p>
+
+ <h3>pivot-core-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.beans</tt> - Classes that provide access to the Java bean
+ properties of an object via a dictionary interface.
+ </li>
+ <li>
+ <tt>org.apache.pivot.collections</tt> - A set of classes and interfaces that serve
+ as generic collections as well as the data model for UI components.
+ </li>
+ <li>
+ <tt>org.apache.pivot.collections.adapter</tt> - A set of collection implementations
+ that are backed by java.util collections.
+ </li>
+ <li>
+ <tt>org.apache.pivot.collections.concurrent</tt> - A set of thread-safe collection
+ implementations.
+ </li>
+ <li>
+ <tt>org.apache.pivot.collections.immutable</tt> - A set of read-only collection
+ implementations.
+ </li>
+ <li>
+ <tt>org.apache.pivot.io</tt> - Classes related to input/output operations.
+ </li>
+ <li>
+ <tt>org.apache.pivot.serialization</tt> - Classes for use in data serialization.
+ </li>
+ <li>
+ <tt>org.apache.pivot.text</tt> - Classes for working with text.
+ </li>
+ <li>
+ <tt>org.apache.pivot.util</tt> - A collection of common utility classes.
+ </li>
+ <li>
+ <tt>org.apache.pivot.util.concurrent</tt> - Classes to simplify the execution of
+ background tasks.
+ </li>
+ <li>
+ <tt>org.apache.pivot.xml</tt> - Classes for working with XML data.
+ </li>
+ </ul>
+
+ <h3>pivot-wtk-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.wtk</tt> - Classes that define the structure and behavior of
+ WTK user interface components.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.content</tt> - Classes representing component data, such
+ as list items or table rows.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.effects</tt> - Classes supporting visual effects such as
+ blurs, reflections, and drop shadows.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.effects.easing</tt> - Contains "easing" operations for
+ producing natural-looking transitions. Based on easing equations developed by
+ <a href="http://robertpenner.com/">Robert Penner</a>.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.media</tt> - Classes to enable multimedia support in
+ Pivot applications.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.media.drawing</tt> - Classes for constructing vector-based
+ drawings.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.skin</tt> - Contains common skins and abstract base
+ classes for theme-specific skins.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.text</tt> - Contains classes representing a text object
+ model.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtk.text.validation</tt> - Provides classes for validating
+ user-entered text.
+ </li>
+ <li>
+ <tt>org.apache.pivot.wtkx</tt> - Provides support for loading WTK components from
+ XML.
+ </li>
+ </ul>
+
+ <h3>pivot-wtk-terra-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.wtk.skin.terra</tt> - Defines skin classes for the default
+ "Terra" theme.
+ </li>
+ </ul>
+
+ <h3>pivot-web-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.web</tt> - Classes for communicating with HTTP-based web
+ services.
+ </li>
+ </ul>
+
+ <h3>pivot-web-server-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.web.server</tt> - Classes to facilitate access to and
+ development of web query services.
+ </li>
+ </ul>
+
+ <h3>pivot-charts-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.charts</tt> - A collection of components for use in charting
+ applications.
+ </li>
+ <li>
+ <tt>org.apache.pivot.charts.content</tt> - Classes representing chart data.
+ </li>
+ </ul>
+
+ <h3>pivot-tools-[version].jar</h3>
+
+ <ul>
+ <li>
+ <tt>org.apache.pivot.tools.json</tt> - Utility applications for working with JSON
+ data.
+ </li>
+ <li>
+ <tt>org.apache.pivot.tools.wtk</tt> - GUI components for use in tool applications.
+ </li>
+ <li>
+ <tt>org.apache.pivot.tools.xml</tt> - Utility applications for working with XML
+ data.
+ </li>
+ </ul>
+
+ <p>
+ Most of Pivot's classes live in the WTK libraries.
+ </p>
+
+ <h2>Architecture</h2>
+
+ <p>
+ The design of WTK is based on the
+ <a href="http://en.wikipedia.org/wiki/Model-view-controller">model-view-controller</a>
+ architecture employed by many current user interface toolkits. In WTK, model data is
+ represented by the generic collection classes defined in the Core library (most
+ commonly <tt>org.apache.pivot.collections.List</tt> and
+ <tt>org.apache.pivot.collections.Map</tt>). The component classes discussed in the
+ next section represent the controller, which acts as the intermediary between the model
+ data and the component's "skin", the MVC view.
+ </p>
+
+ <p>
+ The skin defines the actual appearance of the component, as a component has no inherent
+ visual representation. The skin also defines how the component responds to user input
+ including keyboard and mouse events. Components may have multiple skins (though only a
+ single skin can be installed on any component instance). However, the existence of the
+ skin should be effectively transparent to most developers, as skins do not expose any
+ public API. All interaction with the skin takes place via the skin's component.
+ </p>
+
+ <p>
+ Skins can be "styled" in a manner similar to CSS. Through the component, a skin may
+ expose a set of style properties such as "color" and "font" that a user can change to
+ achieve a custom application appearance without having to write a new skin. By default,
+ all components use the skin classes defined by the Terra look and feel. The skins in
+ this package provide considerable flexibility in setting style properties. Almost every
+ aspect of a Terra skin's appearance can be varied via a style property. Terra also
+ provides customizable "color schemes" that allow a designer to easily replace the
+ color palette for an entire application.
+ </p>
+
+ <p>
+ The appearance of some components can be further customized using "renderers", which
+ are essentially "lightweight components" used to paint the content of the actual
+ component. For example, WTK buttons allow a caller to define the renderer used to
+ paint the button's data, and list views support customized painting of list items via
+ a renderer. Renderers allow large collections of data to be presented very efficiently,
+ as the renderer is used to "rubber stamp" the content, instead of creating an actual
+ component instance for each data element, which would require more memory and processor
+ time.
+ </p>
+
+ <p>
+ Additionally, using renderers, component content is painted the same regardless of the
+ skin that is currently applied. This allows applications to present information
+ consistently as skins are updated or new skins are released.
+ </p>
+
+ <p>
+ Skins and renderers use the Java2D API to draw themselves. See the
+ <a href="http://java.sun.com/docs/books/tutorial/2d/index.html">Java2D Tutorial</a>
+ for more information on Java2D.
+ </p>
+
+ <h3>Class Hierarchy</h3>
+
+ <p>
+ The following diagram shows the WTK component class structure:
+ </p>
+
+ <p><img src="platform_overview/wtk_classes-small.png"/></p>
+ <p class="caption">WTK class hierarchy
+ (<a href="platform_overview/wtk_classes-large.png">large version</a>).</p>
+
+ <p>
+ As shown in the diagram, all WTK components extend an abstract base class called
+ <tt>Component</tt>. Some classes extend <tt>Component</tt> directly, and others extend
+ another abstract class named <tt>Container</tt> that itself extends <tt>Component</tt>.
+ Non-container components are used to present data, collect user input, or both.
+ Container components, as their name implies, contain other components, creating a
+ component hierarchy. Containers serve to arrange and present their child components.
+ </p>
+
+ <p>
+ The root of the container hierarchy is the "display", represented by an instance of
+ the <tt>Display</tt> class. The only allowed direct descendants the display are the
+ window classes, which act as entry points into the user interface. Window classes can
+ contain any type of component except other windows and the display itself. Windows
+ also have an optional owner; owned windows always remain on top of their owner and are
+ automatically hidden when their owner is hidden.
+ </p>
+
+ <p>
+ The window classes include the following types:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <b>Window</b> - Base window class; it is not abstract and is the most basic
+ means by which content may be placed on the screen. It simply provides an
+ undecorated region in which other components may be placed.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Frame</b> - A window with a title bar and border for dragging and resizing.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Dialog</b> - A frame that is generally used for collecting user input
+ (engaging in a "dialog" with the user); may optionally be "modal", blocking
+ input to its owner.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Alert</b> - A dialog that is generally used to present brief notifications
+ to the user.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Sheet</b> - A window that, like a dialog, is generally used for collecting
+ user input; however, unlike dialogs, sheets always have an owner, and are
+ always modal over the owner's client area.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Prompt</b> - A sheet that is generally used to present brief notifications
+ to the user; the sheet equivalent of <tt>Alert</tt>.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>MenuPopup</b> - A "popup" window that is used to present a menu to the user.
+ It can be used stand-alone as a context menu, but is also used by other
+ components including <tt>MenuBar</tt> and <tt>MenuButton</tt>.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Palette</b> - A floating tool palette window.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>FileBrowserSheet</b> - A sheet that allows the user to browse the local file
+ system.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Tooltip</b> - A small, popup-like window that disappears as soon as the user
+ moves the mouse.
+ </p>
+ </li>
+ </ul>
+
+ <p>
+ Below is an example of a Pivot dialog:
+ </p>
+
+ <p><img src="platform_overview/dialog.png"/></p>
+ <p class="caption">A Pivot dialog.</p>
+
+ <h3>Containers</h3>
+
+ <p>
+ Other Pivot containers can be loosely grouped into three categories: layout,
+ navigation, and composite.
+ </p>
+
+ <h4>Layout Containers</h4>
+
+ <p>
+ Layout containers are used primarily to arrange other components on the screen. Layout
+ containers include:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <b>FlowPane</b> - Container that arranges components in a horizontal line,
+ wrapping when contents don't fit on a single line.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>BoxPane</b> - Container that arranges components in a line, either
+ vertically or horizontally.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TablePane</b> - A container that lays out its children in a two-dimensional
+ table structure, optionally spanning table cells.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>GridPane</b> - Similar to TablePane, but without spanning cells and where
+ each cell is the same size.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Border</b> - A container with an optional title that draws a border around
+ a single content component.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>StackPane</b> - Arranges components in layers, like a stack of
+ transparencies.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>SplitPane</b> - Provides a draggable divider between two components
+ allowing a user to dynamically change the size of each; may be horizontal or
+ vertical.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Form</b> - Arranges components in a "form" layout with labels to the left
+ and optional flag messages (e.g. to alert a user to input errors) to the
+ right.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Panel</b> - A container that performs no layout, allowing the application
+ to specify absolute component positions and sizes.
+ </p>
+ </li>
+ </ul>
+
+ <h4>Navigation Containers</h4>
+
+ <p>
+ Navigation containers are used to maximize screen real estate, showing or hiding their
+ children as needed. Navigation containers include:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <b>CardPane</b> - A simple "card stack" of components, only one of which is
+ visible at a time.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TabPane</b> - Similar to CardPane but with built-in "tabs" for navigation;
+ may optionally be "collapsed" such that only the tab buttons show.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Accordion</b> - Similar to <tt>TabPane</tt>, but subcomponents are presented
+ like the folds of an accordion, with headers for navigating between panels.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Expander</b> - Similar to a border but collapsible such that only the title
+ shows.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Rollup</b> - Similar to Expander but with an aribitrary component as a
+ heading instead of a string; when collapsed, only the first component is
+ visible. Can be nested to create the appearance of a "tree" structure.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b><i>Viewport</i></b> - Abstract base class for a scrollable region. Viewport
+ sublcasses include:
+ <ul>
+ <li>
+ <b>ScrollPane</b> - A scrollable area with optional vertical and horizontal
+ scroll bars as well as row and column headers.
+ </li>
+ <li>
+ <b>Panorama</b> - A scrollable area with optional up/down/left/right arrows.
+ </li>
+ </ul>
+ </p>
+ </li>
+ </ul>
+
+ <p>
+ The image below is an example of some Pivot navigation containers:
+ </p>
+
+ <p><img src="platform_overview/navigation.png"/></p>
+ <p class="caption">Some Pivot navigation containers.</p>
+
+ <h4>Composites</h4>
+
+ <p>
+ Composites are simply components that are implemented using other components. For
+ example, a <tt>ScrollBar</tt> is a container consisting of of two button components
+ and a "thumb", the draggable area that allows the user to scroll by clicking and
+ dragging the mouse. Composites include:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <b>ScrollBar</b> - Allows a user to select one of a range of values using
+ up/down buttons or a draggable "thumb" that also represents an extent value.
+ Most often used to facilitate scrolling in a scroll pane.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Spinner</b> - An "up/down" control allowing a user to cycle through a range
+ of pre-defined values.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Slider</b> - Allows a user to select one of a range of values by dragging
+ the mouse.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Menu</b> - Displays a list of actions to the user. Generally displayed in a
+ popup context menu or as part of a menu bar or menu button.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>MenuBar</b> - Provides access to a collection of sub-menus.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Calendar</b> - Allows a user to select a date.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>FileBrowser</b> - Allows a user to select a file.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>ColorChooser</b> - Allows a user to select a color.
+ </p>
+ </li>
+ </ul>
+
+ <h3>Components</h3>
+
+ <p>
+ Non-container components are generally used to present data to the user, retrieve
+ input from the user, or both. Non-container components include:
+ </p>
+
+ <ul>
+ <li>
+ <p>
+ <b>Label</b> - A simple component used to display an uneditable block of
+ (optionally wrapped) text.</p></li>
+ <li>
+ <p>
+ <b>ImageView</b> - A component that displays a static, optionally scaled,
+ image.</p></li>
+ <li>
+ <p>
+ <b><i>Button</i></b> - Abstract base class for buttons, which include:
+ <ul>
+ <li>
+ <b>PushButton</b> - A basic push button. Can be single-push or toggle
+ (selectable); toggle push buttons can be placed in groups such that
+ only one can be selected at at time.
+ </li>
+ <li>
+ <b>Checkbox</b> - A button that displays a checkmark when selected.
+ Supports "tri-state", or "partial" selection.
+ </li>
+ <li>
+ <b>RadioButton</b> - A button that behaves like an old-style car radio
+ button; generally part of a group where only one button can be selected
+ at time.
+ </li>
+ <li>
+ <b>LinkButton</b> - A single-push button that looks like an HTML
+ hyperlink.
+ </li>
+ <li>
+ <b>ListButton</b> - A button that displays a drop-down list of choices
+ when pushed and reflects the user's selection.
+ </li>
+ <li>
+ <b>CalendarButton</b> - A button that displays a pop-up calendar when
+ pushed and reflects the user's selection.
+ </li>
+ <li>
+ <b>MenuButton</b> - A button that displays a drop-down list of menu
+ items; can optionally reflect the user's selection allowing the action
+ associated with the item to be repeated (i.e. behave like a "split
+ button").
+ </li>
+ <li>
+ <b>Menu.Item</b> - A button that provides behavior for menu items.
+ </li>
+ <li>
+ <b>Menu.BarItem</b> - A button that provides behavior for menu bar
+ items.
+ </li>
+ <li>
+ <b>ColorChooserButton</b> - A button that displays a pop-up color
+ chooser when pushed and reflects the user's selection.
+ </li>
+ </ul>
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Separator</b> - A simple horizontal rule component.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TextInput</b> - A component for entering a single line of text.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TextArea</b> - A component for viewing or entering multiple lines of (optionally formatted) text.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>ActivityIndicator</b> - Displays an indeterminate progress state.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>Meter</b> - Displays a progress bar reflecting a completion percentage.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>ListView</b> - Displays a list of optionally selectable items arranged
+ vertically.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TableView</b> - Displays data grouped into rows and columns. Columns are
+ sortable and resizeable, and rows are optionally selectable.
+ </p>
+ </li>
+ <li>
+ <p>
+ <b>TreeView</b> - Displays a hierarchical data structure. Tree nodes are
+ optionally selectable and collapsible.
+ </p>
+ </li>
+ </ul>
+
+ <p>
+ The image below shows some examples of Pivot button components:
+ </p>
+
+ <p><img src="platform_overview/buttons.png"/></p>
+ <p class="caption">Some Pivot buttons.</p>
+
+ <h2>Internationalization/Localization</h2>
+
+ <p>
+ Pivot applications can be localized using the standard Java localization APIs,
+ including resources and resource bundles. In addition, Pivot supports localization
+ using JSON-based resource files, which are more powerful and flexible than Java's
+ standard properties files: hierarchical resource data is much more easily represented,
+ and strings can be encoded in UTF-8 rather than ISO-8859, making it easier to author
+ content for locales with characters that are not available in ISO-8859.
+ </p>
+
+ <h2>XML Markup</h2>
+
+ <p>
+ Pivot applications can be constructed entirely in Java code, but it is often more
+ efficient (and readable) to define a Pivot application using XML. Pivot supports an XML
+ markup language called WTKX to help simplify user interface development. Every
+ component has a corresponding XML element that allows a developer to create an instance
+ of it without writing any Java code. Most component properties accessible from Java are
+ also supported in XML, and, in general, the structure of a user interface can be
+ entirely defined in markup - only application logic and event handling needs to be
+ written in Java. This enables project teams to delegate user interface design and
+ development to non-technical design resources and coding tasks to developers,
+ facilitating a clean separation of responsibility.
+ </p>
+
+ <p>
+ The following is a simple WTKX example that would create two buttons, labeled "OK" and
+ "Cancel", arranged in a horizontal line:
+ </p>
+
+ <source type="xml">
+ <![CDATA[
+ <BoxPane xmlns:wtkx="http://pivot.apache.org/wtkx"
+ xmlns="org.apache.pivot.wtk">
+ <PushButton buttonData="OK"/>
+ <PushButton buttonData="Cancel"/>
+ </BoxPane>
+ ]]>
+ </source>
+
+ <p>
+ Note that the button text is specified using the "buttonData" attribute. Simple
+ string-based data such as this is often sufficient; however, some component
+ properties, including button data, cannot always be easily expressed using XML
+ attributes. For example, a designer may want to create a button containing both an
+ image and a label. WTKX supports the expression of typed data directly in XML using
+ XML namespaces, allowing developers to pass complex data types to components without
+ needing to write Java code to do so. XML namespace prefixes are translated to Java
+ package names by the loader; an instance of
+ <tt>org.apache.pivot.wtk.content.ButtonData</tt>, which defines "icon" and "text"
+ properties, is instantiated and passed as the data to each button as follows:
+ </p>
+
+ <source type="xml">
+ <![CDATA[
+ <BoxPane xmlns:wtkx="http://pivot.apache.org/wtkx"
+ xmlns:content="org.apache.pivot.wtk.content"
+ xmlns="org.apache.pivot.wtk">
+ <PushButton>
+ <buttonData>
+ <content:ButtonData icon="@ok.png" text="OK"/>
+ </buttonData>
+ </PushButton>
+ <PushButton>
+ <buttonData>
+ <content:ButtonData icon="@cancel.png" text="Cancel"/>
+ </buttonData>
+ </PushButton>
+ </BoxPane>
+ ]]>
+ </source>
+
+ <p>
+ The default button renderer is capable of handling this type of data and automatically
+ draws the button appropriately.
+ </p>
+
+ <p>
+ Note that the icon values are preceded by an '@' symbol. This is a directive to the
+ WTKX loader that the following string should be treated as a URL; specifically, a URL
+ that is relative to the source WTKX file. The special syntax is required because XML
+ does not natively support a URL data type. WTKX also supports similar hints for
+ embedding resource values in a WTKX file as well as referring to object instances in
+ markup. This is discussed in more detail in later sections.
+ </p>
+
+ <p>
+ For a detailed description of how WTKX works, refer to the
+ <a href="wtkx_primer.html">WTKX primer</a>.
+ </p>
+
+ <h2>Effects</h2>
+
+ <p>
+ The <tt>org.apache.pivot.wtk.effects</tt> package provides support for adding visual
+ richness to Pivot applications. Effects in Pivot are implemented primarily via two
+ types of classes: decorators and transitions. Decorators allow a caller to attach
+ additional rendering behavior to a component, such as blurs, fades, or drop shadows.
+ Transitions are timed behaviors that are often used to animate elements of a user
+ interface.
+ </p>
+
+ <p><img src="platform_overview/decorator.png"/></p>
+ <p class="caption">Decorator example.</p>
+
+ <h2>Web Queries</h2>
+
+ <p>
+ "Web queries" are Pivot's native means of communicating with remote data services.
+ Fundamentally, a web query is simply an
+ <a href="http://www.ietf.org/rfc/rfc2616.txt">HTTP</a> request. However, the default
+ data format used by a web query is not HTML, but JSON. This allows a caller to
+ effectively invoke database-like operations over the web - the HTTP methods are used
+ in a manner that is very similar to their corresponding SQL equivalents:
+ </p>
+
+ <table>
+ <thead>
+ <tr>
+ <td class="heading">Behavior</td>
+ <td class="heading">SQL Query</td>
+ <td class="heading">HTTP Method</td>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td>Create</td>
+ <td>INSERT</td>
+ <td>POST</td>
+ </tr>
+ <tr>
+ <td>Read</td>
+ <td>SELECT</td>
+ <td>GET</td>
+ </tr>
+ <tr>
+ <td>Update</td>
+ <td>UPDATE</td>
+ <td>PUT</td>
+ </tr>
+ <tr>
+ <td>Delete</td>
+ <td>DELETE</td>
+ <td>DELETE</td>
+ </tr>
+ </tbody>
+ </table>
+
+ <p>
+ These operations, sometimes referred to as "CRUD", form the basis of the
+ <a href="http://en.wikipedia.org/wiki/Representational_State_Transfer">Representational
+ State Transfer</a> (REST) model of building web services. Pivot web queries are
+ designed primarily to facilitate interaction with JSON-based REST services. However,
+ they are sufficiently generic to support communication with any type of HTTP-based
+ service, using any data format (for example, XML). This renders the classes in the
+ <tt>org.apache.pivot.web</tt> package applicable to a broad range of server
+ communication scenarios.
+ </p>
+
+ <p>
+ In addition to the client APIs defined in <tt>org.apache.pivot.web</tt>, the
+ <tt>org.apache.pivot.web.server</tt> package provides classes that simplify the task of
+ implementing and interacting with HTTP web services. <tt>QueryServlet</tt> provides an
+ abstract base class for implementing web query servlets, and <tt>ProxyServlet</tt>
+ provides an HTTP proxy that allows an unsigned applet to issue web queries to services
+ outside of its origin server.
+ </p>
</body>
</document>