<?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="table-views">
    <properties>
        <title>Table Views</title>
        <explore>TableView</explore>
    </properties>

    <body>
        <p>
            Table views are used to present tablular data (data that is grouped into rows and
            columns). Columns are often sortable and resizeable, and rows are generally selectable.
        </p>

        <p>
            Like <a href="lists.html">list views</a>, table views are driven by model data provided
            in a <tt>List</tt> object. The values in the list (which represent the rows shown by
            the table) can be of any type, but are most often instances of
            <tt>Dictionary&lt;String, Object&gt;</tt>, which the default table view renders are
            capable of presenting (for example, <tt>Map&lt;String, Object&gt;</tt> values stored in
            a JSON list or instances of Java bean classes that can be wrapped in a
            <tt>BeanAdapter</tt>).
        </p>

        <p>
            The following simple example populates a <tt>TableView</tt> using an array list
            containing hash maps of string values for each row. The table data represents the
            final standings of the top ten medal-winning countries in the 2008 Summer Olympics:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication" width="480" height="240">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/tableviews/basic_table_view.bxml</src>
            </startup-properties>
        </application>

        <p>
            The BXML source is as follows. Note that the <tt>name</tt> attributes of the
            <tt>TableView.Column</tt> elements correspond directly to the keys in the hash maps;
            this is how <tt>TableView</tt> knows which values to display in each column:
        </p>

        <source type="xml">
            <![CDATA[
            <Window title="Table Views" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:collections="org.apache.pivot.collections"
                xmlns="org.apache.pivot.wtk">
                <Border>
                    <ScrollPane>
                        <TableView bxml:id="tableView">
                            <columns>
                                <TableView.Column name="nation" width="180" headerData="Nation"/>
                                <TableView.Column name="gold" width="60" headerData="Gold"/>
                                <TableView.Column name="silver" width="60" headerData="Silver"/>
                                <TableView.Column name="bronze" width="60" headerData="Bronze"/>
                                <TableView.Column name="total" width="60" headerData="Total"/>
                            </columns>

                            <!-- Source: http://en.wikipedia.org/wiki/2008_Summer_Olympics_medal_table -->
                            <collections:HashMap nation="China" gold="51" silver="21" bronze="28" total="100"/>
                            <collections:HashMap nation="United States" gold="36" silver="38" bronze="36" total="110"/>
                            <collections:HashMap nation="Russia" gold="23" silver="21" bronze="28" total="72"/>
                            <collections:HashMap nation="Great Britain" gold="19" silver="13" bronze="15" total="47"/>
                            <collections:HashMap nation="Germany" gold="16" silver="10" bronze="15" total="41"/>
                            <collections:HashMap nation="Australia" gold="14" silver="15" bronze="17" total="46"/>
                            <collections:HashMap nation="South Korea" gold="13" silver="10" bronze="8" total="31"/>
                            <collections:HashMap nation="Japan" gold="9" silver="6" bronze="11" total="26"/>
                            <collections:HashMap nation="Italy" gold="8" silver="10" bronze="10" total="28"/>
                            <collections:HashMap nation="France" gold="7" silver="16" bronze="17" total="40"/>
                        </TableView>

                        <columnHeader>
                            <TableViewHeader tableView="$tableView"/>
                        </columnHeader>
                    </ScrollPane>
                </Border>
            </Window>
            ]]>
        </source>

        <p>
            This example doesn't do much. Clicking on the header (an instance of
            <tt>TableViewHeader</tt> set as the <tt>ScrollPane</tt>'s <tt>columnHeader</tt>
            property) doesn't sort the data as one might expect. Even if it did, the sort would
            most likely not produce the expected results: the medal counts are represented as
            strings, and would be sorted alphabetically rather than numerically.
        </p>

        <p>
            Also, the <tt>TableView</tt> doesn't fill the available space: the content simply ends
            at the right edge, which is determined by the width of the columns. Sometimes this is
            desirable, but many times it is more visually appealing to provide a "filler" that
            appears when the table is not wide enough to occupy the available space and disappears
            when it is not needed.
        </p>

        <p>
            The next example shows how to create such a "filler". It also demonstrates how to
            populate a <tt>TableView</tt> with JSON data, which represents the medal counts as
            numbers and allows a user to properly sort on their values.
        </p>

        <p>There is no associated Java source code for this example.</p>
    </body>
</document>
