Dialog_message_tap

This class modifies the regular message_tap to make it suitable for dialog boxes which use Windows' dialog box mechanism. See the User's Guide for more discussion.

Dialog_message_tap()

constructor, public

The constructor is unsurprising.

~Dialog_message_tap()

destructor, public

The destructor is unsurprising.

HPROPSHEETPAGE CreatePropertySheetPage (PROPSHEETPAGE<CharT>&)

public

This calls the Win32 primitive CreatePropertySheetPage, wrapping it as necessary to use the message_tap.

The DlgProc member of the PROPSHEETPAGE structure is supplied by this call, so for error checking purposes it makes sure that it's 0 initially.

Likewise, the lParam member of the PROPSHEETPAGE structure is used internally, so must be 0 when you make this call. You don't need this "extra information", since you can use any member data of this object.

The declaration is a template which accepts either PROPSHEETPAGE<char> or PROPSHEETPAGE<wchar_t>, and both forms are indeed in the DLL. However, the char form might not work with the callback functions being written to take wchar_t messages. I have not experimented to see what effect using the -A or -W form of the Win32 primitive CreatePropertySheetPage has on the resulting property sheet page. Likewise, I don’t know what difference it makes to use the -A form of PropertySheet (by using PROPSHEETHEADER<char>). It seems to work superficially, but needs extensive experimenting to see if it has issues with specific messages or other problems. It’s not worth the effort to avoid typing an L in front of the caption string. It’s there if you want to try it, but the example code in demo_prop_page in message_tap_demo.cxx uses wchar_t for both PROPSHEETPAGE and PROPSHEETHEADER structures.

void EndDialog (int result=0)

public

Calls the Win32 primitive EndDialog

Throws an exception if not issued on a modal dialog box.

bool is_modal ()

public

Because this object can be used for both modeless and modal dialog boxes, common code might need to be sensitive to the difference. This function returns this state, as set appropriately by the choice of calling ModelessDialogBox, ModalDialogBox, or CreatePropertySheetPage.

int ModalDialogBox (HINSTANCE module_for_resource, T resource, HWND parent=0)

public

The parameter resource can be of type const char* (so it can be a simple quoted string literal without needing the L prefix), const wchar_t*, or an unsigned short. It refers to a PE-file resource with either a name or an ID number.

This calls the Win32 primitive DialogBox, wrapping it as necessary to use the message_tap.

Upon returning, this message_tap is reset so it may be used again on another window.

Note that it still uses smart pointers, just like any message_tap object, and this object must be dynamically allocated and accessed through handles. If you don’t keep (another) handle to it, it will vanish when this function returns as the window’s reference to this object is dropped when the window is destroyed.

// don't do this: Dialog_message_tap* popup= new Dialog_message_tap; int result= popup->ModalDialogBox (get_Instance(), "SampleDialog", window_handle()); delete popup; // boom! object already deleted.

Instead write:

handle<Dialog_message_tap> popup (new Dialog_message_tap);
int result= popup->ModalDialogBox (get_Instance(), "SampleDialog", window_handle());
// Value of popup is still good.

Typically, you will derive a class from Dialog_message_tap that knows about the various controls in the dialog, and after the call to ModalDialogBox returns, you can access the final values from the object. See the class testhook_2 in the sample file message_tap_demo.cxx.

HWND ModelessDialogBox (HINSTANCE module_for_resource, T resource, HWND parent=0)

public

This calls the Win32 primitive CreateDialog, wrapping it as necessary to use the message_tap.

The parameter resource can be of type const char* (so it can be a simple quoted string literal without needing the L prefix), const wchar_t*, or an unsigned short. It refers to a PE-file resource with either a name or an ID number.

int pre_translate_message (const MSG& msg)

public, override

This overrides the base class to provide the functionality as needed for a dialog box: it calls the Win32 primitive IsDialog.