lazarus/docs/xml/lcl/timepopup.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">
<!--
====================================================================
TimePopup
====================================================================
-->
<module name="TimePopup">
<short>
Contains forms, types, and routines used to display a pop-up for TTimeEdit.
</short>
<descr>
<p>
<file>timepopup.pas</file> contains the <var>TTimePopupForm</var> form and 
the <var>ShowTimePopup</var> routine used to create, configure, and display 
the pop-up form.
</p>
<p>
Author: Michael Fuchs
</p>
</descr>

<!-- used untis -->
<element name="System"/>
<element name="Classes"/>
<element name="SysUtils"/>
<element name="DateUtils"/>
<element name="FileUtil"/>
<element name="LCLType"/>
<element name="Forms"/>
<element name="Controls"/>
<element name="Graphics"/>
<element name="Dialogs"/>
<element name="Grids"/>
<element name="ExtCtrls"/>
<element name="Buttons"/>
<element name="StdCtrls"/>
<element name="ActnList"/>
<element name="WSForms"/>

<element name="TReturnTimeEvent">
<short>
Specifies an event handler signalled to get a time return value.
</short>
<descr>
<p>
<var>TReturnTimeEvent</var> specifies an event handler signalled to validate 
or assign a time value. It is an object procedure which must be implemented 
in an application to respond to the event notification.
</p>
<p>
<var>Sender</var> is the object generating the event notification.
</p>
<p>
<var>ATime</var> is a <var>TDateTime</var> value which contains the time 
value used in the event handler. Only the time portion of the type is 
significant.
</p>
<p>
<var>TReturnTimeEvent</var> is the type passed as an argument to the 
<var>ShowTimePopup</var> routine, and implemented as a private member in 
<var> TTimePopupForm</var>.
</p>
</descr>
<seealso>
<link id="TTimePopupForm"/>
<link id="ShowTimePopup"/>
</seealso>
</element>
<element name="TReturnTimeEvent.Sender">
<short>Object for the event notification.</short>
</element>
<element name="TReturnTimeEvent.ATime">
<short>Time value examined or updated in the event handler.</short>
</element>

<element name="TTimePopupForm">
<short>Implements a form displayed to capture a time value.</short>
<descr>
<p>
<var>TTimePopupForm</var> implements a form displayed to capture and return a 
time value.
</p>
<p>
The form contains grids with Hour and Minute values which can be selected to 
form the time value. The Minutes displayed in the grid are in either 5 minute 
or 30 minute intervals, depending on the layout selected using the 
<var>SetLayout</var> method; Simple layout uses a 5 minute interval and is 
the default layout for the form.
</p>
<p>
It uses an internal <var>TReturnTimeEvent</var> handler to validate or update 
the time value. There are also internal members used to track the control 
associated with the form, and the coordinates where the form is displayed. 
These internals are assigned using values passed as arguments to the 
<var>ShowTimePopup</var> routine.
</p>
</descr>
<seealso>
<link id="ShowTimePopup"/>
<link id="TReturnTimeEvent"/>
<link id="#lcl.editbtn.TTimeEdit">TTimeEdit</link>
</seealso>
</element>

<element name="TTimePopupForm.Bevel1"/>
<element name="TTimePopupForm.MainPanel"/>
<element name="TTimePopupForm.HoursGrid"/>
<element name="TTimePopupForm.MinutesGrid"/>
<element name="TTimePopupForm.MoreLessBtn"/>

<element name="TTimePopupForm.GridsDblClick">
<short>
Implements the OnDblClick event handler for grids controls on the form.
</short>
<descr>
<p>
Calls <var>ReturnTime</var> to signal the <var>OnReturnTime</var> event 
handler (when assigned) and close the form.
</p>
</descr>
<seealso>
<link id="TTimePopupForm"/>
<link id="TCustomForm.Close"/>
<link id="TReturnTimeEvent"/>
</seealso>
</element>
<element name="TTimePopupForm.GridsDblClick.Sender">
<short>Object for the event notification.</short>
</element>

<element name="TTimePopupForm.GridsKeyDown">
<short>
Implements the OnKeyDown event handler for grid controls on the form.
</short>
<descr>
<p>
<var>GridsKeyDown</var> ensures that the virtual key in <var>Key</var> and 
<var>Shift</var> is applied, when required. GridsKeyDown calls for form 
methods for the following:
</p>
<dl>
<dt>VK_ESC</dt>
<dd>Calls the close method to close the Form.</dd>
<dt>VK_RETURN, VK_SPACE</dt>
<dd>Call ReturnTime to validate/update the time value, and close the 
Form.</dd>
</dl>
<p>
When <var>Key</var> is handled in the method, it is set to zero (0). 
Otherwise, it is retained for use in Form or Application key events.
</p>
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.GridsKeyDown.Sender">
<short>Object for the event notification.</short>
</element>
<element name="TTimePopupForm.GridsKeyDown.Key">
<short>Virtual key code examined in the method.</short>
</element>
<element name="TTimePopupForm.GridsKeyDown.Shift">
<short>Key Modifier examined in the method.</short>
</element>

