BLESS (BLitz EventS System) Readme

What is BLESS?

BLESS stands for "BLitz EventS System". It is a small DLL made to augment the event-handling power of BlitzPlus and Blitz3D, hopefully alleviating some of their shortcomings.

Why would I want BLESS?

BlitzPlus users, have you ever wished BlitzPlus had a certain feature, and been frustrated to find that you couldn't code it yourself because of the shortcomings of the language?  Blitz3D users, have you ever wanted some of the event-handling power of BlitzPlus?

BLESS increases the number of Windows events your program can monitor and react to. BlitzPlus gives you access to 21 (or so) events. Blitz3D mostly just gives you access to input-related events. But, with BLESS, you can monitor and react to pretty much any Windows event that occurs for any window -- not just your own Blitz window.

Also, BLESS is built to be very open-ended. With a little knowledge of the Windows API and some documentation from MSDN, it can be a very powerful tool. It was written to be as unintrusive as possible, doing only what Blitz CAN'T do, thereby letting you, the Blitz programmer, implement whatever you like, however you like.

What can I do with BLESS?

Here are some of the things BLESS allows you to do, as shown in the example programs:
  1. Create your own custom Windows gadgets by catching WM_PAINT and WM_DRAWITEM messages
  2. Catch mouse events from any gadget
  3. Monitor keypresses in another program, like notepad
  4. Minimize your app to the system tray
  5. Monitor system tray events, like clicks and mousemoves
  6. Know when other windows are closed
  7. Know when CUT, COPY, and PASTE are used
  8. Know when a treeview node is expanded or contracted
  9. Know when any item in any gadget (treeview, listbox, etc) is changed... with the mouse OR keyboard
  10.  Drag-and-Drop files into your window
But since there are so many different Windows messages, notifications, and events, there are many more possibilities with BLESS.

How does BLESS work?

You tell BLESS an event and gadgets/window you're interested in, and when BLESS notices the particular event happening to the particular gadget or window, it lets you know by sending a BLESS event to your Blitz program. What is a BLESS event?  For BlitzPlus, the BLESS event is disguised as a special character code from the unused portion of the UTF-16 (unicode) range. For Blitz3D, it is disguised as a scancode for a non-existent keyboard key. Either way, for you to detect the event, it's as simple as using KeyHit (Blitz3D) or event $103 (Keystroke in BlitzPlus).

How do I use BLESS?

See the BLESS Documentation for more info. To quickly get up and running, it's as simple as this:
  1. Put bless.bb and bless.dll in your development folder
  2. Put bless.decls in your userlib folder
  3. In your sourcecode, use: Include "bless.bb"
  4. If you're using Blitz3D, use this line: Bless_UseAlternateMethod(True) ; Alternate BLESS event notification method
  5. Then let BLESS know which event and window you want to monitor with Bless_RegisterEvent()
  6. In your main loop or event loop, check BLESS events with KeyHit or event $103
  7. Use EventData() to get any extended event information, if necessary
  8. Before terminating your program, call: Bless_UnregisterEvent(0)
That's it. Also, example source code is included.

Are there known issues in BLESS?

Yes, BLESS is currently classified as beta. Here are some issues:

Is there unknown territory for BLESS?

Yes, I'm interested in knowing how the following work:

  1. Detecting some events (like WM_COMMAND and WM_NOTIFY) on Win95/98/ME systems
  2. BLESS on Unicode-enabled systems (using the default BLESS event method)
  3. BLESS on slow systems
  4. BLESS on non-standard keyboards and other input devices (using the alternate BLESS event method)