From 87907d602832d4d1c9279a1adbae3a035d4a1723 Mon Sep 17 00:00:00 2001 From: dsiders Date: Mon, 6 Feb 2023 00:34:33 +0000 Subject: [PATCH] Docs: DateTimeCtrls/datetimepicker. Adds missing content in topics. Removes redundant whitespace. --- .../datetimectrls/docs/datetimepicker.xml | 380 ++++++++++++++---- 1 file changed, 296 insertions(+), 84 deletions(-) diff --git a/components/datetimectrls/docs/datetimepicker.xml b/components/datetimectrls/docs/datetimepicker.xml index 0152625d74..d6783b2452 100644 --- a/components/datetimectrls/docs/datetimepicker.xml +++ b/components/datetimectrls/docs/datetimepicker.xml @@ -13,7 +13,7 @@ Implements a date/time picker control.

datetimepicker.pas contains an implementation of a date/time -picker control patterned after the Delphi VCL control with the same name. +picker control patterned after the Delphi VCL control with the same name. It contains a cross-platform LCL control which would resemble the VCL TDateTimePicker control as much as possible.

@@ -116,7 +116,7 @@ In the LCL, dates behave uniformly as much as possible -- we do not allow dates -Contains the class reference used to create calendar controls for the platform. +Contains the class reference used to create calendar controls for the platform.

@@ -387,7 +387,7 @@ date/time control. Set type used to stored values from the TDateTimePart enumeration. - + @@ -396,7 +396,7 @@ Set type used to stored values from the TDateTimePart enumeration. Set type used to stored values from the TDateTimePart enumeration which are effectively visible on a date/time control. - + @@ -417,7 +417,7 @@ Uses a small variant of the classic drop-down arrow (filled triangular shape). Uses a larger variant of the classic drop-down arrow (filled triangular -shape). +shape). @@ -518,7 +518,7 @@ TDateTimePicker control. The OnChange handler for the control is signalled when the date/time is -programmatically changed. +programmatically changed. @@ -571,13 +571,14 @@ Base class for date/time picker controls.

-TCustomDateTimePicker is a TCustomControl descendant. It is the base class for -date/time picker controls like TDateTimePicker and TDBDateTimePicker. The -control allows the user to enter Date, Time, or DateTime values. It -incorporates a button on the control to display a drop-down calendar for date -values, or up and down buttons to increment and decrement the numeric values -in a time. Individual parts in the date/time values can be changed using the -Up and Down cursor keys, or by entering the value directly into the control. +TCustomDateTimePicker is a TCustomControl descendant. It is the +base class for date/time picker controls like TDateTimePicker and +TDBDateTimePicker. The control allows the user to enter Date, Time, or +DateTime values. It incorporates a button on the control to display a +drop-down calendar for date values, or up and down buttons to increment and +decrement the numeric values in a time. Individual parts in the date/time +values can be changed using the Up and Down cursor keys, or by entering the +value directly into the control.

TCustomDateTimePicker uses locale-specific settings to format and display @@ -868,7 +869,7 @@ AutoResizeButton is set to True. Window message with the new width and height for the control. - + @@ -980,7 +981,7 @@ the control. True causes the value in IsRightToLeft to be ignored, and the check box is drawn on the left-hand side of the control. - + @@ -1105,7 +1106,7 @@ GetTextOrigin is also used in calculating the preferred size for the control. TPoint instance with the upper-left corner where the text for the control is drawn. - + @@ -1292,7 +1293,7 @@ ShowCheckBox is enabled. The Invalidate method is called to redraw the control. Shift, Ctrl, or Alt modifier for the mouse event. - + @@ -1334,7 +1335,7 @@ Mouse button for the event. Shift, Ctrl, or Alt modifier for the mouse event. - + @@ -1489,7 +1490,7 @@ another control. -Performs actions needed when the control is clicked. +Performs actions needed when the control is clicked.

@@ -1548,7 +1549,7 @@ Mouse button for the event. -Shift, Ctrl, or Alt modifier for the mouse event. +Shift, Ctrl, or Alt modifier for the mouse event. @@ -1564,7 +1565,7 @@ Vertical coordinate for the mouse pointer. -Handles a key up notification for the control. +Handles a key up notification for the control.

@@ -1594,7 +1595,7 @@ Virtual key code for the key up notification. -Shift, Ctrl, or Alt modifiers for the key up notification. +Shift, Ctrl, or Alt modifiers for the key up notification. @@ -2112,19 +2113,21 @@ MinDate or MaxDate values. - + +Value assigned to DateTime. + Anchors, aligns and resizes the control and its button(s). - +