<element name="TTimePopupForm.GridPrepareCanvas">
<short>
Sets the canvas text style for a grid on the form.
</short>
<descr>
<p>
<var>GridPrepareCanvas</var> ensures that the Canvas used to draw grid 
controls (<var>TStringGrid</var>) on the form has been initialized. 
GridPrepareCanvas sets the text layout and alignment needed for the Canvas 
property in the control.
</p>
<p>
<var>Sender</var> contains the grid control updated in the method. All other 
parameters are ignored in the current implementation.
</p>
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.GridPrepareCanvas.sender">
<short>Control updated in the method.</short>
</element>
<element name="TTimePopupForm.GridPrepareCanvas.aCol">
<short>Ignored.</short>
</element>
<element name="TTimePopupForm.GridPrepareCanvas.aRow">
<short>Ignored.</short>
</element>
<element name="TTimePopupForm.GridPrepareCanvas.aState">
<short>Ignored.</short>
</element>

<element name="TTimePopupForm.MoreLessBtnClick">
<short>
Implements the OnClick event handler for the MoreLessBtn button on the form.
</short>
<descr>
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.MoreLessBtnClick.Sender">
<short>Object for the event notification.</short>
</element>

<element name="TTimePopupForm.FClosed"/>
<element name="TTimePopupForm.FOnReturnTime"/>
<element name="TTimePopupForm.FSimpleLayout"/>
<element name="TTimePopupForm.FPopupOrigin"/>
<element name="TTimePopupForm.FCaller"/>

<element name="TTimePopupForm.ActivateDoubleBuffered">
<short>
Ensures that the DoubleBuffered property is updated with the current value 
from the widget set class.
</short>
<descr/>
<seealso/>
</element>

<element name="TTimePopupForm.CalcGridHeights">
<short>
Calculates the total height for the Hours and Minutes grids on the form.
</short>
<descr/>
</element>

<element name="TTimePopupForm.GetTime">
<short>
Gets a TDateTime value for the selected cells in Hours and Minutes grids.
</short>
<descr>
Calls EncodeTime to get the return value for the selected cells.
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.GetTime.Result">
<short>
TDateTime value for the selected cells; only the time portion of the value is 
relevant.
</short>
</element>

<element name="TTimePopupForm.Initialize">
<short>
Initializes the form using the origin and time values specified.
</short>
<descr>
Calls KeepInView to ensure that the form origin remains visible on the 
current monitor. Called from the ShowTimePopup routine.
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.Initialize.PopupOrigin">
<short>Upper left coordinates for the form.</short>
</element>
<element name="TTimePopupForm.Initialize.ATime">
<short>Initial time value displayed on the form.</short>
</element>

<element name="TTimePopupForm.KeepInView">
<short>Ensures that form remains visible on the current monitor.</short>
<descr>
<p>
KeepInView ensures that form remains visible on the current monitor. 
KeepInView tries to put the form on a "nice" place on the screen and make 
sure the entire form is visible. TheCaller typically will be a TTimeEdit 
control, and uses the following logic:
</p>
<ul>
<li>Places the form right under Caller control. If it does not fit...</li>
<li>Place the form above the Caller control. If it does not fit...</li>
<li>Sets the top coordinate to 0 and allows covering the Caller control.</li>
</ul>
</descr>
<seealso/>
</element>
<element name="TTimePopupForm.KeepInView.PopupOrigin">
<short>Upper left coordinates where the form is displayed.</short>
</element>

<element name="TTimePopupForm.ReturnTime">
<short>Validates the current time value for the form.</short>
<descr>
<p>
<var>ReturnTime</var> is a procedure used to validate and possibly update the 
current time value for the form. <var>GetTime</var> is called to get the time 
value using the selected cells in the Hour and Minute grids.
</p>
<p>
ReturnTime signals the internal <var>TReturnTimeEvent</var> event handler 
(when assigned) to validate/update the time value. The TReturnTimeEvent event 
handler is passed as an argument to the <var>ShowTimePopup</var> routine.
</p>
<p>
The <var>Close</var> method is called to close the form if it has not already 
been hidden.
</p>
</descr>
<seealso>
<link id="TTimePopupForm.GetTime"/>
<link id="ShowTimePopup"/>
<link id="#lcl.forms.TCustomForm.Close">TCustomForm.Close</link>
</seealso>
</element>

