lazarus/docs/xml/lcl/calendar.xml

1150 lines
39 KiB
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">
<!--
====================================================================
Calendar
====================================================================
-->
<module name="Calendar">
<short>
Classes and types used to implement TCalendar, a graphic control allowing
selection of a date from a calendar display.
</short>
<descr>
<p>
<file>calendar.pp</file> contains classes and types used to implement
<var>TCalendar</var>, a graphic control allowing selection of a date from a
calendar display.
</p>
<p>
The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TCalendar</li>
</ul>
<p>
<file>calendar.pp</file> is part of the LCL (Lazarus Component Library).
</p>
</descr>
<!-- unresolved references -->
<element name="LCLProc"/>
<element name="Types"/>
<element name="SysUtils"/>
<element name="Classes"/>
<element name="LCLType"/>
<element name="LCLStrConsts"/>
<element name="LMessages"/>
<element name="Controls"/>
<element name="LResources"/>
<element name="Math"/>
<element name="TDisplaySetting">
<short>
Enumerated type with values that control display settings in TCalendar.
</short>
<descr>
<p>
<var>TDisplaySetting</var> is an enumerated type with values that control
display settings in <var>TCalendar</var>. Values from TDisplaySetting are
stored in the <var>TDisplaySettings</var> type.
</p>
<remark>
Use of a display setting requires it to also be implemented on the native
calendar control for a platform / widgetset. Most of the values in
TDisplaySetting are ignored for the Windows platform; only dsShowWeekNumbers
has the desired effect.
</remark>
<remark>
The value <var>dsStartMonday</var> has been removed in LCL version 2.2 or
higher.
</remark>
</descr>
<seealso>
<link id="DefaultDisplaySettings"/>
<link id="TCustomCalendar.DisplaySettings"/>
</seealso>
</element>
<element name="TDisplaySetting.dsShowHeadings">
<short>Displays a month/year heading.</short>
</element>
<element name="TDisplaySetting.dsShowDayNames">
<short>Displays day names.</short>
</element>
<element name="TDisplaySetting.dsNoMonthChange">
<short>Prevents changing the current month.</short>
</element>
<element name="TDisplaySetting.dsShowWeekNumbers">
<short>Displays week numbers.</short>
</element>
<element name="TDisplaySettings">
<short>Set type for TDisplaySetting values.</short>
<descr>
<p>
<var>TDisplaySettings</var> is a set type used to store enumerations values
from TDisplaySetting. It is the type used for the <var>DisplaySettings</var>
property in <var>TCustomCalendar</var>.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.DisplaySettings"/>
<link id="TDisplaySetting"/>
</seealso>
</element>
<element name="DefaultDisplaySettings">
<short>
Default display settings used in TCalendar.
</short>
<descr>
<p>
<var>DefaultDisplaySettings</var> is a constant with the default display
settings used in <var>TCalendar</var>. It is used as the default value for
the DisplaySettings property in TCustomCalendar / TCalendar.
</p>
<p>
DefaultDisplaySettings contains the following TDisplaySetting enumeration
values:
</p>
<dl>
<dt>dsShowHeadings</dt>
<dd>Displays the month/year heading.</dd>
<dt>dsShowDayNames</dt>
<dd>Displays day names.</dd>
</dl>
</descr>
<seealso>
<link id="TCustomCalendar.DisplaySettings"/>
<link id="TDisplaySettings"/>
<link id="TDisplaySetting"/>
</seealso>
</element>
<element name="TCalendarPart">
<short>
Indicates where a mouse click occurred in a calendar control.
</short>
<descr>
<p>
<var>TCalendarPart</var> is an enumerated type with values that indicate
where a mouse click occurred in a calendar control. TCalendarPart is used to
implement the TCustomCalendar.HitTest method.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.HitTest"/>
</seealso>
</element>
<element name="TCalendarPart.cpNoWhere">
<short>
Mouse click cannot be applied to the control; no handle available.
</short>
</element>
<element name="TCalendarPart.cpDate">
<short>Mouse click occurred on a date in the calendar control.</short>
</element>
<element name="TCalendarPart.cpWeekNumber">
<short>Mouse click occurred on a week number in the calendar control.</short>
</element>
<element name="TCalendarPart.cpTitle">
<short>Mouse click occurred on a day heading in the calendar control.</short>
</element>
<element name="TCalendarPart.cpTitleBtn">
<short>
Mouse click occurred on a navigation button in a calendar control.
</short>
</element>
<element name="TCalendarPart.cpTitleMonth">
<short>
Mouse click occurred on the month name heading in the calendar control.
</short>
</element>
<element name="TCalendarPart.cpTitleYear">
<short>
Mouse click occurred on the year number heading in the calendar control.
</short>
</element>
<element name="TCalendarView">
<short>
Defines the view for a calendar.
</short>
<descr>
<p>
<var>TCalendarView</var> is an enumeration type with values that define the
view for a calendar control. TCalendarView makes it possible to set the
calendar view introduced in Windows Vista or later. In other widgetsets, as
well as in older versions of Windows, a calendar has only a standard "month
view" grid with days representing a month. TCalendarView is used to implement
the TCustomCalendar.GetCalendarView method.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.GetCalendarView"/>
</seealso>
</element>
<element name="TCalendarView.cvMonth">
<short>Grid has days for one month.</short>
</element>
<element name="TCalendarView.cvYear">
<short>Grid has months in one year.</short>
</element>
<element name="TCalendarView.cvDecade">
<short>Grid has years from one decade.</short>
</element>
<element name="TCalendarView.cvCentury">
<short>Grid has decades for one century.</short>
</element>
<element name="TCalDayOfWeek">
<short>Represents days of the week used in TCalendar.</short>
<descr>
<p>
<var>TCalDayOfWeek</var> is an enumerated type with values which represent
the day used as the first day of the week in <var>TCustomCalendar</var> and
descendants.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.FirstDayOfWeek"/>
</seealso>
</element>
<element name="TCalDayOfWeek.dowMonday">
<short>Represents Monday.</short>
</element>
<element name="TCalDayOfWeek.dowTuesday">
<short>Represents Tuesday.</short>
</element>
<element name="TCalDayOfWeek.dowWednesday">
<short>Represents Wednesday.</short>
</element>
<element name="TCalDayOfWeek.dowThursday">
<short>Represents Thursday.</short>
</element>
<element name="TCalDayOfWeek.dowFriday">
<short>Represents Friday.</short>
</element>
<element name="TCalDayOfWeek.dowSaturday">
<short>Represents Saturday.</short>
</element>
<element name="TCalDayOfWeek.dowSunday">
<short>Represents Sunday.</short>
</element>
<element name="TCalDayOfWeek.dowDefault">
<short>
Use the default day of the week setting for the platform for the first day of
the week. Not compatible with the value used in Delphi (dowLocaleDefault).
</short>
</element>
<element name="EInvalidDate">
<short>
Exception raised for an invalid date in the calendar control.
</short>
<descr>
<p>
<var>EInvalidDate</var> is an exception raised when a invalid date is
selected in a calendar control.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.MinDate"/>
<link id="TCustomCalendar.MaxDate"/>
</seealso>
</element>
<element name="TCustomCalendar">
<short>
Implements the base class for <var>TCalendar</var>.
</short>
<descr>
<p>
<var>TCustomCalendar</var> is the base class for <var>TCalendar</var>, a
graphic control used to select a date value from the familiar monthly
calendar layout. It includes Date and DateTime properties with the selected
date as a String or a TDateTime value.
</p>
<p>
TCustomCalendar acts as a wrapper for the native calendar control on a given
platform. The range of dates allowed in a native calendar control varies by
platform. Starting in LCL version 3.0, TCustomCalendar includes MinDate and
MaxDate properties which can used to limit the dates displayed on the
calendar to a specified minimum and maximum date. Setting Date or DateTime to
a value outside the allowed range (when used) causes an EInvalidDate
exception to be raised.
</p>
<p>
Please note that MinDate and MaxDate are not supported on all platforms; they
are not implemented for GTK2 and GTK3 because the native calendar control
does not implement or enforce them.
</p>
<p>
DisplaySettings can be used to control the visual layout and behavior for the
calendar. This includes the first day of the week for the calendar layout as
well as use of headings, days names, and week numbers.
</p>
<p>
Use the OnChange, OnDayChanged, OnMonthChanged, and OnYearChanged event
handlers to perform actions needed when the date or its component values have
been modified on the calendar control.
</p>
<p>
Changes made to properties in the control are applied to the widgetset class
instance (the native calendar control) when its handle has been allocated.
</p>
</descr>
<seealso>
<link id="TCalendar"/>
<link id="#lcl.controls.TWinControl">TWinControl</link>
</seealso>
</element>
<!-- private -->
<element name="TCustomCalendar.FDateAsString"/>
<element name="TCustomCalendar.FDate"/>
<element name="TCustomCalendar.FDisplaySettings"/>
<element name="TCustomCalendar.FOnChange"/>
<element name="TCustomCalendar.FDayChanged"/>
<element name="TCustomCalendar.FMonthChanged"/>
<element name="TCustomCalendar.FYearChanged"/>
<element name="TCustomCalendar.FPropsChanged"/>
<element name="TCustomCalendar.FLimitsChanged"/>
<!-- private -->
<element name="TCustomCalendar.CheckRange"/>
<element name="TCustomCalendar.CheckRange.ADate"/>
<element name="TCustomCalendar.CheckRange.AMinDate"/>
<element name="TCustomCalendar.CheckRange.AMaxDate"/>
<element name="TCustomCalendar.GetDateTime">
<short>Gets the value for the DateTime property.</short>
</element>
<element name="TCustomCalendar.GetDateTime.Result">
<short>Value for the DateTime property.</short>
</element>
<element name="TCustomCalendar.GetMaxDateStored"/>
<element name="TCustomCalendar.GetMaxDateStored.Result"/>
<element name="TCustomCalendar.GetMinDateStored"/>
<element name="TCustomCalendar.GetMinDateStored.Result"/>
<element name="TCustomCalendar.SetDateTime">
<short>Sets the value for the DateTime property.</short>
</element>
<element name="TCustomCalendar.SetDateTime.AValue">
<short>New value for the DateTime property.</short>
</element>
<element name="TCustomCalendar.GetProps">
<short>Gets values for properties in the calendar control.</short>
</element>
<element name="TCustomCalendar.SetMaxDate"/>
<element name="TCustomCalendar.SetMaxDate.AValue"/>
<element name="TCustomCalendar.SetMinDate"/>
<element name="TCustomCalendar.SetMinDate.AValue"/>
<element name="TCustomCalendar.SetProps">
<short>Sets values for properties in the calendar control.</short>
</element>
<element name="TCustomCalendar.GetDisplaySettings">
<short>Gets the value for the DisplaySettings property.</short>
<seealso>
<link id="TCustomCalendar.DisplaySettings"/>
<link id="TDisplaySettings"/>
<link id="TDisplaySetting"/>
</seealso>
</element>
<element name="TCustomCalendar.GetDisplaySettings.Result">
<short>Value for the DisplaySettings property.</short>
</element>
<element name="TCustomCalendar.SetDisplaySettings">
<short>Sets the value for the DisplaySettings property.</short>
<seealso>
<link id="TCustomCalendar.DisplaySettings"/>
<link id="TDisplaySettings"/>
<link id="TDisplaySetting"/>
</seealso>
</element>
<element name="TCustomCalendar.SetDisplaySettings.AValue">
<short>New value for the DisplaySettings property.</short>
</element>
<element name="TCustomCalendar.GetDate">
<short>Gets the value for the Date property.</short>
</element>
<element name="TCustomCalendar.GetDate.Result">
<short>Value for the Date property.</short>
</element>
<element name="TCustomCalendar.SetDate">
<short>Sets the value for the Date property.</short>
</element>
<element name="TCustomCalendar.SetDate.AValue">
<short>New value for the Date property.</short>
</element>
<element name="TCustomCalendar.SetFirstDayOfWeek"/>
<element name="TCustomCalendar.SetFirstDayOfWeek.AValue"/>
<element name="TCustomCalendar.IsLimited"/>
<element name="TCustomCalendar.IsLimited.Result"/>
<element name="TCustomCalendar.ApplyLimits"/>
<element name="TCustomCalendar.RemoveLimits"/>
<!-- protected -->
<element name="TCustomCalendar.WSRegisterClass" link="#LCL.LCLClasses.TLCLComponent.WSRegisterClass"/>
<element name="TCustomCalendar.LMChanged">
<short>
Handles the LCL LM_CHANGED message received when the calendar control is
updated.
</short>
<descr>
<p>
<var>LMChanged</var> ensures that event handlers are signalled (when
assigned) when the value in DateTime is updated for the calendar control is
changed. It retrieves the new date value from the widgetset class instance,
and compares it to the existing value in DateTime. DecodeDateTime is used to
get the year, month, and day component values compared in the method. The new
value for DateTime is stored prior to comparing the values.
</p>
<p>
When the date or one of its component values has been changed, the
corresponding event handlers are signalled (when assigned) in the following
order:
</p>
<ul>
<li>OnYearChanged</li>
<li>OnMonthChanged</li>
<li>OnDayChanged</li>
<li>OnChange</li>
</ul>
<p>
An application can assign object procedures to the event handlers to respond
to the change notifications.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.OnYearChanged"/>
<link id="TCustomCalendar.OnMonthChanged"/>
<link id="TCustomCalendar.OnDayChanged"/>
<link id="TCustomCalendar.OnChange"/>
</seealso>
</element>
<element name="TCustomCalendar.LMChanged.Message">
<short>Message handled in the method.</short>
</element>
<element name="TCustomCalendar.LMMonthChanged">
<short>
Handles the LCL LM_MONTHCHANGED message received when the month has been
changed using the calendar control.
</short>
<descr>
<p>
The message is posted as a callback from the widgetset class when the active
month on the control is changed. It can occur when a new date is selected, or
when the GUI is used to change the visible month on the control.
<var>LMMonthChanged</var> ensures that event handlers are signalled (when
assigned) when the month displayed on the calendar control is changed. The
event handlers are signalled in the following order:
</p>
<ul>
<li>OnMonthChanged</li>
<li>OnChange</li>
</ul>
<p>
An application can assign object procedures to the event handlers to respond
to the change notifications.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.OnMonthChanged"/>
<link id="TCustomCalendar.OnChange"/>
</seealso>
</element>
<element name="TCustomCalendar.LMMonthChanged.Message">
<short>Message handled in the method.</short>
</element>
<element name="TCustomCalendar.LMYearChanged">
<short>
Handles the LCL LM_YEARCHANGED message received when the year number has been
changed on the calendar control.
</short>
<descr>
<p>
<var>LMYearChanged</var> handles the message posted as a callback from the
widgetset class when the year number on the control is changed. The message
occurs when the year number is changed as a result of using the navigation
controls on the calendar. It signals the OnYearChanged and OnChange event
handlers (when assigned).
</p>
<p>
An application can assign object procedures to the event handlers to respond
to the change notifications.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.OnYearChanged"/>
<link id="TCustomCalendar.OnChange"/>
</seealso>
</element>
<element name="TCustomCalendar.LMYearChanged.Message">
<short>Message handled in the method.</short>
</element>
<element name="TCustomCalendar.LMDayChanged">
<short>
Handles the LCL LM_DAYCHANGED message received when the day number has been
changed on the calendar control.
</short>
<descr>
<p>
<var>LMDayChanged</var> handles the message posted as a callback from the
widgetset class when the day number on the control is changed. The message
occurs when the day number is changed as a result of using the navigation
keys on the calendar, or when a new day number is clicked with the mouse. It
signals the OnDayChanged and OnChange event handlers (when assigned).
</p>
<p>
An application can assign object procedures to the event handlers to respond
to the change notifications.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.OnDayChanged"/>
<link id="TCustomCalendar.OnChange"/>
</seealso>
</element>
<element name="TCustomCalendar.LMDayChanged.Message">
<short>Message handled in the method.</short>
</element>
<element name="TCustomCalendar.GetControlClassDefaultSize">
<short>
Gets the default dimensions for a new instance of the control.
</short>
<descr>
<p>
<var>GetControlClassDefaultSize</var> is an overridden <var>TSize</var>
function in <var>TCustomCalendar</var>, and re-implements the method from the
ancestor class. It returns the default width and height for the control in
the CX and CY members for the TSize instance. Width (CX) is set to 220
pixels. Height (CY) is set to 190 pixels.
</p>
</descr>
<seealso>
<link id="#lcl.controls.TControl.GetControlClassDefaultSize">TControl.GetControlClassDefaultSize</link>
</seealso>
</element>
<element name="TCustomCalendar.Loaded">
<short>
Performs actions when the component has finished loading during LCL component
streaming.
</short>
<descr>
<p>
<var>Loaded</var> is an overridden method in <var>TCustomCalendar</var>, and
calls the inherited method on entry. It ensures that property values in the
class instance are posted to the widgetset class instance when its handle has
been allocated. At run-time, the following properties are updated in the
widget instance:
</p>
<ul>
<li>DateTime</li>
<li>DisplaySettings</li>
<li>FirstDayOfWeek</li>
<li>MinDate</li>
<li>MaxDate</li>
</ul>
</descr>
<seealso>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.DisplaySettings"/>
<link id="TCustomCalendar.FirstDayOfWeek"/>
<link id="TCustomCalendar.MinDate"/>
<link id="TCustomCalendar.MaxDate"/>
<link id="#lcl.controls.TWinControl.Loaded">TWinControl.Loaded</link>
</seealso>
</element>
<element name="TCustomCalendar.InitializeWnd" link="#lcl.controls.TWinControl.InitializeWnd"/>
<element name="TCustomCalendar.DestroyWnd" link="#lcl.controls.TWinControl.DestroyWnd"/>
<!-- public -->
<element name="TCustomCalendar.Create">
<short>
Constructor for the class instance.
</short>
<descr>
<p>
<var>Create</var> is the constructor for <var>TCustomCalendar</var>. Create
calls the inherited <var>Create</var> method, and sets the style, initial
bounds, and display settings for the calendar. Create sets the default date /
time value to Now, and initializes MinDate and MaxDate to the empty date/time
value (0.0).
</p>
</descr>
<seealso>
<link id="#lcl.controls.TWinControl.Create">TWinControl.Create</link>
</seealso>
</element>
<element name="TCustomCalendar.Create.TheOwner">
<short>Owner of the class instance.</short>
</element>
<element name="TCustomCalendar.HitTest">
<short>
Indicates where a mouse click occurred in the calendar control.
</short>
<descr>
<p>
HitTest is a TCalendarPart function that indicates where a mouse click
occurred in the calendar control. The return value indicates the part of the
control clicked, or cpNoWhere when the handle has not been allocated for the
control. HitTest ensures that the widget-set specific HitTest method is
called.
</p>
</descr>
</element>
<element name="TCustomCalendar.HitTest.APoint">
<short>Coordinates where the mouse click occurred.</short>
</element>
<element name="TCustomCalendar.GetCalendarView">
<short>Gets the current view for the Calendar.</short>
<descr>
<p>
<var>GetCalendarView</var> is a <var>TCalendarView</var> function used to get
the current view for the calendar control. It calls the GetCurrentView class
function in the widgetset class instance when its handle has been allocated.
It is used in components like TCalendarDialog and TCalendarPopupForm to
determine the active view when a Return or Space key is handled.
</p>
</descr>
<seealso>
<link id="TCalendarView"/>
<link id="#lcl.extdlgs.TCalendarDialog">TCalendarDialog</link>
<link id="#lcl.calendarpopup.TCalendarPopupForm">TCalendarPopupForm</link>
</seealso>
</element>
<element name="TCustomCalendar.GetCalendarView.Result">
<short>Current view for the Calendar.</short>
</element>
<element name="TCustomCalendar.Date">
<short>
String representation for the date value on the calendar control.
</short>
<descr>
<p>
<var>Date</var> is a String property that represents the value in DateTime as
a String data type.
</p>
<p>
Reading the value for the property causes both Date and DateTime to be read
from the widgetset class when its handle has been assigned. FormatDateTime is
used to convert the date value to a string type using the ShortDateFormat in
the DefaultFormatSettings variable. If the widget handle is not available,
the member value is used.
</p>
<p>
Setting a new value in Date causes the value in DateTime to be updated, and
the new values are applied to the widgetset class when its handle has been
allocated. An EConvertError exception is raised if the new property value is
not a valid date using the default format settings.
</p>
<p>
Use DateTime to read or write the date value using a TDateTime data type.
</p>
<p>
Use MinDate and MaxDate to set the lower and upper limits for the dates
displayed on the calendar control.
</p>
</descr>
<errors>
<p>
Raises an EConvertError exception when Date contains an invalid date value.
</p>
</errors>
<seealso>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.MinDate"/>
<link id="TCustomCalendar.MaxDate"/>
<link id="#rtl.sysutils.StrToDate">StrToDate</link>
<link id="#rtl.sysutils.DefaultFormatSettings">DefaultFormatSettings</link>
<link id="#rtl.sysutils.TFormatSettings">TFormatSettings</link>
<link id="#rtl.sysutils.EConvertError">EConvertError</link>
</seealso>
</element>
<element name="TCustomCalendar.DateTime">
<short>
Native data type used for a date value on the calendar control.
</short>
<descr>
<p>
<var>DateTime</var> is a <var>TDateTime</var> property with the date value
for the calendar control. It determines the initial month and year displayed
on the control, and the day of the month highlighted at run-time. It is
updated (along with Date) when a new date value is selected using the
calendar control.
</p>
<p>
Reading the value for the property causes both Date and DateTime members to
be retrieved from the widgetset class when its handle has been allocated. If
the handle is not available, the member value is used instead.
</p>
<p>
Setting a new value for the property causes the TDateTime value to be
validated. When MinDate and MaxDate contain non-zero date/time values that
are at least one day apart, the property must in the specified range limits.
When MinDate and MaxDate are not assigned, the RTL MinDateTime and
MaxDateTime constants are used to limit the range for the date value. An
EInvalidDate exception is raised when the date value is not valid for the
data type, or not within the required range.
</p>
<p>
FormatDateTime is called to convert the TDateTime value to its string
representation in Date. An EConvertError exception is raised if the date is
not valid or DefaultFormatSettings contains an invalid ShortDate format.
</p>
<p>
Changes to the property values are sent to the widgetset class instance when
its handle has been allocated. This includes values in the Date, DateTime,
MinDate, MaxDate, DisplaySettings, and FirstDayOfWeek properties.
</p>
<p>
Use the OnChange, OnDayChanged, OnMonthChanged, or OnYearChanged event
handlers to perform actions needed when the date (and its component values)
has been modified in the widget for the calendar control.
</p>
<remark>
The control does not use the time portion of the TDateTime data type. The
time value is not significant unless the specified time is not valid for the
date/time data type.
</remark>
</descr>
<errors>
<p>
EConvertError is raised when the value is not a valid for the TDateTime type.
</p>
<p>
EInvalidDate is raised when the date value is not within the range
represented by MinDate and MaxDate; raised with the message
rsInvalidDateRangeHint.
</p>
</errors>
<seealso>
<link id="TCustomCalendar.Date"/>
<link id="TCustomCalendar.MinDate"/>
<link id="TCustomCalendar.MaxDate"/>
<link id="TCustomCalendar.OnChange"/>
<link id="TCustomCalendar.OnYearChanged"/>
<link id="TCustomCalendar.OnMonthChanged"/>
<link id="TCustomCalendar.OnDayChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.DisplaySettings">
<short>
<var>DisplaySettings</var> contains options which control the appearance or
behavior for the calendar control.
</short>
<descr>
<p>
<var>DisplaySettings</var> contains options which control the appearance or
behavior for the calendar control. DisplaySettings is a set type which
contains zero or more TDisplaySetting values, including:
</p>
<dl>
<dt>dsShowHeadings</dt>
<dd>
Displays a Month/Year heading. Has no effect on the Windows platform; Month
and Year headings are always enabled.
</dd>
<dt>dsShowDayNames</dt>
<dd>
Displays Day names. Has no effect on the Windows platform; Day names are
always enabled.
</dd>
<dt>dsNoMonthChange</dt>
<dd>
Prevents changing the current month on the calendar. Has no effect on the
Windows platform; use MinDate and MaxDate to limit the available calendar
dates.
</dd>
<dt>dsShowWeekNumbers</dt>
<dd>Displays week numbers.</dd>
</dl>
<remark>
The value <var>dsStartMonday</var> is no longer available in LCL version 2.2
or higher. It has been replaced by the <var>FirstDayOfWeek</var> property on
platforms where the capability is supported (Win32, QT, QT5). This is Delphi
compatible, and allows any day of the week to be used as the first day of the
week.
</remark>
</descr>
<seealso>
<link id="TCustomCalendar.FirstDayOfWeek"/>
<link id="TDisplaySettings"/>
<link id="TDisplaySetting"/>
</seealso>
</element>
<element name="TCustomCalendar.FirstDayOfWeek">
<short>
Indicates the day of the week displayed as the first column in the calendar
grid.
</short>
<descr>
<p>
<var>FirstDayOfWeek</var> is a <var>TCalDayOfWeek</var> property which
indicates the day used as the first day of the week. It contains a value from
the TCalDayOfWeek enumeration, and determines the order of the cells
displayed in the calendar grid. The default value is <var>dowDefault</var>,
and indicates the default value provided by the platform or operating system
is used.
</p>
</descr>
<seealso>
<link id="TCalDayOfWeek"/>
</seealso>
</element>
<element name="TCustomCalendar.MaxDate">
<short>
Largest date value that can entered or selected using the calendar control.
</short>
<descr>
<p>
<var>MaxDate</var> is a <var>TDateTime</var> property which contains the
largest date value that can be stored or selected using the calendar control.
</p>
<p>
MinDate and MaxDate are used to range check the date value for the control,
and to avoid the exception raised when an invalid date is provided. They are
also used at run-time to determine the date values that can be displayed and
selected using the native calendar control.
</p>
<p>
The default value for MaxDate is an empty TDateTime value (0.0), and
indicates that the upper limit has not been assigned. Setting a new value for
the property causes the TDateTime value to be validated. The new value in
MaxDate must in the range defined by the RTL MinDateTime and MaxDateTime
constants.
</p>
<p>
When MinDate and MaxDate contain non-zero date/time values that are at least
one day apart, the value in DateTime must in the range represented by the
properties. When MinDate and MaxDate are not assigned, the RTL MinDateTime
and MaxDateTime constants are used to range limit the value in DateTime. An
EInvalidDate exception is raised when the date value is not valid for the
data type, or not within the required range.
</p>
<remark>
MinDate and MaxDate are not supported on all platforms. The values may not be
available or enforced in some widgetset implementations; GTK2 and GTK3 do not
use the values.
</remark>
</descr>
<version>
Introduced in LCL 2.3, and available in LCL versions 3.0 and higher.
</version>
<seealso>
<link id="TCustomCalendar.MinDate"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.MinDate">
<short>
Smallest date value that can entered or selected using the calendar control.
</short>
<descr>
<p>
<var>MinDate</var> is a <var>TDateTime</var> property which contains the
smallest date value that can be stored or selected using the calendar control.
</p>
<p>
MinDate and MaxDate are used to range check the date value for the control,
and to avoid the exception raised when an invalid date is provided. They are
also used at run-time to determine the date values that can be displayed and
selected using the native calendar control.
</p>
<p>
The default value for MinDate is an empty TDateTime value (0.0), and
indicates that the lower limit has not been assigned. Setting a new value for
the property causes the TDateTime value to be validated. The new value in
MinDate must in the range defined by the RTL MinDateTime and MaxDateTime
constants.
</p>
<p>
When MinDate and MaxDate contain non-zero date/time values that are at least
one day apart, the value in DateTime must in the range represented by the
properties. When MinDate and MaxDate are not assigned, the RTL MinDateTime
and MaxDateTime constants are used to range limit the value in DateTime. An
EInvalidDate exception is raised when the date value is not valid for the
data type, or not within the required range.
</p>
<remark>
MinDate and MaxDate are not supported on all platforms. The values may not be
available or enforced in some widgetset implementations; GTK2 and GTK3 do not
use the values.
</remark>
</descr>
<version>
Introduced in LCL 2.3, and available in LCL versions 3.0 and higher.
</version>
<seealso>
<link id="TCustomCalendar.MaxDate"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.OnChange">
<short>
Event handler signalled when the calendar control has been changed.
</short>
<descr>
<p>
<var>OnChange</var> is a <var>TNotifyEvent</var> property with the event
handler signalled when the calendar control is changed. It occurs when a day
number is clicked on the calendar grid, and when the visible month is changed
on the control. OnChange is signalled from the LMChanged, LMDayChanged,
LMMonthChanged, and LMYearChanged methods. The event is signalled after the
new date value from the widget has been assigned to the members for the
DateTime and Date properties.
</p>
<p>
Applications can assign an object procedure to the event handler to respond
to the change notification.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.Date"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
<link id="TCustomCalendar.LMYearChanged"/>
<link id="TCustomCalendar.LMMonthChanged"/>
<link id="TCustomCalendar.LMDayChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.OnDayChanged">
<short>
Event handler signalled when the day number in DateTime has been changed
using the calendar control.
</short>
<descr>
<p>
<var>OnDayChanged</var> is a <var>TNotifyEvent</var> property that represents
the event handler signalled when the day number in the date/time value for
the control has changed. OnDayChanged is signalled from the LMChanged and
LMDayChanged methods. It occurs after the new date value from the widget has
been assigned to the members for the DateTime and Date properties.
</p>
<p>
Applications can assign an object procedure to the event handler to respond
to the change notification.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.Date"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
<link id="TCustomCalendar.LMDayChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.OnMonthChanged">
<short>
Event handler signalled when the month number in DateTime has been changed
using the calendar control.
</short>
<descr>
<p>
<var>OnMonthChanged</var> is a <var>TNotifyEvent</var> property that
represents the event handler signalled when the month number in the date/time
value for the control has changed. OnMonthChanged is signalled from the
LMChanged and LMMonthChanged methods. It occurs after the new date value from
the widget has been assigned to the members for the DateTime and Date
properties.
</p>
<p>
Applications can assign an object procedure to the event handler to respond
to the change notification.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.Date"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
<link id="TCustomCalendar.LMMonthChanged"/>
</seealso>
</element>
<element name="TCustomCalendar.OnYearChanged">
<short>
Event handler signalled when the year number in DateTime has been changed
using the calendar control.
</short>
<descr>
<p>
<var>OnYearChanged</var> is a <var>TNotifyEvent</var> property that
represents the event handler signalled when the year number in the date/time
value for the control has changed. OnMonthChanged is signalled from the
LMChanged and LMYearChanged methods. It occurs after the new date value from
the widget has been assigned to the members for the DateTime and Date
properties.
</p>
<p>
Applications can assign an object procedure to the event handler to respond
to the change notification.
</p>
</descr>
<seealso>
<link id="TCustomCalendar.Date"/>
<link id="TCustomCalendar.DateTime"/>
<link id="TCustomCalendar.LMChanged"/>
<link id="TCustomCalendar.LMYearChanged"/>
</seealso>
</element>
<element name="TCalendar">
<short>
<var>TCalendar</var> allows selection of a date from a calendar display.
</short>
<descr>
<p>
<var>TCalendar</var> is a <var>TCustomCalendar</var> descendant which
implements the graphic control used to select a date value from from the
familiar monthly calendar layout. It includes Date and DateTime properties
with the selected date as a String or a TDateTime value.
</p>
<p>
TCalendar / TCustomCalendar act as a wrapper for the native calendar control
on a given platform. The range of dates allowed in a native calendar control
varies by platform. Starting in LCL version 3.0, TCustomCalendar includes
MinDate and MaxDate properties which can used to limit the dates displayed on
the calendar to a specified minimum and maximum date. Setting Date or
DateTime to a value outside the allowed range (when used) causes an
EInvalidDate exception to be raised.
</p>
<p>
Please note that MinDate and MaxDate are not supported on all platforms; they
are not implemented for GTK2 and GTK3 because the native calendar control
does not implement or enforce them.
</p>
<p>
DisplaySettings can be used to control the visual layout and behavior for the
calendar. This includes the first day of the week for the calendar layout as
well as use of headings, days names, and week numbers.
</p>
<p>
Use the OnChange, OnDayChanged, OnMonthChanged, and OnYearChanged event
handlers to perform actions needed when the date or its component values have
been modified on the calendar control.
</p>
<p>
Changes made to properties in the control are applied to the widgetset class
instance (the native calendar control) when its handle has been allocated.
</p>
</descr>
<seealso>
<link id="TCustomCalendar"/>
</seealso>
</element>
<!-- published -->
<element name="TCalendar.Align" link="#lcl.controls.TControl.Align"/>
<element name="TCalendar.Anchors" link="#lcl.controls.TControl.Anchors"/>
<element name="TCalendar.AutoSize" link="#lcl.controls.TControl.AutoSize"/>
<element name="TCalendar.BorderSpacing" link="#lcl.controls.TControl.BorderSpacing"/>
<element name="TCalendar.Constraints" link="#lcl.controls.TControl.Constraints"/>
<element name="TCalendar.DateTime" link="#lcl.calendar.TCustomCalendar.DateTime"/>
<element name="TCalendar.DisplaySettings" link="#lcl.calendar.TCustomCalendar.DisplaySettings"/>
<element name="TCalendar.DoubleBuffered" link="#lcl.controls.TWinControl.DoubleBuffered"/>
<element name="TCalendar.FirstDayOfWeek" link="#lcl.calendar.TCustomCalendar.FirstDayOfWeek"/>
<element name="TCalendar.Hint" link="#lcl.controls.TControl.Hint"/>
<element name="TCalendar.MinDate" link="#lcl.calendar.TCustomCalendar.MinDate"/>
<element name="TCalendar.MaxDate" link="#lcl.calendar.TCustomCalendar.MaxDate"/>
<element name="TCalendar.ParentDoubleBuffered" link="#lcl.controls.TWinControl.ParentDoubleBuffered"/>
<element name="TCalendar.PopupMenu" link="#lcl.controls.TControl.PopupMenu"/>
<element name="TCalendar.ShowHint" link="#lcl.controls.TControl.ShowHint"/>
<element name="TCalendar.TabOrder" link="#lcl.controls.TWinControl.TabOrder"/>
<element name="TCalendar.Tabstop" link="#lcl.controls.TWinControl.TabStop"/>
<element name="TCalendar.Visible" link="#lcl.controls.TControl.Visible"/>
<element name="TCalendar.OnChange" link="#lcl.calendar.TCustomCalendar.OnChange"/>
<element name="TCalendar.OnChangeBounds" link="#lcl.controls.TControl.OnChangeBounds"/>
<element name="TCalendar.OnClick" link="#lcl.controls.TControl.OnClick"/>
<element name="TCalendar.OnDayChanged" link="#lcl.calendar.TCustomCalendar.OnDayChanged"/>
<element name="TCalendar.OnDblClick" link="#lcl.controls.TControl.OnDblClick"/>
<element name="TCalendar.OnEnter" link="#lcl.controls.TWinControl.OnEnter"/>
<element name="TCalendar.OnExit" link="#lcl.controls.TWinControl.OnExit"/>
<element name="TCalendar.OnKeyDown" link="#lcl.controls.TWinControl.OnKeyDown"/>
<element name="TCalendar.OnKeyPress" link="#lcl.controls.TWinControl.OnKeyPress"/>
<element name="TCalendar.OnKeyUp" link="#lcl.controls.TWinControl.OnKeyUp"/>
<element name="TCalendar.OnMonthChanged" link="#lcl.calendar.TCustomCalendar.OnMonthChanged"/>
<element name="TCalendar.OnMouseDown" link="#lcl.controls.TControl.OnMouseDown"/>
<element name="TCalendar.OnMouseEnter" link="#lcl.controls.TControl.OnMouseEnter"/>
<element name="TCalendar.OnMouseLeave" link="#lcl.controls.TControl.OnMouseLeave"/>
<element name="TCalendar.OnMouseMove" link="#lcl.controls.TControl.OnMouseMove"/>
<element name="TCalendar.OnMouseUp" link="#lcl.controls.TControl.OnMouseUp"/>
<element name="TCalendar.OnMouseWheel" link="#lcl.controls.TControl.OnMouseWheel"/>
<element name="TCalendar.OnMouseWheelDown" link="#lcl.controls.TControl.OnMouseWheelDown"/>
<element name="TCalendar.OnMouseWheelUp" link="#lcl.controls.TControl.OnMouseWheelUp"/>
<element name="TCalendar.OnMouseWheelHorz" link="#lcl.controls.TControl.OnMouseWheelHorz"/>
<element name="TCalendar.OnMouseWheelLeft" link="#lcl.controls.TControl.OnMouseWheelLeft"/>
<element name="TCalendar.OnMouseWheelRight" link="#lcl.controls.TControl.OnMouseWheelRight"/>
<element name="TCalendar.OnResize" link="#lcl.controls.TControl.OnResize"/>
<element name="TCalendar.OnUTF8KeyPress" link="#lcl.controls.TWinControl.OnUTF8KeyPress"/>
<element name="TCalendar.OnYearChanged" link="#lcl.calendar.TCustomCalendar.OnYearChanged"/>
<element name="Register">
<short>Registers components for use in the Lazarus IDE.</short>
<descr>
<p>
Register is the procedure used to register components for use in the Lazarus
IDE. The following components are added to the Lazarus IDE component palette:
</p>
<p>
<b>Misc</b> Tab
</p>
<ul>
<li>TCalendar</li>
</ul>
</descr>
</element>
</module>
<!-- Calendar -->
</package>
</fpdoc-descriptions>