<?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>

        <h3>Architecture</h3>

        <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>

        <h3>Internationalization/Localization</h3>

        <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>

        <h3>XML Markup</h3>

        <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>

        <h3>Effects</h3>

        <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>

        <h3>Web Queries</h3>

        <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>
