Tutorial 1 - Getting started writing Whisker tasks in Visual Basic

Source code for this project is supplied in the Tutorials folder (by default, within \Program Files\WhiskerControl).

Requirements

Typically, these will be the same machine, running the Programmer's edition of Whisker.

Setting up a new VB project

Run Visual Basic.

Select a 'Standard Exe' New Project.

You will see something like the screen below. This is the main window, the toolbox (left), the project explorer (top right) and the properties panel (bottom right), and immediate window (bottom). There may be some other windows showing, such as 'window position', which you can close.

Note: These different windows can be closed, and reopened from the View menu. Save yourself time later, by getingt used to closing, opening and positioning these windows – otherwise it can be very confusing when one suddenly disappears!

A new project in Visual Basic 6.0.

Visual Basic has given you a form (a simple kind of 'window' template) to play with. When the VB application is running, that form will be displayed to the user, and (most importantly) that form will receive messages ("EVENTS") from Windows.

Usually in VB these events will be things like mouse clicks – in our application, they are going to be the Whisker Events (licks, lever presses, etc) that we care about.

Making the form capable of receiving these events is simply a matter of placing an object on the form. This object is the Whisker SDK Control (A 'Control' is the name of the things that Visual Basic can put on forms). The panel on the left (with the General button) is the control toolbox – these are all the things we can add to the form. At the moment, our SDK Control isn't in there, so we have to tell VB to add it to our toolbox.

Adding the Whisker SDK control to the toolbox

Right click on the toolbox , and select Components… from the menu.

Components (left) and the Toolbox (right)

