Infragistics(R) NetAdvantage(R) Windows Forms
PreviousLocationsDropDownButtonToolTipDisplaying Event
See Also  Example E-mail your feedback on this topic.
Infragistics.Win.Misc Namespace > UltraNavigationBar Class : PreviousLocationsDropDownButtonToolTipDisplaying Event

Occurs when a tooltip is about to be displayed for the dropdown button which provides access to the previous locations dropdown list.

Syntax

Visual Basic (Declaration) 
Public Event PreviousLocationsDropDownButtonToolTipDisplaying As ToolTipDisplayingHandler
C# 
public event ToolTipDisplayingHandler PreviousLocationsDropDownButtonToolTipDisplaying

Event Data

The event handler receives an argument of type ToolTipDisplayingEventArgs containing data related to this event. The following ToolTipDisplayingEventArgs properties provide information specific to this event.

PropertyDescription
Cancel (Inherited from System.ComponentModel.CancelEventArgs)Gets or sets a value indicating whether the event should be canceled.
ScreenLocation Gets/sets the location at which the tooltip will be displayed, expressed in screen coordinates.
ToolTipText Gets/sets the string that is displayed in the tooltip.

Example

The following code sample demonstrates how to pre-populate the UltraNavigationBar's PreviousLocations collection, and how to customize the size of the list as well as the tooltip that is displayed when the cursor hovers over the dropdown button which displays the list. It also demonstrates how to persist the contents of the list across application sessions.

For an overview of how to handle events in Visual Basic or Visual C#, see Event Handlers in Visual Basic and Visual C#. For specific information and code examples illustrating how to consume events in your application, see Consuming Events in the .NET Framework Developer's Guide.

