Dialog templates

For quick, casual copies of dialogs, a dialog import can be handy. But when you want to formalize the import process for a dialog — and ensure that other bot developers import all required items — make the dialog available as a dialog template. There is no impact to the dialog itself. Once you make a dialog available as a template, the dialog can no longer be imported as a dialog. It can only be imported as a dialog template. The dialog itself is automatically made a part of the template definition, but you need to specify other dependencies.

Take care when specifying the dependencies. Successful use of the dialog template by other bot developers depends on whether all needed items other dialogs, environment variables, etc.

You don't need to specify any integrations. All integrations used by all the dialogs that are a part of the dialog template are automatically included in the actual import.

If you subsequently change the dialog in a way that impacts the template definition, remember to update the template definition accordingly. Publishing a dialog template changes its status from "draft" to "published.

Once you publish a dialog template, there is no way to unpublish it. Delete the dialog template instead. In the Update Template Definition window, click Publish in the lower-right corner. Deleting a dialog template has no impact on the dialog itself.

The process deletes the template definition for the dialog, which means the dialog can no longer be imported by others as a dialog template. When you import a dialog template, you import the dialog, the integrations used in the dialog, and all other required items upon which the dialog relies. These other items can include:.

After you import a dialog template into a destination bot, it becomes a normal dialog within the bot, and it functions as if you had created the dialog from scratch. Keep in mind that importing a dialog template often can involve importing many dialogs. After the import, carefully review all the imported dialogs against the dialogs that existed in the bot before the import. The goal is to ensure that you have not inadvertently imported the same dialog in different ways on different occasions, i.

You can select only a single dialog template. You can select from the dialog templates defined in the bots and bot templates to which you have access in your organization.

Review the list of associated items other dialogs, domains, environment variables, global functions that will be imported as a part of the dialog template. These are the items that the bot developer who created the template has specified as required by the dialog. When the owner window is not already disabled, the system automatically disables the window and any child windows belonging to it when it creates the modal dialog box. The owner window remains disabled until the dialog box is destroyed.

Although a dialog box procedure could potentially enable the owner window at any time, enabling the owner defeats the purpose of the modal dialog box and is not recommended. When the dialog box procedure is destroyed, the system enables the owner window again, but only if the modal dialog box caused the owner to be disabled. An application that receives this message should release the mouse capture so that the user can move the mouse in the modal dialog box. Because the system disables the owner window, all mouse input is lost if the owner fails to release the mouse upon receiving this message.

To process messages for the modal dialog box, the system starts its own message loop, taking temporary control of the message queue for the entire application. When the system retrieves a message that is not explicitly for the dialog box, it dispatches the message to the appropriate window. The application can use this message to carry out a background task while the dialog box remains on the screen. When an application uses the message in this way, the application must frequently yield control for example, by using the PeekMessage function so that the modal dialog box can receive any user input.

An application destroys a modal dialog box by using the EndDialog function. In most cases, the dialog box procedure calls EndDialog when the user clicks Close from the dialog box's window menu or clicks the OK or Cancel button in the dialog box. The dialog box can return a value through the DialogBox function or other creation functions by specifying a value when calling the EndDialog function.

The system returns this value after destroying the dialog box. Most applications use this return value to determine whether the dialog box completed its task successfully or was canceled by the user. The system does not return control from the function that creates the dialog box until the dialog box procedure has called the EndDialog function. An application creates a modeless dialog box by using the CreateDialog or CreateDialogIndirect function.

CreateDialog requires the name or identifier of a resource containing a dialog box template; CreateDialogIndirect requires a handle to a memory object containing a dialog box template.

Two other functions, CreateDialogParam and CreateDialogIndirectParam , also create modeless dialog boxes; they pass a specified parameter to the dialog box procedure when the dialog box is created.

CreateDialog and other creation functions return a window handle to the dialog box. The application and the dialog box procedure can use this handle to manage the dialog box. A modeless dialog box neither disables the owner window nor sends messages to it. When creating the dialog box, the system makes it the active window, but the user or the application can change the active window at any time.

If the dialog box does become inactive, it remains above the owner window in the Z order, even if the owner window is active. The application is responsible for retrieving and dispatching input messages to the dialog box. Most applications use the main message loop for this.

To permit the user to move to and select controls by using the keyboard, however, the application must call the IsDialogMessage function. For more information about this function, see Dialog Box Keyboard Interface. A modeless dialog box cannot return a value to the application as a modal dialog box does, but the dialog box procedure can send information to the owner window by using the SendMessage function.

An application must destroy all modeless dialog boxes before terminating. It can destroy a modeless dialog box by using the DestroyWindow function. In most cases, the dialog box procedure calls DestroyWindow in response to user input, such as clicking the Cancel button. If the user never closes the dialog box in this way, the application must call DestroyWindow. DestroyWindow invalidates the window handle to the dialog box, so any subsequent calls to functions that use the handle return error values.

To prevent errors, the dialog box procedure should notify the owner that the dialog box has been destroyed. Many applications maintain a global variable containing the handle to the dialog box. When the dialog box procedure destroys the dialog box, it also sets the global variable to NULL , indicating that the dialog box is no longer valid. The dialog box procedure must not call the EndDialog function to destroy a modeless dialog box.

A dialog box template is binary data that describes the dialog box, defining its height, width, style, and the controls it contains. To create a dialog box, the system either loads a dialog box template from the resources in the application's executable file or uses the template passed to it in global memory by the application. In either case, the application must supply a template when creating a dialog box. A developer creates template resources by using a resource compiler or a dialog box editor.

A resource compiler converts a text description into a binary resource, and a dialog box editor saves an interactively constructed dialog box as a binary resource. An explanation of how to create template resources and add them to the application's executable file is beyond the scope of this overview. For more information about creating template resources and adding them to an executable file, see the documentation provided with your application development tools.

A dialog box template in memory consists of a header that describes the dialog box, followed by one or more additional blocks of data that describe each of the controls in the dialog box. The template can use either the standard format or the extended format. You can create a memory template by allocating a global memory object and filling it with the standard or extended header and control definitions. A memory template is identical in form and content to a template resource. Many applications that use memory templates first use the LoadResource function to load a template resource into memory, then modify the loaded resource to create a new memory template.

For more information about creating a dialog box template in memory, see Templates in Memory. The following sections describe the styles, measurements, and other values used in a dialog box template. Every dialog box template specifies a combination of style values that define the appearance and features of the dialog box.

The number and type of styles for a template depends on the type and purpose of the dialog box. For a list of values, see Dialog Box Styles. The system passes all window styles specified in the template to the CreateWindowEx function when creating the dialog box. The system may pass one or more extended styles depending on the specified dialog box styles. Most dialog boxes are pop-up windows that have a window menu and a title bar.

Otherwise, the application is responsible for displaying the dialog box by using the ShowWindow function. Every dialog box template contains measurements that specify the position, width, and height of the dialog box and the controls it contains. I'll list the most popular methods:. Each of the mentioned methods above have their pros and cons, but that's beyond the scope of this article.

Now as promised, here's a small overview on how each of the mechanisms work. If you are not using the dialog designer, you will have to create the controls in the code by calling the CreateWindow function. As for MFC dialog based applications, the concept is similar, however everything is wrapped into neat classes.

So, all you have to do is:. What is a dialog template? It is a structure that defines the styles and dimensions of a given dialog. There is an extended version of this structure that renders the latter obsolete.

When you compile your application, the resources get compiled separately using the RC. EXE resource compiler tool, which will produce the. RES binary file out of the.

RC text file , and finally everything will be linked together to produce one executable module.