Google Git
Sign in
apache / pivot / 74621e9500653a1647b4b0915b8456a78193cd99 / . / tutorials / www / platform-overview.xml
blob: 176cd9597235fd6e2ea8d9167af98b02eb2cd9f9 [file] [log] [blame]
<?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="platform-overview">
<properties>
<title>Platform Overview</title>
</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, etc.
</li>
<li>
<b>Web</b> - Classes to facilitate implementation of and communication with remote
data services.
</li>
<li>
<b>Charts</b> - Classes for adding interactive charting capabilities to Pivot
applications.
</li>
</ul>
<p>
The classes in each category are packaged and distributed in a corresponding library or
set of libraries:
</p>
<h3>Core</h3>
<h4>pivot-core-[version].jar</h4>
<ul>
<li>
<tt>org.apache.pivot.beans</tt> - Classes that facilitate and simplify programmatic
interaction with Java bean types.
</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.json</tt> - Classes for working with JSON data.
</li>
<li>
<tt>org.apache.pivot.serialization</tt> - Classes for use in data serialization.
</li>
<li>
<tt>org.apache.pivot.sql</tt> - Classes for working with SQL data.
</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>WTK</h3>
<h4>pivot-wtk-[version].jar</h4>
<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> - Classes representing "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 representing media resources.
</li>
<li>
<tt>org.apache.pivot.wtk.skin</tt> - Theme-independent skins and abstract base
classes for theme-specific skins.
</li>
<li>
<tt>org.apache.pivot.wtk.text</tt> - Text object model classes.
</li>
<li>
<tt>org.apache.pivot.wtk.text.validation</tt> - Classes for validating user-entered
text.
</li>
</ul>
<h4>pivot-wtk-terra-[version].jar</h4>
<ul>
<li>
<tt>org.apache.pivot.wtk.skin.terra</tt> - Defines skin classes for the default
"Terra" theme.
</li>
</ul>
<h3>Web</h3>
<h4>pivot-web-[version].jar</h4>
<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>Charts</h3>
<h4>pivot-charts-[version].jar</h4>
<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>
<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 interfaces 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>SuggestionPopup</b> - A popup window that provides "auto-complete"
functionality for a text input.
</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 containers,
navigation containers, and composites.
</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>GridPane</b> - Container that arranges components in a two-dimensional grid
where each cell is given the same size, based on the available width and
height.
</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>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>ColorChooser</b> - Allows a user to select a color.
</p>
</li>
<li>
<p>
<b>FileBrowser</b> - Allows a user to select a file.
</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>ColorChooserButton</b> - A button that displays a pop-up color
chooser 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>
</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>
While Pivot applications can be localized using the standard Java localization APIs,
Pivot supports additional localization features 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 the ISO-8859 character set.
</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 BXML that can be used to help simplify user interface
development. The following example demonstrates the use of BXML to create two buttons
labeled "OK" and "Cancel" arranged in a horizontal line:
</p>
<source type="xml">
<![CDATA[
<BoxPane xmlns:bxml="http://pivot.apache.org/bxml"
xmlns="org.apache.pivot.wtk">
<PushButton buttonData="OK"/>
<PushButton buttonData="Cancel"/>
</BoxPane>
]]>
</source>
<p>
A more detailed overview of BXML can be found in the
<a href="bxml-primer.html">BXML primer</a> section.
</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 style="border:solid 1px #999999; border-collapse:collapse">
<style>
td {
border:solid 1px #999999;
padding:3px;
}
td.heading {
font-weight:bold;
}
</style>
<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>