CIS205 - Visual Basic

Objectives of the Week

Understand Windows Menus and how to use the VB Menu Editor
Become familiar with Windows Common Dialogs
How to use the Clipboard object in VB
To write Functions and Subroutines
How to Build an .EXE and a VB Distribution Package

Menus and the Menu Editor

A menu bar is a standard feature in most programs written for the Windows platform. The menu and the submenu structure provide standard access to many functions that are common to many applications.

Look at the Menu Editor icon on the Tool Bar. Clicking on this icon will open the Menu Editor dialog which allows you to build the program's menu structure and the selection characteristics.

Note some of the menu characteristics:

Keyboard Shortcuts
Standard Control Key Selections
Separator Bars
Ellipse (...)
Arrows
Checked Selections

Keyboard Shortcuts	Alt Key Combinations, just like on the other form controls
Standard Control Key Selections	Standard Control Key Shortcuts. Don't reinvent these combinations
Separator Bars	Cosmetic. Used to separate related selections into a group
Ellipse (...)	Ellipse tells you that this is NOT the final selection
Arrows	The next selection is a submenu
Checked Selections	Allows the menu selection to me toggled on or off

Build the menu structure by setting each menu selection property.

Use the Arrow keys, along with Next, Insert, and Delete to build and maintain the Menu Structure.

Naming Conventions: Select a meaningful Caption and then name the menu selection with the mnu prefix

Caption	This is what the user will see.
Name	Use the mnu prefix
Short Cut	Select the shortcut from the drop down
Enabled	Always select Enabled
Visible	Always select Visible
Checked	If you want this selection to toggle on and off. You will need some code in your program to maintain the toggle state.

Separator Bar	Make the Caption a Dash (-)

Each menu selection is a control and as you will see, has much in common with the Command Button. The menu selections can easily be used to supplement or to replace the command button events.

Your program can be designed to use:
mnuPrint_Click() rather than cmdPrint_Click()

But what is perhaps a better design feature is to build in both selections and the support is easily implemented using the following code:

Private Sub mnuPrint_Click()
cmdPrint_Click

End Sub

By calling the Command Button Click procedure from the Menu Event Handler , it's pretty easy to support both user options.

Each of the Menu control properties can be changed using your program code just like any other set of Control properties.

Private Sub mnuBold_Click()
    If mnuBold.Checked Then
        mnuBold.Checked = False
    Else
        mnuBold.Checked = True
    End If

End Sub

Use this example to see how to address the control properties.

It's no different than any other control.

But use this specific example to see how to maintain a menu item that used the checked property

Common Dialog

The Common Dialog control allows for standard access to a set of common control functions. These functions are part of the Windows environment. You see these functions whenever you Open or Save a File, Print a document, or when you change a color or font.

Select Project | Components | Microsoft Common Dialog Control

Selecting the Common Dialog will add this control to your ToolBox. The control will display as a small icon on your form. It is not sizable and is invisible at run time.

CommonDialogForm.jpg (6223 bytes)

Notice that this object is implemented using COMDLG32.OCX in the \WINDOWS\SYSTEM directory.

Take a moment to look at the number of custom controls that are available to Visual Basic.

Name the Common Dialog Control dlgCD. Generally, there is only one Common Dialog found on a form.

There are six Common Dialog Methods:

ShowOpen	Used to select a file to Open. This does not open the file. You control the type and location of the files to be displayed, and the user can select one of the listed files. The control only makes the name of the selected file available to the program.
ShowSave	Used to specify the name of the file you are saving. This does not save the file. You control the type and the location of where the user can save the file.
ShowColor	You can select the Color Selection for Text and for Control Foreground and Background
ShowFont	You can select the font and other characteristics for the form and the controls on the form.
ShowPrint	Select the destination for the program's printed output
ShowHelp	Displays the Help file you specify. You must set the HelpFile and HelpCommand properties otherwise, the ShowHelp method will not run.

They are all similar, but we will discuss only ShowColor and ShowFont this week

There are generally three steps in using the Dialog Controls:

Initialize Dialog Properties to match the current form controls
Show the Dialog
Use the returned Dialog Properties to modify the current form controls

The Flag Property

There are many Flag Property values available for each of the Dialog Methods. In general, this property controls the way that the specific dialog is displayed on the screen.

For example, when using the Color Dialog, you can code the Flag property to allow or restrict the user from defining custom colors.

Private Sub mnuColor_Click()
dlgCD.Flags = cdlCCFullOpen
dlgCD.ShowColor

End Sub

Private Sub mnuColor_Click()
dlgCD.Flags = cdlCCPreventFullOpen
dlgCD.ShowColor

End Sub

There are many Flags Property values that are specific to each Common Dialog Show method. Check the Common Dialog Help for each range of values and initialize accordingly prior to invoking the Show Method.

