Windows and PowerBASIC Dynamic Dialog Tools
The Windows operating system supports the creation of windows in two distinct ways - as standard windows and as dialog windows. Standard windows are created using the CreateWindow API and require generally a fair amount of coding to initialize and manage in an application.

Dialog windows are created using the CreateDialog API. The resulting dialog windows have some limitations, but provide perhaps 90% of the functionality of a standard window. The attraction of dialog windows is that they automate aspects of windows management and generally require fewer lines of code to initialize and manage as compared to standard windows.

There's an interesting thread on this at the PowerBASIC web site forums.

With PowerBASIC, both approaches to window creation/management are supported.

PowerBASIC supports the use of Windows API, allowing programmers the option to create standard windows in those cases where the limitations of dialog windows are an issue.

PowerBASIC also provides built-in functions which simplify the creation and management of dialog windows. In particular, the DIALOG, CONTROL and CB (callback) functions are used to create and manage dialogs, as well as to place standard Windows controls on the dialogs. The PowerBASIC functions which support dialog windows are called Dynamic Dialog Tools (DDT).

This tutorial page discusses the DIALOG function. The CONTROL and CB (callback) functions are discussed on other pages in this tutorial.

DIALOG
The DIALOG function supports the creation and management of dialog windows, as per the dicussion above. A categorized list of the available DIALOG statements and their actions is provided below. Throughout PowerBASIC documentation you'll see the use of the word dialog, which refers to dialog windows as created using PowerBASIC functions.

DIALOG Syntax
The syntax for each of the DIALOG statements is provided here. As you can see, only the DIALOG NEW statement has any level of complexity to it. All the other statements require just a few arguments.

DIALOG Arguments
In the syntax summary above, the various DIALOG statements use many common arguments. Here's a list of the arguments for each category as called out in the syntax summary above. The summary is categorized into four sections.

Create
  • PIXELS/UNITS - Coordinate units that apply to dialog
  • hParent - Handle of dialog parent (0 or %HWND_DESKTOP if no parent)
  • title$ - Caption
  • x&, y& - Upper/left coordinates
  • xx&, yy& - Width/height of dialog
  • style& - Describes how dialog will be displayed
  • extstyle& - Optional description of how dialog wil be displayed
  • hDlg - Handle of dialog
  • callback - PowerBASIC function that received dialog messages
  • lResults& - Numeric result of executing a DIALOG statement
 
Set Properties
  • hDlg - Dialog on which action is taken
  • x&, y& - width/height or upper/left coordinates
  • wide&, high& - width/height of dialog
  • titletext$ - caption
  • index& - Index of user data being accessed
  • usrval& - Value to assign to user value at index
  • foreclr& - foreground RGB color
  • backclr& - background RGB color
  • newicon$ - icon to display in caption
  • showstate& - name of icon in resource file
  • lResult& - Numeric result of executing a DIALOG statement
 
Get Properties
  • hDlg - Dialog on which action is taken
  • wide&, high& - width/height of dialog
  • x&, y& - width/height or upper left coordinates
  • titletext$ - caption
  • index& - Index of user data being accessed
  • retvar& - Numeric result of executing a DIALOG statement
  • xx&, yy& - Results of PIXEL/UNITS converion
 
Run-Time Management
  • hDlg - Dialog on which action is to be taken
  • sleep& - Milliseconds to sleep
  • count$ - Number of active dialogs
  • Msg& - Numeric message to send to another dialog
  • wParam& - first message parameter
  • lParam& - second message parameter

Comments
A few of the DIALOG statements take advantage of various aspects of Windows programming which may not be obvious or familiar to all programmers. Here are some short discussions intended to clarify some DIALOG operations.

Example #1 - Dialog Source Code
Here's a simple dialog (window) ...

... and the code used to create it. 

    #COMPILE EXE
    #DIM ALL
    FUNCTION PBMAIN () AS LONG
        LOCAL hDLG AS DWORD
        DIALOG NEW 0, "Simple PowerBASIC Dialog",,, 160, 50, , TO hDlg
        DIALOG SHOW MODAL hdlg
    END FUNCTION

This dialog has nothing but a caption - no system control, no minimize/maximize/exit button and is non-resizable.

Note that if you run this code there is no "X" feature in the upper right corner of the window. Use Alt-F4 to close the window.

