The dbicList control is capable of reading and writing XML data. The data can be read and written as a string into or from memory, or to and from a file. The control is also capable of creating XML data for the entire control, or from a specific collection within the control.
The use of XML makes it easy to create a snapshot of the current state of the control, save it, and then reload it again at a later time. XML support also makes it easy to send an XML file to another instance of the object (user, application, etc.) to restore the state of one instance into another.
The dbicList control contains a ReadXMLFile method and a WriteXMLFile method to save and read the control’s formatting and data at runtime. In addition to the runtime XML methods the dbicList control contains an XMLRead property and an XMLWrite property that are surfaced in the property inspector to load and save XML at design time. A valid XML file can be read from a local drive, a mapped drive, or from a valid URL. NOTE: XML files cannot be written to a URL, they can only be written to a local or mapped drive. The control has one additional XML property, the StyleFile property, that allows the developer to specify an XML file to load when the control is first instanced.
The XML functionality of the dbicList control as a whole persists the formatting of the control itself and its Columns and Items collections (including fonts and colors). Each of the collections in the control also have an XMLRead and an XMLWrite method to persist their values individually. NOTE: The XML functionality will not persist any image information other than the index values of the images in the attached image list.
Example: Create a file of all data in the control and a file of just the time bar links.
VB.NET
‘Create a file C:\ListXML.XML containing all the formatting and data in the control
Me.dbicList.WriteXMLFile("C:\ListXML.XML")
‘ Create a file C:\ ListItemsXML .XML containing just the list items in the control.
Me.dbicList.Items.WriteXMLFile("C:\ListItemsXML.XML")
C#
//Create a file C:\ ListXML.XML containing all the data in the control
this.dbicList.WriteXMLFile(“C:\\ ListXML.XML”);
//Create a file C:\ ListItemsXML.XML containing just the list time bar links data
this.dbicList.Items.WriteXMLFile(“C:\\ ListItemsXML.XML”);
NOTE: The collections do not contain a method to read an XML file. The ReadXMLFile method from the main control is capable of determining the type of data being read and load it appropriately.
Example: Read XML data for the dbicList controL.
VB.NET
'Read in the XML file containing the formatting for the control for the Automobile Inventory Report
Me.dbicListReports.ReadXMLFile("AutoInventory.XML")
C#
// Read in the XML file containing the formatting for the control for the Automobile Inventory
this.dbicListReports.ReadXMLFile("AutoInventory.XML");
Reading and Writing XML Strings
The dbicList control contains an XMLString property. This property is capable of being used to read and write data for the control in an XML format into and from a string variable, bypassing the need to store XML in a file. The Items and Columns collections also contain an XMLString property. NOTE: The XMLString property for the collections is read only, that is they can be read to ascertain the state of the data being held in the collection. These properties cannot be written to in order to set their values. Just like the ReadXMLFile method, the XMLString property for the dbicList control is used to read any and all types of XML for the control.
Reading and Writing XML Files at Design Time
One of the benefits of the XML functionality built into the dbicList control is the ability to read and write XML files at design time. This can be very useful in instances where a control is being upgraded from one version to another (i.e. save the properties, upgrade, and then load in the new control), or to share control styles between developers.
The property window for the dbicList includes an XMLRead property and an XMLWrite property. When a character string is entered into one of these fields, an Open (XMLRead) or Save File (XMLWrite) dialog will appear to allow the developer to specify the path to read or write an XML file. NOTE: The XMLWrite property will only write data for the entire control (i.e. not individual collection data).
Write Many, Read Once
The concept of Write Many, Read Once refers to the variety of methods to write an XML file or get an XML string, but there is only one way to read XML into the dbicList control. To write or get XML data, the developer can use a method or property directly from the control as whole (all data) or from the individual collection that is storing the pertinent data.
The data created by any of the write methods will contain the proper header identifying the type of data in the XML string. This header is used by the ReadXMLFile method or the XMLString property of the main control to identify the type of data being loaded and apply it appropriately.
NOTE: When data for the entire control is read, all collection data for the control is cleared in anticipation of the new data. If data for a collection only is read, the collection being updated will not be cleared. Data for an individual collection will be appended to the data currently stored in the collection. It is the responsibility of the developer to clear a collection before loading the collection specific XML data.