Example: Change the form background color

Private Sub mnuColor_Click()
    ' Initialize
    dlgCD.Flags = cdlCCFullOpen

    ' Call the Dialog
    dlgCD.ShowColor

    ' Set form Properties
    frmMain.BackColor = dlgCD.Color

End Sub

Example: Change the font of a text box

Private Sub mnuAllFonts_Click()
    ' Initialize
    dlgCD.Flags = cdlCFScreenFonts

    dlgCD.FontName = txtText.FontName
    dlgCD.FontBold = txtText.FontBold
    dlgCD.FontItalic = txtText.FontItalic
    dlgCD.FontSize = txtText.FontSize

    ' Call the Dialog
    dlgCD.ShowFont

    'Set TextBox Properties
    txtText.FontName = dlgCD.FontName
    txtText.FontBold = dlgCD.FontBold
    txtText.FontItalic = dlgCD.FontItalic
    txtText.FontSize = dlgCD.FontSize

End Sub

Clipboard

The Clipboard is a Windows Temporary Storage Location. It is used as a means for a program to store information that may then be referenced by the same program or another program. The most common use of this storage is in the Copy, Cut and Paste logic built into most Windows programs. The Clipboard can be accessed in Visual Basic as an object using a set of Methods.

Clipboard Methods
Mostly what you do with the Clipboard is Put Information In and Take Information Out. You can also examine the type of information stored and you can empty the Clipboard contents.

GetFormat(vbCFText)	Used to Query the Clipboard to determine what type or format of information that is currently stored. In this case, the query asks if the Clipboard holds Text data. The Method returns a Boolean value.
GetText()	Access the contents of the Clipboard
Clear	Empty the Clipboard
SetText	Place data in the Clipboard

The Copy Cut and Paste function for a Text Box will operate on the currently selected text. You must Select the information you want to Copy or Cut out of the program by holding the mouse button down and moving the mouse cursor across the text you wish to select.

SelText, SelStart and SelLength properties of the TextBox control describe what text has been selected. The SelText property is used in the Copy, Cut and Paste operations.

Copy, Cut and Paste Logic

Copy	Clipboard.Clear Clipboard.SetText txtText.SelText	Put selected text into the Clipboard
Cut	mnuCopy_Click txtText.SelText = ""	Copy, the "Delete" the selected text
Paste	txtText.SelText = Clipboard.GetText()	Replace the selected text with the Clipboard contents. If nothing was selected, the paste operation will insert the Clipboard contents starting at the current Text Box cursor position.

The Clipboard can contain more than just text. It can contain Formatted Text (Rich Text) and Graphics (Bitmaps). These formats are not supported by the TextBox. The paste operation will fail if the contents of the Clipboard contain incompatible data. The effect of this failure will range from having nothing being pasted into the TextBox, to having Garbage pasted in.

Querying the Clipboard and Disabling the Paste Option

Looking back at the structure of the menu, it seems that you cannot code an event handler for the top level menu items. When you click on them in design mode, all that happens is that the sub level menus are displayed. But from within the code window, you can select the menu option and write code that will be triggered before the top level menu item's sub menu is displayed. This is the perfect hook to effect the sub menu options. In this case, if there is incompatible data in the clipboard, it's appropriate to disable the Paste option.

Private Sub mnuEdit_Click()
      mnuCut.Enabled = True
      mnuCopy.Enabled = True

      mnuPaste.Enabled = Clipboard.GetFormat(vbCFText)

End Sub

Always enable Copy and Cut, but use the Boolean return value from the GetFormat method to determine if there is text stored in the Clipboard object. This method returns True if there is text in the Clipboard and returns False if there is not.

This is exactly what we need to determine weather to Enable or Disable the Paste option.

One more example related to the Selection Properties of the TextBox. A standard Edit option in many programs is the Select All (Ctrl-A) option. This option will highlight or select all of the text in the TextBox. This is, the standard keyboard shortcut for dragging the mouse across the entire content of the control in order to highlight its contents.

Here is the code:

Private Sub mnuSelect_Click()
txtText.SelStart = 0
txtText.SelLength = Len(txtText.Text)

End Sub

Start at the beginning by setting the .SelStart property to zero

Use the Len() function to determine how many characters are in the TextBox, and use that value to set the value of SelLength.

Subroutines and Functions

A General Procedure is a piece of code that is not connect to a control event handler. These come in two flavors:

Subroutine	A utility procedure that performs a particular task
Function	Same as a Subroutine but the Function returns a single value

A General Procedures is used to isolate a specific task that may be required in more than one situation to a single block of code. This procedure can be invoked where ever in is necessary. The logic is coded in only one place, which make the maintenance of these Utility type routines easier. If the code needs to be changed, it need only be changed in one place as that single copy is call from a number of locations.

