BLESS (BLitz EventS System) Documentation

Setup

BLESS is simple to set up.
  1. Copy bless.dll and bless.bb into your development folder
  2. 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

  1. 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.
  2. 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.
  3. hwndSource% is the window handle of the window or gadget that you want to monitor.  Get this with QueryObject or FindWindowEx (or similar).
  4. 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:

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

  1. 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:

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

  1. BlessID% tells BLESS which BLESS event you want to retrieve information for. It is the same as used previously in Bless_RegisterEvent()
  2. 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

  1. Of course, be sure to include bless.bb in your program.
  2. 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.
  3. Learn to use tools like MSDN, API Guide, API Viewer, and WinDowse.
  4. Post to the Blitz forums with your BLESS successes, failures, and questions.
  5. 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.
  6. Understand the WinAPI.
  7. Understand the examples.