Reflections of my thoughts….

In the last installment, we’ve seen using the basic version of task dialog. But usually when we see the task dialogs in Windows Vista or 7, it’s more detailed and can have flashy icons etc. Let’s see how to take more control over the task dialogs.

TaskDialogIndirect function can be used to have more options with task dialogs. TASKDIALOGCONFIG structure is used along with TaskDialogIndirect API.

As you’re seeing above the task dialog contains different type of controls, icons and capable of displaying more information to the user. It can have lengthy big buttons, radio buttons, checkbox, footer area, progressbar, custom icon, displaying predefined buttons like OK, Cancel, Yes, No etc. even we can have control over the buttons in the titlebar( minimize, maximize button etc)

The following code describes creating a task dialog with more flexible options. User can specify the callback functions which can be used to control the behavior if the controls and contents in the task bar. Filling the TASKDIALOGCONFIG structure is simple and straight forward as we’re seeing the code. The detailed option can be obtained from MSDN page.

HRESULT CALLBACK CTaskDialogSampleDlg::TaskDialogCallbackProc(
  __in  HWND hwnd,
  __in  UINT uNotification,
  __in  WPARAM wParam,
  __in  LPARAM lParam,
  __in  LONG_PTR dwRefData
)
{
	if( TDN_CREATED == uNotification )
	{
		::SendMessage( hwnd, TDM_SET_BUTTON_ELEVATION_REQUIRED_STATE, IDOK, TRUE );
		::SendMessage( hwnd, TDM_SET_PROGRESS_BAR_RANGE, 0, 100 );
	}
	else if( TDN_HYPERLINK_CLICKED == uNotification )
	{
		ShellExecute( 0, L"open", (LPCTSTR) lParam, 0, 0, SW_SHOW );
	}
	else if( TDN_TIMER == uNotification )
	{
		static int i = 0;
		::SendMessage( hwnd, TDM_SET_PROGRESS_BAR_POS, i++,0 );
	}

	return 0;
}

void CTaskDialogSampleDlg::OnBnClickedButton1()
{
	int nButtonPressed                  = 0;
	TASKDIALOGCONFIG config             = {0};
	const TASKDIALOG_BUTTON buttons[]   = {
		{ IDOK, L"Elevate Privilege" },
		{ IDCANCEL, L"Run with user privilege" }
	};

	const TASKDIALOG_BUTTON radiobuttons[] = {
		{ IDCANCEL, L"Test Radio" }};
	config.cbSize                       = sizeof(config);
	config.hInstance                    = AfxGetApp()->m_hInstance;
	config.dwCommonButtons              = TDCBF_OK_BUTTON | TDCBF_CANCEL_BUTTON;
	config.pszMainIcon                  = TD_SHIELD_ICON;
	config.pszMainInstruction           = L"Main Instruction";
	config.pszContent                   = L"This is the content.";
	config.pszVerificationText          = L"Conifirm license agreement";
	config.pButtons                     = buttons;
	config.cButtons                     = ARRAYSIZE(buttons);
	config.pRadioButtons				= radiobuttons;
	config.cRadioButtons				= ARRAYSIZE( radiobuttons );
	config.dwFlags						= TDF_SHOW_PROGRESS_BAR |
		TDF_EXPAND_FOOTER_AREA | TDF_ENABLE_HYPERLINKS | TDF_CAN_BE_MINIMIZED
		| TDF_USE_COMMAND_LINKS | TDF_CALLBACK_TIMER;
	config.pszExpandedInformation		= _T( "<a href=\"http://codereflect.com/\" >Codereflect.com</a>" );
	config.pfCallback = TaskDialogCallbackProc;
	BOOL bVerification = FALSE;
	TaskDialogIndirect(&config, &nButtonPressed, NULL, &bVerification);

	switch (nButtonPressed)
	{
	case IDOK:
		break; // the user pressed button 0 (change password).
	case IDCANCEL:
		break; // user canceled the dialog
	default:
		break; // should never happen
	}
}

The callback function is also easy to manage. There are predefined set of events for each type of control and we can simply make use of these controls by sending various messages to update its state and values. One of the best example is updating the progressbar during the lifetime of messagebox. Once the timer is enabled, the callback function will be automatically fired on discrete time interval. The notify messages are specified in detail in MSDN Documentation. Please check it.

To compile this source code, please use latest version of Visual Studio 2010 or any prior version with Windows Vista/7 SDK. You can also use express edition of Visual C++ to try this API.

Every programmer must be familiar with the MessageBox es in any platform. It’s the simplest way to notify the user to take an action or provide notifications. Windows provides standard message box functionality with MessageBox API for displaying MessageBox with most frequently used buttons (OK, Cancel, Yes, No etc) and icons (error, warning, info etc.) This is again limited in programmer’s point of view and most we used to create our own messagebox to meet our extended purpose.

Windows UI has revamped since windows Vista and the UI experience was totally new from its predecessors. Most of the Windows Vista/7 applications display and extended form of messagebox called task dialog. Task dialog gives us more flexibility over the typical messagebox we used to have in Windows. We can display progress bars, extended information on footer, custom icons, predefined icons like Shield Icons (to indicate UAC elevation is required for operation etc.)

Task dialog comes with a simple set of interfaces and also provides an advanced version of interface to take control over what all we’re displaying in the task dialog

Displaying a Simple Taskbar

A simple task dialog can be displayed by calling TaskDialog API. The default buttons like OK, Yes, No, Cancel, Retry and close button. It’s simple as displaying a normal messagebox. The major difference is that we can have a custom icon, also a main instruction to show the intention of task dialog and main content provides further description of it. Organization of message is better readable and can have more focus than standard messagebox.

	TASKDIALOG_COMMON_BUTTON_FLAGS tButton =
		TDCBF_OK_BUTTON| TDCBF_YES_BUTTON|
		TDCBF_NO_BUTTON| TDCBF_CANCEL_BUTTON|
		TDCBF_RETRY_BUTTON| TDCBF_CLOSE_BUTTON;

	int nClickedBUtton;
	TaskDialog( m_hWnd, NULL,
		_T("Demonstrating TaskDialog API"),
		_T("This is the main instruction"), _T("This shows the main content"),
		tButton,
		MAKEINTRESOURCE( IDI_SHIELD ),
		&nClickedBUtton );

In the above code you can see the default buttons are displayed with binary OR “|” operator. The return value is passed as parameter and can refer after calling the API. The return value of the function gives the error status. S_OK means the dialog was successfully displayed. the details of the parameters and return values are described in the TaskDialog API documentation. In the next installment, let’s have a look at advanced usage of Task Dialog.