This will bring up a dialog like the one shown Find the Whisker SDK Control ActiveX Control module, and select it as shown above (Note ActiveX is Microsoft's name for the kind of technology used to write controls.

[If you cant see anything like 'Whisker SDK Control' in the list of controls, then you can look for it manually by selecting browse. It exists as a file called "Whisker SDK.ocx" in the system directory (if you have installed the SDK). Click 'Browse' and type Whisker SDK.ocx in the dialog that appears.]

Click OK, and the Control should now be shown in the toolbox.

Adding the Whisker SDK control to the form

Now, if you select the Whisker SDK control in the toolbox (by clicking it), and then click-drag an area on the form, a control will appear on the form. The control is a fixed size (unlike most VB controls, so you can drag it to be any size, but it will always snap back). You can put the control where you like on the form, as it wont be visible on the screen when your task is running.

Note: many aspects of Visual Basic programming require us to distinguish between how things behave whilst we are programming (design time) and whilst the application is running (run time). So to use the standard parlance, we would say that the Whisker SDK Control is "invisible at runtime".  You will become more familiar with this terminology as you go on.

Setting the Control's properties

Control properties.

When the Control is selected, the properties panel will show a set of properties associated with the control object. Some of these properties govern how the control will behave (in terms of which Server it tries to talk to, etc.), and some govern how the form (i.e. VB) will deal with the control.

If you click on a property, the pane at the bottom of the property panel gives a brief introduction to what each property does. At the top of the list are three special lines: (Name), (About) and (Custom).

The most important line to begin with is (Name). This shows and sets the name that VB will use internally to refer to the control. By  default this will be "WhiskerSDK1" which we can change to something else. Change it to "Whisker".

This name 'Whisker' can now be used within your program to access all of the Whisker functions from within the control.

The (About) line contains a button in the right hand field. Clicking it shows an 'about box' – which shows you the copyright notice, the version number of the control, and (of course) my name in lights!

The (Custom) line shows a property page for the control. Many of the other properties relating to your task (the name it will use to identify itself to the server, which server to connect to, where to look for media files, etc) can be accessed from this property page.

Note: This page (unlike the main properties pane) can be viewed at run-time – that is, the user of your program can be shown this page (by means of a control function "ChangeSettings") in case they want to change these settings. This means that you don't have to write the same code in each of your programs to allow the user to choose the server, for example.

Take a moment to look at the properties. Visual Basic initialises them with sensible defaults – server name 'localhost' is a IP networking shorthand for 'this machine'. With the servername set to this, the application will try to talk to a server running on the same machine. That's (nearly always) what we'll want to do! Use both the properties panel, and the (Custom) button to play with the settings. Change the name of the task – call it something like "Harry's first whisker task" if you want….

Adding code to the form

In VB, code can live in 3 main places.

For now, we're only going to scratch the surface of VB programming, and put all of our code in the form. The code in a form is used to manipulate the data represented by that form (remember – the form is a kind of window which can be presented to the user), and also to respond to events that windows sends to the form.

Note: Using code modules and class modules allows you to code in a much more concise & logical way than just plonking all your code in a form. As you get more used to VB programming, it is worth learning about 'object oriented' approaches. This will allow you to write programs quickly, and produce code that is much easier to understand and to debug!

If you double click on the form, or click the view code button, the main window will switch from the 'form designer' to the 'code editor'.

The 'View Code' button

The code editor is where you type in the program. The code for a VB application will all be inside subroutines (similar to PROCedures in BBC BASIC).

Why? Why doesn't it just start at the beginning?

The idea of a program needing a 'first line' is something people who have learned BBC BASIC, or similar languages, are used to. But it doesn't make much difference to the logic where in the code the 'entry point' actually is – for example we could take a BBC BASIC program and put all of the stuff that isn't inside PROCedures, into procedure called 'start', and replace the first line with PROCstart. It wouldn't make any difference to how the program worked.

VB will call your code when it needs to – in response to an event, or at certain times, such as when it has started the program, or when the user has clicked the 'close' button on the form. It is possible to setup a VB project so that it starts with one procedure (sub main) as the 'beginning of the application', rather than loading a form. But you can learn how to do that later!

The Form_Load subroutine

If you double-clicked on the form to get to the code editor, you will now see the beginning and end of a subroutine marked by VB. This is the routine that VB will call as it starts the application, so we can regard it as the 'start' of our application.

If you clicked the View Code button to start the editor, you can insert the Form_Load subroutine by using the two pull-down menus at the top of the editor window. Select 'Form' in the left hand box, and 'Load' in the right hand box.

Form → Load

Note: The Form_Load subroutine is an Event-handling routine. That is, VB calls this routine when the 'being loaded' event happens to the form. [If our application just shows this form, this event happens as soon as the application starts]. All event routines have the same naming practise "objectname_eventname".

Calling Whisker functions

Let's say that we want to connect to the whisker server as soon as the form is loaded. We will need to tell VB to connect the control to the server – this is done by calling one of the control's methods "ConnectToServer".

Under the line

Private Sub Form_Load()

Type the following

       Whisker.ConnectToServer

Did something funny happen when you were typing? You should have seen a box pop up as soon as you typed the period (full stop) after whisker. This is a handy feature of VB – it knows all of the methods (functions) and properties that can be accessed through the Whisker SDK control object – so you don't have to remember them all!

Now we can test the program. Run WhiskerServer (on the same machine), and once it has started, run the VB program (Run->Start; press F5; or click the blue arrow on the toolbar). You should see the form appear. On the Server Window's left hand panel, click on the plus next to the server, and then on the plus next to Clients. You should see your client's name.

Well done – you've written your first Whisker client.

Extending the client: The VB Status Client Deluxe

Although we have written a client, even in our flush of pride at our new creation, we will have to admit one thing. It's a bit rubbish. So – let's make it into something useful.

A useful client could be one that monitored what was happening on the server. There is a simple client that does just this - the Whisker StatusClient which comes with the server. The status client connects to the server, and asks for information about all connected clients, which it then displays. The display does not update unless the user clicks a button. For our first 'useful' client, we can make an enhanced version of a status client which asks Whisker for a Timer, so that it can refresh its information every couple of seconds.

All the code we need is below – paste or type it into the code window. You can get VB to insert the Whisker subs by using the two menus at the top of the code window.

Private Sub Form_Load()

       Whisker.ConnectToServer

       Whisker.TimerSetEvent "refresh", 2000, -1

End Sub

'called by VB when we start the application.

'It connects to the server, and then asks Whisker for a timer.

'The Timer will send the EVENT (a string 'refresh') after 2000 ms, and repeat indefinitely.

Private Sub Whisker_Event(ByVal EventMessage As String, ByVal Time As Long)

       Cls

       Whisker.SendToServer "WhiskerStatus"

       Whisker.Status = "Connected for " + Str(Time / 1000) + " seconds"

End Sub

'Called by VB whenever an event occurs.

'Clears the form background, then sends a command message to the server

'Updates the client's reported status to reflect how long we've been connected

Private Sub Whisker_Info(ByVal InfoMessage As String, ByVal Time As Long)

       Print InfoMessage

End Sub

'Called by VB whenever the server sends information.

'Prints the information onto the form

Now run the program. If you copied the code right, you now have a truly useful program in 6 lines of hand-written code (count them). That's why VB is called a Rapid Application Development language!

Note: in response to receiving the command "WhiskerStatus" the server sends a set of information about all connected clients. See the programmer's guide for details.

Making it truly useful

Although this client works, it is not actually that useful. Why not? Well we wouldn't want to use a Whisker Timer to update the display, because we might well want this client to be running on a different machine to the Server. Generally, it's not a good idea to allow clients from other machines to control devices on the Server across the network  (although you can set the server up that way if you want). Because a Timer counts as a device – a remote monitor client will not be able to do this.

We can make it more useful by asking Windows to time the interval for us using the Timer control instead of the Whisker Timer. This is a simple modification to the code above, and is left as an exercise. You will have to look at the online help for VB and find out about Timer controls [Don't worry about updating the client's status with the connection time in your new version – that is only included to show that the client is updating!]

If you can't work out how to do it, then the answer can be found, along with the source code, in the Tutorial 1 Files folder – but try to figure it out for yourself first!

When you've got the program working, you can turn it into an .EXE file which runs without VisualBasic (under File→Make Exe). There's your first completed Whisker Client!

A word of warning: any client that uses the SDK Control can only be run on machines with the SDK installed. However, your licence allows you to install the SDK on as many machines as you like (although you can only install one copy of the real Editions of WhiskerServer per licence).

A note on oversimplifications

The client we knocked up above has some problems.

First, it uses the simple (but not that useful) Form.Print and Form.Cls functions. Don't use these for more complex tasks – as they are not very helpful!

Second, the Whisker_Event() procedure doesn't check the contents of the event message to find out what it was – this is no good at all for most clients, as they need to respond to many different events. See the tutorial example on converting an !Arachnid client to Whisker to see how this is done.

Pointers for future programming

Some of the remaining Tutorials wont make sense yet to entirely novice programmers. However, glance through to get a feel of where things are going. Then have a look at any of the VB tutorials available on the web, to get more confident with the basics, practice writing some VB code, and refer back there!