Introducing the Visual Basic .NET Power Pack
Microsoft Visual Basic .NET version 2003
Summary: This article discusses the Visual Basic Power Pack, a collection of custom controls that provides enhanced user interface elements to client based applications. (17 printed pages)
Overview of the Power Pack Controls
FolderViewer and FileViewer Controls
The Visual Basic Power Pack consists of seven custom controls written in Visual Basic .NET 2003. The controls provide enhanced user interface elements and enable you to create more interesting and more colorful client based applications.
The Power Pack controls consist of:
- BlendPanel. This provides a background for a form where the color fades from one shade to another.
- UtilityToolbar. This is a toolbar whose look and feel is similar to the Internet Explorer toolbar.
- ImageButton. This is a button that displays a graphic over a transparent background.
- NotificationWindow. This displays text and graphics in a pop-up window (commonly known as "toast").
- TaskPane. This is a container that provides collapsible frames for displaying additional information on a form.
- FolderViewer. This displays directories in a hierarchical format.
- FileViewer. This displays a list of the files in a specified directory.
The Power Pack controls are available for download from the Visual Basic Power Pack GotDotNet Workspace. The download includes the complete source code for the controls, this article, and a small sample application.
The code for the Power Pack controls resides in one project, named VbPowerPack. The project contains one or more files for each of the controls. These files all reside in the same directory.
The controls reside in the VbPowerPack namespace. Classes that support design-time functionality for the controls are in the VbPowerPack.Design namespace. For simplicity sake, we decided not to put these into a separate assembly, although that could be done.
Most of the source files are classes and enumerations for those classes. There are some modules and classes that provide helper functions and code for working with Win32 and Windows Shell libraries.
To use the Power Pack controls you should open the VbPowerPack project and build it. This creates the VbPowerPack.dll file. To add the Power Pack controls to your Toolbox right-click on the toolbox and choose Add|Remove Items. In the .NET Frameworks Components tab, select Browse and then select VbPowerPack.dll. You can now use the Power Pack controls the same way you would use user or custom controls you may have created.
The Power Pack includes a sample application based on the SQL Server Northwind database. The Products form is the main form and displays product information. The form uses the BlendPanel, UtilityToolbar, ImageButton, NotificationWindow, and TaskPane controls. The DocBrowser form is called when the user clicks Look up and uses the FolderViewer and FileViewer controls.
Figure 1. The sample application's Products form
Blended backgrounds are used in many user interfaces, for example the Task Bar in Windows Media Player or the individual frames in the Task Panes of various Office 2003 products. In these backgrounds, the color fades from one shade to another shade over some gradient.
The Power Pack adds this gradient functionality in the form of the BlendPanel control (see the file BlendPanel.vb). A BlendPanel is simply a Panel control that has no BackColor property, but instead has a Blend property. The Blend property is an instance of the BlendFill class (defined in the file BlendFill.vb) and controls how the background is painted. The constructor for the BlendFill class takes as parameters the Style (the direction of the gradient), StartColor, and FinishColor.
At design-time, selecting the Blend property in the Properties window brings forward the BlendFillEditor UI (see the files BlendFillEditor.vb and BlendFillEditorUI.vb). The Direction tab is used to select the shading direction. The choices are:
- Vertical. The BlendPanel gets darker as you move from bottom to top. This is the default direction for the BlendPanel.
- Horizontal. The BlendPanel gets darker as you move from right to left.
- Forward Diagonal. The BlendPanel gets darker as you move from lower right to upper left.
- Backward Diagonal. The BlendPanel gets darker as you move from lower left to upper right.
The Start Color tab is used to set the gradient's beginning color. The default start color is System.Drawing.SystemColors.InactiveCaption. The End Color tab is used to set the gradient's ending color. The default end color is System.Drawing.SystemColors.Window.
Figure 2. Setting the Blend property of a BlendPanel
At runtime you can change the look of the BlendPanel by setting the Blend property to a new instance of the BlendFill class and specifying different values for Blend.Style, Blend.StartColor, and Blend.FinishColor. The Blend.Style, Blend.StartColor, and Blend.FinishColor properties are read-only, therefore, to change any of them you must set the BlendPanel's Blend property using the following syntax:
BlendPanel1.Blend = _ New VbPowerPack.BlendFill(blendstyle, startcolor, finishcolor)
Blend.Style can be set to one of the following:
- VbPowerPack.BlendStyle.Vertical (this is the default)
Blend.StartColor and Blend.FinishColor can be set to any Color.
The sample Products form has a menu choice for BlendPanel Options. This brings up a dialog providing the ability to change the direction of the BlendPanel. The following code calls the option dialog and passes to it the current BlendStyle. The code then changes the BlendStyle based on what the user chose. The StartColor and FinishColor remain the same. They are set to their existing values.
' When the user chooses BlendPanel from the Options menu ' bring up the BlendPanelOptions form. Dim frmOptions As New BlendPanelOptions ' Pass the BlendPanel's current Style to the form. This will ' be used to This will be used to display the current settings. frmOptions.BlendStyle = BlendPanel1.Blend.Style If frmOptions.ShowDialog = DialogResult.OK Then ' Change the Blend of the BlendPanel to reflect the new Style ' chosen by the user. Keep the StartColor and EndColor the same. ' Note that the Style, StartColor and FinishColor properties are ' read only.To change any of these you must set the Blend of the ' BlendPanel. Me.BlendPanel1.Blend = New _ VbPowerPack.BlendFill(frmOptions.BlendStyle, _ BlendPanel1.Blend.StartColor, BlendPanel1.Blend.FinishColor) End If
The form also contains logic to change the BlendPanel's StartColor and FinishColor based on the amount of each product in stock. If there are fewer than 10 units in stock the BlendPanel turns red. The BlendPanel color is set back when the user scrolls to a record that has more than 10 units in stock.
If drvProducts("UnitsInStock") < 10 Then BlendPanel1.Blend = New _ VbPowerPack.BlendFill(BlendPanel1.Blend.Style, _ System.Drawing.Color.IndianRed, _ System.Drawing.Color.Crimson) Else ' Store the BlendPanel's current StartColor to a string variable. strCurrentStartColor = BlendPanel1.Blend.StartColor.ToString ' Store the BlendPanel's original StartColor to a string variable. strOriginalStartColor = _ System.Drawing.SystemColors.InactiveCaption.ToString ' If the BlendPanel's gradient had been changed, set it back to ' its default colors. If Not strCurrentStartColor = strOriginalStartColor Then BlendPanel1.Blend = New _ VbPowerPack.BlendFill(BlendPanel1.Blend.Style, _ System.Drawing.SystemColors.InactiveCaption, _ System.Drawing.SystemColors.Window) End If End If
Toolbars have long been a convenient way to provide access to common functionality, whether it is formatting, navigating, editing, updating, and so on. The Power Pack supplies the UtilityToolBar control (see the files UtilityToolbar.vb and UtilityToolbarButtons.vb), which inherits from the Windows Forms' ToolBar control. The UtilityToolbar includes a pre-fabricated set of buttons and events to go along with those buttons and is written to mimic the look and feel of the Internet Explorer toolbar.
After adding an UtilityToolBar to a form you can select the Buttons property in the Properties window. This brings forward the Customize Toolbar dialog (see the file UtilityToolbarCustomizeDialog.vb). This dialog is modeled after the similar dialog in Internet Explorer. To compare the two, you can select View | Toolbars | Customize in Internet Explorer.
Figure 3. Adding buttons to the UtilityToolbar
Note The default setting for Text Options is Selective text on right. This is why if you choose Back and Forward buttons, only the Back button has text. Many early users of the Power Pack thought this was a bug. However, it is by design and is how the toolbar in Internet Explorer works.
Important properties of the UtilityToolbar include:
- Buttons. The collection of ToolBar Buttons that make up the UtilityToolbar.
- IconOptions. This controls how the icons and images are displayed. This can be set to either of the following:
- VbPowerPack.UtilityToolBarIconOptions.SmallIcons (this is the default)
- ShowText. This controls if and where text is shown in relation to the image for each Toolbar Button. This can be set to one of the following:
- VbPowerPack.UtilityToolBarShowText.ShowSelectiveLabels (this is the default)
- Appearance. This controls the appearance of the UtilityToolbar and can be set to either of the following:
- ToolBarAppearance.Normal (this is the default)
Note If you use an UtilityToolBar and a BlendPanel on the same form, you need to be aware of a drawing issue when the UtilityToolbar's Appearance is set to Flat. To see the behavior add the BlendPanel first and set the Dock property to Fill. Then add an UtilityToolbar to the form. The UtilityToolBar is now contained in the BlendPanel. When you run the form you will see remnants of the screen in the UtilityToolBar. There are two ways to avoid this issue. The first is to set the UtilityToolbar's Appearance to Normal. The second is to add the UtilityToolBar to the form first, and then add the BlendPanel.
The UtilityToolBar has events associated with each of the buttons it can contain. For example the BackPressed event fires when the Back button is selected.
The sample Products form has Back, Forward, and Save buttons in the UtilityToolbar. Code to move from product to product is included in the code for the BackPressed and ForwardPressed events.
The Products form has a menu choice for UtilityToolbar Options. This brings up a dialog providing the ability to change the UtilityToolbar's appearance, icon options, and text options. The following code calls the options dialog and passes to it the current settings for Appearance, IconOptions, and Text. The code then changes these settings based on what the user chose.
' When the user chooses UtilityToolbar from the Options menu ' bring up the UtilityToolbarOptions form. Dim frmOptions As New UtilityToolbarOptions ' Pass the UtilityToolbar's current Appearance, IconOptions and ' ShowText settings to the form. This will be used to display the ' current settings. frmOptions.UtilityToolbarAppearance = UtilityToolBar1.Appearance frmOptions.UtilityToolbarIcons = UtilityToolBar1.IconOptions frmOptions.UtilityToolbarText = UtilityToolBar1.ShowText If frmOptions.ShowDialog = DialogResult.OK Then ' Change the Appearance, IconOptions and ShowText settings to ' reflect the user's choices. UtilityToolBar1.Appearance = frmOptions.UtilityToolbarAppearance UtilityToolBar1.ShowText = frmOptions.UtilityToolbarText UtilityToolBar1.IconOptions = frmOptions.UtilityToolbarIcons End If
Another way to accomplish this is to use the ShowCustomizeDialog method of the UtilityToolBar. This brings up the same dialog you used to create the UtilityToolbar.
The Products form does not allow changes to be made to discontinued products. It therefore has code to set the Enabled property of the UtilityToolbar's Save button to False if the product is discontinued. Alternatively, you could use the Visible property of the button and have the Save button appear and disappear rather than be enabled or disabled.
It is possible to add buttons to the UtilityToolbar in much the same way you would add buttons to a Windows Form Toolbar.
Dim newButton As New VbPowerPack.UtilityToolBarButton UtilityToolBar1.Buttons.Add(newButton) newButton.Text = "Click Me"
Note As written, the UtilityToolbar supports a fixed number of images and therefore does not expose an ImageList property. This means that you although you can add a button to the UtilityToolbar, you will not be able to assign it an image.
It is straightforward to add an image to a Button control. The image appears, along with text, in the rectangular button, which of course continues to look like a normal button. The ImageButton control (see the file ImageButton.vb) is a button that has a transparent background and displays a masked image. Therefore, all the user sees is the image. The ImageButton inherits from Control and performs in all regards as a regular Button. It implements IButtonControl and can therefore be set as the AcceptButton or CancelButton on a form.
The ImageButton provides many more image options than the Button control. Important properties of the ImageButton include:
- NormalImage. This is the image that will be displayed when the ImageButton is in its normal state.
- HoverImage. This is the image that will be displayed when the user hovers the mouse over the ImageButton.
- PressedImage. This is the image that will be displayed when the user clicks the ImageButton and holds down the mouse button.
- DisabledImage. This is the image that will be displayed when the ImageButton is disabled. If no DisabledImage is specified the NormalImage is faded a bit to appear disabled.
- SizeMode. Determines how the button is resized based on the size of the image and the size of the text displayed. This can be set to either of the following:
- VbPowerPack.ImageButtonSizeMode.AutoSize (this is the default)
- ShowFocusRect. This determines whether or not the ImageButton displays a dotted rectangle when it gets the focus. The rectangle does not appear if the ImageButton does not have the focus.
The sample Products form contains two ImageButtons, each with the text displayed to the right. As expected, code that runs when the button is clicked is in the Click method of each button.
Figure 4. ImageButtons on the sample Products form
Notification windows (sometimes referred to as "toast") are used in applications such as Windows Messenger to display information to users in a visual manner. These windows typically appear just above or below the status area of the Windows Taskbar.
You can add this type of notification to your solutions with the NotificationWindow control (see file NotificationWindow.vb). The NotificationWindow is a borderless form with a BlendPanel to give it the correct appearance. The window positions itself appropriately depending on the location of the Windows TaskBar.
At design-time the NotificationWindow is a non-visual component and resides in the Component Tray.
Important properties of the NotificationWindow include:
- DefaultText. The text that will display by default in the window.
- DefaultTimeout. The default length of time in milliseconds before the window disappears.
- ShowStyle. This determines how the window appears. This can be set to one of the following:
- VbPowerPack.NotificationShowStyle.Slide. The window slides out from the Windows taskbar. This is the default.
- VbPowerPack.NotificationShowStyle.Fade. The window will fades into and out of existence.
- VbPowerPack.NotificationShowStyle.Immediately. The window appears with no special effect.
- Blend. The NotificationWindow includes a BlendPanel and you can control the color and gradient using a BlendFill (as you saw earlier in this article).
- BottomImage. This is used to add an image to the bottom of the window.
- CornerImage. This is used to add an image to the top left of the window.
- TextIsHyperLink. Controls whether or not the text in the window should be shown as a hyperlink label.
At runtime you use the Notify method to cause the window to appear. The Notify method has several overloads that enable you to substitute for the window's properties. For example, to display the NotificationWindow using the current values of each property:
To display specific text but still use the current values of the other properties:
To display specific text for five seconds but still use the current values of the other properties:
Notify("some text", 5000)
There is also an override of Notify that enables you to specify values for all of the window's properties.
The sample Products form uses a NotificationWindow for two purposes. The first is to inform the user there was a problem printing. The second is to indicate that an item is discontinued.
' If the currently displayed Product is discontinued alert the user ' by displaying a notification window. If drvProducts("Discontinued") = True Then ' This is the image that will be displayed in the notification ' window. img = Image.FromFile("C:\VBPowerPackSample\wgcustomerdetails.ico") With NotificationWindow1 ' Display the image in the upper left of the notification ' window. .CornerImage = img.GetThumbnailImage(32, 32, Nothing, Nothing) ' Have the notification window slide up from the bottom of the ' screen. .ShowStyle = VbPowerPack.NotificationShowStyle.Slide End With ' Display the notification window with the specified text. frmNotification = NotificationWindow1.Notify("This item is discontinued") End If
Figure 5. Displaying information to the user with a NotificationWindow
The NotificationWindow disappears after the timeout period has passed or if the user clicks on it. In the Products form the notification above times out after three seconds but applies only to the discontinued product. The window should close when the user moves to a different record. The Notify method returns a reference to the notification window, which is a form. The sample form thus includes the following line of code to cause the form, if it exists (meaning the NotificationWindow is visible), to close when the user moves off the current record.
If Not IsNothing(frmNotification) Then frmNotification.Close()
A hallmark of good user interface design is to group and display information in the most efficient manner. Key information should be front and center with related information off to the side. It is helpful if the user can show or hide related information as needed. The Windows Explorer has this type of UI. On the left is an area containing frames such as System Tasks, File and Folder Tasks, Other Places, and Details. These frames can be collapsed or expanded to hide or show the information.
The Power Pack provides a TaskPane control (see the file TaskPane.vb) so you can create similar UI in your solutions. The TaskPane is a container for TaskFrames (see the file TaskFrame.vb). The TaskFrame is a panel with a caption bar, which contains a button. Clicking on the caption bar or the button expands or collapses the TaskFrame.
The TaskPane is a container control so when you add one to the form you will see an empty rectangle. Use the TaskFrames property in the Properties window to access the TaskFrame Collection Editor (see the file TaskFrameDesigner.vb). You can then add TaskPanes to the TaskFrame using this dialog.
Most of the properties you will set when using a TaskPane are related to the individual TaskFrames. Important properties of the TaskFrame include:
- Image. Specifies the image to be displayed in the caption bar.
- Text. Specifies the caption to be displayed in the caption bar.
- BackColor. This specifies the background color to be used in the area of the TaskFrame below the caption bar.
- CaptionBlend. The caption bar includes a BlendPanel and you can control the color and gradient using a BlendFill.
- CaptionHighlightColor. This specifies the color of the caption when the mouse is hovering across the caption bar.
- CollapseButtonVisible. This determines whether or not the collapse button is displayed on the caption bar. If it is not, the user cannot collapse or expand the TaskFrame manually.
- IsExpanded. This controls and/or indicates whether or not the TaskFrame is expanded. Changing the value will cause the TaskFrame to collapse or expand.
- CornerStyle. This controls how the corners are drawn for the caption bars at the top of the individual TaskFrames. The default is to use the style determined by the operating system. This can be set to one of the following:
- VbPowerPack.TaskFrameCornerStyle.SystemDefault. This tracks the style used by the operating system and is the default.
The TaskPane has a CollapseAll method to collapse all of its TaskFrames and an ExpandAll method to expand them all. There are not methods to collapse or expand individual frames, however you can expand or collapse a TaskFrame by changing its IsExpanded property.
If TaskPane1.TaskFrames(0).IsExpanded = False Then TaskPane1.TaskFrames(0).IsExpanded = True End If
You can use the TaskPane's FrameCollapsed and FrameExpanded events to respond to the associated actions. Use e.TaskFrame to determine which frame was collapsed or expanded.
If e.TaskFrame.Name = "tskfrmOrderSummary" Then ...
The sample Products form has a TaskPane docked to the right side of the form. There are two TaskFrames, one to display information on the product's supplier and one to display order history for the product. The order history is generated only when the TaskFrame is expanded, not when the user scrolls from product to product.
Figure 6. Displaying additional product information in a TaskPane
Visual Studio .NET 2003 ships with the FolderBrowserDialog and OpenFileDialog controls. These are used to browse and select folders and files respectively. These are handy controls but they are modal dialogs. They cannot be used together. It is possible to select a folder in the OpenFileDialog, but it is not possible to see both the list of folders and files at the same time. In addition, these system dialogs cannot be customized to fit the needs to specific scenarios.
The Visual Basic Power Pack provides the FolderViewer (see the file FolderViewer.vb) and FileViewer (see the file FileViewer.vb) controls. These share much functionality with the FolderBrowserDialog and OpenFileDialog. The FolderViewer is based on the TreeView control and the FileViewer is based on the ListView control.
Important properties of the FolderViewer include:
- RootPath. This determines the top-most folder displayed in the FolderViewer. The default value for this is empty and the FolderViewer then displays the Desktop as the top most node.
- CurrentFolder. This returns the folder selected by the user.
Important properties of the FileViewer include:
- Path. This determines, or returns, the directory being viewed, or selected. The default value is My Computer.
- Pattern. This is used to filter the types of files displayed.
- View. This controls how the files are displayed. This can be set to one of the following:
- View.LargeIcon (this is the default)
- SortBy. This is used to sort the files displayed in the FileViewer. This can be set to one of the following:
- VbPowerPack.FileViewerSortBy.Name (this is the default)
- Files. This returns a collection of the files displayed in the FileViewer.
- SelectedFiles. This returns a collection of the files selected by the user.
The Look Up button on the sample Products form calls the Document Browser form. The form has a FolderViewer and a FileViewer. The RootPath of the FolderViewer is set in the form's Load method. When the user selects a node in the FolderViewer, the Path property of the FileViewer is set to that directory and the FileViewer is updated to display the files in that directory.
Figure 7. The sample application's document browser form
Note There are instances where you cannot set the FileViewer's Path to a directory selected in the FolderViewer. For example, selecting My Computer in the FolderViewer will cause an exception to be thrown when the FileViewer's Path is set to the FolderViewer's CurrentDirectory. When you select My Computer, the FolderViewer's CurrentFolder contains a GUID. The FileViewer is not able to display this and is written to throw an exception. You could then set the FileViewer's Path to the string "My Computer".
' Store the current Path to a string variable. filePath = FileViewer1.Path Try ' Change the directory the FileViewer will look in. Set it to the ' directory selected in the FolderViewer. FileViewer1.Path = FolderViewer1.CurrentFolder Catch ex As Exception ' Alert the user by displaying a notification window. ' Specify the image that will be displayed in the notification ' window. img = Image.FromFile("C:\VBPowerPackSample\wgcustomerdetails.ico") ' The image will appear in the upper left of the notification ' window. NotificationWindow1.CornerImage = img.GetThumbnailImage(32, 32, _ Nothing, Nothing) ' Display the notification window with the specified text. frmNotification = NotificationWindow1.Notify("Sorry, that is not a folder you can view") ' Set the FileViewer Path back to its previous value. FileViewer1.Path = filePath End Try
When the user double clicks on a file displayed in the FileViewer, the file is opened in the appropriate program.
' Create an instance of a Process class to be used to run an ' application. proc = New Process ' Store the name of the selected file to a string variable. fileName = FileViewer1.SelectedFiles(0).Name ' Tell the Process what file to use. proc.StartInfo.FileName = FileViewer1.Path & "\" & fileName ' Tell the process to use the operating system shell to start the ' process. proc.StartInfo.UseShellExecute = True Try ' Start the process. proc.Start() Catch ex As Exception ' If there is a problem launching the process alert the user by ' displaying a notification window. ' This is the image that will be displayed in the notification ' window. img = Image.FromFile("C:\VBPowerPackSample\wgcustomerdetails.ico") ' The image will appear in the upper left of the notification ' window. NotificationWindow1.CornerImage = img.GetThumbnailImage(32, 32, _ Nothing, Nothing) ' Display the notification window with the specified text. frmNotification = NotificationWindow1.Notify("Couldn't open " & _ fileName) End Try
The user can filter the files in the FileViewer by entering a pattern in the textbox and selecting the Pattern button. The Reset button clears the pattern so all files are displayed.
FileViewer1.Pattern = txtPattern.Text
In addition, the Document Browser form offers the user the ability to switch among the various FileViewer views and also sort the files.
The Visual Basic Power Pack provides a collection of custom controls that you can use to add an extra element of visual appeal to your client-based applications. The controls are designed to be fairly simple to use, both at design-time and runtime. And since the controls ship with the source code, you can extend or change the behavior of the controls as you see fit.
You are welcome to join the Visual Basic Power Pack Workspace on GotDotNet at http://www.gotdotnet.com/Community/Workspaces/workspace.aspx?id=167542e0-e435-4585-ae4f-c111fe60ed58. There you will be able to discuss the controls and download updates and new versions as they become available. And if you like, you can contribute to updates and new versions.