Galaxy Viewer 2.0

Description: We add some new features to our Galaxy Viewer 1.0 project including a descriptive text box and a combo box to select text items you'd like to view. Major topics covered include using the SELECT CASE structure, adding Modules to a project, creating Functions and populating and accessing a ComboBox.
Controls needed: Combo Box, Text Box.
Level: Beginner-Intermediate

If you want you can open the Galaxy 1.0 project and select Save As.. from the file menu. Then save it as Galaxy 2.0; this way you only have to add the new code and don't destroy version 1.0 (in case you make a mistake).
1. Now add the following statement to the General Declarations section;
Option Explicit

Adding Option Explicit to the General Declarations section of your program will cut down on errors caused by misspelled variable names; after this you will be forced to declare all variables and if you misspell a variable that you've already declared VB will let you know with an error message.

2. Now add a TextBox, ComboBox and Line control to your form; you may need to resize your form. Your form should be layed out approximately like the picture above.

3. Now go to the properties box and set the following by typing in these new values;

Control	Property	Set Value To
Text1	Name	txtContent
" "	Text	(erase text)
" "	MultiLine	True
Line1	Name	linAccent
" "	BorderWidth	5
Combo1	Name	cboSelectText

4. Save the project as "Galaxy2".

5. Now we'll go to the lstPlanets_Click event and make it a little more readable by replacing the multiple IF..THEN..ELSE statements with a SELECT CASE control structure; each one has it uses and you can check Visual Basic Help for additional examples of when to use each one. Change the code in your lstPlanets_Click event to the code shown below; notice how much neater the code is?

Private Sub lstPlanets_Click()
'--------------------------------------------------
'Path stores value of App.Path
'--------------------------------------------------
Dim Path As String

Path = App.Path
'------------------------------------------------------
'Set the default value for the ComboBox "cboSelectText"
'to 0 "General Info."
'------------------------------------------------------
cboSelectText.ListIndex = 0 'initialize to 0
    
  Select Case lstPlanets.ListIndex
      Case 0
        imgShow.Picture = LoadPicture(Path + "/asteroid.bmp")
        txtContent.Text = GetInfo(0)
      Case 1
        imgShow.Picture = LoadPicture(Path + "/earth.bmp")
        txtContent.Text = GetInfo(1)
      Case 2
        imgShow.Picture = LoadPicture(Path + "/jupiter.bmp")
        txtContent.Text = GetInfo(2)
      Case 3
        imgShow.Picture = LoadPicture(Path + "/mars.bmp")
        txtContent.Text = GetInfo(3)
      Case 4
        imgShow.Picture = LoadPicture(Path + "/merc.bmp")
        txtContent.Text = GetInfo(4)
      Case 5
        imgShow.Picture = LoadPicture(Path + "/meteor.bmp")
        txtContent.Text = GetInfo(5)
      Case 6
        imgShow.Picture = LoadPicture(Path + "/neptune.bmp")
        txtContent.Text = GetInfo(6)
      Case 7
        imgShow.Picture = LoadPicture(Path + "/pluto.bmp")
        txtContent.Text = GetInfo(7)
      Case 8
        imgShow.Picture = LoadPicture(Path + "/saturn.bmp")
        txtContent.Text = GetInfo(8)
      Case 9
        imgShow.Picture = LoadPicture(Path + "/craft.bmp")
        txtContent.Text = GetInfo(9)
      Case 10
        imgShow.Picture = LoadPicture(Path + "/sun.bmp")
        txtContent.Text = GetInfo(10)
      Case 11
        imgShow.Picture = LoadPicture(Path + "/uranus.bmp")
        txtContent.Text = GetInfo(11)
      Case 12
        imgShow.Picture = LoadPicture(Path + "/venus.bmp")
        txtContent.Text = GetInfo(12)
    End Select
End Sub

The new "txtContent.Text = GetInfo(0)" statement you may be wondering about is what's known as a function call. What we are doing is calling the function GetInfo in the module (see step 6 below) and sending it the index value, - (0) in this example-, which will tell the function what ListItem was selected. The function will then use this value to decide which text to send back. You'll need to explore functions in the VB Help files and other sample projects or books you may have; it is an important part of programming you'll need to be comfortable with and this is only a very simple example.

Since this is new let's review. Let's assume the user clicks on the first item in the ListBox -Asteroids- which has a ListIndex value of 0. Then in plain english this code...

  Select Case lstPlanets.ListIndex
      Case 0
        imgShow.Picture = LoadPicture(Path + "/asteroid.bmp")
        txtContent.Text = GetInfo(0)

