Getting Started
Sample Programs
Code Snippets

Web Sites
More Tutorials
User Groups
Talk Shows

Progress Bar

GBIC >> PowerBASIC >> Tutorials >> DDT - Dynamic Dialog Tools

PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC - the scope of the language as well as it's specific capabilities.

Introduction       Projects       Language           Messages       Functions           Advanced
  • Overview
  • Examples
  • IDE
  • Compilation
  • Distribution
  • Project Files
  • DDT Windows
  • Controls
  • Menus
  • Dialogs  
  • Help Files
  • Resources  
  • Templates  
  • Project Shell  
  • Syntax
  • Operators
  • Data Types
  • Variables
  • Scope
  • Declarations  
  • Procedures
  • Flow Control
  • Windows
  • Messages
  • Callbacks
  • Mouse
  • Keyboard
  • Dialogs
  • Controls
  • Subclassing
  • Arithmetic
  • Trig  
  • Strings
  • Arrays
  • Date/Time
  • Printing
  • Files
  • Folders
  • Keyboard
  • Mouse
  • Sound
  • System
  • Error Traps
  • Debugging
  • Objects
  • Graphics
  • Databases
  • API
  • DLLs
  • ASM
  • Threads
  • 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.

    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 NEW - create new dialog (does not display)
    • DIALOG SHOW MODAL - display/activate dialog (modal)
    • DIALOG SHOW MODELESS - display/activate dialog (modeless)
    • DIALOG END - close and destroy a dialog
      Set Properties
    • DIALOG SET CLIENT - set width/height of dialog client area
    • DIALOG SET LOC - set upper/left position of dialog
    • DIALOG SET SIZE - set width/hight of dialog
    • DIALOG SET TEXT - set dialog caption
    • DIALOG SET USER - set 1 of 8 user dialog values
    • DIALOG SET COLOR - set dialog background color (RGB)
    • DIALOG SET ICON - change dialog icon
    • DIALOG STATE - change visible state of dialog
      Get Properties
    • DIALOG GET CLIENT - get width/height of dialog client area
    • DIALOG GET LOC - get upper/left location of dialog
    • DIALOG GET SIZE - get width/height of dialog
    • DIALOG GET TEXT - get dialog caption
    • DIALOG GET USER - get 1 of 8 user data dialog values
    • DIALOG UNITS - convert dialog units to pixels
    • DIALOG PIXELS - convert pixels to dialog units
      Run-Time Management
    • DIALOG DISABLE - disable dialog (cannot receive mouse/keyboard messages)
    • DIALOG DOEVENTS - process messages, sleep, relinquish time slice
    • DIALOG POST - send message to dialog, continue without waiting
    • DIALOG SEND - send message to dialog, wait until complete
    • DIALOG REDRAW - direct dialog/child controls to redraw

    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.

      NEW[PIXELS, | UNITS,] hParent, title$, [x&], [y&], xx&, yy&
      [, [style&] [, [exstyle&]]] [,] TO hDlg
      SHOW MODALhDlg [[,] CALL callback] [TO lResult&]
      SHOW MODELESShDlg [[,] CALL callback] [TO lResult&]
      ENDhDlg [, lResult&]
      Set Properties
      FONT[DEFAULT] fontname$ [,points&, style&, charset&]
      SET CLIENThDlg, x&, y&
      SET LOChDlg, x&, y&
      SET SIZEhDlg, wide&, high&
      SET TEXThDlg, titletext$
      SET USERhDlg, index&, usrval&
      SET COLORhDlg, foreclr&, backclr&
      SET ICONhDlg, newicon$
      STATEhDlg, showstate& [TO lResult&]
      Get Properties
      GET CLIENThDlg TO wide&, high&
      GET LOChDlg TO x&, y&
      GET SIZEhDlg TO x&, y&
      GET TEXThDlg TO titletext$
      GET USERhDlg, index& TO retvar&
      UNITShDlg, x&, y& TO PIXELS xx&, yy&
      PIXELShDlg, x&, y& TO UNITS xx&, yy&
      Run-Time Management
      DOVENTS[sleep&] [TO count&]
      POSThDlg, Msg&, wParam&, lParam&
      SENDhDlg, msg&, wParam&, lParam& [TO lResult&]

    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.

    • 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

    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.

    • Modality - when a widow is shown MODAL, code statements following the display of the window are halted. But code following the MODELESS display of a window will continue to execute.

    • Dimensions - the DIALOG statements use pixels or dialog units corresponding to the units specified when the dialog was created.

    • USER - dialogs are allocated 8 long-integer values the programmer can set. DIALOG SET/GET USER statements refer to accessing/retrieving those values.

    • DOEVENTS - In addition to allowing a program to pause, the DOEVENTS also allows a dialog to temporarily give control back to Windows so that it and other applications can perform tasks. Without using DOEVENTS, a PowerBASIC can cause other programs to appear sluggish or non-responsive. Generally, DOEVENTS is used when a PowerBASIC program is executing a long loop of instructions.

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

    ... and the code used to create it.

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

    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
            LOCAL hDLG AS DWORD, style&
                     %WS_SYSMENU OR %WS_CAPTION
            DIALOG NEW 0, "Simple PowerBASIC Dialog",,, 160, 50, style& , TO hDlg
            DIALOG SHOW MODAL hdlg

    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.

    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.


    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.

      %DS_3DLOOK Non-bold font and 3D borders around controls.
      %DS_ABSALIGN Define coordinates as screen, not client.
      %DS_CENTER Centered above task bar.
      %DS_CENTERMOUSE Center mouse in dialog.
      %DS_CONTEXTHELP Puts question mark in title bar.
      %DS_CONTROL Create child dialog. Used for tab control pages.
      %DS_MODALFRAME Modal display.
      %DS_NOFAILCREATE Create dialog regardless of errors.
      %DS_SETFONT Sets dialog/child control fonts.
      %DS_SETFOREGROUND Place dialog in foreground.
      %DS_SYSMODAL Create a system-modal dialog box.
      %WS_BORDER Create thin-line dialog border.
      %WS_CAPTION Include title bar in dialog.
      %WS_CHILD Create child dialog. Use with %DS_CONTROL.
      %WS_CLIPCHILDREN Exclude child control area from redraw.
      %WS_CLIPSIBLINGS Clip (not overdraw) child controls during repaint.
      %WS_DISABLED Initially disable dialog.
      %WS_DLGFRAME Use typical dialog border.
      %WS_HSCROLL Display horizontal scroll bar.
      %WS_ICONIC Minimize dialog when created.
      %WS_MAXIMIZE Maximize dialog when created.
      %WS_MAXIMIZEBOX Add maximize button.
      %WS_MINIMIZE Minimize dialog when cretaed.
      %WS_MINIMIZEBOX Add minimize button.
      %WS_OVERLAPPED Create overlapped dialog (caption and border).
      %WS_OVERLAPPEDWINDOW Combination - displays standard, full-featured window
      %WS_POPUP Create popup dialog (no caption or border).
      %WS_POPUPWINDOW Create popup dialog with a border and system menu.
      %WS_SYSMENU Display system menu. Requires %WS_CAPTION.
      %WS_THICKFRAME Display sizing border (dialog will be resizable).
      %WS_VSCROLL Display vertical scroll bar.

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

      %WS_EX_ACCEPTFILES Accepts drag+drop files (sends %WM_DROPFILES).
      %WS_EX_APPWINDOW Dialog will display on taskbar when minimized.
      %WS_EX_CLIENTEDGE Display border with a sunken edge.
      %WS_EX_CONTEXTHELP Include question mark title bar.
      %WS_EX_CONTROLPARENT Enable TAB key navigation.
      %WS_EX_LEFT Set left-aligment as default.
      %WS_EX_LEFTSCROLLBAR Place scroll bar on left side of dialog.
      %WS_EX_LTRREADING Display text left to right.
      %WS_EX_MDICHILD Create MDI child window.
      %WS_EX_NOPARENTNOTIFY Suppress %WM_PARENTNOTIFY on create/destroy.
      %WS_EX_OVERLAPPEDWINDOW Extended - client/window edges.
      %WS_EX_PALETTEWINDOW Combination - topmost tool window.
      %WS_EX_RIGHT Set right-alignment (specific languages only).
      %WS_EX_RIGHTSCROLLBAR Place scrollbar on right side.
      %WS_EX_RTLREADING Use right-to-left reading order.
      %WS_EX_STATICEDGE Display 3D border.
      %WS_EX_TOOLWINDOW Create a tool window (minimal content/functionality).
      %WS_EX_TOPMOST Keep dialog above all other windows.
      %WS_EX_TRANSPARENT Draw low zorder windows before dialog.
      %WS_EX_WINDOWEDGE Display border with raised edge.

    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_POPUP
    • %WS_CHILD
    • %WS_BORDER
    • %WS_GROUP
    • %WS_EX_RIGHT
    • %WS_EX_LEFT

    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.

      StyleCombination Equivalents
    • %WS_TILED
    • %WS_ICONIC
    • %WS_CHILD

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