From 471bba54b89dbe16ecdd6f70da842c031632d8c4 Mon Sep 17 00:00:00 2001 From: dsiders Date: Sat, 6 Jan 2024 20:27:50 +0000 Subject: [PATCH] Docs: LCL/comctrls. Adds topics for changes in 76bbc6e2. Issue #19169. * TLVChangingEvent * TCustomListView.CanChange * TCustomListView.OnChanging * TListView.OnChanging --- docs/xml/lcl/comctrls.xml | 175 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 175 insertions(+) diff --git a/docs/xml/lcl/comctrls.xml b/docs/xml/lcl/comctrls.xml index 1d708d15ee..d628ef8006 100644 --- a/docs/xml/lcl/comctrls.xml +++ b/docs/xml/lcl/comctrls.xml @@ -12122,6 +12122,75 @@ TLVChangeEvent is the type used for the OnChange property in Indicates the property value that was changed in Item. + + +Defines an event handler signalled when a widgetset class is updating an item +on a list view control. + + +

+TLVChangingEvent is an object procedure used to define the event +handler signalled when a list item on a TListView is being updated by the +widgetset class instance. It is the type used to implement the OnChanging +property in TCustomListView, and allows the pending change to be accepted or +rejected on an item-by-item basis. +

+

+The Sender argument contains the object for the event notification, +It must be cast to TCustomListView to access properties and methods specific to +the list view control. +

+

+Item contains the TListItem instance on the list view control which +is being updated, and the values for the modified list item. +

+

+Change indicates which value in Item is being modified: the caption +text, the image for the item, or the item drawing state. See TItemChange for +the values used in the argument, and their meanings. +

+

+AllowChange is a variable Boolean argument which allows the handler +to indicate whether the change is accepted or rejected. Set AllowChange to +False to reject the modified value in Item. +

+

+See TCustomListView.OnChanging +for more information about the event notification for the list view control. +

+ + +Added in LCL version 4.0. + + + + + + + + + + +Object (TCustomListView control) for the event notification. + + + + +List item with the pending change, + + + + +Identifies the list item value changed in the notification. + + + + +Indicates whether the change is accepted or rejected in the event handler. +True for an accepted change. + + + Specifies an event handler used to locate a list view item using the @@ -13356,6 +13425,7 @@ and List View Work Areas. + @@ -14110,6 +14180,13 @@ item are changed. CNNotify updates property values and calls methods in the class instance as needed to respond to the notification message.

+

+Please note that LVN_ITEMCHANGING control notification is handled in the +ListViewParentMsgHandler routine in the widgetset class for the Windows +platform. Changes are accepted and applied when CanChange in the list view +control returns True. No additional processing is performed for the +notification message in the Windows message process loop. +

 @@ -14531,6 +14608,63 @@ the programmer has assigned a method to this event. + + +Indicates whether a change notification can be applied for an item on the list +view control. + + +

+CanChange is a Boolean function used to determine whether +a change notification message for an item in a list view control can be +accepted and applied. CanChange is called from the widgetset class instance, +and occurs when change notification messages are handled for the list view +control. +

+

+CanChange signals the OnChanging event handler (when assigned) to determine the +return value for the method. The return value is True if the changed +value in AItem is accepted and can be applied to the list item. The return +value is False if the modification is rejected in the OnChanging event +handler. +

+ +Interestingly, the return value is True if AChange contains an Integer value +that is not represented in the TItemChange enumeration. In this case, +the OnChanging event is not signalled. + +

+In the current LCL implementation, CanChange and OnChanging apply to the +Windows widgetset only. Other platforms do not generate a change notification +for item values. +

+ + +Added in LCL version 4.0. + + + + + + + + + +Returns True if the modified value in the list item is accepted. + + + + +List item with the modified value examined in the method. + + + + +Indicates which value in the list item has been modified. Corresponds to the +ordinal values in the TItemChange enumeration. + + + Performs actions to handle a mouse click on a Report view column header. @@ -16200,6 +16334,46 @@ a list item has been changed. + + +Event handler signalled when a change notification is received for a list item. + + +

+OnChanging is a TLVChangingEvent property with the event +handler signalled when a change notification is handled for the list view +control. It allows modifications to list items to be handled on an item-by-item +basis. It is signalled from the CanChange method (when assigned), and occurs +when the widgetset class handles change notification messages for the control. +

+

+An application can implement and assign a handler to the property to determine +whether a pending change is accepted or rejected for a list item. +

+

+See TItemChange for the changes items or states +available in the event notification. +

+

+See TLVChangingEvent for more information +about the event type and its arguments. +

+

+Please note that CanChange and OnChanging are relevant for the Windows platform +only. Other platforms do not generate or handle change notifications for list +item values. +

+ + +Added in LCL version 4.0. + + + + + + + + Event handler signalled when a column header for the control is clicked. @@ -18417,6 +18591,7 @@ GetRGBColorResolvingParent method. +