exmlgrid - faq

How do you find the control's help / documentation on your computer:

  • Open the Run dialog on your Windows, and type exg2antt.chm, to run the exg2antt's help file. By default, the setup installs the CHM file into your system folder, so you can open the control's help / documentation by typing the control's name followed by .chm extension in the Run dialog box.
  • Locate and Run the ExG2antt.chm shortcut from the component's folder.
  • For How-To questions, you can run the ExHelper.exe shortcut located in the component's folder.
  • For How-To questions, you can locate and run the HOWTODO.chm shortcut from the component's folder.

Frequently Asked Questions - General

Click the programming language you use for general questions:

How-To Questions

Click the programming language you use for how-to questions:

Exontrol Software - EXMLGrid FAQ page

Frequently Asked Questions - EXMLGrid Component

Listed below are the questions that we are asked quite often. Before you write us, be sure to check here. 

Are you looking for something?

Just press CTRL+F ( or select Edit\Find menu item ) and you have a dialog that will help you to locate the string that are you looking for.

Where can I find the control's release notes?

The control's release notes can be found on our web site, looking for the Release Notes column in the control's main page. Click here for direct link.

How can I add a new node?

The control provides a Nodes property that get access to the control's nodes collection. Each Node object provides a Nodes property that get access to the child nodes collection. Each time when a new node is added, the control fires the AddNode event. Use the Add method of the Nodes collection to insert a new node to the nodes collection like in the following sample:

With XMLGrid1
    With .Nodes
        With .Add("Root")
            With .Nodes
                .Add "Child <b>1</b>"
                .Add "Child <b>2</b>"
            End With
        End With
    End With
End With

How can I assign an editor to a node?

Any node can have it's own editor. Use the Editors property to add a new editor of specified type to the Editors collection and use the Editor property of the Node object to assign an editor to the node like in the following sample:

With XMLGrid1
    With .Editors
        With .Add("Integer",EditType)
            .Numeric = exInteger
        End With
    End With
    
    With .Nodes
        With .Add("Edit <b>Integer</b>", "just an editable text")
            .Editor = "Integer"
        End With
    End With
End With
        

Is there any dependency to the msxml.dll file?

The component was built using the C++, ATL, STL with no runtime dependencies. Files like msxml.dll, mfc42.dll, msvcrt.dll, ... MFC runtime files are NOT required. The control installs samples how to load XML files using MS XML parser, SAX parser, and so on.

Is there any print and print preview support?

Yes, the Exontrol ExPrint component ( exprint.dll ) provides Print and Print Preview capabilities for the eXMLGrid component. Once that you can have the exPrint component in your Components list, insert a new instance of "ExPrint 1.0 Control Library" to your form and add the following VB code:

Private Sub Command1_Click()
    With Print1
        Set .PrintExt = XMLGrid1.Object
        .Preview
    End With
End Sub

The following sample shows how to call Preview method in C#:

private void button1_Click(object sender, System.EventArgs e)
{
	axPrint1.PrintExt = aXMLGrid1.GetOcx();
	axPrint1.Preview();
} 

The Exontrol Print Preview mainframe looks like follows:

Is there any Fit-To-Page option for print and print preview?

The Exontrol ExPrint component ( exprint.dll ) provides Print and Print Preview capabilities for the Exontrol EXMLGrid component.

The requirements for the FitToPage option:

  • Exontrol.ExPrint version 5.2 ( or greater )

  • Exontrol.EXMLGrid version 10.0 ( or greater )

If these are not meet, the Options("FitToPage") property has NO effect.

The FitToPage option could be one of the following:

  • On, (Fit-To-Page) the control's content is printed to a single page ( version 6.1 )
  • p%, (Adjust-To) where p is a positive number that indicates the percent from normal size to adjust to. For instance, the "FitToPage = 50%" adjusts the control's content to 50% from normal size. ( version 8.1 )
  • w x, (Fit-To Wide) where w is a positive number that indicates that the control's content fits w pages wide by how many pages tall are required. For instance, "FitToPage = 3 x" fits the control's content to 3 pages wide by how many pages tall is are required. ( version 8.1 )
  • x t, (Fit-To Tall) where t is a positive number that specifies that the control's content fits t pages tall by how many pages wide are required. For instance, "FitToPage = x 2" fits the control's content to 2 pages tall by how many pages wide are required. ( version 8.1 )
  • w x t, (Fit-To) where w and t are positive numbers that specifies that the control's content fits w pages wide by t pages tall. For instance, "FitToPage = 3 x 2" fits the control's content to 3 pages wide by 2 pages tall. ( version 8.1 )

The following VB6 sample shows how to show the eXMLGrid/COM's content to one page when print or print preview the component:

Private Sub Command1_Click()
    With Print1
        .Options = "FitToPage = On"
        Set .PrintExt = XMLGrid1.Object
        .Preview
    End With
End Sub

The following VB/NET sample shows how to show the eXMLGrid/NET's content to one page when print or print preview the component:

