lazarus/docs/xml/lcl/calendarpopup.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--

Documentation for LCL (Lazarus Component Library) and LazUtils (Lazarus 
Utilities) are published under the Creative Commons Attribution-ShareAlike 4.0 
International public license.

https://creativecommons.org/licenses/by-sa/4.0/legalcode.txt
https://gitlab.com/freepascal.org/lazarus/lazarus/-/blob/main/docs/cc-by-sa-4-0.txt

Copyright (c) 1997-2025, by the Lazarus Development Team.

-->
<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>
Original Author: Vincent Snijders.
</p>
<p>
<file>calendarpopup.pas</file> is part of the LCL (Lazarus Component Library).
</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 a 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 private <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, 
display settings, and date range 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"/>

<!-- private -->
<element name="TCalendarPopupForm.Initialize">
<short>Configures the Calendar control in the pop-up form.</short>
<descr>
<p>
<var>Initialize</var> is a method which configures the calendar control 
displayed on the form using the values passed in the arguments to the method.
</p>
<p>
<var>ADateTime</var> contains the initial TDateTime value for the calendar, 
and is stored in the DateTime property in Calendar.
</p>
<p>
<var>DisplaySettings</var> contains the set of display options enabled for 
the calendar, and is stored in the DisplaySettings property in Calendar.
</p>
<p>
<var>AMinDate</var> and <var>AMaxDate</var> indicate the range of dates that 
can be displayed or selected using the calendar, and is stored in the 
corresponding properties in Calendar. The Calendar uses the values to limit 
its DateTime selection to a required range of values. The values also prevent 
an exception raised when a TDateTime value is not supported on the native 
Calendar control.
</p>
<p>
Initialize is called when the ShowCalendarPopup routine creates, configures, 
and executes the pop-up calendar dialog.
</p>
</descr>
<version>
Modified in LCL version 3.0 to include minimum and maximum date arguments.
</version>
<seealso>
<link id="ShowCalendarPopup"/>
<link id="#lcl.calendar.TCalendar.DateTime">TCalendar.DateTime</link>
<link id="#lcl.calendar.TCalendar.DisplaySettings">TCalendar.DisplaySettings</link>
<link id="#lcl.calendar.TCalendar.MinDate">TCalendar.MinDate</link>
<link id="#lcl.calendar.TCalendar.MaxDate">TCalendar.MaxDate</link>
</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.Initialize.AMinDate">
<short>Minimum date value allowed on the calendar.</short>
</element>
<element name="TCalendarPopupForm.Initialize.AMaxDate">
<short>Maximum date value allowed on the calendar.</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>

<!-- private -->
<element name="TCalendarPopupForm.ReturnDate">
<short>
Signals the OnReturnDate event handler using the DateTime value in the 
Calendar control.
</short>
<descr>
<p>
The TReturnDateEvent routine signalled in the method is provided when the 
ShowCalendarPopup routine is called. It is implemented as an object procedure 
in the control which displays the calendar pop-up form. For example: 
TDateEdit; it includes private methods used for the OnReturnDate and 
OnShowHide arguments passed to ShowCalendarPopup.
</p>
<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 an overloaded procedure used to create, 
configure, and display a TCalendarPopupForm instance using the arguments 
passed to the routine. The argument values are stored to the TCalendar 
instance on the dialog form by calling the Initialize method.
</p>
<p>
ShowCalendarPopup calls the Show method in the form to make it visible. The 
KeepInView method in the form is called to ensure that the pop-up is fully 
visible on the current monitor.
</p>
<p>
ShowCalendarPopup is called from the ButtonClick method in TDateEdit. The 
caller sets the argument values, including the date range in AMinDate and 
AMaxDate, to the defaults needed for the control. AMinDate is set to the date 
value for September 14, 1752 (the start of the Gregorian calendar in 
England). AMaxDate is set to the date portion of the MaxDateTime constant in 
the RTL (December 31, 9999). When omitted, an empty TDateTime value (0.0) is 
used in the arguments and does not impose a date range for the calendar 
pop-up.
</p>
</descr>
<version>
Modified in LCL version 3.0 to include an overloaded variant with minimum 
and maximum date arguments.
</version>
<seealso>
<link id="TCalendarPopupForm"/>
<link id="TReturnDateEvent"/>
<link id="#lcl.calendar.TDisplaySettings">TDisplaySettings</link>
<link id="#lcl.editbtn.TDateEdit.ButtonClick">TDateEdit.ButtonClick</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.AMinDate">
<short>
Minimum date value that can be displayed or selected using the Calendar on 
the dialog, or an empty value (0.0) when omitted.
</short>
</element>
<element name="ShowCalendarPopup.AMaxDate">
<short>
Minimum date value that can be displayed or selected using the Calendar on 
the dialog, or an empty value (0.0) when omitted.
</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>