lazarus/docs/xml/lcl/xmlpropstorage.xml

<?xml version="1.0" encoding="UTF-8"?>
<fpdoc-descriptions>
  <package name="lcl">

    <!--
      ====================================================================
      XMLPropStorage
      ====================================================================
    -->

    <module name="XMLPropStorage">
      <short>
        Contains a component that stores Form Session Properties in XML format.
      </short>
      <descr>
        <p>
          In this unit you can find an implementation of a name/value pair storage container in XML format.
        </p>
        <p>
          This container will get the Form's Session Properties that you setup in <link id="#LCL.Forms.TForm">TForm.SessionProperties</link> and read/write them on the file you specify on <link id="#LCL.XmlPropStorage.TXMLPropStorage.FileName">TXMLPropStorage.FileName</link>.
        </p>
      </descr>

      <!-- unresolved type references -->
      <element name="Classes"/>
      <element name="SysUtils"/>
      <element name="XMLConf"/>
      <element name="DOM"/>
      <element name="XMLRead"/>
      <element name="XMLWrite"/>
      <element name="LCLProc"/>
      <element name="Forms"/>
      <element name="LazConfigStorage"/>
      <element name="LazUTF8"/>

      <!-- object Visibility: default -->
      <element name="TPropStorageXMLConfig">
        <short>
          Wrapper class around <url href="http://wiki.freepascal.org/xmlconf">XMLConf</url>.<url href="http://wiki.freepascal.org/TXMLConfig">TXMLConfig</url>.
        </short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- object TPropStorageXMLConfig -->

      <!-- procedure Visibility: public -->
      <element name="TPropStorageXMLConfig.DeleteSubNodes">
        <short>Deletes sub nodes on a path.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TPropStorageXMLConfig.DeleteSubNodes -->

      <!-- argument Visibility: default -->
      <element name="TPropStorageXMLConfig.DeleteSubNodes.ARootNode">
        <short>The path of the node to have it's sub nodes deleted.</short>
      </element> <!-- argument TPropStorageXMLConfig.DeleteSubNodes.ARootNode -->

      <!-- procedure Visibility: public -->
      <element name="TPropStorageXMLConfig.LoadFromStream">
        <short>Loads XML content from a stream.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TPropStorageXMLConfig.LoadFromStream -->

      <!-- argument Visibility: default -->
      <element name="TPropStorageXMLConfig.LoadFromStream.s">
        <short>The stream to load the XML content from.</short>
      </element> <!-- argument TPropStorageXMLConfig.LoadFromStream.s -->

      <!-- procedure Visibility: public -->
      <element name="TPropStorageXMLConfig.SaveToStream">
        <short>Saves XML content to a stream.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TPropStorageXMLConfig.SaveToStream -->

      <!-- argument Visibility: default -->
      <element name="TPropStorageXMLConfig.SaveToStream.s">
        <short>The stream to save the XML content to.</short>
      </element> <!-- argument TPropStorageXMLConfig.SaveToStream.s -->

      <!-- property Visibility: public -->
      <element name="TPropStorageXMLConfig.XMLDoc">
        <short>Contains the XML document.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- property TPropStorageXMLConfig.XMLDoc -->

      <!-- object Visibility: default -->
      <element name="TCustomXMLPropStorage">
        <short>
          Implements the base class for the XML Form's Session Properties Storage.
        </short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- object TCustomXMLPropStorage -->

      <!-- variable Visibility: private -->
      <element name="TCustomXMLPropStorage.FCount">
        <short />
        <descr />
        <seealso />
      </element> <!-- variable TCustomXMLPropStorage.FCount -->

      <!-- variable Visibility: private -->
      <element name="TCustomXMLPropStorage.FFileName">
        <short />
        <descr />
        <seealso />
      </element> <!-- variable TCustomXMLPropStorage.FFileName -->

      <!-- variable Visibility: private -->
      <element name="TCustomXMLPropStorage.FXML">
        <short />
        <descr />
        <seealso />
      </element> <!-- variable TCustomXMLPropStorage.FXML -->

      <!-- variable Visibility: private -->
      <element name="TCustomXMLPropStorage.FRootNode">
        <short />
        <descr />
        <seealso />
      </element> <!-- variable TCustomXMLPropStorage.FRootNode -->

      <!-- variable Visibility: private -->
      <element name="TCustomXMLPropStorage.FRootNodePath">
        <short />
        <descr />
        <seealso />
      </element> <!-- variable TCustomXMLPropStorage.FRootNodePath -->

      <!-- function Visibility: protected -->
      <element name="TCustomXMLPropStorage.GetXMLFileName">
        <short>Getter for the property <link id="#LCL.XmlPropStorage.TCustomXMLPropStorage.FileName">TCustomXMLPropStorage.FileName</link>.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- function TCustomXMLPropStorage.GetXMLFileName -->

      <!-- function result Visibility: default -->
      <element name="TCustomXMLPropStorage.GetXMLFileName.Result">
        <short>
          The current value of the property <link id="#LCL.XmlPropStorage.TCustomXMLPropStorage.FileName">TCustomXMLPropStorage.FileName</link>.
        </short>
      </element> <!-- function result TCustomXMLPropStorage.GetXMLFileName.Result -->

      <!-- function Visibility: protected -->
      <element name="TCustomXMLPropStorage.RootSection">
        <short>Returns the name of the RootSection.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- function TCustomXMLPropStorage.RootSection -->

      <!-- function result Visibility: default -->
      <element name="TCustomXMLPropStorage.RootSection.Result">
        <short>The current value of RootSection.</short>
      </element> <!-- function result TCustomXMLPropStorage.RootSection.Result -->

      <!-- function Visibility: protected -->
      <element name="TCustomXMLPropStorage.FixPath">
        <short>
          Turns '.' notation into '/' notation for the XPATH-like implementation in <url href="http://wiki.freepascal.org/xmlconf">XMLConf</url>.
        </short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- function TCustomXMLPropStorage.FixPath -->

      <!-- function result Visibility: default -->
      <element name="TCustomXMLPropStorage.FixPath.Result">
        <short>The fixed path is returned with '.' replaced by '/'.</short>
      </element> <!-- function result TCustomXMLPropStorage.FixPath.Result -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.FixPath.APath">
        <short>The path to be fixed.</short>
      </element> <!-- argument TCustomXMLPropStorage.FixPath.APath -->

      <!-- property Visibility: protected -->
      <element name="TCustomXMLPropStorage.XMLConfig">
        <short>
          Property to access the <link id="#LCL.XmlPropStorage.TPropStorageXMLConfig">TPropStorageXMLConfig</link>.
        </short>
        <descr />
        <seealso />
      </element> <!-- property TCustomXMLPropStorage.XMLConfig -->

      <!-- procedure Visibility: public -->
      <element name="TCustomXMLPropStorage.StorageNeeded">
        <short>Ask the underlying storage object for an entry.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TCustomXMLPropStorage.StorageNeeded -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.StorageNeeded.ReadOnly">
        <short>If the item is read-only.</short>
      </element> <!-- argument TCustomXMLPropStorage.StorageNeeded.ReadOnly -->

      <!-- procedure Visibility: public -->
      <element name="TCustomXMLPropStorage.FreeStorage">
        <short>Frees an entry from the underlying storage object.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TCustomXMLPropStorage.FreeStorage -->

      <!-- function Visibility: public -->
      <element name="TCustomXMLPropStorage.DoReadString">
        <short>Implements the actual reading of a value from the underlying storage container.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- function TCustomXMLPropStorage.DoReadString -->

      <!-- function result Visibility: default -->
      <element name="TCustomXMLPropStorage.DoReadString.Result">
        <short>The value of the section/ident requested.</short>
      </element> <!-- function result TCustomXMLPropStorage.DoReadString.Result -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoReadString.Section">
        <short>The section to be read.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoReadString.Section -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoReadString.Ident">
        <short>The ident to be read.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoReadString.Ident -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoReadString.TheDefault">
        <short>If has no value then return this as default.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoReadString.TheDefault -->

      <!-- procedure Visibility: public -->
      <element name="TCustomXMLPropStorage.DoWriteString">
        <short>
          Implements writing of a string value to the underlying storage container.
        </short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TCustomXMLPropStorage.DoWriteString -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoWriteString.Section">
        <short>The section to be written.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoWriteString.Section -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoWriteString.Ident">
        <short>The ident to be written.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoWriteString.Ident -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoWriteString.Value">
        <short>The value to be written.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoWriteString.Value -->

      <!-- procedure Visibility: public -->
      <element name="TCustomXMLPropStorage.DoEraseSections">
        <short>Erases a section from the underlying storage container.</short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure TCustomXMLPropStorage.DoEraseSections -->

      <!-- argument Visibility: default -->
      <element name="TCustomXMLPropStorage.DoEraseSections.ARootSection">
        <short>The path to the section that will be erased.</short>
      </element> <!-- argument TCustomXMLPropStorage.DoEraseSections.ARootSection -->

      <!-- property Visibility: public -->
      <element name="TCustomXMLPropStorage.FileName">
        <short>
          Name of the file where the property data is saved in XML format.
        </short>
        <descr />
        <seealso />
      </element> <!-- propert TCustomXMLPropStorage.FileName -->

      <!-- property Visibility: public -->
      <element name="TCustomXMLPropStorage.RootNodePath">
        <short>Name of the root object path on your XML file.</short>
        <descr />
        <seealso />
      </element> <!-- property TCustomXMLPropStorage.RootNodePath -->

      <!-- object Visibility: default -->
      <element name="TXMLPropStorage">
        <short>
          Implements a class for XML Form Session Properties storage.
        </short>
        <descr />
        <errors />
        <seealso>
          <link id="#LCL.Forms.TForm">TForm.SessionProperties</link>
          <link id="#LCL.INIPropStorage.TINIPropStorage">TINIPropStorage</link>
          <link id="#LCL.JSONPropStorage.TJSONPropStorage">TJSONPropStorage</link>
        </seealso>
      </element> <!-- object TXMLPropStorage -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.StoredValues" link="#LCL.PropertyStorage.TCustomPropertyStorage.StoredValues">
        <short />
        <descr />
        <seealso />
      </element> <!-- property TXMLPropStorage.StoredValues -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.FileName" link="#LCL.XmlPropStorage.TCustomXmlPropStorage.FileName">
        <short />
        <descr />
        <seealso />
      </element> <!-- property TXMLPropStorage.FileName -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.RootNodePath" link="#LCL.XmlPropStorage.TCustomXmlPropStorage.RootNodePath">
        <short />
        <descr />
        <seealso />
      </element> <!-- property TXMLPropStorage.RootNodePath -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.Active" link="#LCL.PropertyStorage.TCustomPropertyStorage.Active">
        <short />
        <descr />
        <seealso />
      </element> <!-- property TXMLPropStorage.Active -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.OnSavingProperties" link="#LCL.PropertyStorage.TCustomPropertyStorage.OnSavingProperties">
        <short />
        <descr />
        <errors />
        <seealso />
      </element> <!-- property TXMLPropStorage.OnSavingProperties -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.OnSaveProperties" link="#LCL.PropertyStorage.TCustomPropertyStorage.OnSaveProperties">
        <short />
        <descr />
        <errors />
        <seealso />
      </element> <!-- property TXMLPropStorage.OnSaveProperties -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.OnRestoringProperties" link="#LCL.PropertyStorage.TCustomPropertyStorage.OnRestoringProperties">
        <short />
        <descr />
        <errors />
        <seealso />
      </element> <!-- property TXMLPropStorage.OnRestoringProperties -->

      <!-- property Visibility: published -->
      <element name="TXMLPropStorage.OnRestoreProperties" link="#LCL.PropertyStorage.TCustomPropertyStorage.OnRestoreProperties">
        <short />
        <descr />
        <errors />
        <seealso />
      </element> <!-- property TXMLPropStorage.OnRestoreProperties -->

      <element name="TXMLConfigStorage">
        <short>
          Implements a configuration storage mechanism using XML-tagged content.
        </short>
        <descr>
          <p>
            <var>TXMLConfigStorage</var> is a <var>TConfigStorage</var> descendant which implements an XML-storage mechanism for configuration or other values.
          </p>
          <p>
            TXMLConfigStorage allows names (paths) and values to be accessed using an XPATH-like syntax.
          </p>
          <p>
            It provides implementations of the abstract virtual methods defined in the ancestor class. It provides overridden constructors that allow the class instance to be created for a qualified file name, a TXMLConfig instance, a subset of values in a TXMLConfig instance, or a stream. Internally, it use TXMLConfig as the storage for values in the class instance.
          </p>
          <p>
            Use the XMLConfig property to access the internal storage for class instance. Use the overridden methods to read, write, or delete the names and values in the class instance. For example:
          </p>
          <ul>
            <li>DeleteFullPathValue</li>
            <li>GetFullPathValue</li>
            <li>SetDeleteFullPathValue</li>
            <li>SetFullPathValue</li>
          </ul>
        </descr>
        <errors />
        <seealso>
          <link id="#lazutils.lazconfigstorage.TConfigStorage">TConfigStorage</link>
        </seealso>
      </element>

      <!-- private -->
      <element name="TXMLConfigStorage.FFilename"/>
      <element name="TXMLConfigStorage.FFreeXMLConfig"/>
      <element name="TXMLConfigStorage.FXMLConfig"/>

      <!-- protected -->
      <element name="TXMLConfigStorage.GetFullPathValue">
        <short>
          Gets the String value stored at the specified path in the XML storage.
        </short>
        <descr>
          <p>
            Calls the GetValue method for the internal TXMLConfig instance.
          </p>
        </descr>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.GetFullPathValue.Result">
        <short>
          Value retrieved from the internal storage, or ADefault when the path is not found.
        </short>
      </element>
      <element name="TXMLConfigStorage.GetFullPathValue.APath">
        <short>Path to the XML node with the requested value.</short>
      </element>
      <element name="TXMLConfigStorage.GetFullPathValue.ADefault">
        <short>
          Default value returned if APath is not found in the internal storage.
        </short>
      </element>

      <element name="TXMLConfigStorage.SetFullPathValue">
        <short>Sets the value for the specified path.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.SetFullPathValue.APath">
        <short>Path to the XML node where the value is stored.</short>
      </element>
      <element name="TXMLConfigStorage.SetFullPathValue.AValue">
        <short>Value stored in the XML node for the specified path.</short>
      </element>

      <element name="TXMLConfigStorage.SetDeleteFullPathValue">
        <short>Sets the value for or deletes the XML node at the specified path.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.SetDeleteFullPathValue.APath">
        <short>Path to the XML node with the value updated or removed in the method.</short>
      </element>
      <element name="TXMLConfigStorage.SetDeleteFullPathValue.AValue">
        <short>
          Value for the specified path. An empty value causes the path to be removed.
        </short>
      </element>

      <element name="TXMLConfigStorage.DeleteFullPath">
        <short>
          Deletes the XML node and its content and the specified path.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.DeleteFullPath.APath">
        <short>Path to the XML node removed in the method.</short>
      </element>

      <element name="TXMLConfigStorage.DeleteFullPathValue">
        <short>Deletes the value stored in the XML node at the specified path.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.DeleteFullPathValue.APath">
        <short>Path to the XML node with the value removed in the method.</short>
      </element>

      <!-- public -->
      <element name="TXMLConfigStorage.Clear">
        <short>Removes all XML nodes stored in the XMLConfig storage.</short>
        <descr>
          <p>
            Calls the Clear method in XMLConfig.
          </p>
        </descr>
        <seealso>
          <link id="TXMLConfigStorage.XMLConfig"/>
        </seealso>
      </element>

      <element name="TXMLConfigStorage.Create">
        <short>Constructor for the class instance.</short>
        <descr>
          <p>
            <var>Create</var> is the overridden, overloaded constructor for the class instance. The overloaded variants allow the XML content to read from various sources like a file name, a TXMLConfig instance, a scoped TXMLConfig instance, or a TStream instance.
          </p>
          <p>
            Use WriteToDisk or SaveToStream to specify where the XML content is stored .
          </p>
        </descr>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.Create.Filename">
        <short>Qualified file name where the XML content is stored.</short>
      </element>
      <element name="TXMLConfigStorage.Create.LoadFromDisk">
        <short>
          True to load existing XML content from the file, or False to create an empty storage.
        </short>
      </element>
      <element name="TXMLConfigStorage.Create.TheXMLConfig">
        <short>
          TXMLConfig instance where the XML paths and values are stored.
        </short>
      </element>
      <element name="TXMLConfigStorage.Create.StartPath">
        <short>
          Initial path for values read and written in the class instance.
        </short>
      </element>
      <element name="TXMLConfigStorage.Create.s">
        <short>
          Stream with the XML content loaded in the XMLConfig storage.
        </short>
      </element>

      <element name="TXMLConfigStorage.Destroy">
        <short>Destructor for the class instance.</short>
        <descr>
          <p>
            <var>Destroy</var> is the overridden destructor for the class instance. It uses the value in FreeXMLConfig to determine whether the TXMLConfig instance in XMLConfig is freed in the method. When set to True, XMLConfig is freed and set to Nil.
          </p>
          <p>
            Destroy calls the inherited destructor prior to exiting from the method.
          </p>
        </descr>
        <seealso>
          <link id="TXMLConfigStorage.Create"/>
          <link id="TXMLConfigStorage.FreeXMLConfig"/>
          <link id="TXMLConfigStorage.XMLConfig"/>
        </seealso>
      </element>

      <element name="TXMLConfigStorage.XMLConfig">
        <short>
          TXMLConfig with the values accessed and maintained in the class instance.
        </short>
        <descr>
          Read-only TXMLConfig property.
        </descr>
        <seealso/>
      </element>

      <element name="TXMLConfigStorage.FreeXMLConfig">
        <short>
          Indicates whether the TXMLConfig instance is freed when the class is destroyed.
        </short>
        <descr>
          <p>
            <var>FreeXMLConfig</var> is a <var>Boolean</var> property which indicates if the TXMLConfig instance in XMLConfig is freed when the class instance is destroyed.
          </p>
        </descr>
        <seealso/>
      </element>

      <element name="TXMLConfigStorage.WriteToDisk">
        <short>Stores the values in XMLConfig to the specified file name.</short>
        <descr/>
        <seealso/>
      </element>

      <element name="TXMLConfigStorage.GetFilename">
        <short>Gets the file name passed as an argument to the constructor.</short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.GetFilename.Result">
        <short>File passed as an argument to the overloaded constructor.</short>
      </element>

      <element name="TXMLConfigStorage.SaveToStream">
        <short>
          Saves the content in XMLConfig to the specified TStream instance.
        </short>
        <descr/>
        <seealso/>
      </element>
      <element name="TXMLConfigStorage.SaveToStream.s">
        <short>TStream instance where the XML content is stored.</short>
      </element>

      <!-- procedure Visibility: default -->
      <element name="Register">
        <short>
          Registers <link id="#LCL.XmlPropStorage.TXMLPropStorage">TXMLPropStorage</link> on the 'Misc' tab of the component palette.
        </short>
        <descr />
        <errors />
        <seealso />
      </element> <!-- procedure Register -->

    </module> <!-- moduleXMLPropStorage -->
  </package> <!-- package lcl -->
</fpdoc-descriptions>