A task dialog is similar to a Unicode message box with several extra features.
Like a message box, it is formatted by the operating system. More
A task dialog can have more general icons, messages and buttons than a message box. In addition, a task dialog may have a set of radio buttons, command links, a progress bar and one checkbox, described as a verification checkbox. Also, a callback routine may be specified to receive notification messages.
A task dialog is usually created using the Euphoria function TaskDialog.
Task dialogs are independent of any other GUI (Graphic User Interface) software and may be used in a program without any other GUI or which also uses other GUI software such as win32lib or wxEuphoria without interfering with its operation except to pause it while the task dialog is open. For example, a task dialog could be activated before starting another GUI and, later, when the other GUI is running, another task dialog could be activated from an event handler.
All text should be in 16-bit Unicode (UTF-16). The routine does not translate from 8-bit codes, but Euphoria sequences containing 7-bit ASCII should not need translation. A few extended ASCII 8-bit codes may need translation, particularly the euro currency symbol. Unicode characters in the supplementary planes (UTF-32 above #FFFF) will be detected and displayed as unknown characters since they are not supported by the typeface used by task dialogs.
More information on task dialog boxes may be found in the Microsoft documentation for the TaskDialogIndirect API and the TASKDIALOGCONFIG structure. See also the simpler TaskDialog API
A task dialog can be created quite easily. The following example is the first example in the Examples folder.
include TaskDialog.e
object Result = TaskDialog(0, -- No parent window
, -- Flags omitted - using default
"Simple test", -- Title
"Click any button or radio button", -- The main instruction
-- The next two lines are the Content giving more information
"This is a simple test dialog to check the TaskDialog wrapper."&
"\nThe euro symbol "AC&" is hexadecimal 20AC",
-- the next line is the footer text.
#300A&" Footer text goes here "ĬB,
-- Next the main icon (none) and footer icon
{0,{TD_INFORMATION_ICON}},
-- The next two lines are the buttons and the radio buttons
{TDCBF_OK_BUTTON,TDCBF_CANCEL_BUTTON,{100,"Maybe"},{200,#BF&"Che?"},{IDOK}},
{{101,"English"},{102,"Swedish"},{103,"Vanish"},{104,"Klingon"},{102}},
-- The next two lines are expanded text
{"This is 'expanded text' which is usually not shown\nuntil"&
" it is expanded by pressing 'Show More information'",
-- then the two control texts continuing the same parameter
"Show more information","Collapse the extra information"},
"Do you want to click this checkbox?") -- Verification checkbox text
-- There is no callback procedure, so the parameter is omitted.
include taskdialog.e
namespace TaskDlg
public function TaskDialog(object hWndInst = 0, object Flags = TDF_default, object Title = 0,
object MainText, object Content_W = 0, object Footer = 0,
object Icons = 0, sequence Buttons = {}, sequence Radios = {},
sequence ExpandCC = {}, object Verify = 0, object CallBack = 0)
The normal behaviour of this routine is to create a configuration structure defining a task dialog and then display the task dialog. The configuration structure is defined in the Microsoft documentation TASKDIALOGCONFIG. The parameters of TaskDialog correspond to the fields of that structure but are not in the same order and some parameters correspond to more than one field,
For an alternative use of this function see the Multi-page dialogs section.
The following features of the Windows API are unlikely to be required, but are supported by this routine
Assuming that DontDisplay is omitted, or set to its default value of 0, TaskDialog returns a sequence of four elements.
If an argument error was detected before calling TaskDialogIndirect:
Otherwise, TaskDialog returns results from TaskDialogIndirect:
If DontShow has been set, the return value is a pointer to the configuration structure so that the task dialog can be created later; see Multi-page dialog
A callback routine is an application-defined function called from a task dialog when various events occur. To register a callback routine, use the CallBack parameter in TaskDialog routine. In the full form {RID,CBdata,DontDisplay}:
A typical header for the callback function could be:
function MyCallback(atom hwnd, atom uNotification, atom wParam, atom lParam, dwRefData)
The task dialog calls this function with the following values:
The callback function should return 0 except as indicated in the notifications TDN_BUTTON_CLICKED and TDN_TIMER
For more information refer to the Microsoft documentation TaskDialogCallbackProc
include taskdialog.e namespace TaskDlg public function SendMessageW(atom hWnd, integer Msg, integer wParam = 0, object lParam = 0)
Used to send a message from a task dialog callback routine to the task dialog. Messages for task dialogs are listed in Task dialog messages
See the descriptions of the messages TDM_SET_PROGRESS_BAR_STATE, TDM_SET_PROGRESS_BAR_RANGE and TDM_SET_PROGRESS_BAR_POS. For all other task dialog messages the return value is irrelevant.
This is a general routine which may also be useful elsewhere.
include taskdialog.e namespace TaskDlg export procedure FreeConfig(atom config)
Releases the memory allocated to a task dialog structure that was created using the TaskDialog function. Usually called from TaskDialogIndirect which, in turn, is usually called from TaskDialog. Do not call this procedure to release a structure that was not created by TaskDialog.
config : A pointer to an extended task dialog structure
include taskdialog.e namespace TaskDlg export function TaskDialogIndirect(atom config, integer Clean = 0)
Displays a task dialog as defined by a TASKDIALOGCONFIG structure created by the TaskDialog routine and almost always called directly from it.
The only circumstances in which a program would call this routine directly is if one or more task dialog configuration structures have been created in advance without displaying them; perhaps to create a multi-page dialog that can be displayed using TDM_NAVIGATE_PAGE messages.
The results from the TaskDialogIndirect API; a sequence of four elements.
The descriptions below are brief. More detailed descriptions of these constants may be found in the original Microsoft documentation for the TASKDIALOGCONFIG structure.
include taskdialog.e namespace TaskDlg export constant TDF_ENABLE_HYPERLINKS
Enables hyperlink processing by the callback routine. Be wary of unsafe links
include taskdialog.e namespace TaskDlg export constant TDF_USE_HICON_MAIN
Set this flag if a main icon is specified via a handle
include taskdialog.e namespace TaskDlg export constant TDF_USE_HICON_FOOTER
Set this flag if a footer icon is specified via a handle
include taskdialog.e namespace TaskDlg export constant TDF_ALLOW_DIALOG_CANCELLATION
Allow dialog cancellation using Alt-F4, Escape and the title bar's close button
include taskdialog.e namespace TaskDlg export constant TDF_USE_COMMAND_LINKS
Diplays custom buttons as command links with a standard task dialog glyph instead of push buttons. Use them when more information is to be associated with the button. All characters up to the first new line character will be treated as the link's main text. The remainder will be displayed under the main text.
include taskdialog.e namespace TaskDlg export constant TDF_USE_COMMAND_LINKS_NO_ICON
Not recommended. Displays custom buttons as command links instead of push buttons, but without a glyph. See TDF_USE_COMMAND_LINKS for more information.
include taskdialog.e namespace TaskDlg export constant TDF_EXPAND_FOOTER_AREA
Expand the footer area instead of the content (if there is expanded informaton)
include taskdialog.e namespace TaskDlg export constant TDF_EXPANDED_BY_DEFAULT
Expanded information is displayed when the task dialog is initially displayed
include taskdialog.e namespace TaskDlg export constant TDF_VERIFICATION_FLAG_CHECKED
The verification checkbox, if present, will be checked when the task dialog is initially displayed
include taskdialog.e namespace TaskDlg export constant TDF_SHOW_PROGRESS_BAR
A progress bar is to be displayed
include taskdialog.e namespace TaskDlg export constant TDF_SHOW_MARQUEE_PROGRESS_BAR
A marquee progress bar is to be displayed
include taskdialog.e namespace TaskDlg export constant TDF_CALLBACK_TIMER
The callback routine is to be called approximately every 200 milliseconds
include taskdialog.e namespace TaskDlg export constant TDF_POSITION_RELATIVE_TO_WINDOW
The task dialog is centered to the window specified as the parent. If this flag is not set, or no parent is specified, the task dialog is centered in the screen
include taskdialog.e namespace TaskDlg export constant TDF_RTL_LAYOUT
Indicates that text is to be read right to left
include taskdialog.e namespace TaskDlg export constant TDF_NO_DEFAULT_RADIO_BUTTON
Indicates that no default radio button will be selected
include taskdialog.e namespace TaskDlg export constant TDF_CAN_BE_MINIMIZED
Allows the task dialog to be minimized
include taskdialog.e namespace TaskDlg export constant TDIF_SIZE_TO_CONTENT
Deprecated. Use TDF_SIZE_TO_CONTENT instead
include taskdialog.e namespace TaskDlg export constant TDF_SIZE_TO_CONTENT
Adjust the width of the task dialog according to the content area, if present, unless a width is specified in the TaskDialog argument Content_W
include taskdialog.e namespace TaskDlg export constant TDCBF_OK_BUTTON
The task dialog contains the push button OK. If no common or custom buttons are specified the dialog will contain an OK button by default
include taskdialog.e namespace TaskDlg export constant TDCBF_YES_BUTTON
The task dialog contains the push button Yes
include taskdialog.e namespace TaskDlg export constant TDCBF_NO_BUTTON
The task dialog contains the push button No
include taskdialog.e namespace TaskDlg export constant TDCBF_CANCEL_BUTTON
The task dialog contains the push button Cancel. If this button is specified the task dialog will respond to typical cancel actions (Alt-F4 and Escape)
include taskdialog.e namespace TaskDlg export constant TDCBF_RETRY_BUTTON
The task dialog contains the push button Retry
include taskdialog.e namespace TaskDlg export constant TDCBF_CLOSE_BUTTON
The task dialog contains the push button Close
include taskdialog.e namespace TaskDlg export constant TD_WARNING_ICON
An exclamation-point icon appears in the task dialog
include taskdialog.e namespace TaskDlg export constant TD_ERROR_ICON
A stop-sign icon appears in the task dialog
include taskdialog.e namespace TaskDlg export constant TD_INFORMATION_ICON
An icon consisting of a lower case i in a circle icon appears in the task dialog
include taskdialog.e namespace TaskDlg export constant TD_SHIELD_ICON
A shield icon appears in the task dialog
include taskdialog.e namespace TaskDlg export constant S_OK
Successful
include taskdialog.e namespace TaskDlg export constant S_FALSE
Returned by a callback routine to indicate special action required.
include taskdialog.e namespace TaskDlg export constant E_OUTOFMEMORY
Insufficient memory to display the task dialog
include taskdialog.e namespace TaskDlg export constant E_INVALIDARG
One or more arguments are invalid
include taskdialog.e namespace TaskDlg export constant E_FAIL
Task dialog failed for an unknown reason
include taskdialog.e namespace TaskDlg export constant IDCANCEL
The Cancel button was pressed
include taskdialog.e namespace TaskDlg export constant IDNO
The NO button was pressed
include taskdialog.e namespace TaskDlg export constant IDOK
The OK button was pressed
include taskdialog.e namespace TaskDlg export constant IDRETRY
The Retry button was pressed
include taskdialog.e namespace TaskDlg export constant IDYES
The Yes button was pressed
include taskdialog.e namespace TaskDlg export constant IDCLOSE
The Close button was pressed
The task dialog calls the application's callback routine with these notifications. In notifications where the values of wParam and lParam are not mentioned they are 0.
include taskdialog.e namespace TaskDlg export constant TDN_BUTTON_CLICKED
wParam is the command ID of a button that has been clicked. lParam is 0. If the callback routine returns S_FALSE (1) the task dialog will continue instead of its normal action, which is to finish and return.
include taskdialog.e namespace TaskDlg export constant TDN_CREATED
A second indication that the task dialog has been created following the TDN_DIALOG_CONSTRUCTED notification. This notification can usually be ignored. The task dialog has still not been displayed but would be displayed on return unless a default radio button is to be set.
include taskdialog.e namespace TaskDlg export constant TDN_DESTROYED
Indicates that the task dialog has been destroyed.
Do not send any more messages to it!
include taskdialog.e namespace TaskDlg export constant TDN_DIALOG_CONSTRUCTED
This is the first notification received by the callback routine and indicates that the task dialog has been created and messages may be sent to it to modify its appearance. The dialog has not yet been displayed.
include taskdialog.e namespace TaskDlg export constant TDN_EXPANDO_BUTTON_CLICKED
Indicates that the button which expands or collapses the expanded information has been clicked. wParam is True (1) if the information is expanded, False (0) if it is collapsed. lParam is 0.
include taskdialog.e namespace TaskDlg export constant TDN_HELP
Indicates that the F1 key has been pressed while the task dialog has focus.
include taskdialog.e namespace TaskDlg export constant TDN_HYPERLINK_CLICKED
Indicates that a hyperlink has been selected. lParam is a pointer to a unicode string with the URL of the hyperlink. wParam is 0.
include taskdialog.e namespace TaskDlg export constant TDN_NAVIGATED
"A navigation has occurred". This indicates that the previous task dialog has been replaced by a new one.
include taskdialog.e namespace TaskDlg export constant TDN_RADIO_BUTTON_CLICKED
Indicates that a radio button has been clicked. wParam is its ID
This notification is also received just before the dialog is displayed when a default radio button is set.
include taskdialog.e namespace TaskDlg export constant TDN_TIMER
Indicates that a time interval has elapsed. wParam is the total time in milliseconds since the task dialog was created or the timer was reset. The timer can be rest by returning S_FALSE from the callback routine.
include taskdialog.e namespace TaskDlg export constant TDN_VERIFICATION_CLICKED
Indicates that the state of the verification checkbox has been changed wParam is True (1) if it is checked and False (0) otherwise.
A callback routine can send these messages to the task dialog using SendMessageW. The descriptions are incomplete. Consult the Microsoft documentation for each message for more information.
include taskdialog.e namespace TaskDlg export constant TDM_NAVIGATE_PAGE
Replaces the existing task dialog with a new one. wParam must be 0 and
lParam must be a pointer to a new TASKDIALOGCONFIG structure.
include taskdialog.e namespace TaskDlg export constant TDM_CLICK_BUTTON
Simulates a click of the button identified by wParam. lParam must be 0.
The callback routine receives a TDN_BUTTON_CLICKED notification for it.
include taskdialog.e namespace TaskDlg export constant TDM_SET_MARQUEE_PROGRESS_BAR
Show the progress bar in marquee mode if wParam is true. False turns off marquee mode. lParam must be 0.
include taskdialog.e namespace TaskDlg export constant TDM_SET_PROGRESS_BAR_STATE
lParam must be 0.
wParam may be 1 to set the normal state, 2 to set an error state or 3 to set a paused state.
Returns non-zero if successful, 0 if it fails.
include taskdialog.e namespace TaskDlg export constant TDM_SET_PROGRESS_BAR_RANGE
wParam must be 0.
The lower 16 bits of lParam specifies the minimum. The default value is 0.
The higher 16 bits of lParam specify the maximum. The default value is 100.
Returns the previous minimum and maximum in the same format.
include taskdialog.e namespace TaskDlg export constant TDM_SET_PROGRESS_BAR_POS
lParam must be 0.
wParam is an integer specifying the new position.
Returns with the previous position.
include taskdialog.e namespace TaskDlg export constant TDM_SET_PROGRESS_BAR_MARQUEE
wParam is True to turn the marquee display on, False to turn it off.
lParam specifies the time in milliseconds between animation updates. If 0, it is set to 30 milliseconds.
include taskdialog.e namespace TaskDlg export constant TDM_SET_ELEMENT_TEXT
Updates a text element in a dialog. The size of the task dialog may change to accommodate the new text.
lParam is a unicode string (or a pointer to a pre-allocated unicode string).
wParam is one of the values TDE_CONTENT, TDE_EXPANDED_INFORMATION, TDE_FOOTER or TDE_MAIN_INSTRUCTION to indicate which text is to be updated.
include taskdialog.e namespace TaskDlg export constant TDM_CLICK_RADIO_BUTTON
Simulates a click of the radio button identified by wParam. lParam must be 0.The callback routine receives a TDN_RADIO_BUTTON_CLICKED notification for it.
include taskdialog.e namespace TaskDlg export constant TDM_ENABLE_BUTTON
Enables or disables the button whose ID is in wParam.
lParam is 0 to disable the button, non-zero to enable it.
include taskdialog.e namespace TaskDlg export constant TDM_ENABLE_RADIO_BUTTON
Enables or disables the radio button whose ID is in wParam.
lParam is 0 to disable the radio button, non-zero to enable it.
include taskdialog.e namespace TaskDlg export constant TDM_CLICK_VERIFICATION
wParam is true (1) to set the verification checkbox, false (0) to clear it.
lParam is true (1) to set the focus to the checkbox, false (0) to leave the focus unaltered.
include taskdialog.e namespace TaskDlg export constant TDM_UPDATE_ELEMENT_TEXT
Updates a text element in a dialog. WARNING: The size of the task dialog will not be changed and longer text may be clipped!
lParam is a unicode string (or a pointer to a pre-allocated unicode string).
wParam is one of the values TDE_CONTENT, TDE_EXPANDED_INFORMATION, TDE_FOOTER or TDE_MAIN_INSTRUCTION to indicate which text is to be updated.
include taskdialog.e namespace TaskDlg export constant TDM_SET_BUTTON_ELEVATION_REQUIRED_STATE
Specifies whether a button or command link should have a User Account Control (UAC) shield icon; that is whether it requires 'elevation'.
wParam is the ID of the button.
lParam is non-zero to require elevation, 0 to specify no elevation.
include taskdialog.e namespace TaskDlg export constant TDM_UPDATE_ICON
wParam is 0 to update the main icon, 1 to update the footer icon.
lParam identifies the new icon by means of a handle, if TDF_USE_HICON_MAIN is set and otherwise one of the predefined icons.
include taskdialog.e namespace TaskDlg export constant TDE_CONTENT
Used in a TDM_SET_ELEMENT_TEXT or TDM_UPDATE_ELEMENT_TEXT message to indicate that the Content text is to be changed
include taskdialog.e namespace TaskDlg export constant TDE_EXPANDED_INFORMATION
Used in a TDM_SET_ELEMENT_TEXT or TDM_UPDATE_ELEMENT_TEXT message to indicate that the expanded information is to be changed
include taskdialog.e namespace TaskDlg export constant TDE_FOOTER
Used in a TDM_SET_ELEMENT_TEXT or TDM_UPDATE_ELEMENT_TEXT message to indicate that the footer text is to be changed
include taskdialog.e namespace TaskDlg export constant TDE_MAIN_INSTRUCTION
Used in a TDM_SET_ELEMENT_TEXT or TDM_UPDATE_ELEMENT_TEXT message to indicate that the main instruction is to be changed
To create a multi-page task dialog, create the task dialog configurations using TaskDialog with the CallBack subparameter DontDisplay set to non-zero. TaskDialog then returns the address of the configuraion structure instead of displaying the task dialog. Create the first page using TaskDialogIndirect and switch to later pages using the TDM_NAVIGATE_PAGE message in the callback routine. Free the memory for the configurations using FreeConfig.