<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="LCL">
    <!--
    ====================================================================
      CalendarPopup
    ====================================================================
    -->
    <module name="CalendarPopup">
      <short>Implements a pop-up form with a TCalendar control for TDateEdit.</short>
      <descr>
        <p>
          <file>calendarpopup.pas</file> implements a non-modal calendar popup for a TDateEdit control. It includes a ShowCalendarPopup routine to configure, display, and capture the return value for the pop-up form.
        </p>
        <p>
          Author: Vincent Snijders
        </p>
      </descr>

      <!-- used units -->
      <element name="System"/>
      <element name="Classes"/>
      <element name="SysUtils"/>
      <element name="Forms"/>
      <element name="Controls"/>
      <element name="Graphics"/>
      <element name="Dialogs"/>
      <element name="Calendar"/>
      <element name="LCLProc"/>
      <element name="LCLType"/>

      <element name="TReturnDateEvent">
        <short>
          Specifies an event handler signalled when a date is selected on a pop-up calendar form.
        </short>
        <descr>
          <p>
            <var>TReturnDateEvent</var> specifies an event handler signalled when a date is selected on a pop-up calendar form. TReturnDateEvent is the type used to implement the <var>OnReturnDate</var> event handler in    <var>TCalendarPopupForm</var>. Applications must implement an object procedure used to respond to the event notification. It is passed as an argument to the <var>ShowCalendarPopup</var> routine.
          </p>
        </descr>
        <seealso>
          <link id="ShowCalendarPopup"/>
        </seealso>
      </element>
      <element name="TReturnDateEvent.Sender">
        <short>Object for the event notification; normally the pop-up calendar form.</short>
      </element>
      <element name="TReturnDateEvent.Date">
        <short>TDateTime value for the date selected on the calendar form.</short>
      </element>

      <element name="TCalendarPopupForm">
        <short>
          Implements a non-modal pop-up form used to select a date from a TCalendar control.
        </short>
        <descr>
          <p>
            <var>TCalendarPopupForm</var> is a <var>TForm</var> descendant which implements a non-modal pop-up form used to select a date with a TCalendar control. It includes the <var>OnReturnDate</var> event handler to perform the actions needed when a date is selected using the Calendar control.
          </p>
          <p>
            TCalendarPopupForm is used as the non-modal dialog executed when the Button for the <var>TDateEdit</var> control is clicked.
          </p>
          <p>
            Use the <var>ShowCalendarPopup</var> routine to create, configure, and display a pop-up calendar form.
          </p>
        </descr>
        <seealso>
          <link id="ShowCalendarPopup"/>
          <link id="#lcl.editbtn.TDateEdit">TDateEdit</link>
        </seealso>
      </element>

      <element name="TCalendarPopupForm.Calendar">
        <short>TCalendar control used to select a date on the form.</short>
        <descr>
          <p>
            <var>Calendar</var> is a <var>TCalendar</var> member which contains the calendar control displayed on the form. It allows selection of date, and calls the <var>ReturnDate</var> method when the Month, Day, or Year in the control is changed using either the mouse or the keyboard. Calendar is configured in the <var>Initialize</var> method using the <var>TDateTime</var> and <var>TDisplaySettings</var> provided as arguments.
          </p>
          <p>
            Use the <var>ShowCalendarPopup</var> routine to provide the date/time value and display settings needed in the pop-up calendar form.
          </p>
        </descr>
        <seealso>
          <link id="TCalendar"/>
          <link id="ShowCalendarPopup"/>
          <link id="TDisplaySettings"/>
        </seealso>
      </element>

      <element name="TCalendarPopupForm.CalendarDblClick">
        <short>
          Performs actions needed when a double click mouse event occurs in the Calendar control.
        </short>
        <descr>
          <p>
            <var>CalendarDblClick</var> ensures that the mouse event is within the bounds for the <var>Calendar</var> control by calling its <var>HitTest</var> method.  When the mouse event occurs on the Month or Year calendar parts, the <var>ReturnDate</var> method is called to signal the <var>OnReturnDate</var> event handler and close the form.
          </p>
        </descr>
        <seealso>
          <link id="#lcl.calendar.TCustomCalendar.HitTest">TCustomCalendar.HitTest</link>
          <link id="#lcl.calendar.TCalendarPart">TCalendarPart</link>
        </seealso>
      </element>
      <element name="TCalendarPopupForm.CalendarDblClick.Sender">
        <short>Object for the event notification.</short>
      </element>

      <element name="TCalendarPopupForm.CalendarKeyDown">
        <short>Implements the OnKeyDown event handler for the Calendar control.</short>
        <descr>
          <p>
            <var>CalendarKeyDown</var> is a procedure which implements the <var>OnKeyDown</var> event handler for the <var>Calendar</var> control. The method ensures that the key down virtual key code represented by <var>Key</var> and <var>Shift</var> is applied to the Calendar control, and includes:
          </p>
          <dl>
            <dt>VK_RETURN, VK_SPACE</dt>
            <dd>
              Calls <var>ReturnDate</var> to apply the selected date value in Month view, and signals the <var>OnReturnDate</var> event handler.
            </dd>
            <dt>VK_ESCAPE</dt>
            <dd>Calls <var>Close</var> to close the form.</dd>
          </dl>
          <p>
            If the virtual key code is handled in the method, the value in Key is set to zero (0). Otherwise, it is retained for use in event handlers at the Form or Application level.
          </p>
        </descr>
        <seealso>
          <link id="#lcl.forms.TCustomForm.Close">TCustomForm.Close</link>
        </seealso>
      </element>
      <element name="TCalendarPopupForm.CalendarKeyDown.Sender">
        <short>Object for the event notification; the Calendar control in this case.</short>
      </element>
      <element name="TCalendarPopupForm.CalendarKeyDown.Key">
        <short>Virtual key code examined in the method.</short>
      </element>
      <element name="TCalendarPopupForm.CalendarKeyDown.Shift">
        <short>Virtual key modifier examined in the method.</short>
      </element>

      <element name="TCalendarPopupForm.FormClose">
        <short>Implements the OnClose event handler for the form.</short>
        <descr>
          <p>
            Ensures that the <var>FormDeactivate</var> method is removed from the registered OnDeactivate handlers in <var>Application</var>. The value in <var>CloseAction</var> is set to <var>caFree</var> in the method.
          </p>
        </descr>
        <seealso></seealso>
      </element>
      <element name="TCalendarPopupForm.FormClose.Sender">
        <short>Object for the event notification.</short>
      </element>
      <element name="TCalendarPopupForm.FormClose.CloseAction">
        <short>Close action to perform on exit from the event handler.</short>
      </element>

      <element name="TCalendarPopupForm.FormCreate">
        <short>Implements the OnCreate event handler for the form.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TCalendarPopupForm.FormCreate.Sender">
        <short>Object for the event notification.</short>
      </element>

      <element name="TCalendarPopupForm.FormDeactivate">
        <short>Implements the OnDeactivate event handler for the form.</short>
        <descr>
          <p>
            Ensures that the <var>FormDeactivate</var> method is added to the OnDeactivate handlers in <var>Application</var>.
          </p>
        </descr>
        <seealso></seealso>
      </element>
      <element name="TCalendarPopupForm.FormDeactivate.Sender">
        <short>Object for the event notification.</short>
      </element>

      <element name="TCalendarPopupForm.FCaller"/>
      <element name="TCalendarPopupForm.FClosed"/>
      <element name="TCalendarPopupForm.FOnReturnDate"/>

      <element name="TCalendarPopupForm.Initialize">
        <short>Configures the Calendar control in the pop-up form.</short>
        <descr>
          <p>
            Applies the values in the <var>ADate</var> and <var>DisplaySettings</var> arguments to the <var>Calendar</var> control.
          </p>
        </descr>
        <seealso></seealso>
      </element>
      <element name="TCalendarPopupForm.Initialize.ADate">
        <short>Date value assigned to the Calendar control.</short>
      </element>
      <element name="TCalendarPopupForm.Initialize.DisplaySettings">
        <short>Display settings applied to the Calendar control.</short>
      </element>

      <element name="TCalendarPopupForm.KeepInView">
        <short>
          Ensures that the form and the calling control are visible on the current monitor.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TCalendarPopupForm.KeepInView.PopupOrigin">
        <short>Coordinates where the pop-up form is displayed.</short>
      </element>

      <element name="TCalendarPopupForm.ReturnDate">
        <short>
          Signals the OnReturnDate event handler using the DateTime value in the Calendar control.
        </short>
        <descr>
          <p>
            Calls <var>Close</var> to close the form if it has not already been executed.
          </p>
        </descr>
        <seealso></seealso>
      </element>

      <element name="ShowCalendarPopup">
        <short>Creates, configures, and displays a TCalendarPopupForm instance.</short>
        <descr>
          <p>
            <var>ShowCalendarPopup</var> is a procedure used to create, configure, and display a <var>TCalendarPopupForm</var> instance. ShowCalendarPopup stores arguments to the routine in properties for the pop-up calendar form, and calls its <var>Initialize</var> method to configure the <var>Calendar</var> control.
          </p>
          <p>
            ShowCalendarPopup calls the <var>Show</var> in the form to make it visible, and calls <var>KeepInView</var> to ensure that the form is fully visible on the current monitor.
          </p>
        </descr>
        <seealso>
          <link id="TCalendarPopupForm"/>
          <link id="TReturnDateEvent"/>
          <link id="#lcl.calendar.TDisplaySettings">TDisplaySettings</link>
        </seealso>
      </element>
      <element name="ShowCalendarPopup.APosition">
        <short>Coordinates where the pop-up calendar form is displayed.</short>
      </element>
      <element name="ShowCalendarPopup.ADate">
        <short>Initial date displayed in the Calendar for the form.</short>
      </element>
      <element name="ShowCalendarPopup.CalendarDisplaySettings">
        <short>Display settings applied to the Calendar control.</short>
      </element>
      <element name="ShowCalendarPopup.OnReturnDate">
        <short>Event handler signalled when a new date value is selected.</short>
      </element>
      <element name="ShowCalendarPopup.OnShowHide">
        <short>Event handler signalled when the pop-up form is shown or hidden.</short>
      </element>
      <element name="ShowCalendarPopup.ACaller">
        <short>The control which creates the pop-up and captures its return value.</short>
      </element>

    </module>
    <!-- CalendarPopup -->
  </package>
</fpdoc-descriptions>