...says, "Ok the user selected the first item -which has a ListIndex of 0- so let me go to my Select Case statement and find the which Case is equal to the ListIndex current value of zero. Found it, now what do I do? Oh yea, I load the asteroid.bmp. Ok what now? Ahhh... I'll get the text for this by calling the GetInfo function. I'll send it the ListIndex value so it can figure out what text I want. When I get back the result from GetInfo I'll stuff that string in txtContent.Text" and I'll be done! We'll explain the processing in GetInfo in a minute.

You'll notice that instead of the hard-coded Path we had in Galaxy 1 -in my case "c:\program files\devstudio\vb\myprojects\"- we now made Path equal to a something called App.Path. Visual Basic stores some information about your project in the App Object and you can get access to that information by using App. + then tell it what you want -in this case the path. In order to use App.Path the file you are looking for must be in the directory your project is in, or one of its sub-directories.

I also added a backslash (\) to the bitmap name since app.path did not return this. In the next version of this project, Galaxy 3, we'll see how to check for the presence of the backslash and add it if needed -this is a common issue you will face.

If you are particularly sharp, you may have wondered why I used Path = App.Path and didn't just use it like this imgShow.Picture = LoadPicture(App.Path + "venus.bmp"). Well, we could have done that, and it would work fine. However, each call to App.Path would mean your program would have to go and resolve or figure out what value is stored in App.Path. Considering the path isn't changing, that's a waste of your programs time. In this simple example you might not notice the difference. In a larger project, where your program had to get the value a hundred or a thousand times it could add up, and along with other poor coding practices could slow your program down.

Don't ignore Visual Basics Online Help, it is loaded with searchable information and includes many useful code samples that you can try, and even use as-is in your own programs. There are also several useful sample programs on the CD that will contain helpful code that you can use -you may want to check out the tutorial entitled Unsupported Extras on VB5 CD.

6. Here is where we'll add the modProcessRequest module and the GetInfo function that we talked about earlier. These will hold the text descriptions and the code to process them. We'll look at better ways to store data in our next project, for instance we could have read the text from a text file or even a database. My main purpose here was to introduce you to functions and modules. In the Galaxy 3 tutorial I hope to cover file I/O and database issues.

Now add a new module to your project by selecting the Add Module option from the menu or toolbar. Then change the Name property to modProcessRequest.

Modules provide a convenient way to organize code that may be called by different procedures. You can also put general procedures and useful functions you create in a module and then reuse it in other projects. Functions contain program statements that manipulate data and then return a specified value.                           

7. Then select the module in the Project window and add the following code;

Option Explicit
Public Function GetInfo(Choice As Long) As String

'-------------------------------------------------
'Module:modProcessRequest.Bas              8/25/98
'-------------------------------------------------
'Author:Burt Abreu
'
'Purpose:Function receives choice from
'lstPlanets_Click event and then processes
'returning descriptive text to the txtContent
'Text property.
'-------------------------------------------------
  
'-------------------------------------------------
'Create and initialize NewLine variable which will
'use the ascii values for carriage return and line
'feed to create the functionality of a  key
'on the typewriter. Those of you using VB 5.0 or
'higher can use the constant vbCrLf for this.
'-------------------------------------------------
  Dim NewLine As String
  NewLine = Chr(13) + Chr(10)

  
  Select Case Choice
    Case 0 ' "asteroid"
    '--------------------------------------------
    'Process users combo box selection and assign
    'appropriate text to txtContent Text property
    'using a nested Select Case Statement.
    '-------------------------------------------- 
    'The outer Select Case determines which ListItem
    'the user selected. The inner Select Case deter-
    'mines which ComboBox item was selected (ie General
     'Info)and returns the correct text.
    '--------------------------------------------