Private Sub Button1_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles Button1.Click
    With Exprint1
        .Options = "FitToPage = On"
        .PrintExt = EXMLGrid1
        .Preview()
    End With
End Sub

Is there any option to load large files without hanging the UI?

Yes. You need to load the XML files using threads. The "Sample\VC\Virtual.MS.Load.XML" folder contains a VC sample that creates a thread to be used to load the XML file. The sample starts the thread as soon as the user selects a file. The thread ends when last node is loaded.

The value of a node disappears when I add a child node. Is this correct or is it a bug?

This behavior is by design. The Value property is not displayed if the node contains child nodes. Use the Name property to assign a caption for the node.

How do I assign a new look for the selected item?

The component supports skinning parts of the control, including the selected item. Please check the control's help file for the Add method of the Appearance object. There you will find almost everything you need to change the visual appearance for most of the UI parts of the control. Shortly, the idea is that identifier of the skin being added to the Appearance collection is stored in the first significant byte of property of the color type. In our case, we know that the SelBackColor property changes the background color for the selected item. This is what we need to change. In other words, we need to change the visual appearance for the selected item, and that means changing the background color of the selected item. So, the following code ( blue code ) changes the appearance for the selected item:
With XMLGrid1
    .VisualAppearance.Add &H34, App.Path + "\aqua.ebn"
    .SelBackColor = &H34000000
End With

Please notice that the 34 hexa value is arbitrary chosen, it is not a predefined value. Shortly, we have added a skin with the identifier 34, and we specified that the SelBackColor property should use that skin, in order to change the visual appearance for the selected item. Also, please notice that the 34 value is stored in the first significant byte, not in other position. For instance, the following sample doesn't use any skin when displaying the selected item:

With XMLGrid1
    .VisualAppearance.Add &H34, App.Path + "\aqua.ebn"
    .SelBackColor = &H34
End With  

This code ( red code ) DOESN'T use any skin, because the 34 value is not stored in the higher byte of the color value. The sample just changes the background color for the selected item to some black color ( RGB(0,0,34 ) ). So, please pay attention when you want to use a skin and when to use a color. Simple, if you are calling &H34000000, you have 34 followed by 6 ( six ) zeros, and that means the first significant byte of the color expression. Now, back to the problem. The next step is how we are creating skins? or EBN files? The Exontrol's exbutton component includes a builder tool that saves skins to EBN files. So, if you want to create new skin files, you need to download and install the exbutton component from our web site. Once that the exbutton component is installed, please follow the steps.

Let's say that we have a BMP file, that we want to stretch on the selected item's background.

  1. Open the VB\Builder or VC\Builder sample
  2. Click the New File button ( on the left side in the toolbar ), an empty skin is created. 
  3. Locate the Background tool window and select the Picture\Add New item in the menu, the Open file dialog is opened.
  4. Select the picture file ( GIF, BMP, JPG, JPEG ). You will notice that the visual appearance of the focused object in the skin is changed, actually the picture you have selected is tiled on the object's background.
  5. Select the None item, in the Background tool window, so the focused object in the skin is not displaying anymore the picture being added.
  6. Select the Root item in the skin builder window ( in the left side you can find the hierarchy of the objects that composes the skin ), so the Root item is selected, and so focused.
  7. Select the picture file you have added at the step 4, so the Root object is filled with the picture you have chosen.
  8. Resize the picture in the Background tool window, until you reach the view you want to have, no black area, or change the CX and CY fields in the Background tool window, so no black area is displayed.
  9. Select Stretch button in the Background tool window, so the Root object stretches the picture you have selected.
  10. Click the Save a file button, and select a name for the new skin, click the Save button after you typed the name of the skin file. Add the .ebn extension.
  11. Close the builder

You can always open the skin with the builder and change it later, in case you want to change it.

Now, create a new project, and insert the component where you want to use the skin, and add the skin file to the Appearance collection of the object, using blue code, by changing the name of the file or the path where you have selected the skin. Once that you have added the skin file to the Appearance collection, you can change the visual appearance for parts of the controls that supports skinning. Usually the properties that changes the background color for a part of the control supports skinning as well.

How do I enumerate the nodes in the control?

The ItemByPosition property retrieves the node giving its position. Use the FirstNode property to retrieve the first child node, and the NextNode property to retrieve the next child node. The following sample enumerates the nodes in the control:

Private Sub enumerate(ByVal x As EXMLGRIDLibCtl.XMLGrid)
    With x.Nodes
        Dim i As Long
        For i = 0 To .Count - 1
            enumNodes .ItemByPosition(i)
        Next
    End With
End Sub

Private Sub enumNodes(ByVal n As EXMLGRIDLibCtl.Node)
    Dim c As EXMLGRIDLibCtl.Node
    Debug.Print n.Name
    Set c = n.FirstNode
    While Not c Is Nothing
        enumNodes c
        Set c = c.NextNode
    Wend
End Sub

