Docs: LCL/shellctrls. Adds, updates topics for changes in 4fba6929.

docs/xml/lcl/shellctrls.xml

@@ -219,6 +219,7 @@ methods implemented in the descendent classes.
 </element>
 
 <element name="TCustomShellTreeView.FObjectTypes"/>
+<element name="TCustomShellTreeView.FPopulateDelayed"/>
 <element name="TCustomShellTreeView.FRoot"/>
 <element name="TCustomShellTreeView.FShellListView"/>
 <element name="TCustomShellTreeView.FFileSortType"/>
@@ -1528,51 +1529,81 @@ method, and when a new value is assigned to AutoSizeColumns property.
 </seealso>
 </element>
 
+<element name="TCustomShellListView.CreateHandle">
+<short>
+Creates the handle for the control and populates the Items property.
+</short>
+<descr>
+<p>
+<var>CreateHandle</var> is an overridden method in 
+<var>TCustomShellListView</var>. It calls the inherited method on entry to 
+allocate the handle for the windowed control with creation parameters and 
+window flags as needed. An internal flag is checked to determine if the 
+control is waiting for handle creation to finish loading the values in Items. 
+When set, PopulateWithRoot is called to load the file system entries in Items 
+and the flag is cleared.
+</p>
+<p>
+CreateHandle is called from methods in the ancestor class when HandleNeeded 
+is called for the class instance or its Parent.
+</p>
+</descr>
+<seealso>
+<link id="TCustomShellListView.Items"/>
+<link id="TCustomShellListView.PopulateWithRoot"/>
+<link id="TCustomShellListView.Root"/>
+<link id="#lcl.controls.TWinControl.CreateHandle">TWinControl.CreateHandle</link>
+<link id="#lcl.controls.TWinControl.HandleNeeded">TWinControl.HandleNeeded</link>
+<link id="#lcl.controls.TWinControl.HandleAllocated">TWinControl.HandleAllocated</link>
+</seealso>
+</element>
+
 <element name="TCustomShellListView.PopulateWithRoot">
 <short>
-Fills the list view with file system information for the root directory.
+Fills the list view with file system information for the directory in Root.
 </short>
 <descr>
 <p>
 <var>PopulateWithRoot</var> is a procedure used to fill the <var>Items</var> 
-in the list view with file system entries for the <var>Root</var> directory.
+property with file system entries for the directory specified in 
+<var>Root</var>.
 </p>
 <p>
-No actions are performed in the method at design-time, or when 
+No actions are performed in the method at design-time, or when Root contains 
-<var>Root</var> contains an empty string (<b>''</b>).
+an empty string (<b>''</b>). In addition, the actions may be delayed if the 
+Handle for control has not been allocated. An internal flag is set to 
+indicate the condition, and PopulateWithRoot will be called again when the 
+Handle is created in CreateHandle.
 </p>
 <p>
-<var>PopulateWithRoot</var> calls the internal <var>GetFilesInDir</var> 
+PopulateWithRoot calls the internal GetFilesInDir helper routine to get a 
-helper to get a list of file system items for the path which match the 
+list of file system items for the path which match the Mask and ObjectTypes 
-<var>Mask</var> and <var>ObjectTypes</var> specified for the control. Each of 
+specified for the control. Each of the files in the list are passed to 
-the files in the list are passed to <var>DoAddItem</var> / 
+DoAddItem / OnAddItem to determine if they can be added to the Items property.
-<var>OnAddItem</var> to determine if they can be added to the 
-<var>Items</var> in the control.
 </p>
 <p>
-A <var>TListItem</var> instance is added to Items to represent the files or 
+A TListItem instance is added to Items to represent each of the files or 
-directories. The <var>Data</var> property in the list item is used to store a 
+directories. The Data property in the list item is used to store a pointer to 
-pointer to the file size. Values are added to <var>SubItems</var> with the 
+the file size. Values are added to SubItems in the list item to store the
 string representation for the file size, and the file extension.
 </p>
 <p>
-When <var>UseBuiltInIcons</var> is set to <b>True</b>, the 
+When UseBuiltInIcons is set to <b>True</b>, the GetBuiltInImageIndex method 
-<var>GetBuiltInImageIndex</var> method is called to get the 
+is called to get the ImageIndex for the built-in icon on a list item. This 
-<var>ImageIndex</var> for the built-in icon for a list item. This action is 
+action is performed using the path to the current file name when LargeImages 
-performed using the path to the current file name when LargeImages and/or 
+and/or SmallImages have not been assigned. The value in ViewStyle determines 
-SmallImages have not been assigned. The value in <var>ViewStyle</var> 
+the image size requested. When ViewStyle is <var>vsIcon</var>, LargeImages is 
-determines the image size requested. When ViewStyle is <var>vsIcon</var>, 
+checked (when assigned). Otherwise, SmallImages is checked (when assigned). 
-LargeImages is checked (when assigned). Otherwise, <var>SmalImages</var> is 
+If an image list exists in either LargeImages or SmallImages, the existing 
-checked (when assigned). If an imagelist exists in either LargeImages or 
+ImageIndex in the list item is used.
-SmallImages, the existing ImageIndex in the list item is used.
 </p>
 <p>
-The <var>OnFileAdded</var> event handler is signalled (when assigned) for 
+The OnFileAdded event handler is signalled (when assigned) for each new entry 
-each new entry added to Items.
+added to Items.
 </p>
 <p>
-The <var>Sort</var> method is called prior to exit to order the Items in the 
+The Sort method is called prior to exit to order the Items in the control 
-control using the option specified in the <var>FileSortType</var> property.
+using the option specified in the FileSortType property.
 </p>
 </descr>
 <seealso>
@@ -1585,6 +1616,7 @@ control using the option specified in the <var>FileSortType</var> property.
 <link id="TCustomShellListView.DoAddItem"/>
 <link id="TCustomShellListView.OnAddItem"/>
 <link id="TCustomShellListView.OnFileAdded"/>
+<link id="TCustomShellListView.CreateHandle"/>
 <link id="TAddItemEvent"/>
 <link id="TCSLVFileAddedEvent"/>
 </seealso>
@@ -2021,7 +2053,6 @@ the Windows platform only.
 </remark>
 </descr>
 <seealso>
-<link id="TCustomShellListView.GetBuiltInImageIndex"/>
 <link id="TCustomShellListView.Items"/>
 <link id="TCustomShellListView.PopulateWithRoot"/>
 <link id="TListItem.ImageIndex"/>