<?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-panes">
    <properties>
        <title>Table Panes</title>
        <explore>TablePane</explore>
    </properties>

    <body>
        <p>
            Table panes are used to arrange components in a variable 2-dimensional grid, much like
            an HTML table. Table panes have a "columns" collection that defines the column
            structure of the table and a "rows" collection that defines both the row structure of
            the table and the contents of each row.
        </p>

        <p>
            Note that a special syntax can be used to specify the width of a TablePane.Column or the height of a TablePane.Row:
        </p>

        <ul>
            <li>
                "-1" - default size, the column will be as wide as the widest component in that column,
                or a row would be as tall as the tallest component in that row.
            </li>
            <li>
                "a number > -1" - absolute size,
                that number will be the width in pixels for a column, or the height in pixels for a row.
            </li>
            <li>
                "n*" - relative size,
                calculate the remaining space available in the column or in the row
                (using all relative columns/row cells),
                then add up the total of the relative values, divide the space by that number and reallocate
                the space for each column or row by multiplying the final value by each relative number.<br/>
                For example if the total space is 300 pixels and the column widths are "1*", "2*" and "3*":<br/>
                total relative value = 1 + 2 + 3 = 6<br/>
                base value = 300 / 6 = 50<br/>
                column widths = 1 * 50 = 50, 2 * 50 = 100, 3 * 50 = 150 (total 50 + 100 + 150 = 300)
            </li>
        </ul>
        <br/>

        <p>
            Table panes support a number of styles that allow a caller to customize the arrangement
            of child components:
        </p>

        <ul>
            <li>
                "padding" - the amount of space the table pane reserves around the perimeter of the
                container.
            </li>
            <li>
                "horizontalSpacing" - the amount of space the table pane inserts between columns.
            </li>
            <li>
                "verticalSpacing" - the amount of space the table pane inserts between rows.
            </li>
            <li>
                "showHorizontalGridLines" - whether horizontal grid lines will be painted in the
                space between rows. Note that this will be ignored if "verticalSpacing" is zero, as
                there would be no space in which to paint the grid lines.
            </li>
            <li>
                "showVerticalGridLines" - whether vertical grid lines will be painted in the space
                between columns. Note that this will be ignored if "horizontalSpacing" is zero, as
                there would be no space in which to paint the grid lines.
            </li>
            <li>
                "horizontalGridColor" - the color of the horizontal grid lines.
            </li>
            <li>
                "verticalGridColor" - the color of the vertical grid lines.
            </li>
            <li>
                "highlightBackgroundColor" - the background color of rows and columns whose
                "highlighted" flag is set to <tt>true</tt>.
            </li>
        </ul>

        <p>
            Below is a sample application that demonstrates a basic table pane structure and
            responds to mouse clicks with information about where the user clicked:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="560" height="340">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/layout/simple_table_panes.bxml</src>
            </startup-properties>
        </application>

        <p>The BXML source for the application is shown below:</p>

        <source type="xml" location="org/apache/pivot/tutorials/layout/simple_table_panes.bxml">
            <![CDATA[
            <layout:SimpleTablePanes bxml:id="window" title="Table Panes" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:layout="org.apache.pivot.tutorials.layout"
                xmlns="org.apache.pivot.wtk">
                <Border>
                    <TablePane bxml:id="tablePane" styles="{verticalSpacing:1, showHorizontalGridLines:true,
                        horizontalSpacing:1, showVerticalGridLines:true}">
                        <columns>
                            <TablePane.Column width="-1"/>
                            <TablePane.Column width="50"/>
                            <TablePane.Column width="-1"/>
                            <TablePane.Column width="1*"/>
                            <TablePane.Column width="2*"/>
                        </columns>

                        <TablePane.Row height="-1">
                            <TablePane.Filler/>
                            <Label text="50" styles="{horizontalAlignment:'center'}"/>
                            <Label text="-1" styles="{horizontalAlignment:'center'}"/>
                            <Label text="1*" styles="{horizontalAlignment:'center'}"/>
                            <Label text="2*" styles="{horizontalAlignment:'center'}"/>
                        </TablePane.Row>

                        <TablePane.Row height="50">
                            <Label text="50" styles="{verticalAlignment:'center'}"/>
                        </TablePane.Row>

                        <TablePane.Row height="-1">
                            <Label text="-1" styles="{verticalAlignment:'center'}"/>
                        </TablePane.Row>

                        <TablePane.Row height="1*">
                            <Label text="1*" styles="{verticalAlignment:'center'}"/>
                        </TablePane.Row>

                        <TablePane.Row height="2*">
                            <Label text="2*" styles="{verticalAlignment:'center'}"/>
                        </TablePane.Row>
                    </TablePane>
                </Border>
            </layout:SimpleTablePanes>
            ]]>
        </source>

        <p>
            The Java source is as follows. Most of the code is simply event handling logic that
            responds to mouse clicks:
        </p>

        <source type="java">
            <![CDATA[
            package org.apache.pivot.tutorials.layout;

            import java.net.URL;

            import org.apache.pivot.beans.Bindable;
            import org.apache.pivot.collections.Map;
            import org.apache.pivot.util.Resources;
            import org.apache.pivot.wtk.BoxPane;
            import org.apache.pivot.wtk.Component;
            import org.apache.pivot.wtk.ComponentMouseButtonListener;
            import org.apache.pivot.wtk.Label;
            import org.apache.pivot.wtk.MessageType;
            import org.apache.pivot.wtk.Mouse;
            import org.apache.pivot.wtk.Orientation;
            import org.apache.pivot.wtk.Prompt;
            import org.apache.pivot.wtk.TablePane;
            import org.apache.pivot.wtk.Window;

            public class SimpleTablePanes extends Window implements Bindable {
                private TablePane tablePane = null;

                @Override
                public void initialize(Map<String, Object> namespace, URL location, Resources resources) {
                    tablePane = (TablePane)namespace.get("tablePane");

                    tablePane.getComponentMouseButtonListeners().add(new ComponentMouseButtonListener.Adapter() {
                        @Override
                        public boolean mouseClick(Component component, Mouse.Button button, int x, int y, int count) {
                            int rowIndex = tablePane.getRowAt(y);
                            int columnIndex = tablePane.getColumnAt(x);

                            if (rowIndex >= 0
                                && columnIndex >= 0) {
                                TablePane.Row row = tablePane.getRows().get(rowIndex);
                                TablePane.Column column = tablePane.getColumns().get(columnIndex);

                                int rowHeight = row.getHeight();
                                int columnWidth = column.getWidth();

                                String message = "Registered Click At " + rowIndex + "," + columnIndex;

                                Label heightLabel = new Label(String.format("The row's height is %d (%s)",
                                    rowHeight,
                                    rowHeight == -1 ? "default" : (row.isRelative() ? "relative" : "absolute")));
                                Label widthLabel = new Label(String.format("The column's width is %d (%s)",
                                    columnWidth,
                                    columnWidth == -1 ? "default" : (column.isRelative() ? "relative" : "absolute")));

                                BoxPane body = new BoxPane(Orientation.VERTICAL);
                                body.add(heightLabel);
                                body.add(widthLabel);

                                Prompt.prompt(MessageType.INFO, message, body, SimpleTablePanes.this);
                            }

                            return false;
                        }
                    });
                }
            }
            ]]>
        </source>

        <p>
            The following is a more involved application that allows the user to interact with the
            table pane and get a feel for how the different settings affect layout. The
            application manages the table pane's styles via the controls on the left and responds
            to right-clicks over the table pane itself. The user can also drag the splitter to see
            the effect it has on the relative columns in the grid pane.
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="560" height="340">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/layout/table_panes.bxml</src>
            </startup-properties>
        </application>
    </body>
</document>