The enumerate function enumerates the root nodes as they are displayed. The enumNodes function recursively enumerates the child nodes for each node.

Load and Save XML data

The control supports built-in LoadXML and SaveXML methods to load and save your XML data. The LoadXML method loads XML data from a file, a URL, an IStream, a SAFEARRAY, or an IXMLDOMDocument. The SaveXML method saves control's content  to a file, an XML document object, or a custom object that supports persistence. Both methods uses the MSXML ( MSXML.DOMDocument, XML DOM Document ) parser.

Save data using the Exontrol's XMLGrid control.

The control support built-in SaveXML method that saves the control's content to XML format. In case, you need to save the your content in a different way we will show you few things you should know about.  Simple, you need to know how to enumerate nodes in the control and to save data to a file. The following sample enumerates the nodes in the control:

Private Sub enumerate(ByVal x As EXMLGRIDLibCtl.xmlGrid)
    With x.Nodes
        Dim i As Long
        For i = 0 To .Count - 1
            enumNodes .Item(i)
        Next
    End With
End Sub

Private Sub enumNodes(ByVal n As EXMLGRIDLibCtl.node)
    Dim c As EXMLGRIDLibCtl.node
    Debug.Print n.Name
    Set c = n.FirstNode
    While Not c Is Nothing
        enumNodes c
        Set c = c.NextNode
    Wend
End Sub  

The enumerate function enumerates the root nodes in the control. The enumNodes function enumerates recursively the child nodes for each node. Now, that we know to enumerate the nodes in the control we need to figure out a way to save this data, so we slightly change these functions so we build a string in XML format. These functions can be customize as much as possible to fit your requirements, and they are provided just to give you an idea how to save your data.

Private Function save(ByVal x As EXMLGRIDLibCtl.XMLGrid) As String
    With x.Nodes
        Dim i As Long
        For i = 0 To .Count - 1
            save = save + saveNodes(.ItemByPosition(i), "")
        Next
    End With
End Function

Private Function saveNodes(ByVal n As EXMLGRIDLibCtl.Node, ByVal i As String) As String
    Dim c As EXMLGRIDLibCtl.Node
    saveNodes = i + "<" + n.Name + ">"
    Set c = n.FirstNode
    If c Is Nothing Then
        saveNodes = saveNodes + n.Value
    Else
        saveNodes = saveNodes + vbCrLf
        While Not c Is Nothing
            saveNodes = saveNodes + saveNodes(c, i + vbTab)
            Set c = c.NextNode
        Wend
        saveNodes = saveNodes + i
    End If
    saveNodes = saveNodes + "</" + n.Name + ">" + vbCrLf
End Function

The save method generates a XML format for each root node. The saveNodes method generates XML format for each node. The name of the node is put between < > characters, and if it contains no child nodes, the node's value is added betwen <> and </> characters. As you can see, starting from these functions you can customize the way you save your data as you require. For instance, we have changed these functions so each line of the XML format is printed separately so they can be saved to a file or to a stream as you require.

Private Sub writeLine(s As String, ByVal uData As Variant)
    Debug.Print s
    s = ""
End Sub

Private Function save(ByVal x As EXMLGRIDLibCtl.XMLGrid, ByVal uData As Variant) As String
    With x.Nodes
        Dim i As Long
        For i = 0 To .Count - 1
            saveNodes .ItemByPosition(i), "", uData
        Next
    End With
End Function

Private Sub saveNodes(ByVal n As EXMLGRIDLibCtl.Node, ByVal i As String, ByVal uData As Variant)
    Dim c As EXMLGRIDLibCtl.Node
    Dim l As String
    l = i + "<" + n.Name + ">"
    Set c = n.FirstNode
    If c Is Nothing Then
        l = l + n.Value
    Else
        writeLine l, uData
        While Not c Is Nothing
            saveNodes c, i + vbTab, uData
            Set c = c.NextNode
        Wend
        l = l + i
    End If
    l = l + "</" + n.Name + ">"
    writeLine l, uData
End Sub

The writeLine method is called each time the saveNodes method generates a new line while saving your XML data. The uData parameter can be used store the file where you are saving this data, and can be taken as an extra or user data. For instance, you can save your data to a file using a sample like follows:

Private Sub writeLine(s As String, ByVal uData As Variant)
    Print #uData, s
    s = ""
End Sub

Private Sub saveToFile(ByVal x As EXMLGRIDLibCtl.XMLGrid, ByVal f As String)
    Open f For Output As #1
        save x, 1
    Close #1
End Sub

The writeLine method uses the uData parameter to identify the file where the line s is written. The saveToFile method opens a file for writing and lets the save method to enumerate the nodes in the control so each line is saved to the opened file.

How can I insert a hyperlink?

Use the <a> anchor element in Name property of the Node, or when inserting a node using the Add method. The control fires the AnchorClick event when the user clicks an anchor element. Use the ShowToolTip property to programmatically show a tooltip for specified anchor element.
Copyright 1999-2017 Exontrol. All rights reserved.