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:
- Create your own custom Windows gadgets by catching WM_PAINT and WM_DRAWITEM messages
- Catch mouse events from any gadget
- Monitor keypresses in another program, like notepad
- Minimize your app to the system tray
- Monitor system tray events, like clicks and mousemoves
- Know when other windows are closed
- Know when CUT, COPY, and PASTE are used
- Know when a treeview node is expanded or contracted
- Know when any item in any gadget (treeview, listbox, etc) is changed... with the mouse OR keyboard
- 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:
- Put bless.bb and bless.dll in your development folder
- Put bless.decls in your userlib folder
- In your sourcecode, use: Include "bless.bb"
- If you're using Blitz3D, use this line: Bless_UseAlternateMethod(True) ; Alternate BLESS event notification method
- Then let BLESS know which event and window you want to monitor with Bless_RegisterEvent()
- In your main loop or event loop, check BLESS events with KeyHit or event $103
- Use EventData() to get any extended event information, if necessary
- 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:
- Some problems may occur when running more than one program that uses BLESS (at the same time)
- In
the Notepad Demo, sometimes Blitz3D doesn't process the WM_DESTROY
message after rapidly pressing a bunch of characters and quickly
closing Notepad
- If Bless_UnregisterEvent(0) isn't called before
program termination, Windows may not completely unload the DLL for a
few minutes, during which time BLESS events may not work completely.
- Since
Bless_EventData only returns information for the last event that
occurred of a certain BLESS event ID, any previous event data not
queried will be lost. So, if events occur very rapidly, (like
WM_MOUSEMOVE while rapidly moving the mouse), not all mouse event
coordinates may be able to be retrieved.
Is there unknown territory for BLESS?
Yes, I'm interested in knowing how the following work:
- Detecting some events (like WM_COMMAND and WM_NOTIFY) on Win95/98/ME systems
- BLESS on Unicode-enabled systems (using the default BLESS event method)
- BLESS on slow systems
- BLESS on non-standard keyboards and other input devices (using the alternate BLESS event method)