VisualNewt Software

Programming Using NSBasicCE

ARTICLE 4--CommandButtons

All content (c)1999, 2002 Serg Koren.

All rights reserved.

Welcome to the forth installment of NSBasic.

This time we go over the most common user-interface object you will use: CommandButtons.

Leftovers from Last Time

Last time I we talked about Objects, Properties, and Methods, and I gave you a simple program that had a ListBox object that hid when you double-clicked it:

'---start code here--- ' 

' A simple program that creates a ListBox and lets us show and hide it by clicking on it 

' 

' A subroutine to create a ListBox on the screen 

SUB MakeAListBox 	

    ADDOBJECT "ListBox","MyListBox",50,50,100,100 ' create an empty ListBox 

END SUB         

' A SUB to handle a DblClick Event (a Click event handler) for the ListBox called "listbox" 

SUB MyListBox_DblClick 	

    MyListBox.Hide ' Hide listbox 

END SUB         

' Our main routine where the main things happen...good to always have one 

SUB Main 	MakeAListBox 

' create a ListBox 

END SUB         

Main ' our one and only Immediate command for this program to run the Main SUB '

---end code here---

I then asked you to write a short program (like above), but include a CommandButton Object. The program should have:

1) A ListBox

2) A CommandButton

The program should:

1) Hide the ListBox when you double-click it.

2) Unhide (use the Show method) the ListBox when you tap (Click) the CommandButton.

And I promised to show you one version of the code (and a simpler version).

Here's the version you probably came up with (or a something very similar):

'---start code here--- 

' 

' A simple program that creates a ListBox and lets us show and hide it by clicking on it 

' 

' A subroutine to create a ListBox on the screen 

SUB MakeAListBox 		

   ADDOBJECT "ListBox","MyListBox",50,50,100,100 ' create an empty ListBox 

END SUB   

' A subroutine to create a CommandButton on the screen 

SUB MakeACommandButton 		

   ADDOBJECT "CommandButton","MyCommandButton",50,75,100,50   ' create a CommandButton named MyCommandButton 

END SUB  

' A SUB to handle a DblClick Event (a DblClick event handler) for the ListBox called "MyListBox" 

SUB MyListBox_DblClick 		

   MyListBox.Hide ' Hide MyListBox 

END SUB  

' A SUB to handle a Click Event (a Click event handler) for the CommandButton called "MyCommandButton" 

SUB MyComandButton_Click 		

   MyListBox.Show  ' Show the ListBox "MyListBox" when the user clicks "MyCommandButton" 

END SUB  

' Our main routine where the main things happen...good to always have one 

SUB Main 		

   MakeAListBox         ' create a ListBox   

   MakeACommandButton   ' create a CommandButton 

END SUB  Main ' our one and only Immediate command for this program to run the Main SUB 

'---end code here---

The new code consists of the MakeACommandButton and MyCommandButton_Click subroutines, plus the MakeACommandButton line in the Main subroutine.

The points to remember from last article are:

1. Call Methods using the name of the object, a period, and the name of the Method: MyListBox.Show
2. Write event handlers using the name of the object, an underscore, and the name of the Method (event to be handled): MyListBox_DblClick

Now this looks like a lot of code (believe me it isn't) and complicated (again it isn't). If you followed the last article this should all make sense, if not reread the last article or email me with questions (Serg@VisualNewt.com).

