From 0525ede13bfabc17535e1ee30af45c3f7f18dfc8 Mon Sep 17 00:00:00 2001 From: dsiders Date: Sat, 14 Oct 2023 06:04:35 +0100 Subject: [PATCH] Docs: LCL/xmlpropstorage. Updates content in TCustomXMLPropStorage, TXMLPropStorage topics. --- docs/xml/lcl/xmlpropstorage.xml | 143 +++++++++++++++++++++++++------- 1 file changed, 112 insertions(+), 31 deletions(-) diff --git a/docs/xml/lcl/xmlpropstorage.xml b/docs/xml/lcl/xmlpropstorage.xml index e0a3fa5db9..476d82d2b0 100644 --- a/docs/xml/lcl/xmlpropstorage.xml +++ b/docs/xml/lcl/xmlpropstorage.xml @@ -93,10 +93,52 @@ at: -Implements the base class for the XML Form's Session Properties Storage. +Implements the base class for XML storage of Form Session properties. - - + +

+TCustomXMLPropStorage is a TFormPropertyStorage +descendant used to save or restore properties values in an XML file. It +introduces new properties, methods, and members needed to read or write values +in an XML file. +

+

+Values read or written using the class are defined in the SessionProperties for +a TForm or a TFrame instance. At design-time, use the SessionProperties +property editor in the Object Inspector to maintain the property names. At +run-time, the property names can be assigned using a string like: +

+ +Form1.SessionProperties := 'Width;Height;Image1.Width'; + +

+Use the FileName property to specify where the XML content is stored. +

+

+Use the RootNodePath property to specify the path to a node in the XML document +where the XML content is stored. +

+

+At run-time, default handler routines (attached to the parent form) are used to +Save or Restore the content in the XML file when the form is created or +destroyed. +

+

+Use the StoredValues property to specify property names cannot be assigned +using the Object Inspector; this may be needed for properties which cannot be +represented as a singular value or does not have published visibility. Use the +OnSaveProperties and OnRestoreProperties event handlers to store or restore the +values for items in StoredValues. +

+

+A demonstration program is located in the examples directory at: +

+$(LazarusDir)/examples/propstorage + + + +TFormPropertyStorage + @@ -116,8 +158,7 @@ Gets the value for the FileName property. -The current value in the -TCustomXMLPropStorage.FileName property. +The current value for the FileName property. @@ -127,7 +168,7 @@ The current value in the -The current value of RootSection. +The current value for the RootSection property. @@ -147,52 +188,47 @@ Turns '.' notation into '/' notation for the XPATH-like implementation in -Property to access the TPropStorageXMLConfig. +Property to access the XML configuration file where the content is stored. - + +TPropStorageXMLConfig + -Ask the underlying storage object for an entry. +Ensures the underlying storage object is allocated at run-time. - -If the item is read-only. +True if the item is read-only. Not used in the method. -Frees an entry from the underlying storage object. +Frees the underlying storage object for the class instance. -Implements the actual reading of a value from the underlying storage -container. +Implements reading of a value from the underlying storage container. - The value of the section/ident requested. - The section to be read. - The ident to be read. - -If has no value then return this as default. +If no value is available then return this as the default value. @@ -202,15 +238,12 @@ Implements writing of a string value to the underlying storage container. - The section to be written. - The ident to be written. - The value to be written. @@ -220,7 +253,6 @@ Implements writing of a string value to the underlying storage container. - The path to the section that will be erased. @@ -229,21 +261,67 @@ Implements writing of a string value to the underlying storage container. Name of the file where the property data is saved in XML format. - + +

+Defaults to the application name with a '.xml' extension if no value is +specified in the property. +

+ -Name of the root object path on your XML file. - +Name of the root object path in the XML file. + +

+Provides the name path to the XML node where the property values are stored in +FileName. +

+ -Implements a class for XML Form Session Properties storage. +Implements a class for XML storage of Form Session properties. - + +

+TXMLPropStorage is a TCustomXMLPropStorage descendant +used to save or restore properties values using an XML file. It introduces new +properties, methods, and members needed to read or write values in an XML file. +

+

+Values read or written using the class are defined in the SessionProperties for +a TForm or TFrame instance. At design-time, use the SessionProperties property +editor in the Object Inspector to maintain the property names. At run-time, the +property names can be assigned using a string like: +

+ +Form1.SessionProperties := 'Width;Height;Image1.Width'; + +

+Use the FileName property to specify where the XML content is stored. +

+

+Use the RootNodePath property to specify the path to a node in the XML document +where the XML content is stored. +

+

+At run-time, default handler routines (attached to the parent form) are used to Save or Restore the content in the XML file. +

+

+Use the StoredValues property to specify property names cannot be assigned +using the Object Inspector; this may be needed for properties which cannot be +represented as a singular value or does not have published visibility. Use the +OnSaveProperties and OnRestoreProperties event handlers to store or restore the +values for items in StoredValues. +

+

+A demonstration program is located in the examples directory at: +

+$(LazarusDir)/examples/propstorage + TForm.SessionProperties TINIPropStorage @@ -513,10 +591,13 @@ Saves the content in XMLConfig to the specified TStream instance. Registers -TXMLPropStorage on the 'Misc' tab of the component palette. +TXMLPropStorage +on the 'Misc' tab in the component palette. - + +TXMLPropStorage +