Visual BasicCopy Code
Imports System
Imports System.Drawing
Imports System.IO
Imports System.Collections.Generic
Imports System.ComponentModel
Imports Infragistics.Shared
Imports Infragistics.Win
Imports Infragistics.Win.Misc
Imports Infragistics.Win.Misc.UltraWinNavigationBar
Imports System.Text

    '   Handles the form's 'Load' event.
    Private Sub Form1_Load(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles MyBase.Load

        Dim fss As New FileSystemSupport(Me.ultraNavigationBar1, Me.ultraTree1)
        fss.Populate()

        '  If this is the first time the application is being run, initialize
        '  the PreviousLocations collection by populating it from the special
        '  system folders. If this is not the first time the application is
        '  being run, load the previous locations from a file.
        If (Me.runOnce) Then
            Me.InitializePreviousLocations(Me.ultraNavigationBar1)
        Else
            Dim folderPath As String = System.Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData)
            Dim filePath As String = String.Format("{0}\{1}.xml", folderPath, "PreviousLocations")
            If System.IO.File.Exists(filePath) Then
                Me.ultraNavigationBar1.PreviousLocations.LoadFromXml(filePath)
            End If

        End If

        '  Register as a listener of the PreviousLocationsDropDownButtonToolTipDisplaying event.
        AddHandler Me.ultraNavigationBar1.PreviousLocationsDropDownButtonToolTipDisplaying, AddressOf Me.OnPreviousLocationsDropDownButtonToolTipDisplaying
    End Sub

    '   Handles the form's 'Closing' event.
    Private Sub Form1_FormClosing(ByVal sender As Object, ByVal e As System.Windows.Forms.FormClosingEventArgs) Handles Me.FormClosing
        Dim folderPath As String = System.Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData)
        Dim filePath As String = String.Format("{0}\{1}.xml", folderPath, "PreviousLocations")
        Me.ultraNavigationBar1.PreviousLocations.SaveAsXml(filePath)
    End Sub

    '  Populates the specified UltraNavigationBar's PreviousLocations collection
    '  from the local machine's special system folders.
    Private Sub InitializePreviousLocations(ByVal navigationBar As UltraNavigationBar)

        If navigationBar Is Nothing Then Throw New ArgumentNullException("navigationBar")

        '  Clear the current contents of the collection.
        navigationBar.PreviousLocations.Clear()

        '  Set the tooltip text for the dropdown button to something
        '  a little more descriptive than the default.
        navigationBar.PreviousLocationsSettings.DropDownButtonToolTipText = "Click to show most recently visited locations"

        '  Restrict the number of items that can exist in the collection to 50.
        navigationBar.PreviousLocationsSettings.MaximumItems = 50

        '  Pre-populate the collection with some of the most commonly used
        '  directories to provide "shortcuts" for the end user.
        Dim pathSeparator As String = navigationBar.PathSeparator
        Dim values As Array = System.Enum.GetValues(GetType(Environment.SpecialFolder))
        Dim previousLocations As NavigationBarPreviousLocationsCollection = navigationBar.PreviousLocations

        Dim i As Integer = 0
        For i = 0 To values.Length - 1

            Dim folderPath As String = System.Environment.GetFolderPath(values.GetValue(i))
            folderPath = folderPath.Replace("\", pathSeparator)
            Dim Location As UltraNavigationBarLocation = navigationBar.FromFullPath(folderPath)
            If (Not Location Is Nothing AndAlso previousLocations.Contains(Location) = False) Then
                previousLocations.Add(Location)
            End If
        Next

        '  Set the MaximumDropDownItems property to the same value as the
        '  inital number of members in the collection.
        navigationBar.PreviousLocationsSettings.MaximumDropDownItems = previousLocations.Count

    End Sub

    Private Sub OnPreviousLocationsDropDownButtonToolTipDisplaying(ByVal sender As Object, ByVal e As ToolTipDisplayingEventArgs)
        Dim navigationBar As UltraNavigationBar = sender
        Dim previousLocations As NavigationBarPreviousLocationsCollection = navigationBar.PreviousLocations

        '  If the PreviousLocations collection is not empty, display the
        '  full path for the first 5 members in the tooltip text.
        If previousLocations.Count > 0 Then

            Dim sb As StringBuilder = New StringBuilder()
            sb.Append(String.Format("Shortcuts:{0}", Environment.NewLine))

            Dim count As Integer = Math.Min(previousLocations.Count, 5)
            Dim i As Integer = 0

            For i = 0 To count - 1

                sb.Append(previousLocations(i).GetFullPath(FullPathFormat.EditMode))

                '  Append a new line if this is not the last iteration of the loop
                '  if it is the last iteration, and the collection count is greater
                '  than what we are showing here, append an ellipsis.
                If (i < (count - 1)) Then
                    sb.Append(Environment.NewLine)
                Else
                    If (previousLocations.Count > count) Then sb.Append("...")
                End If
            Next

            '  Assign the string we just built to the ToolTipText property
            '  of the event arguments...this will override the value of the
            '  DropDownButtonToolTipText property (of the control's
            '  PreviousLocationsSettings), so that this string will be displayed
            '  instead.
            e.ToolTipText = sb.ToString()
        End If
    End Sub
C#Copy Code
using System;
using System.Drawing;
using System.IO;
using System.Collections.Generic;
using System.ComponentModel;
using Infragistics.Shared;
using Infragistics.Win;
using Infragistics.Win.Misc;
using Infragistics.Win.Misc.UltraWinNavigationBar;

    //  Handles the form's 'Load' event.
    private void Form1_Load(object sender, EventArgs e)
    {
        //  Populate the NavigationBar and Tree from the local machine's file system
        FileSystemSupport fss = new FileSystemSupport( this.ultraNavigationBar1, this.ultraTree1 );
        fss.Populate();

        //  If this is the first time the application is being run, initialize
        //  the PreviousLocations collection by populating it from the special
        //  system folders. If this is not the first time the application is
        //  being run, load the previous locations from a file.
        if ( this.runOnce )
            this.InitializePreviousLocations( this.ultraNavigationBar1 );
        else
        {
            string folderPath = System.Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
            string filePath = String.Format(@"{0}\{1}.xml", folderPath, "PreviousLocations");
            if ( System.IO.File.Exists(filePath) )
                this.ultraNavigationBar1.PreviousLocations.LoadFromXml(filePath);
        }

        //  Register as a listener of the PreviousLocationsDropDownButtonToolTipDisplaying event.
        this.ultraNavigationBar1.PreviousLocationsDropDownButtonToolTipDisplaying += new ToolTipDisplayingHandler(this.OnPreviousLocationsDropDownButtonToolTipDisplaying);
    }

    //  Handles the form's 'Closing' event.
    private void Form1_FormClosing(object sender, FormClosingEventArgs e)
    {
        int count = this.ultraNavigationBar1.PreviousLocations.Count;
        int rootCount = this.ultraNavigationBar1.RootLocation.Locations.Count;

        string folderPath = System.Environment.GetFolderPath(Environment.SpecialFolder.ApplicationData);
        string filePath = String.Format(@"{0}\{1}.xml", folderPath, "PreviousLocations");
        this.ultraNavigationBar1.PreviousLocations.SaveAsXml(filePath);
    }

    //  Populates the specified UltraNavigationBar's PreviousLocations collection
    //  from the local machine's special system folders.
    private void InitializePreviousLocations( UltraNavigationBar navigationBar )
    {
        if ( navigationBar == null )
            throw new ArgumentNullException("navigationBar");

        //  Clear the current contents of the collection.
        navigationBar.PreviousLocations.Clear();

        //  Set the tooltip text for the dropdown button to something
        //  a little more descriptive than the default.
        navigationBar.PreviousLocationsSettings.DropDownButtonToolTipText = "Click to show most recently visited locations";

        //  Restrict the number of items that can exist in the collection to 50.
        navigationBar.PreviousLocationsSettings.MaximumItems = 50;

        //  Pre-populate the collection with some of the most commonly used
        //  directories to provide "shortcuts" for the end user.
        string pathSeparator = navigationBar.PathSeparator;
        Array values = Enum.GetValues( typeof(Environment.SpecialFolder) );
        NavigationBarPreviousLocationsCollection previousLocations = navigationBar.PreviousLocations;

        for ( int i = 0; i < values.Length; i ++ )
        {
            string folderPath = System.Environment.GetFolderPath( (Environment.SpecialFolder)values.GetValue(i) );
            folderPath = folderPath.Replace( @"\", pathSeparator );
            UltraNavigationBarLocation location = navigationBar.FromFullPath( folderPath );
            if ( location != null && previousLocations.Contains(location) == false )
                previousLocations.Add( location );
        }

        //  Set the MaximumDropDownItems property to the same value as the
        //  inital number of members in the collection.
        navigationBar.PreviousLocationsSettings.MaximumDropDownItems = previousLocations.Count;
    }

    //  Handles the UltraNavigationBar's PreviousLocationsDropDownButtonToolTipDisplaying event.
    private void OnPreviousLocationsDropDownButtonToolTipDisplaying(object sender, ToolTipDisplayingEventArgs e)
    {
        UltraNavigationBar navigationBar = sender as UltraNavigationBar;
        NavigationBarPreviousLocationsCollection previousLocations = navigationBar.PreviousLocations;

        //  If the PreviousLocations collection is not empty, display the
        //  full path for the first 5 members in the tooltip text.
        if ( previousLocations.Count > 0 )
        {
            StringBuilder sb = new StringBuilder();
            sb.Append( string.Format("Shortcuts:{0}", Environment.NewLine) );

            int count = Math.Min(previousLocations.Count, 5);
            for ( int i = 0; i < count; i ++ )
            {
                sb.Append( previousLocations[i].GetFullPath(FullPathFormat.EditMode) );

                //  Append a new line if this is not the last iteration of the loop;
                //  if it is the last iteration, and the collection count is greater
                //  than what we are showing here, append an ellipsis.
                if ( i < (count - 1) )
                    sb.Append(Environment.NewLine);
                else
                {
                    if ( previousLocations.Count > count )
                        sb.Append( "..." );
                }
            }

            //  Assign the string we just built to the ToolTipText property
            //  of the event arguments...this will override the value of the
            //  DropDownButtonToolTipText property (of the control's
            //  PreviousLocationsSettings), so that this string will be displayed
            //  instead.
            e.ToolTipText = sb.ToString();
        }
    }

Remarks

The PreviousLocationsDropDownButtonToolTipDisplaying event fires whenever the cursor hovers over the PreviousLocationsDropDownButtonUIElement. If the UltraNavigationBarPreviousLocationsSettings's UltraNavigationBarPreviousLocationsSettings.DropDownButtonToolTipText property is not specifically set, a tooltip is only displayed in the case where a listener of the event assigns a non-empty value to the Infragistics.Win.Misc.UltraWinNavigationBar.ToolTipDisplayingEventArgs.ToolTipText property of the event arguments. This makes it possible to either display a tooltip without handling the event (using the UltraNavigationBarPreviousLocationsSettings' DropDownButtonToolTipText property), or dynamically assign the text to be displayed in response to the event (using the ToolTipDisplayingEventArgs' ToolTipText property).

See Also