Called when the value in BiDiMode or ShowCheckBox is changed, and when the window handle is created for the control in CreateWnd method.

- + @@ -2138,6 +2141,7 @@ value has been changed. + @@ -2202,73 +2206,189 @@ keys applied to the control result in a new Date or Time value. - - - + +Applies an automatic layout policy and scaling proportions to the control. + + +

+DoAutoAdjustLayout is an overridden method in +TCustomDateTimePicker. It calls the inherited method on entry to resize the +control using the specified layout policy and scaling factors. It ensures that +the width for drop-down or up/down button on the control is scaled from its +default value to the PPI setting used in the Font. +

+

+Font scaling is performed in AutoAdjustLayout (when needed) and occurs prior +to calling DoAutoAdjustLayout. +

+ + +TControl.DoAutoAdjustLayout + - + +Automatic layout policy applied in the method. It is a value from the +TLayoutAdjustmentPolicy enumeration, and determines whether horizontal / +vertical / or both sizes are adjusted in the method. It generally reflects the +constraints for the device type where the application is running. + - + +Scaling factor applied to the horizontal size in the control. + - + +Scaling factor applied to the vertical size in the control. + - - + +Adds the specified handler routine to the internal list of OnChange event +handlers for the control. + + +

+AddHandlerOnChange ensures that the internal TMethodList for the +class instance has been allocated, and calls its Add method using the +specified argument values. +

+ - + +Handler routine added to the handler list in the method. + - + +True if the handler routine is stored as the first handler in the list. +False if it is appended to end of the list. + - - + +Adds the specified handler routine to the internal list of OnCheckBoxChange +events handlers for the control. + + +

+AddHandlerOnCheckBoxChange ensures that the internal TMethodList +for the class instance has been allocated, and calls its Add method using the +specified argument values. +

+ - + +Handler routine added to the handler list in the method. + - - + +True if the handler routine is stored as the first handler in the list. +False if it is appended to end of the list. + - + +Removes the specified OnChange handler routine from the internal list for the +handler type. + - + + + - + +Handler routine removed in the method. + - + +Removes the specified OnCheckBoxChange handler routine from the internal list +for the handler type. + - + +Handler routine removed in the method. + - - - + +Set with the date/time parts which are effectively hidden on the control. + + +

+EffectiveHideDateTimeParts is a read-only TEffectiveDateTimeParts +property which contains the date/time parts which are effectively hidden for +the control. Values are included in the set to indicate that specific date/ +time parts are not visible for the configuration settings in the control, or +explicitly hidden using the HideDateTimeParts property. +

+

+Properties which affect date/time part visibility include: +

+
    +
  • Kind
    • +
  • TimeDisplay
    • +
  • TimeFormat
    • +
  • HideDateTimeParts
    • +
+

+The TDateTimePart values in EffectiveHideDateTimeParts are determined when a +new value is assigned to one of these properties. +

+ + + + + + + + + - - - + +Indicates the effective display order for the date parts on the control. + + +

+EffectiveDateDisplayOrder is a read-only TDateDisplayOrder property +which contains the effective order for the date parts displayed on the +control. It reflects the order for the date found parts found when +DateDisplayOrder contains ddoTryDefault. +

+

+The value for the property is assigned when the value in the DateDisplayOrder +property is changed. It indicates the order for the date parts found in the +date formats from DefaultFormatSettings. The tokens in the short date format +are examined to determine the order for the date parts. If an order cannot be +determined using the short date format, the long date format in +DefaultFormatSettings is checked. If an order cannot be determined using +either format value, the order indicated by ddoYMD is used. +

+ + + + +SysUtils.DefaultFormatSettings + @@ -2633,26 +2753,33 @@ additional OnChange handler routines for the control. - + +Event handler signalled when the Checked state for a check box on the control has been changed. + - + +Event handler signalled when the drop-down calendar dialog for the control has +been displayed. + - + +Event handler signalled when the drop-down calendar dialog has been closed. + -Displays a check box on the control when enabled. +Displays a check box on the control when enabled.

@@ -2879,7 +3006,7 @@ Use HideDateTimeParts to hide any date/time part which would otherwise be visible for the settings in Kind, DateDisplayOrder, TimeDisplay and TimeFormat properties.

- + @@ -2935,7 +3062,7 @@ normally visible for the property settings in the control. -The Time value displayed and edited using the control. +The Time value displayed and edited using the control.

@@ -2978,7 +3105,7 @@ settings in the properties. -The Date value displayed and edited using the control. +The Date value displayed and edited using the control.

