<?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="calendars">
    <properties>
        <title>Calendars</title>
    </properties>

    <body>
        <p>
            Pivot provides two types of calendar components: a standalone <tt>Calendar</tt>
            component that can be used anywhere within an application's user interface, and a
            <tt>CalendarButton</tt> component that, like a <a href="list-buttons.html">list
            button</a>, displays a popup calendar when pressed.
        </p>

        <p>
            The following sample application demonstrates both component types. Selecting a date
            on one calendar automatically updates the other calendar as well as setting the text
            of a label to the currently selected date:
        </p>

        <application class="org.apache.pivot.wtk.ScriptApplication"
            width="300" height="400">
            <libraries>
                <library>core</library>
                <library>wtk</library>
                <library>wtk-terra</library>
                <library>tutorials</library>
            </libraries>
            <startup-properties>
                <src>/org/apache/pivot/tutorials/calendars/calendars.bxml</src>
            </startup-properties>
        </application>

        <p>
            The BXML source is as follows:
        </p>

        <source type="xml" location="org/apache/pivot/tutorials/calendars/calendars.bxml">
            <![CDATA[
            <Window title="Calendars" maximized="true"
                xmlns:bxml="http://pivot.apache.org/bxml"
                xmlns="org.apache.pivot.wtk">
                <Border styles="{padding:8}">
                    <Form>
                        <Form.Section>
                            <Border Form.label="Calendar" styles="{color:10}">
                                <Calendar bxml:id="calendar" selectedDate="${calendarButton.selectedDate}">
                                    <calendarSelectionListeners>
                                        function selectedDateChanged(calendar, previousSelectedDate) {
                                            calendar.year = calendar.selectedDate.year;
                                            calendar.month = calendar.selectedDate.month;
                                        }
                                    </calendarSelectionListeners>
                                </Calendar>
                            </Border>
                            <CalendarButton bxml:id="calendarButton" Form.label="Calendar button"
                                selectedDate="${calendar.selectedDate}"/>
                        </Form.Section>
                        <Form.Section>
                            <Label bxml:id="selectedDateLabel" Form.label="Selected date"
                                text="${calendar.selectedDate}"/>
                        </Form.Section>
                    </Form>
                </Border>
            </Window>
            ]]>
        </source>

        <p>
            Note that there is no Java or script code associated with this example. The calendars
            are kept in sync via a Pivot feature called <i>property binding</i>. This feature allows
            a caller to declaratively create a relationship between a source and target property such
            that changes to the source are automatically reflected in the target.
        </p>

        <p>
            In BXML, a binding relationship is created via the "${...}" syntax shown in the sample
            code. For example, the following markup ensures that any changes to the "calendar.selectedDate"
            property are automatically propagated to the <tt>Label</tt>'s "text" property:
        </p>

        <source type="xml">
            <![CDATA[
            <Label bxml:id="selectedDateLabel" Form.label="Selected date"
                text="${calendar.selectedDate}"/>
            ]]>
        </source>

        <p>
            Property binding is discussed in more detail in the
            <a href="property_binding.html">Property Binding</a> section.
        </p>
    </body>
</document>
