Recipe 14.28. Adding Pop-up Help to Controls
Dialog boxes in Windows applications support pop-up help on controls. On such forms, clicking the question-mark button in the upper-right corner of the form and then clicking on a form control displays a tooltip-like message describing the use of the control. (See Figure 14-27 for an example.) You want to add a similar feature to controls on your form.
Figure 14-27. Pop-up help for a control
Sample code folder: Chapter 14\PopupHelp
Include a HelpProvider control on your form, and use it to enable the pop-up help.
Create a new Windows Forms application, and add a Button control to the form. We'll add pop-up help to this button. Next, add a HelpProvider control to the form, which you'll find in the Components part of the Windows Forms Toolbox. This control (HelpProvider1) appears in the off-form area of the designer.
Change the form's
. The button won't appear yet because it only appears when the Minimize and Maximize
To set the help message for the Button control, select it on the form. One of the control's properties is HelpString on HelpProvider1 , which appears indirectly through the HelpProvider1 control. Add some text to this property.
To view the pop-up help, run the program, click on the question-mark button, and then click on the Button control. The pop-up help will appear until you click some-where else.
control also supports more standard online help
To enable web-page-based help, add a HelpProvider control to your form, and change its HelpNamespace property to any valid web page.
To display help through HTML Help files, set the
property to the help-file
The HelpNavigator on HelpProvider1 property includes other methods with which you can access compiled help pages. For instance, the TableOfContents and Index values, when used, bring up the Table of Contents page and the Index page for the online help, respectively.
Recipe 14.29. Maintaining
The user of your application is allowed to configure certain aspects of the application to suit her preferences. You would like to save these per-user settings so that the application uses them the
Sample code folder: Chapter 14\UserSettings
Use the My.Settings feature of Visual Basic to enable user-and application-specific settings.
This recipe's sample code remembers the position of the form on the screen from one use to the next, and it also displays the
Create a new Windows Forms application. Add a Button control named ActPrefs , and set its Text property to Preferences … Then add a Label control named UserName , and set its Text property to Your name is not set . and its UseMnemonic property to False . Adjust the form to look like Figure 14-28.
Figure 14-28. Controls on the user preferences sample
Open the Project Properties window, and select the Settings tab. This panel
Leave the Scope for both settings as User , and don't provide any Value column data. Close the Project Properties window and return to the form.
Add the following source code to the form's code template:
Private Sub ActPrefs_Click(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles ActPrefs.Click ' ----- Prompt the user to change his/her preferred name. Dim newName As String newName = InputBox("Enter your name.") If (newName.Trim( ) <> "") Then ' ----- Save the user's preferences. My.Settings.PrefsUserName = newName.Trim UserName.Text = "Your name is " & newName.Trim & "." End If End Sub Private Sub Form1_Load(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles MyBase.Load ' ----- Display the user-defined name, if available. If (My.Settings.PrefsUserName <> "") Then UserName.Text = "Your name is " & _ My.Settings.PrefsUserName & "." End If End Sub
Return to the Form Designer, and select the form. Expand the form's (ApplicationSettings) property, and change the Location subproperty to MainFormLocation .
Run the program to test it. Each time you exit and restart the program, it remembers where you moved the form on the display. If you click the Preferences button and enter your name when prompted, it also remembers this setting the next time the program runs.
The My.Settings object is new in Visual Basic 2005. It provides a standard way to manage user-and application-specific settings. Each time the program exits, it saves any settings changes to an XML file, and it reads in that same file the next time the program runs. The exact location of this file varies, but its default location in Windows XP is:
C:\Documents and Setting\<username>\Local Settings\ Application Data\<projectname>\<specialhash>\ <version>\user.config
Application-specific settings, although not used in this sample program, are stored in an app.config file in the folder that contains your application assembly. Application-specific settings cannot be modified through the running application; you can only change them by changing the app.config file.