The one question you may be asking, is why do we use a DblClick (double-click) for the list box, instead of a Click as in the CommandButton? Apart from letting you use more than one type of Method and event handler, the ListBox only responds to single clicks (Click) if there is something in the listbox to click on. Otherwise it only responds to DblClick events. (We'll talk more about Events in the next article).

Now for the simplification (believe me it is). Look at the Main subroutine. It calls two subroutines which "make" or "setup" things. Specifically, the methods set up parts of the user interface. What we can do is factor (like in math...remove the common bits) that code out into a separate subroutine, and replace it with a single call to a subroutine in Main. Like this:

SUB Main 		

   SetupUI  ' call a routine to setup our User Interface 

END SUB

So we replaced two lines of code (which did similar things...namely setting up parts of the User Interface) with a single line of code. That's simplified it. But what is this thing called "SetupUI"? It's a call to a new method we write using the lines we took out! Like this:

'   A subroutine to set up all the bits of our user interface (controls). 

SUB SetupUI 	

   MakeAListBox  ' create a ListBox 	

   MakeACommandButton ' create a CommandButton	 

END SUB 

 So our new (simplified) program now looks like: 

'---start code here--- 

' 

' A simple program that creates a ListBox and lets us show and hide it by clicking on it 

' 

' A subroutine to create a ListBox on the screen 

SUB MakeAListBox

   ADDOBJECT "ListBox","MyListBox",50,50,100,100 ' create an empty ListBox 	 

END SUB 

' A subroutine to create a CommandButton on the screen          

SUB MakeACommandButton 	

    ADDOBJECT "CommandButton","MyCommandButton",50,75,100,50 ' create a CommandButton named MyCommandButton  

END SUB   

' A SUB to handle a DblClick Event (a DblClick event handler) for the ListBox called "MyListBox" 

SUB MyListBox_DblClick 	

   MyListBox.Hide ' Hide MyListBox 		

END SUB  

' A SUB to handle a Click Event (a Click event handler) for the CommandButton called "MyCommandButton" 

SUB MyComandButton_Click 	

   MyListBox.Show  ' Show the ListBox "MyListBox" when the user clicks "MyCommandButton" 	

END SUB   

'   A subroutine to set up all the bits of our user interface (controls). 

SUB SetupU

   MakeAListBox  		' create a ListBox
   MakeACommandButton ' create a CommandButton 

END SUB   

' Our main routine where the main things happen...good to always have one 

SUB Main 	

   SetupUI   ' set up our controls 		

END SUB  Main ' our one and only Immediate command for this program to run the Main SUB 

'---end code here---

You may be shaking your head at this point, totally confused. How is this simpler? Right now, it looks like we've added more code and made things more complex. True we've added more code. It's false that it's more complex. The code is easier to follow, easier to understand, we know now that those two lines that we "factored out" set up our user interface, because our Main now tells us that it does. (SetupUI tells you exactly what those lines do, whereas the individual lines may be doing something else such as modifying the user interface, instead of just setting it up). Also, this is a very simple program, as you write more complex programs, you'll be putting all sorts of stuff into your Main subroutine, which would confuse any other reader (and you) about what exactly those line do.

Factoring is a common computer programming concept. It tries to replace code with a common function, with a single subroutine (or function) call, to make the code more understandable. The other reason for factoring is that it makes the factored lines (those two lines in our example) reusable. If you ever needed to set up your user interface more than once in the program you'd only have to write:

...
SetupUI
...
SetupUI
....

instead of:

...
MakeAListBox  ' create a ListBox
MakeACommandButton ' create a CommandButton
...
MakeAListBox  ' create a ListBox
MakeACommandButton ' create a CommandButton
....

Which you have to admit is a lot less typing. Factoring is a "good thing", to steal a phrase. Byte-sized chunks are easier to digest than pages of commands.

Ok...our little program doesn't do much and it really looks kind of pitiful. Our list is empty and our button looks kind of drab and not really like a button. We're going to change our program (it'll still be pitiful, but it won't look as drab.) keeping all we've gone over in mind.

CommandButtons

The CommandButton we've used is one of the two user interface controls (commonly known as widgets) you'll use most frequently. We'll start our in-depth tour of widgets with the CommandBox, and go right into the other most frequentlyused widget, the MSGBOX.

Referring to the NSBasic manual (and proven by our little program earlier), you create a CommandButton the same way you created the ListBox. The only difference in the command was that "CommandButton" followed the key word ADDOBJECT instead of "ListBox". So, from this we can see that NSBasic has a nice consistent way of creating objects. They all follow the same pattern:

ADDOBJECT "the type of object","the name you give your object", xpos, ypos, width,height

Some objects require all these pieces (such as CommandButton) while others only require some of them, but basically if you know how to create one object you know them all. The differences lie in the Events, Methods, and Properties of each object.

A CommandButton, is a simple button, that the user clicks on to get something to happen. It has some text (a label) that describes what the button does. You can change its colors and the style of the text in the label. It's a fairly simple, but very flexible object.

One thing you should be aware of is that if you look at the CommandButton page of the manual, the Properties, Methods, and Events section of the page refer you to other pages. These pages describe each of the corresponding items, and the values that you can set them to. For instance, the BackColor of a CommandButton (the color of the background--that is, the button face color) can be set to a Color...which in turn is explained on yet another page. After a while you'll remember what goes with what thing. But at first, you'll have to do a fair amount of cross-referencing. Just look up the pages Properties, Events, or Methods as needed.

Ok, back to CommandButtons. Let's give our CommandButton in our example program a title. How do we do this? Well, a CommandButton has a Property (remember this is a characteristic of the object) called Caption. And let's make the button say "Hello" on its face. Again, we refer to properties using the dot "." notation. So we would write:

MyCommandButton.Caption = "Hello"

(Remember to put words that are visible to the user, like the caption in quotes--"Hello" instead of Hello.)

Where do we put this line? Well, it's part of creating our button so put it in the bit of code that creates our button, namely "MakeACommandButton"

' A subroutine to create a CommandButton on the screen 

SUB MakeACommandButton 	

   ADDOBJECT "CommandButton","MyCommandButton",50,75,100,50   ' create a CommandButton named MyCommandButton 	MyCommandButton.Caption = "Hello" 

END SUB

Make this change to your program and rerun it. Your button now has as caption! It looks much more like a real button now. We can make the text in the caption standout, by using the FontBold property. (A Font in computer-talk is the shape of the family of letters or text being used to write with. That is, the shape when you ignore things like underlines, italics, and bold, etc.) When you cross-reference FontBold you find it's set to True/False (something known as a Boolean in computerspeak). So if we set it to True, then the text in the caption should be highlighted. Add the line to MakeACommandButton again. I'll wait for you to do it....back? Good. This is what the line looks like:

MyCommandButton.FontBold = True

When you rerun the program you see the caption is darker and stands out now. Take some time now, and play with all the other Properties of a CommandButton. Try different values for them to see their effect on your single button. A lot of these Properties are common to other objects, so if you experiment with them on the CommandButton, you'll know what they do and how to use them in other Objects.

For the time being ignore Properties labelled as (read-only) in the manual. We don't have enough programming yet under our belts to deal with read-only properties.

Onward!

A CommandButton only handles two Events (Methods you can call): Click and GotFocus. We've seen and worked with Click already; this is the Event that triggers your Click event handler method. GotFocus is a bit harder to explain. In simplest terms, GotFocus means the object has been selected (not clicked) but selected. Typically, you move the focus (selection) around by using the Tab button on the keyboard. It moves the selection (highlighting) around from object to object as you hit Tab. You can then hit the Enter key (or the Casio's Action Wheel) to generate a "click" event on that button or control that has "GotFocus". What the GotFocus event handler lets you do, is let you execute some commands whenever the object (CommandButton in this case) gets highlighted. For instance, maybe you have a message come up like a tool-tip (help bubble) whenever someone selects or highlights your button. You could do that in your GotFocus event handler (since NSBasic doesn't support tooltips).

CommandButton Methods include two that we've played with already: Hide and Show. In addition there is something called "SetFocus" you can call this method (MyCommandButton.SetFocus) to highlight the button (and consequently generate a GotFocus event, which would cause your MyCommandButton_GotFocus method to run.) Phew! Now we see some of the power of Objects! Some methods can create secondary events: Doing a SetFocus causes a GotFocus event to be created which causes your GotFocus event handler (method/subroutine) to run. Take a deep breath and reread what we've done so far. It's a lot to digest, and once you understand (or at least feel comfortable with) all this, you're on the road to being a programmer!

The last metthod a CommandButton deals with is Move. This lets you Move the button from your program--that is, alter where it sits depending on something else. Lets move our button to the right 5 units each time the user taps (Clicks) on it. Cross-referencing Move we see it takes similar values to the actual creation command...so in essence we're reacreating our button somewhere else on the screen. This should be simple then, and it is, but we haven't gone over a crucial part of programming yet, namely something known as "parameters" or "parameter passing". We'll leave this for another time.

That's all there really is to CommandButtons (and lots of other Objects) in NSBasic.

To get you used to using CommandButtons, I want you to write a program for next time.

The program should have:

1. Four command buttons.
2. Each button should have a different label: Bold, Italic, Underline, and Normal

The program should:

1. Start with all captions in the default style (not Bold, Underlined, or Italic)
2. When you hit the button that says "Bold" the label style should go bold (stand out)
3. When you hit the button that says "Italic" the label style should switch to italics
4. When you hit the button that says "Underline" the label style should underline
5. When you hit the button that says "Nomal" all label styles should go normal (the default) and undo everything else.
6. No button should affect any other button except for the "Normal" button which affects all the others.
7. Use factoring.

It's not that hard really. Take is slow and if you get stuck reread the sections of the article that explain what you're stuck on. Check for typos, and use double-quotes! We'll go over the answer next time, and we'll finally explain what a SUBroutine really is, and get our first explanation and use of FUNCTIONs. We'll also go over our next Object, the MSGBOX.

If you get stuck or have a question about anything we've gone over, feel free to email me at Serg@VisualNewt.com

Cheers!