<element name="TTimePopupForm.SetLayout">
<short>Sets the layout used in Minute grid for the form.</short>
<descr>
<p>
<var>SimpleLayout</var> indicates whether the Minutes grid on the form use 
the simple layout. Simple layout uses a 30 minute interval between cells in 
the grid, and offers a more compact appearance. When SimpleLayout is False, a 
5 minute interval is used between cells in the Minute grid.
</p>
</descr>
<seealso>
</seealso>
</element>
<element name="TTimePopupForm.SetLayout.SimpleLayout">
<short>Uses the compact 30 minute interval when True.</short>
</element>

<element name="TTimePopupForm.SetTime">
<short>Sets the time value displayed on the form.</short>
<descr/>
<seealso/>
</element>
<element name="TTimePopupForm.SetTime.ATime">
<short>Time value applied to the Hour and Minute grid.</short>
</element>

<element name="TTimePopupForm.FormClose">
<short>Performs actions needed when the form is closed.</short>
<descr>
<p>
<var>FormClose</var> reimplements the FormClose event handler for the form to 
ensure that the <var>FormDeactivate</var> method is removed from the 
registered deactivate handlers in the global <var>Application</var> instance. 
FormClose sets the value in <var>CloseAction</var> to <var>caFree</var> to 
free the form instance.
</p>
</descr>
<seealso>
<link id="TTimePopupForm.FormDeactivate"/>
<link id="#lcl.forms.Application">Application</link>
<link id="#lcl.forms.TApplication.RemoveOnDeactivateHandler">TApplication.RemoveOnDeactivateHandler</link>
</seealso>
</element>
<element name="TTimePopupForm.FormClose.Sender">
<short>Object for the event notification.</short>
</element>
<element name="TTimePopupForm.FormClose.CloseAction">
<short>Close action to perform on exit form the method.</short>
</element>

<element name="TTimePopupForm.FormCreate">
<short>Performs actions needed when the form instance is created.</short>
<descr>
<p>
<var>FormCreate</var> reimplements the FormCreate method to initialize the 
form instance, and register its deactivation handler. FormCreate sets the 
form to us the Simple layout, calls <var>SetLayout</var>, and registers the 
<var>FormDeactivate</var> method as a deactivation handler in the global 
<var>Application</var> instance.
</p>
</descr>
<seealso>
<link id="TTimePopupForm"/>
<link id="#lcl.forms.Application">Application</link>
<link id="#lcl.forms.TApplication.AddOnDeactivateHandler">TApplication.AddOnDeactivateHandler</link>
</seealso>
</element>
<element name="TTimePopupForm.FormCreate.Sender">
<short>Object for the event notification.</short>
</element>

<element name="TTimePopupForm.FormDeactivate">
<short>Performs action needed when the form is deactivated.</short>
<descr>
<p>
<var>FormDeactivate</var> reimplements the FormDeactivate event handler for 
the form. FormDeactivate call the <var>Hide</var> method to immediately hide 
the form. Otherwise, it would remain visible while in a Drag operation, for 
example. If not already active, the <var>Close</var> method is called prior 
to exiting from the method.
</p>
</descr>
<seealso>
<link id="TCustomForm.Close"/>
<link id="TCustomForm.Hide"/>
</seealso>
</element>
<element name="TTimePopupForm.FormDeactivate.Sender">
<short>Object for the event notification.</short>
</element>

<element name="ShowTimePopup">
<short>
Creates, initializes, and displays a TTimePopupForm instance.
</short>
<descr>
<p>
<var>ShowTimePopup</var> is a routine used to create, initialize, and display 
a <var>TTimePopupForm</var> instance. Arguments passed to the routine 
identify the time value and the control associated with the pop-up, event 
handlers assigned to the form instance, and the layout and position for the 
form.
</p>
</descr>
<seealso>
<link id="TTimePopupForm"/>
<link id="TReturnTimeEvent"/>
</seealso>
</element>
<element name="ShowTimePopup.Position">
<short>Coordinates where the form is displayed.</short>
</element>
<element name="ShowTimePopup.ATime">
<short>Initial time value for the form.</short>
</element>
<element name="ShowTimePopup.DoubleBufferedForm">
<short>Indicates if DoubleBuffered is enabled in the form instance.</short>
</element>
<element name="ShowTimePopup.OnReturnTime">
<short>Event handler signalled when the time value is changed.</short>
</element>
<element name="ShowTimePopup.OnShowHide">
<short>Event handler signalled when the form is show or hidden.</short>
</element>
<element name="ShowTimePopup.SimpleLayout">
<short>
<b>True</b> indicates the simple (compact) layout is used for the Minute grid 
on the form.
</short>
</element>
<element name="ShowTimePopup.ACaller">
<short>Control with the time value updated using the pop-up form.</short>
</element>

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