This article discusses how the ToolTipsFactory tooltips can be used with the ListBox-control provided by the .NET-Framework.
Listsboxes are widely used controls to present lists of items to application-users. The items in this lists can be plain strings, which just represent themselves (e.g. a list of city names) or they can be more complex objects, which appear in the (visible) list with a descriptive name provided by the object, but where most of the information held by a specific object (item) is still hidden. Depending on the kind of information and the function of a ListBox-control in an application, different scenarios are possible for the usage of the ToolTipsFactory tooltips in conjunction with the ListBox-control.
The most basic use of a tooltip on a ListBox-control, is to give a generic description about the information presented by the ListBox. Such a generic (static) description is usually assigned to the tooltip of the ListBox at design-time, as described in the section on "Provided properties" and other sections of the ToolTipsFactory documentation. In this case, the tooltip popping-up for a specific ListBox-control would always show the same content when the cursor moves over the control:
Of course, this usage of the ToolTipsFactory tooltips would never justify this article. As mentioned above, this has been extensively discussed in other sections.
When used on a ListBox-control, the ToolTipsFactory tooltips can do much more then just display static content. For a listbox, where "the listed string is the message", there is no need for dynamic tooltips. But in cases, where the entries in the listbox are just references to complex objects containing more information, the tooltips provide the means to present more information about a specific list-entry to the user in a really natural way.
In the following we are going to discuss two different approaches on how the MultiLineToolTip component can be used to dynamically show more information about a list-entry, but the described techniques apply to the other tooltip components as well. The source-code and the corresponding Visual Studio project for this sample can be found in the "<ToolTipsFactoryHomeDir>.\Samples\ListBox1"-directory.
For both approaches we are going to use a set of instances of the Customers-class as it is defined below:
Class Customer
Friend Name As String = ""
Friend LastName As String = ""
Friend City As String = ""
Friend Birthdate As Date
Friend CustomerID As Long
Friend PendingOrders As Integer
Sub New(ByVal id As Long, ByVal custName As String, _
ByVal custLastName As String, ByVal custCity As String, _
ByVal custBirthdate As String, _
ByVal pendorders As Integer)
'Assign the values to the corresponding members...
CustomerID = id
Name = custName
LastName = custLastName
City = custCity
Birthdate = Date.Parse(custBirthdate)
PendingOrders = pendorders
End Sub
Public Overrides Function ToString() As String
Return LastName & ", " & Name
End Function
End Class
The goal of the first approach, we are going to elaborate, will be to make the MultiLineToolTip display all information of the Customer-object currently selected in the ListBox-control.
In the sample-project a ListBox-control (lbCustomers) is going hold a list of this Customer-objects, as shown by the image:
This Customer-objects are created and assigned to an ArrayList (customersList) in the Load-event of the form (Form1). This customersList is then assigned to the ListBox-control (lbCustomers) as DataSource (see Listing 2).
Private Sub Form1_Load(ByVal sender As Object, ByVal e As EventArgs) _
Handles MyBase.Load
'Create the Customer-objects and add them to the customersList....
customersList.Add(New Customer(10234, "Frank", "Smith", _
"New York", "3.4. 1955", 12))
customersList.Add(New Customer(9225, "Ellen", "Jackson", _
"Detroit", "12.12. 1966", 48))
customersList.Add(New Customer(11333, "Jason", "Devoe", _
"Miami", "11.11. 1911", 225))
customersList.Add(New Customer(16001, "Clara", "Forrest", _
"Denver", "6.7. 1975", 3))
customersList.Add(New Customer(4042, "Pat", "Neill", _
"Las Vegas", "9.9. 1982", 35))
customersList.Add(New Customer(12317, "Jim", "Cool", _
"Nome", "2.7. 1963", 8))
customersList.Add(New Customer(8154, "Nancy", "Smart", _
"Atlanta", "3.4. 1955", 12))
'Define the customersList as DataSource for the listbox...
Me.lbCustomers.DataSource = customersList
'...and make sure, no item is selected.
Me.lbCustomers.SelectedIndex = -1
'We need this clone of the customersList to show another approach
'on how the MultiLineToolTip can dynamically change its content...
customersList2 = customersList.Clone
'...and assign it as DataSource for the second listbox (lbCustomers2)
'on Form1
Me.lbCustomers2.DataSource = customersList2
Me.lbCustomers2.SelectedIndex = -1
End Sub
The code in Listing 1 and Listing 2 is only needed to get some actual data in place for our example. In a real application, the DataSource for the ListBox will most probably be a some data from a database and not hard-coded values.
After this prelude, we can now concentrate on how we can make the tooltip for lbCustomers display all information about the selected object.
Obviously,
this has to happen in one of the SelectedIndexChanged- or SelectedValueChanged-events,
because the information displayed in the tooltip should change as soon as
another list-item is selected. For this example, we have opted for the SelectedIndexChanged-event, as
shown below:
Private Sub
lbCustomers_SelectedIndexChanged(ByVal sender As
Object, _
ByVal e As
EventArgs) _
Handles
lbCustomers.SelectedIndexChanged
'If no Customer is selected...
If Me.lbCustomers.SelectedIndex = -1 Then'...the tooltip should reflect this as well.
Me.MultiLineTT.GetMultiLineToolTip(lbCustomers) _
.Text = "No customer selected!"
Exit Sub
End If
Dim newText As String = ""
Dim c As Customer
'Get the Customer-object selected in the listbox...
c = CType(Me.lbCustomers.SelectedItem, Customer)
'With the values provided by the Customer-object, we can
'build the (multiline) string to be displayed by the 'tooltip.newText &= "ID : " & c.CustomerID.ToString & vbNewLine
newText &= "Customer : " & c.LastName & "," & c.Name & vbNewLine
newText &= "City : " & c.City & vbNewLine
newText &= "Birthdate : " & c.Birthdate.ToShortDateString & vbNewLine
newText &= "Orders : " & c.PendingOrders.ToString
'This is the crucial line of code, which makes the tooltip
'display the new text. It also makes sure that the tooltip
'pops-up again, if its AutoPopDelay already has expired.
Me.MultiLineTT.Start(lbCustomers, newText)
End Sub