@@ -3059,7 +3186,7 @@ Enables updates to affected date/time parts when the value for a date/time part is cycled beyond its upper or lower limits. -

+

Cascade is a Boolean property which indicates if a change to the value for a date/time part (like Day number) can increase or decrease the value in another date/time part (like Month or Year number). @@ -3120,7 +3247,7 @@ when the current selection is filled with a valid value for the part. Contains the user-specified set of date/time parts which are hidden on the -control. +control.

@@ -3516,28 +3643,50 @@ control, which includes:

  • MinDate (TheSmallestDate)
  • MaxDate (TheSmallestDate)
  • CenturyFrom (1941)
    • +
  • +CustomMonthNames (Resources allocated and configured to redraw the control +when changed). +

    • Create sets the value for each of the text segments used during editing of the date or time parts to an empty string ('').

    -The effect display order and visibility for the date/time parts is initially -determined in the method. +The effective display order and visibility for the date/time parts is +initially determined in the method.

    - + +Owner of the class instance which receives notification events. + Destructor for the class instance. - - + +

    +Destroy is the overridden destructor for the class instance. It +frees resources allocated in the class instance, including: +

    +
      +
    • The drop-down or up/down button.
      • +
    • OnChange handler(s).
      • +
    • OnCheckBoxChange handler(s).
      • +
    • The TStringList instance for CustomMonthNames.
      • +
    +

    +Destroy calls the inherited method prior to exit to free the class instance. +

    +     + + +     @@ -3568,7 +3717,9 @@ Adjusts the selected text part to ensure it is on one of the values used for a Date. - + + + @@ -3577,7 +3728,9 @@ Adjusts the selected text part to ensure it is on one of the values used for a Time. - + + + @@ -3586,41 +3739,100 @@ Validates and applies the specified character to the control.

    -Handles the following character values: +SendExternalKey handles the following character values in +AKey:

    -
    'N'
    -
    Sets DateTime to the NullDate value.
    +
    'N', 'n'
    +
    +Applies the value in NullDate to the DateTime value for the control. +
    '0'..'9'
    Applied to the value for the selected text part.
    -
    'A', 'P'
    -
    Applied to the AM/PM indicator in a 12-hour time value.
    +
    'A', P'
    +
    Applied to the AM/PM indicator in a 12-hour time value when selected.
    +

    +Values in the LeadingZeros, AutoAdvance, and Options properties are enforced +after the character value is applied to the control. +

    +

    +No actions are performed in the method if the control or its text parts are +not Enabled, or ReadOnly is set to True. +

     - + + +     -Character value examined and optionally applied to the control. +Character value examined and optionally applied to the control. - - - + +Validates and applies the specified virtual key code to the control. + + +

    +SendExternalKeyCode handles the following virtual key values in +Key: +

    +
    +
    VK_N ('N')
    +
    Sets DateTime to the NullDate value.
    +
    VK_0..VK_9 ('0'..'9')
    +
    Applied to the value for the selected text part.
    +
    VK_A ('A'), VK_P ('P')
    +
    Applied to the AM/PM indicator in a 12-hour time value when selected.
    +
    +

    +If the text parts are enabled for the control, the value in Key is converted +to its character equivalent and SendExternalKey is used to apply the character +value. +

    +

    +If text parts are not enabled, the following value is handled for the control: +

    +
    +
    VK_SPACE (#32)
    +
    Toggles the check box state when ShowCheckBox is set to True.
    +
    +     + + +     - + +Virtual key code examined and optionally applied to the control. + - + +Removes all event handler routines for the specified object. + - +

    +RemoveAllHandlersOfObject is an overridden method in +TCustomDateTimePicker. It calls the inherited method on entry to remove all +event handlers attached to the TObject instance in AnObject. It calls the +RemoveAllMethodsOfObject method in the internal TMethodList instances in the +control to free the handler types maintained in TCustomDateTimePicker. +

    + +TControl.RemoveAllHandlersOfObject +TControlHandlerType +TMethodList.RemoveAllMethodsOfObject +     - + +Object instance with the event handler routines removed in the method. + @@ -3672,7 +3884,7 @@ Performs actions needed when editing has been completed in the control. -implements a date/time picker control. +Implements a date/time picker control.

    @@ -3846,11 +4058,11 @@ for the TDateTime type. Returns True if the specified value is Not A Number (NAN), contains the Infinite value, or is outside the minimum and maximum values for the type. - + -TDateTime value examined in the routine. +TDateTime value examined in the routine.