Here's the code...

      
         Select Case Form1.cboSelectText.ListIndex
           Case 0 'General Info Selected
            '
            'The return string of the function will be the text
            'for the list box

            GetInfo = "Here you can write some interesting" _
            & " general information about asteroids that" _
            & " will introduce the subject."
           Case 1'Statistics Selected
            GetInfo = "Here you can write some statistics" _
            & " about asteroids, their size, weight etc."
           Case 2'History Selected
            GetInfo = "Here you see the NewLine in action; we use it to" _
            & " create, what else, a new line; rather than wrapping" _
            & " the text." & NewLine & NewLine _
            & "Question: What's the name of the oldest known asteroid?" & NewLine _
            & NewLine _
            & "Answer: Rip Van Twinkle."
         End Select
         Exit Function  ' we got what we wanted
    '-------------------------------------------------------------
    'You could add inner select cases to each of the next cases if
    'you wanted to; we won't since we figure you get the idea.
    '-------------------------------------------------------------
    Case 1 '"earth"
      GetInfo = "Write small blurb about earth here."
    Case 2 '"jupiter"
      GetInfo = "Write small blurb about jupiter here."
    Case 3 '"mars"
      GetInfo = "Write small blurb about mars here."
    Case 4 '"mercury"
      GetInfo = "Write small blurb about mercury here."
    Case 5 ' "meteor"
      GetInfo = "Write small blurb about meteors here."
    Case 6 ' "neptune"
      GetInfo = "Write small blurb about neptune here."
    Case 7 '"pluto"
      GetInfo = "Write small blurb about pluto here."
    Case 8 '"saturn"
      GetInfo = "Write small blurb about saturn here."
    Case 9 '"space craft"
      GetInfo = "Write small blurb about space craft here."
    Case 10 '"sun"
      GetInfo = "Write small blurb about sun here."
    Case 11 '"uranus"
      GetInfo = "Write small blurb about uranus here."
    Case 12 '"venus"
      GetInfo = "Write small blurb about venus here."
    End Select
End Function

Since this can be confusing, I'll walk you through it. The user already selected the Asteroid item with the ListBox. Now he uses the ComboBox cboSelectText to select what info he want's about Asteroids -in this case let's assume that the user selected the first item General Info. That sets the ListIndex value for cboSelectText to 0. So in the code below, the ListIndex value is compared to the inner Case statements and BINGO! We found a match, so we assign the corresponding text to GetInfo with the assignment operator (=) like this...

Remember this next bit of code?

 
cboSelectText.ListIndex = 0

  Select Case lstPlanets.ListIndex
      Case 0
        imgShow.Picture = LoadPicture(Path + "/asteroid.bmp")
        txtContent.Text = GetInfo(0)

Yep, that's where we called the GetInfo function, passing it the value of 0. The string we assigned to GetInfo has gotten passed back and if we could peek into this call we could see the returned text stored in there and it would look something like this;

txtContent.Text = GetInfo("Here you can write some interesting general information about asteroids that will introduce the subject.")

8. Lastly we'll add all the remaining code. Change the Form_Load event to look like this...

Private Sub Form_Load()

'Clear the combo and list boxes
  Form1.lstPlanets.Clear
  Form1.cboSelectText.Clear

'---------------------------------
'Add items to the List box when the
'Form Loads using AddItem.
'---------------------------------
    Form1.lstPlanets.AddItem "Asteroids"
    Form1.lstPlanets.AddItem "Earth"
    Form1.lstPlanets.AddItem "Jupiter"
    Form1.lstPlanets.AddItem "Mars"
    Form1.lstPlanets.AddItem "Mercury"
    Form1.lstPlanets.AddItem "Meteor"
    Form1.lstPlanets.AddItem "Neptune"
    Form1.lstPlanets.AddItem "Pluto"
    Form1.lstPlanets.AddItem "Saturn"
    Form1.lstPlanets.AddItem "Space Craft"
    Form1.lstPlanets.AddItem "Sun"
    Form1.lstPlanets.AddItem "Uranus"
    Form1.lstPlanets.AddItem "Venus"
End Sub

'----------------------------------
'Add items to the Combo Box when the
'Form Loads using AddItem.
'----------------------------------
'The ItemData area of a list box 
'is a great place to store numbers. 
'This could be a record number from 
'a database. Here we are using the 
'number as a pointer that we can 
'select the text with.
'----------------------------------
    Form1.cboSelectText.AddItem "General Info."
    Form1.cboSelectText.ItemData(Form1.cboSelectText.NewIndex) = 1
    Form1.cboSelectText.AddItem "Statistics"
    Form1.cboSelectText.ItemData(Form1.cboSelectText.NewIndex) = 2
    Form1.cboSelectText.AddItem "History"
    Form1.cboSelectText.ItemData(Form1.cboSelectText.NewIndex) = 3
End Sub

The ItemData property is an array of long integer values with the same number of items as a control's List property. You can associate a unique value with each item to identify it. For example, you can use an employee's ID number to identify each employee name in a ListBox. The ItemData property is often used as an index for an array of data structures associated with items in a ListBox.

