<?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="push-buttons">
    <properties>
        <title>Push Buttons</title>
    </properties>

    <body>
        <p>
            Below is an example of a Pivot <tt>PushButton</tt>. Clicking the button opens a simple
            modal dialog informing the user that the button was clicked:
        </p>

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

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

        <source type="xml" location="org/apache/pivot/tutorials/buttons/push_buttons.bxml">
            <![CDATA[
            <buttons:PushButtons title="Push Buttons" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns:buttons="org.apache.pivot.tutorials.buttons"
                xmlns="org.apache.pivot.wtk">
                <Border>
                    <BoxPane styles="{padding:4, horizontalAlignment:'center',
                        verticalAlignment:'center'}">
                        <PushButton bxml:id="pushButton" buttonData="Click Me!"/>
                    </BoxPane>
                </Border>
            </buttons:PushButtons>
            ]]>
        </source>

        <p>
            Note the use of the custom "buttons" namespace. This namespace is associated with the
            <tt>org.apache.pivot.tutorials.buttons</tt> package. The root element,
            <tt>&lt;buttons:PushButtons&gt;</tt> represents an instance of
            <tt>org.apache.pivot.tutorials.buttons.PushButtons</tt> - a custom,
            application-specific subclass of the <tt>org.apache.pivot.wtk.Window</tt> class.
            When the BXML file is loaded, an instance of this class will be returned.
        </p>

        <p>
            The source code for the <tt>PushButtons</tt> class is shown below:
        </p>

        <source type="java" location="org/apache/pivot/tutorials/buttons/PushButtons.java">
            <![CDATA[
            package org.apache.pivot.tutorials.buttons;

            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.Alert;
            import org.apache.pivot.wtk.Button;
            import org.apache.pivot.wtk.ButtonPressListener;
            import org.apache.pivot.wtk.MessageType;
            import org.apache.pivot.wtk.PushButton;
            import org.apache.pivot.wtk.Window;

            public class PushButtons extends Window implements Bindable {
                private PushButton pushButton;

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

                    pushButton.getButtonPressListeners().add(new ButtonPressListener() {
                        @Override
                        public void buttonPressed(Button button) {
                            Alert.alert(MessageType.INFO, "You clicked me!", PushButtons.this);
                        }
                    });
                }
            }
            ]]>
        </source>

        <p>
            Note that the <tt>PushButtons</tt> class implements the <tt>org.apache.pivot.beans.Bindable</tt>
            interface. This interface defines a single method, <tt>initialize()</tt>, that is called
            when the root element of a BXML file has been completely loaded. This allows the bound
            class to perform additional initialization tasks such as event registration.
        </p>

        <p>
            In the <tt>initialize()</tt> method, the application registers an event listener that
            is called when the button is pressed. When this listener is invoked, the <tt>buttonPressed()</tt>
            event handler method calls a static method of the <tt>Alert</tt> class to display a simple
            message to the user.
        </p>
    </body>
</document>