The Task Dialog

Updated Feb 11, 2009:

The Task Dialog is a Windows dialog control released with Windows Vista, and is available in all later versions of the Windows operating system. It is designed to display a dialog box with options or commands that allow the user to perform a “task” (hence the name).

In its most basic configuration the task dialog can just be an aesthetically pleasing replacement to the traditonal message box, but it can be upgraded to include advanced controls like hyperlinks, radio buttons, command links, and progress indicators.

Curtain’s Task Dialog class wraps most of the native Task Dialog’s functionality.

Python 2 isn’t officially supported by Curtains, but users of Python 2 who wish to use the dialog must convert all string input to the unicode type.

Since the task dialog is not always available (happens if the executable does not load comctl32.dll version 6, or if the operating system is older than Vista), you are advised to check that it is before attempting to use it and provide fallback behavior if it isn’t. The dialog functions will do this for you, but if you are accessing the class directly, there is a constant that will help you determine if it is available.

curtains.TASK_DIALOG_AVAILABLE

Bool indicating whether the TaskDialog class is usable on the current platform.

Task Dialog Class

class TaskDialog[(title, heading, content[, buttons[, icon[, parenthwnd]]])]

Parameters:

• title (str) – window title of the dialog.
• heading – heading that appears at the top of the dialogs client area.
• content (str) – the main message being conveyed by the dialog.
• buttons (python sequence of strings) – the text of each button on the dialog. See set_buttons() for more details on the options available.
• icon (string or int or None) – the main icon to be used. See set_main_icon().
• parenthwnd (return value of loadoemicon() or None.) – the parent of the dialog, so that it appears centered and modal.

TaskDialog.bind(event, func)

Bind a function to one of the task dialog events. Events and signatures are documented at Task Dialog Events.

Return type:TaskDialog

TaskDialog.set_title(title)

Set the window title of the dialog. Calling this has not effect after show() has been called.

Return type:TaskDialog

TaskDialog.set_heading(heading)

Set the heading / main instruction of the dialog.

Return type:TaskDialog

TaskDialog.set_content(content)

Set the text content or message that the dialog conveys.

Return type:TaskDialog

TaskDialog.set_footer(footer)

Set the footer text of the dialog.

Return type:TaskDialog

TaskDialog.set_buttons(buttons[, convert_stock_buttons])

Set the buttons on the dialog using the list of strings in buttons where each string is the label for a new button.

Each string may use some special syntax to give the generated button some extra features. Placing a + sign at the start of the string will cause a shield icon to by displayed on the button (indicating that the button’s command requires elevation). This behavior can be avoided by placing a \ character before the + character.

An ALL CAPS string will cause the button to become the default button on the dialog (unless superceded by another ALL CAPS string). In this event, all letters except the first will be converted to lowercase before assigned to the button. This behavior can be avoided by placing a \ character just before the first letter.

If the button text is any of the following (regardless of letter casing), a stock Windows version of the button is inserted in its place:

ok, cancel, yes, no, retry, close.

Note that none of these buttons will convert to command links even if the directive is given with show(). You can set convert_stock_buttons to false to avoid this behavior.

Calling this method has not effect after show() has been called

Parameters:

• buttons (python sequence of strings.) – label of each button on the dialog.
• convert_stock_buttons (bool) – whether special buttons are converted to their Windows counterparts automatically. True by default.

Return type:

TaskDialog

TaskDialog.set_radio_buttons(buttons[, default])

Add radio buttons to the dialog using the list of strings in buttons.

Calling this method has not effect after show() has been called

Parameters:

• buttons (python sequence of strings) – label of each radio button.
• default (integer or None) – index of the defaulted radio button. Set to None for no default radio button.

Return type:

TaskDialog

TaskDialog.set_main_icon(icon)

Set the icon that appears at the top of the dialog.

You may use one of the following string literals for the icon argurment:

warning: An exclamation-point icon appears in the dialog box.

error: A stop-sign icon appears in the dialog box.

information: An icon consisting of a lowercase letter i in a circle appears in the dialog box.

shield: A security crest icon appears in the dialog box.

Alternatively, the icon argument may be any value returned by loadoemicon().

Calling this method has not effect after show() has been called

Return type:TaskDialog

TaskDialog.set_footer_icon(icon)

Set the icon that appears in the footer of the dialog.

See set_main_icon().

Calling this method has not effect after show() has been called

Return type:TaskDialog

TaskDialog.set_expander(expander_data[, expanded[, at_footer]])