The cboSelectText_Click() event gets the listbox selection and calls the GetInfo function to return the text to the TextBox. The same code was placed into the cboSelectText_Change() event so that the user could type in the response instead of clicking on the list(see note at end).

Private Sub cboSelectText_Change()
Dim rs 'returned string from GetInfo function
Dim Choice As Long

' *** get the text of the list
Choice = Form1.lstPlanets.ListIndex
' *** call the function and get the display text
rs = GetInfo(Choice)
' *** display the text
Form1.txtContent.Text = rs
End Sub

Private Sub cboSelectText_Click()
Dim rs
Dim Choice As Long

' *** get the text of the list
Choice = Form1.lstPlanets.ListIndex
' *** call the function and get the display text
rs = GetInfo(Choice)
' *** display the text
Form1.txtContent.Text = rs

End Sub

With....End With

Ok, now you have the basics done. As I was looking at this code I saw how we could optimize it a little bit more -and teach you something useful at the same time- so I decided to add this extra section.

Visual Basic has a useful statement called the With statement that we can use to optimize and clarify our code. Here's an example using a snip from our code.

    Form1.lstPlanets.AddItem "Asteroids"
    Form1.lstPlanets.AddItem "Earth"
    Form1.lstPlanets.AddItem "Jupiter"
    Form1.lstPlanets.AddItem "Mars"
    Form1.lstPlanets.AddItem "Mercury"
    Form1.lstPlanets.AddItem "Meteor"
    Form1.lstPlanets.AddItem "Neptune"
    Form1.lstPlanets.AddItem "Pluto"
    Form1.lstPlanets.AddItem "Saturn"
    Form1.lstPlanets.AddItem "Space Craft"
    Form1.lstPlanets.AddItem "Sun"
    Form1.lstPlanets.AddItem "Uranus"
    Form1.lstPlanets.AddItem "Venus"

Notice how we repeat the Form1.lstPlanets.AddItem over and over? Wouldn't it be great to just do it once? Well you can with the With statement! Here's how the new code would look, you can change replace this code in the Form_Load Event.

  With Form1.lstPlanets
      .AddItem "Asteroids"
      .AddItem "Earth"
      .AddItem "Jupiter"
      .AddItem "Mars"
      .AddItem "Mercury"
      .AddItem "Meteor"
      .AddItem "Neptune"
      .AddItem "Pluto"
      .AddItem "Saturn"
      .AddItem "Space Craft"
      .AddItem "Sun"
      .AddItem "Uranus"
      .AddItem "Venus"
  End With

I mentioned earlier how by saving the App.Path value in a variable we could make our program a little more effecient, this is another example. Notice that the code is easier to read; also, when you use With your are telling VB that everything between the With and End With tags is refering to (in this case)Form1.lstPlanets, otherwise VB would have to figure out which object we are using on every line! What a waste! This is a handy statement that you will use again with other structures, be sure to check out your online help file.

You can also use this statement with properties of objects. Here's how....

  With txtBox
       .Height = 1000
       .Width = 1000
       .MaxLength = 50
       .Text = "With is a cool statement!"
  End With

Let's see if we can change any other code...

Just beneath the code we just altered in Form_Load, change that next bit of code to look like this...

With Form1.cboSelectText
     .AddItem "General Info."
     .ItemData(Form1.cboSelectText.NewIndex) = 1
     .AddItem "Statistics"
     .ItemData(Form1.cboSelectText.NewIndex) = 2
     .AddItem "History"
     .ItemData(Form1.cboSelectText.NewIndex) = 3
End With

One last tip; you may have noticed that we used the following convention "Form1.cboSelectText.Clear". Since Form1 is the current form you could just as easily reffered to "cboSelectText.Clear" instead; however it's good programming practice to do it the way we did, with time your projects will probably use several forms and be larger and more complex. Remember! proper commenting and adhereing to naming conventions and programming standards now, will save you hours of grief debugging your programs later..

That's all of it! Review the code carefully, experiment with the concepts presented here, check out the Visual Basics help files and ask questions. If you'd like to down load the complete Galaxy 2.0 project, in VB 5.0 format, click here. Make sure and change the path in the lstPlanets_Click event so that your program can find the pictures.

Also, I am using a VB6 Beta for some testing, and since I assume most of you don't have VB6 yet , I left the original VB5 project here. You can use it to start and make the modifications I suggested in the tutorial. If somebody feels sorry for their neighbors and wants to recreate the project in VB5 let me know and I'll post the updated version -thanks!