BLESS (BLitz EventS System) Documentation
Setup
BLESS is simple to set up.
- Copy bless.dll and bless.bb into your development folder
- Copy bless.decls into your userlibs folder
Now you're ready to use BLESS.
Functions
Bless_RegisterEvent
Bless_RegisterEvent%(BlessID%, WindowsEvent%, hwndSource%, hwndDest%)
Description
Tells BLESS that you want to receive notification of a certain event
occurrence on a certain window or gadget
Parameters
- BlessID% is a user-defined BLESS Event ID. It
should be between BLESS+0 and BLESS+2047 if using the default BLESS
event notification method, or if using the alternate BLESS event
notification method, between BLESS_0 and BLESS_110. This is
the character code or scancode (respectively) that you should check for
in your event/main loop.
- WindowsEvent% refers to any Windows notification or
message, many of which are defined in Bless.bb (such as
WM_LBUTTONDOWN). This is the event that you want to catch.
- hwndSource% is the window handle of the window or gadget
that you want to monitor. Get this with QueryObject or
FindWindowEx (or similar).
- hwndDest% is the handle of the window that you want to send
the BLESS event to. When BLESS detects WindowsEvent%
occurring to hwndSource%, it sends BlessID% (as a keypress) to
hwndDest%. In most cases, hwndDest% should be the window
handle of your main Blitz window.
Return Values
Bless_RegisterEvent returns True if successful, and False otherwise.
Some things that could cause failure are:
- Using a BlessID that's out of range according to the BLESS
event notification method being used.
- Not having bless.dll in the search path
- Trying to register a BlessID that's already registered
Bless_UnregisterEvent
Bless_UnregisterEvent%(BlessID%)
Description
Tells BLESS that you are no longer interested in the BLESS event
BlessID (previously registered with Bless_RegisterEvent).
Frees up resources used by Bless_RegisterEvent().
Parameters
- BlessID% corresponds to any BlessID previously registered
with Bless_RegisterEvent(). Or, if 0 is sent instead of a
BlessID%, then all the previously registered BLESS events will be
unregistered and all resources freed. It is recommended to
call Bless_UnregisterEvent(0) before terminating the Blitz program.
Return Values
Bless_UnregisterEvent returns True if successful, and False
otherwise. Some things that could cause failure are:
- There are no registered BLESS events
- There is no registered BLESS event corresponding to BlessID%
Bless_EventData
Bless_EventData(BlessID%, evd*)
Description
Provides extended event information for a particular BLESS
event. The data corresponds to the wParam and lParam
parameters of the event (see MSDN for the particular Windows event
specification).
Parameters
- BlessID% tells BLESS which BLESS event you want to retrieve
information for. It is the same as used previously in
Bless_RegisterEvent()
- The evd parameter, in most cases, should be
"Bless_EventData", which is a custom type instance defined in
bless.bb. Its fields are wparam and lparam (e.g.
Bless_EventData\wparam) which are filled with only the most recent
event corresponding to the particular BlessID.
Return Values
None. However, evd is an [out] parameter.
Comments
If you are interested in the extended event information,
Bless_EventData() should be called as soon as possible after detecting
the BLESS event. For example, for BlessID "BLESS+5", you
should call Bless_EventData(BLESS+5, Bless_EventData) right after
detecting the BLESS event with KeyHit() or event $103. If you wait too
long and another event occurs which corresponds to the same BlessID,
then the previous event data will be lost. This is necessary,
because BLESS has no way of knowing when and how each Windows event is
processed by Blitz, and what information the programmer may be
interested in, and for how long. Thus, keeping a queue of all the event
data for each BLESS event would be unreasonably complex. Anyway, this
doesn't usually pose much of a problem--event handling is quite fast.
Bless_UseAlternateMethod
Bless_UseAlternateMethod(bAlt%)
Description
Allows the programmer to switch between using the default BLESS event
notification method or the alternate BLESS event notification method.
Generally, the programmer should use the default method with BlitzPlus,
and the alternate method with Blitz3D.
Parameters
1. bAlt% should be True for the
alternate method, or False for the default method. If the default
method is wanted, the programmer need not call this function.
Return Values
None.
Notes
If any BLESS events have been registered before calling
Bless_UseAlternateMethod (and changing the notification method), they
will all be unregistered. Therefore, it is best to call this before
registering any BLESS events. If Bless_UseAlternateMethod() is called
with the same method parameter that's currently in use, nothing happens.
When using the default event notification method, BLESS sends keystroke
events to Blitz, with character codes in the range BLESS to
BLESS+2047. These can be detected with event
$103. When the alternate event notification method is enabled,
BLESS sends keydown events to Blitz, with scancodes specified by
BLESS_0 through BLESS_110. These can be detected with KeyHit()
or event $101.
With the default method, the character codes are in the range of the
unused (at least singly) UTF-16 Unicode range. With the
alternate method, the scancodes should theoretically be unused by 99%
of the keyboards out there. As of the beta release, it is
unknown how BLESS will respond on unicode-configured systems with the
default method, or with non-standard keyboards and input devices with
the alternate method.
Hints
- Of course, be sure to include bless.bb in your program.
- Sometimes, when monitoring events with the Blitz window out
of focus (for instance, when it's minimized to the tray and the mouse
pointer is clicking on the tray icon), the events may not be processed
by Blitz until the mouse pointer moves back over to the Blitz window
(or something similar which causes the message pump to start pumping
again). To alleviate this, make sure you call CreateTimer (like
CreateTimer(60)) at the beginning of your program. This will make sure
that BLESS events get pushed through the message pump quickly.
- Learn to use tools like MSDN, API Guide, API Viewer, and
WinDowse.
- Post to the Blitz forums with your BLESS successes,
failures, and questions.
- At least in this beta, always call Bless_UnregisterEvent(0)
before terminating the program. If the program terminates
abnormally with BLESS events having been registered, and they don't
seem to be working after restarting your program, try killing and
re-running explorer.exe, or just wait a few minutes.
- Understand the WinAPI.
- Understand the examples.