Set up a collapsible control that can reveal further information about the task that the dialog performs.

Calling this method has not effect after show() has been called

Parameters:

• expander_data (python sequence of three strings) – three element tuple or list. At index 0: the label for the control it is collapsed. At index 1: the label for the control when it is expanded. At index 2: the extra text the control reveals.
• expanded (bool) – whether the control is expanded by default.
• at_footer (bool) – whether the expanded text appears at the footer, rather than below the content text of the dialog box.

Return type:

TaskDialog

TaskDialog.set_rangeless_progress_bar([ticks])

Set the progress bar on the task dialog as a marquee progress bar.

Marquee progress bars do not have a set range; the progress indicator moves across the bar in a loop.

Calling this method has not effect after show() has been called

Parameters:

• ticks (int) – amount of milliseconds to wait before the progress indicator gets redrawn.

Return type:

TaskDialog

TaskDialog.set_progress_bar(callback[, low[, high[, pos]]])

Set the progress bar on the task dialog.

Calling this method has not effect after show() has been called

Parameters:

• callback – a python callable with no arguments that returns the new position of the progress indicator.
• low (int) – lower end of the range for the progress bar. Default = 0
• high (int) – higher end of the range of the progress bar. Default = 100
• pos – initial position of the progress indicator. Default = 0

Return type:

TaskDialog

TaskDialog.set_check_box(label[, checked])

Set up a verification check box that appears on the task dialog.

Parameters:

• label (str) – text label of the check box.
• checked (bool) – whether the box is checked by default.

Calling this method has not effect after show() has been called

Return type:TaskDialog

TaskDialog.set_width(width)

Set the width, in pixels, of the taskdialog.

Calling this method has not effect after show() has been called

Return type:TaskDialog

TaskDialog.show([command_links[, centered[, can_cancel[, can_minimize[, hyperlinks[, additional flags]]]]]])

Build and display the dialog box.

Parameters:

• command_links (bool) – if this is set to True, buttons will be converted to Windows Vista command links. If you use this setting, you can separate the heading and description of the command link using a newline character.
• centered (bool) – if this is set to True and the dialog has a parent, the dialog will be centered on top of the parent window. Otherwise, the dialog is centered on screen.
• can_cancel (bool) – if this is set to True, the dialog is supplied with a close button and can be cancelled by the user pressing ESC or ALT + F4, regardless of whether a stock cancel button was supplied.
• can_minimize (bool) – if this is set to True, the user is allowed to minimize the dialog.
• hyperlinks (bool) – this is an experimental setting. If set to true, hypertext references <a href="code">text</a> are converted to hyperlinks, and HYPERLINK_CLICKED events are fired when they are pressed.
• additional_flags (int) – allows you to specify your own settings to the task dialog’s behavior. This is not officially supported, however, the flags are in the source code and you can search msdn for details on what they do.

Returns:

three element tuple with indices: 0: original text of the clicked button, unless a stock button was used in which case the lowercase variants are used (see set_buttons()). 1: original text of the clicked radio button if a radio button was clicked, 0 otherwise. 2: bool indicating whether the checkbox (if any set) was checked.

Task Dialog Events

The task dialog supports the follow events, which are listened for by calling TaskDialog.bind():

curtains.CREATED

Gets fired when the task dialog is created.

Callback signature: ()

curtains.NAVIGATED

FIXME: Not really sure what this does.

Callback signature: ()

curtains.BUTTON_CLICKED

Gets fired when a button is clicked on the dialog.

Callback signature: (label)

label: Text label of the clicked button.

curtains.RADIO_BUTTON_CLICKED

Gets fired when a radio button is clicked on the dialog.

Callback signature: (label)

label: Text label of the clicked radio button.

curtains.HYPERLINK_CLICKED

Gets fired when a hyperlink is clicked (the hyperlinks agrument to show() must have been set to True).

Callback signature: (href)

href: The href parameter of the hyperlink that was clicked.

curtains.TIMER

Gets fired approximately every 200 milliseconds.

Callback signature: (ticks)

ticks: number of milliseconds since last TIMER event.

curtains.DESTROYED

Gets fired when the dialog is destroyed (after being closed, etc.)

Callback signature: ()

curtains.VERIFICATION_CLICKED

Gets fired when the verification check box is clicked.

Callback signature: (checked)

checked: True if box is now checked, false if not.

curtains.EXPANDER_BUTTON_CLICKED

Gets fired when the expander control is clicked.

Callback signature: (collapsed)

collapsed: True if the expander control if collapsed, false if not.