What's All this Hooplah About "Events"

Before getting into the weeds on how to setup a function to handle your text input and all that, let's talk a little bit about Events. You can think of events in development as analogous to events in real life. While you may have 20 events going on at any given time, you can really only give your full attention to one of them at a time. Often we say that we're "multitasking" when we're doing a bunch of stuff at once. But, really, we're only sharing our full attention between the tasks.

This is a similar thing with Events on your computer. For every window you have open, you've got events going on. You may have Blitz open, a browser open, a calculator, etc. When you go into one of these, it has not only *your* focus, but also the operating system's focus.

However, things still go on in the background that your OS has to deal with. For example, there may be one of those annoying rotating ads on the webpage that your browser is on. Every few seconds, your computer is prompted to go and update that (even if you're not looking at it!), and it does so. In essence, your OS is given an Event that it must then give a quick focus to before returning to other things.

I'm not going to get into the weeds on how to do Event Driven Development here, but you will see some things in BlitzPlus that you've not seen in the other Blitz products, so I wanted to make sure you at least had an idea of what is going on.

So, as an idea of it imagine that you have an application that allows people to build maps for your game. Now, you can have it take over the full screen and lock the person into a loop that doesn't allow their computer to do anything other than work on your map editor...or you can give them some freedom to do other things, going back and forth, as they design a really sweet level for you. Now, since you'll want the computer to be able to do normal processing in the background, you will have to set up your program to only take action when it is prompted to. Enter Events.

By using Events you can have your little map maker sitting there all day long doing nothing, taking up very little CPU cycles (if any) until the user shows up and clicks on something. Once they click on something, your computer will receive an Event about what they clicked and will notify your program that something has happened. From there your program (assuming you've coded it correctly!) will take the information and process it accordingly. When it's done, it will drop it's CPU utilization once again and wait around for the next Event.

As you can see, this means that your program is only doing stuff when necessary and, therefore, does not hog the CPU. Depending on your goals, this can be a very good thing.

BlitzPlus Event Codes

Here is a list of some of the more common Event Codes. There may be more of these, but these are the ones that I've been able to find. Note that I got these from a thread on the BlitzBasic website that Simon had posted to...so the thanks goes to him.

You'll need these codes in order to do Events in BlitzPlus. Also, in the example code for this tutorial, I use a few of these as well.

Designing the Function

I was interested in getting a window popup that gave the user the ability to enter in some text for a map editor that I'm working on. Well, I quickly found that this wasn't a simple function call that BlitzPlus offers. I knew that I could get text, have buttons, and do a popup, so I realized that it was up to me to code the little function that I'd need.

I put together a list of needs for the function:

• Text input window name. Let the coder name the window.
• Text for inside the window. Let the coder specify what the text input is for.
• Default text for the input field. Allow the coder to pre-populate the field.
• The maximum amount of text allowed. Allow the coder to set a limit on the number of characters.
• X,Y location of the window. Allow the coder to decide where the window is going to popup.
• Ability to close the window with the "X" in the upper-right of the window
• Ability to trap the use of the "ESC" key and the "ENTER" key, returning updated data on "ENTER" and nothing on "ESC".
• Putting in an "OK" and "CANCEL" button and returning nothing or updated data accordingly.

• CreateWindow: Allows the creation of a new window Gadget
• CreateLabel: Assigns a title to a previously created window
• CreateTextField: Creates a field of pre-determined size for textual uses
• CreateButton: Allows the creations of a push button (such as "Ok", "Cancel")
• SetGadgetLayout: Allows the automatic control of a gadget when the window is altered (resized, moved, etc.)
• ActivateGadget: Makes a previously defined Gadget available for use
• SetGadgetText: Fills a text-based Gadget with specified text
• WaitEvent: Awaits a particular event (from the above list)
• EventID: Returns the ID of any Event that was activated
• EventData: Returns specific data in regards to the Event that was activated (ie. "Enter" key)
• EventSource: Returns the specific source of an Event that was activated (ie. "Ok" button)
• FreeGadget: Frees a Gadget from memory and releases it from the Event system

The Input_GetText$ Function

After designing the function and learning a bit about the Event and Gadget commands, I started coding. I have adopted a new method for any libs I create, and that is to name variables and functions with a precursary value. For example, the library that I was creating was simply called "input.bb". Thus, every variable and function will start with "Input_". I do this because I find it highly unlikely that I'll use that header, if you will, in any of my main program variable or function declarations. Also, I know I won't use it in other libs I make because they'll have their own specific headers. You don't need to take this tact for your libs, of course, it's just the method that I've decided to adopt. The biggest thing is that you adhere to some method and stay consistent with it (unless, of course, you find something better).

Here now is the function with complete commenting. Please refer comments to see what I'm doing throughout:

Remember that you will need to have the Events list I put at the beginning of this tutorial. To demo this code, put the above into your BB editor and then put the following above it (I've included the Events list again here):

Conclusion

I hope you've found this brief tutorial helpful. Please feel free to use/modify/etc. this code for whatever you may need.

-Krylar

• To discuss this article with others, please click HERE.