Example #2 - A More Complex Dialog
Here's an example of a more useful dialog, containing the standard features users expect, which are misssing from the example above.

... and again, the code used to create it. 

    #COMPILE EXE
    #DIM ALL
    FUNCTION PBMAIN () AS LONG
        LOCAL hDLG AS DWORD, style&
        style& = %WS_HSCROLL OR %WS_HSCROLL OR %WS_MAXIMIZEBOX OR _
                 %WS_MINIMIZEBOX OR %WS_SIZEBOX OR %WS_VSCROLL OR _
                 %WS_SYSMENU OR %WS_CAPTION
        DIALOG NEW 0, "Simple PowerBASIC Dialog",,, 160, 50, style& , TO hDlg
        DIALOG SHOW MODAL hdlg
    END FUNCTION

You can see that the primary difference between Example 1 and Example 2 is in the value of the style with which the dialog is created. There are a fairly large number of equates available to modify the look of a dialog.

style&
The optional style& variable in a DIALOG NEW statement is a bitmask describing how a dialog looks. Combining style is accomplished by using the OR function with each desired style, as in this following example, which is the default style used by PowerBASIC if none is supplied by the programmer. 

style& = %DS_3DLOOK OR %DS_SETFONT OR %DS_MODALFRAME OR %DS_NOFAILCREATE _
         OR %WS_BORDER OR %WS_CLIPSIBLINGS OR %WS_DLGFRAME OR %WS_POPUP

Where the style& variable is supplied the user must include all desire style parameters, even those which make up the default style. None of the default style parameters are added by PoweBASIC when a value for style& is supplied.

The exception to this requirement is that regardless of whether the source code supplies a style, or leaves it blank, PowerBASIC always adds the %DS_NOFAILCREATE, %DS_SETFONT and %DS_3DLOOK parameters to the dialog style.

Style Parameters
This table lists the available style parameters and describes the effect they have on a dialog. The descriptions are intentionally kept brief. For more information see the online Help at the PowerBASIC home page.

extStyle&
A second, extended style bitmask can also be used, with the following parameter options.

Windows Styles Reference
This is the list of possible window styles, as pulled from the Win32API.INC file. The list above shows which of these are applied by default to windows created within PowerBASIC. These can be used individually or in combination as values for the style& and extStyle& CONTROL ADD arguments.

  • %WS_OVERLAPPED
  • %WS_POPUP
  • %WS_CHILD
  • %WS_MINIMIZE
  • %WS_VISIBLE
  • %WS_DISABLED
  • %WS_CLIPSIBLINGS
  • %WS_CLIPCHILDREN
  • %WS_MAXIMIZE
  • %WS_BORDER
  • %WS_DLGFRAME
  • %WS_VSCROLL
  • %WS_HSCROLL
  • %WS_SYSMENU
  • %WS_THICKFRAME
  • %WS_GROUP
  • %WS_TABSTOP
  • %WS_MINIMIZEBOX
  • %WS_MAXIMIZEBOX
  • %WS_EX_DLGMODALFRAME
  • %WS_EX_NOPARENTNOTIFY
  • %WS_EX_TOPMOST
  • %WS_EX_ACCEPTFILES
  • %WS_EX_TRANSPARENT
  • %WS_EX_MDICHILD
  • %WS_EX_TOOLWINDOW
  • %WS_EX_SMCAPTION
  • %WS_EX_WINDOWEDGE
  • %WS_EX_CLIENTEDGE
  • %WS_EX_CONTEXTHELP
  • %WS_EX_RIGHT
  • %WS_EX_LEFT
  • %WS_EX_RTLREADING
  • %WS_EX_LTRREADING
  • %WS_EX_LEFTSCROLLBAR
  • %WS_EX_RIGHTSCROLLBAR
  • %WS_EX_CONTROLPARENT
  • %WS_EX_STATICEDGE
  • %WS_EX_APPWINDOW
  • %WS_EX_LAYERED
  • %WS_EX_NOINHERITLAYOUT
  • %WS_EX_LAYOUTRTL
  • %WS_EX_COMPOSITED
  • %WS_EX_NOACTIVATE

In addition to the styles above, there are several styles whose values are equal, or equal to combinations of other styles. Knowing the combination types can save you some typing effort by simplifying your PowerBASIC code.

If you have any suggestions or corrections, please let me know.