HWND_vpapa

This class is a virtual base for various mix-ins that deal with windows. Its concept is to make a C++ object that is synonomous with a HWND. See the User’s Guide for more discussion.

HWND_vpapa()

constructor, public

The constructor is unsurprising.

~HWND_vpapa()

destructor, virtual, public

The destructor will unhook the class, to ensure that subsequent messages don’t get sent to a nonexistant object. The WinProc itself is a thunk that’s a member of this class, so the WinProc function pointer becomes invalid! Normally, the window owns this object so it won’t be destructed until after the window is destroyed, but usage can vary and the situation could be complex, so this is there just to be safe.

void forge_reference()

protected

This creates a fake reference to this object, to mimic a handle being kept by the HWND. It is called by message_tap::hook as part of the binding operation. Another implementation of such a binding would do likewise.

It is named forge as a double entendre: it indicates “to form or give shape to” as in forging a chain, but it also indiates counterfeiting, because this relationship is formed by doctoring the books.

This is actually implemented by keeping a handle to itself as a private member, because that is the only easy way to do it without breaking encapsulation of the smart pointer system. It would be possible to implement without needing an extra data member, but keeping the implementation straightforward and simple is more important.

See also: release_forged_reference.

void release_forged_reference()

protected

This release the extra reference count created by forge_reference. It is called by message_tap::unhook when the HWND is destroyed, to mimic the HWND’s destructor holding a handle to this object.

It must be used cautiously, as it can trigger delete this; if that was the only remaining owned reference!

void report_error (const classics::exception& X)

public, virtual

This function is called to log non-fatal errors generated within the class, and any exceptions caught by the internal hook handler.

The supplied implementation calls X.show(). This probably does not need to be changed, since you can customize the meaning of show already, on an application-wide basis.

void set_window_handle (HWND)

public

This function performs half the work needed to associate this object with the specified Win32 Window handle. It sets the data member so that subsequent calls to window_handle will return the specified window handle.

It is used to complete the circuit if you used message_tap::get_WndProc to directly specify the window proc or dialog proc, as opposed to subclassing an existing window. Specifically, hook calls this for you.

It is an error to call this function more than once (unless it is redundant—the parameter is the same). This catches errors from duplicate use of the same instance.

See also: message_tap::get_WndProc

HWND window_handle() const

public

This returns the Win32 window handle of the window to which this class is paired with.

Note that this is a const member, as the state of this object is not affected. However, you can still modify the corresponding window object through this HWND, since there is no const-ness concept on HANDLE’s.

See also: set_window_handle, message_tap::hook