To add a Procedure to your code, select Tools | Add Procedure

When adding a procedure:

Select a Meaningful Name
Select Sub or Function

Make the scope (for now) Private

Parameters

A parameter represents a value that may be passed to a Subroutine or Function. The target General Procedure will use this value as a local variable. This "local variable" will be initialized using the value passed from the caller.

Here is an example from the text:

Private Sub SelectColor(lngInCommingColor as Long)
        With dlgCD
                .Flags = cdlCCRGBInit
                .Color = lngInCommingColor
                .ShowColor
        End With

End Sub

Calling the Subroutine:

Private Sub cmdChangeColor_Click()

        Dim lngColor as Long

        lngColor = lblLabel.ForeColor
        SelectColor lngColor
        lblLabel.ForeColor = dlgCD.Color

End Sub

The subroutine accepts a Long variable that will contain a value that represents a color. This variable is treated as a local variable, even though there is no Dim statement for it.

The value is used to initialize the dialog prior to calling the ShowColor method.

In the caller, the Local Variable lngColor is passed to the subroutine. In passing the parameter, the value of lngColor is assigned to lngInCommingColor.

When more than one parameter is passed, the assignments are made by position.

Parameters can be passed in one of two ways:

ByRef	By Reference means that the subroutine or function CAN change or effect the value of the parameter after the subroutine or function completes. This is the default for Functions
ByVal	By Value means that the subroutine or function CAN NOT change or effect the value of the parameter after the subroutine or function completes. This is the default for Subroutines

The ByRef or ByVal is coded in the subroutine or function as part of the General Procedure.
Private Sub SelectColor(ByVal lngInCommingColor as Long)

When passing a variable By Reference, VB tells the General Procedure where the variable is located back in the caller. This was the General Procedure can change the callers variable.

When passing a variable By Value, VB send a copy of the variable to the General Procedure. This variable can be changed, but the copy is thrown away when the General Procedure terminates, so the original is always left untouched.

In the new release of VB, it has already been promised that all passing of parameters will Default to being passed By Value. This will lead to some problems with existing Functions as they currently default to By Reference when not explicitly specified.

Subroutine

A subroutine is invoked from the "caller". It performs the task for which it was designed, and when it completes, control is pass to the instruction following the one that invoked it.

Functions

Functions work much like Subroutines, except that they return a single value to the caller. The function works much like an assignment statement and takes on the characteristics of a variable.

Take this example:

Private Function sngFtoC(ByVal sngFar as Single) As Single
    Dim sngResult As Single

    sngResult = (sngFar - 32) * (5 / 9)

    sngFtoC = sngResult

End Function

Private Sub cmdConvert_Click()
    Dim sngFar As Single
    Dim sngCel As Single

    sngFar = Val(txtFar.Text)
    sngCel = sngFtoC(sngFar)

    MsgBox sngCel

End Sub

The function is one that will convert a Fahrenheit temperature to a Celsius temperature. The input to the function, passed as a parameter is the Fahrenheit value to be converted. The value returned from the function is the Celsius value.

Note the function naming convention. The three character prefix indicates the return value type just like any variable you may define. Also note the return type specified by coding As Single.

The result is passed back to the caller by making an assignment to the function name. The name of the function acts as a variable used to communicate with the caller. This assignment must be made, or else the value can not be properly returned to the caller.

In the caller, the result is returned through an assignment statement just like a simple variable assignment.

What about an .EXE file

Creating an .EXE or "standalone" executable program is easy in Visual Basic.

It is as easy as selecting File | Make .EXE from the VB Menu Bar. This process will start with a full compile and create the .EXE in the Project Directory.

Easy! Right?

But why won't it run on my workstation?

Often, if you copy that .EXE from the project directory and try to run it on another workstation, the program will fail. This will occur for a couple of reasons. Visual Basic programs need to have the VB Run Time installed in order to function. These are the pieces that provide your Visual Basic program with the environment it needs to run under Windows. A second reason might be that you have used Custom Controls in your programs, and the support code is not available on the target workstation.

So what do you do to get the program to run?

Visual Basic includes with it, the Package and Deployment Wizard. This is available under the Add-Ins Menu option in VB or under the Visual Studio Tools selection accessed using the Win95 Start | Programs selection.

Select Package and Deployment Wizard from the Add-Ins or from the Windows Program Selection.

The wizard will analyze the project and include any Custom Controls along with the VB Runtime Modules.

It will then create a set of installation files including a Setup program. This setup may be written to Floppy Images or to an image that may be burned to a CD or stored on the Internet for download.

The user will install from floppies or using the download by running Setup, just like most shrink-wrapped software packages.