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.* .. currentmodule:: curtains 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. .. data:: 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]]])] :param title: window title of the dialog. :type title: str :param heading: heading that appears at the top of the dialogs client area. :type title: str :param content: the main message being conveyed by the dialog. :type content: str :param buttons: the text of each button on the dialog. See :meth:`set_buttons` for more details on the options available. :type buttons: python sequence of strings :param icon: the main icon to be used. See :meth:`set_main_icon`. :type icon: string or int or None :param parenthwnd: the parent of the dialog, so that it appears centered and modal. :type parenthwnd: return value of :func:`loadoemicon` or None. .. method:: TaskDialog.bind(event, func) Bind a function to one of the task dialog events. Events and signatures are documented at :ref:`Task-dialog-events`. :rtype: TaskDialog .. method:: TaskDialog.set_title(title) Set the window title of the dialog. Calling this has not effect after :meth:`show` has been called. :rtype: TaskDialog .. method:: TaskDialog.set_heading(heading) Set the heading / main instruction of the dialog. :rtype: TaskDialog .. method:: TaskDialog.set_content(content) Set the text content or message that the dialog conveys. :rtype: TaskDialog .. method:: TaskDialog.set_footer(footer) Set the footer text of the dialog. :rtype: TaskDialog .. method:: 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 :meth:`show`. You can set convert_stock_buttons to false to avoid this behavior. Calling this method has not effect after :meth:`show` has been called :param buttons: label of each button on the dialog. :type buttons: python sequence of strings. :param convert_stock_buttons: whether special buttons are converted to their Windows counterparts automatically. True by default. :type convert_stock_buttons: bool :rtype: TaskDialog .. method:: 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 :meth:`show` has been called :param buttons: label of each radio button. :type buttons: python sequence of strings :param default: index of the defaulted radio button. Set to None for no default radio button. :type default: integer or None :rtype: TaskDialog .. method:: 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 :func:`loadoemicon`. Calling this method has not effect after :meth:`show` has been called :rtype: TaskDialog .. method:: TaskDialog.set_footer_icon(icon) Set the icon that appears in the footer of the dialog. See :meth:`set_main_icon`. Calling this method has not effect after :meth:`show` has been called :rtype: TaskDialog .. method:: 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 :meth:`show` has been called :param expander_data: 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. :type expander_data: python sequence of three strings :param expanded: whether the control is expanded by default. :type expanded: bool :param at_footer: whether the expanded text appears at the footer, rather than below the content text of the dialog box. :type at_footer: bool :rtype: TaskDialog .. method:: 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 :meth:`show` has been called :param ticks: amount of milliseconds to wait before the progress indicator gets redrawn. :type ticks: int :rtype: TaskDialog .. method:: TaskDialog.set_progress_bar(callback[, low[, high[, pos]]]) Set the progress bar on the task dialog. Calling this method has not effect after :meth:`show` has been called :param callback: a python callable with no arguments that returns the new position of the progress indicator. :param low: lower end of the range for the progress bar. Default = 0 :type low: int :param high: higher end of the range of the progress bar. Default = 100 :type high: int :param pos: initial position of the progress indicator. Default = 0 :rtype: TaskDialog .. method:: TaskDialog.set_check_box(label[, checked]) Set up a verification check box that appears on the task dialog. :param label: text label of the check box. :type label: str :param checked: whether the box is checked by default. :type checked: bool Calling this method has not effect after :meth:`show` has been called :rtype: TaskDialog .. method:: TaskDialog.set_width(width) Set the width, in pixels, of the taskdialog. Calling this method has not effect after :meth:`show` has been called :rtype: TaskDialog .. method:: TaskDialog.show([command_links[, centered[, can_cancel[, can_minimize[, hyperlinks[, additional flags]]]]]]) Build and display the dialog box. :param command_links: 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. :type command_links: bool :param centered: 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. :type centered: bool :param can_cancel: 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. :type can_cancel: bool :param can_minimize: if this is set to True, the user is allowed to minimize the dialog. :type can_minimize: bool :param hyperlinks: this is an experimental setting. If set to true, hypertext references ``text`` are converted to hyperlinks, and :data:`HYPERLINK_CLICKED` events are fired when they are pressed. :type hyperlinks: bool :param additional_flags: 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. :type additional_flags: int :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 :meth:`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: Task Dialog Events ------------------ The task dialog supports the follow events, which are listened for by calling :meth:`TaskDialog.bind`: .. data:: CREATED Gets fired when the task dialog is created. Callback signature: ``()`` .. data:: NAVIGATED *FIXME: Not really sure what this does*. Callback signature: ``()`` .. data:: BUTTON_CLICKED Gets fired when a button is clicked on the dialog. Callback signature: ``(label)`` ``label``: Text label of the clicked button. .. data:: 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. .. data:: HYPERLINK_CLICKED Gets fired when a hyperlink is clicked (the ``hyperlinks`` agrument to :meth:`show` must have been set to True). Callback signature: ``(href)`` ``href``: The href parameter of the hyperlink that was clicked. .. data:: TIMER Gets fired approximately every 200 milliseconds. Callback signature: ``(ticks)`` ``ticks``: number of milliseconds since last :data:`TIMER` event. .. data:: DESTROYED Gets fired when the dialog is destroyed (after being closed, etc.) Callback signature: ``()`` .. data:: VERIFICATION_CLICKED Gets fired when the verification check box is clicked. Callback signature: ``(checked)`` ``checked``: True if box is now checked, false if not. .. data:: 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.