BlitzCoder - Blitz Basic Game Development Resources

Blitz2D Intermediates: Re-usable Functions (Libraries) by Krylar

Introduction:

Once you get a function working really swell, wouldn't it be great to use it over and over again? Most of the time we get so involved in the coding of our game that we don't really plan things out well. This is bad because in the next game we go to write we'll need to go through the same issues we went through before.

One of the coolest things is to take a little extra time to create a library (that you can use the BlitzBasic Include on) that you can use over and over again. This doesn't mean you won't need to make some minor changes to that library, but thought through well enough...those changes *should* be minimal.

Thinking REUSABLE!

The first thing I try to think of when planning for reusability in a library is keeping the amount of data in the calling function low. I don't want the caller to have to do tons of stuff in order to get the library to work. Ideally, I should only have to Include the library and then call one management function for that library. Granted you may want to call other functions specifically too, but I try to design with the one function thought.

I do this for a couple of reasons. First off it's to protect the caller from goofing up the library. If the library requires that things be called in a certain order and the caller doesn't follow that order...kaboom. Secondly, I don't wanna have to remember a bunch of stuff!

Another thing I plan for is configurations. There are a few ways to go about this. First off you can have an uber function that takes 50 arguments to set things up. This is a rough way to go for the caller though and isn't recommended. Another way is to have a bunch of indidual functions that set up pieces of the library. Again, I don't recommend this because if a user forgets one...kaboom.

A third method is to put all of the configuration options into a file that the user can edit. Done correctly, this is an excellent option because it allows the user to control the outcome of the library without having to touch the code. This can also be overkill though, depending on your library's purpose. Additionally, this doesn't guarantee that the user will be able to do everything he/she wants without still making code changes.

The last way I can think of is to put together a set of values (of type CONST is usually the best) that the user can alter in the code itself, and also to comment the places in the code where the user should focus making changes as necessary.

By doing this the user really shouldn't have to do much altering at all in order to get things working in the way they want them to work!

The Directory Example

In order to demonstrate this, I created a directory navigation tool. It's not visually stunning, and it's functionality is somewhat limited, but it gets the idea across.

The goal was to write a library that did the following:

Display a dialog box with buttons and such at the user's specified X,Y location
Allow user to create their own dialog box graphics and provide proper X,Y,Width,Height info for each button they design and for the file listing area, and allow the user to edit the code to have functionality for added buttons
Allow user to control the number of files to list in the dialog box
Allow the user to decide what color to draw the file listing in
List all the files and DIRectories in the current directory
Allow the user to click on up/down arrows to scroll the directory
Allow the user to click on any file and have that file be the currently selected file
Allow the user to click on any DIRectory or Drive letter and have the library change to the selected directory
Return the filename, with the path, that the user selected, or NULL if no file or CANCEL was selected

With that I first setup the following CONST values, and the graphic image:

Const MaxFilesPerListing=18                 ; how many lines will your graphical listbox hold?
  Const StartListingAt_X_Coordinate=215       ; Where is the leftmost character to print out on X?  
  Const StartListingAt_Y_Coordinate=140       ; Where is the leftmost character to print out on Y?
  Const ListingFontHeight=16                  ; What size font are you using? (Default is 16)
  Const RedListingFont=0                      ; What Red color do you want?
  Const GreenListingFont=0                    ; What Green color do you want?
  Const BlueListingFont=0                     ; What Blue color do you want?
  Const CurrentFileX=272                      ; Where is the leftmost character of the "File:" field to print on X?
  Const CurrentFileY=444                      ; Where is the leftmost character of the "File:" field to print on Y?
  Const DirectoryImageX=200                   ; Where should your graphic directory image start to draw on the X-Axis?
  Const DirectoryImageY=100                   ; Where should your graphic directory image start to draw on the Y-Axis?

; The following four consts determine the box to check for actual file/directory clicks from the user.  If the
  ; moust is within this box, the functions will assume a file or directory click is in effect.
  Const DirListingX1=215                     
  Const DirListingX2=561
  Const DirListingY1=140
  Const DirListingY2=428

; Load up the main directory graphic
  Global Directory_Image=LoadImage("Graphics\directory.bmp")

Now the user can control a lot of stuff just by changing the CONST values, and the user can change the dialog box graphic by either updating "directory.bmp" to their taste or by creating something new altogether.

The next step was setting up the areas where the user could make code changes. Now, granted, the user *could* change anything they wanted, but that's not really the idea. The idea is to set it up so they don't *have* to make any...or many...changes. With that in mind, I tried to cover the necessary things: Scroll up, scroll down, Ok button, Cancel button, file selections, directory changes. But the user may not like my layout or may want to have a File Types section, etc. So I comment thoroughly and then put in things like this:

; under here is where you could add a bunch of your own buttons and
  ; functions for what they do, etc.
  Select OpenItemSelected$
         Case "OK"                         ; clicked the OK button
              ExitDirectoryMain = 1       ; break out of the loop
         Case "CANCEL"
              CurrentFileSelected$="NULL" ; reset the CurrentFileSelected
              ExitDirectoryMain = 1       ; break out of the loop
         Case "SCROLLDOWN"
              ; update the FileListOffset so when the ShowDirectory
              ; function is called it will appear to scroll down
              FileListOffset = FileListOffset + 1
              If FileListOffset >= TotalFiles - MaxFilesPerListing
                 FileListOffset = TotalFiles - MaxFilesPerListing
              EndIf
         Case "SCROLLUP"
              ; update the FileListOffset so when the ShowDirectory
              ; function is called it will appear to scroll up
              FileListOffset = FileListOffset - 1
              If FileListOffset < 0
                 FileListOffset = 0
              EndIf 
         Case "DIRCHANGE" ; called only if the item clicked was <DIR>
              ; reset the FileListOffset to be the first element in the new DIR
              FileListOffset = 0
              ; Get TotalFiles for the new DIR
              TotalFiles=GetDirectory(CurrentDir$())
              ; reset the CurrentFileSelected
              CurrentFileSelected$="NULL"
         Default
              ; The user must have clicked on a file, so put the filename 
              ; into CurrentFileSelected
              CurrentFileSelected$ = OpenItemSelected$
  End Select

Now the user only has to add another Case in order to add functionality. Plus they can easily edit the code between the cases to change functionality.

Calling ONE function

For me the best coding-interface to a library is a single function. Again, I understand that this isn't always possible, but I always attempt it ;)

In the Directory library case, I thought that the best way to handle things was to allow the user to choose the graphic to use for the mouse cursor, plus I wanted to get the screen's width and height so I could save the entire background graphic. I do this save so the user gets the screen back exactly as it was prior to calling the Directory library.

Now, in order to use this Directory library the user simply does the following:

When the library returns, the value of CurrentFileSelected$ will be the filename the user selected...or NULL.

Conclusion

This little library is great for loading files and jumping around, but it's not as robust as it should be. Again, though, that wasn't the point ;) However, I would highly recommend that you take this library and update it to have expanded abilities such as:

Allowing the user to input the file name
Allowing the user to select to display on the file types (such as .bmp, or .bb) that they want
Showing the drive letters in a seperate box from the file listing box

Basically making the Directory library more like the Windows file interface.

To grab a lame little demo of this and all the Directory library source code: Click Here

Until next time...cya!

-Krylar

For a printable copy of this article, please click HERE.