DIALOG NEW statement

Purpose | Create a new dialog in memory, ready for display.
Syntax | DIALOG NEW [PIXELS, | UNITS,] hParent, title$, [x&], [y&], xx&, yy& [, [style&] [, [exstyle&]]] [,] TO hDlg

Remarks

A new empty dialog is created, but not yet displayed. Once the dialog has been created and all of the desired controls have been added with CONTROL ADD statements, the dialog can be displayed with the DIALOG SHOW MODELESS, or DIALOG SHOW MODAL statements.

If a modeless dialog is created, the application must create a DIALOG DOEVENTS message pump for the duration of the dialog. Failure to provide a message pump can result in disruptions to the display of the dialog, or the inability of the dialog to respond to messages such as button clicks, etc. Modal dialogs do not require a message pump.To change the displayed state of a dialog (i.e., hidden, minimized, etc) after the dialog has been created, use the DIALOG SHOW STATE statement.

If a dialog does not have either %WS_CHILD or %WS_POPUP styles, Windows may enforce a minimum dialog width of some 60-70 dialog units.

PIXELS | If the PIXELS keyword is specified, all size and position parameters are specified in pixels. In this case, related statements such as DIALOG GET LOC will also return values in Pixels.
UNITS | If UNITS is specified (or no scaling option is specified), all size and position parameters are specified in Dialog Units. (default)
| DIALOG NEW takes the following parameters.
hParent | Handle of the parent window or dialog. If there is no parent, use zero (0) or %HWND_DESKTOP. If the dialog is MODAL, the parent window/dialog will be disabled while this "child" dialog is running.
title$ | The text displayed in the title or caption bar of the dialog.
x&, y& | Optional location of the top-left corner for the dialog. The location is specified in the same terms (pixels or dialog units) as specified in the DIALOG NEW statement. If neither x& and y& are specified, the dialog is centered on the screen. If %CW_USEDEFAULT (&H080000000) is specified, the default Windows position is used (cascading from the upper-left corner).

xx&, yy&

The width and height of the dialog. The size is specified in the same terms (pixels or dialog units) as specified in the DIALOG NEW statement.

If the default dialog style (or any other dialog style that includes the %WS_CAPTION style) is used, the width and height parameters specify the client size only, and this does not include any caption and border dimensions.

If the style does not include %WS_CAPTION, the width and height specify the overall dialog size, including the caption and border, if any.

Note that %WS_CAPTION is a combination of the %WS_BORDER and %WS_DLGFRAME styles. The default dialog style includes %WS_BORDER and %WS_DLGFRAME styles, so it implicitly includes the %WS_CAPTION style.

style&

An optional bitmask describing how the dialog should be displayed. default style of &H084C000D4& is made up %DS_3DLOOK, %DS_SETFONT, %DS_MODALFRAME, %DS_NOFAILCREATE, %WS_BORDER, %WS_CLIPSIBLINGS, %WS_DLGFRAME and %WS_POPUP. used if parameter omitted from statement completely. For example:

DIALOG NEW 0, "Dialog Title",,, 100, 200,, TO hDlg

Custom style values replace the default values. That is, they are not additional to the default style values - your code must specify all necessary style parameters (with the exception of %DS_NOFAILCREATE, %DS_SETFONT and %DS_3DLOOK, which are automatically added into the style& parameter by PowerBASIC).

This also applies to the extended styles parameter - if your code specifies a custom primary style, the default extended style will no longer be in effect either. In this case, an explicit extended style may also need to be added to the DIALOG NEW statement if an explicit primary style is specified.

The primary style& value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%DS_3DLOOK Give the dialog box a non-bold font, and draw three-dimensional borders around controls in the dialog box. The %DS_3DLOOK style is not required by applications marked with #OPTION VERSION4 or #OPTION VERSION5; as Windows automatically applies the 3D appearance. DDT dialogs are always created with this style. (default)

%DS_3DLOOK | Give the dialog box a non-bold font, and draw three-dimensional borders around controls in the dialog box. The %DS_3DLOOK style is not required by applications marked with #OPTION VERSION4 or #OPTION VERSION5; as Windows automatically applies the 3D appearance. DDT dialogs are always created with this style. (default)
%DS_ABSALIGN | Indicate that the coordinates of the dialog box are screen coordinates; otherwise, Windows assumes they are client coordinates.
%DS_CENTER | Center the dialog box in the working area (the area not obscured by the task bar and system tray). This is the default if x& and y& are not specified.
%DS_CENTERMOUSE | Center the mouse cursor in the dialog box when the dialog is initially created.
%DS_CONTEXTHELP | Include a question mark in the title bar of the dialog box. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a control in the dialog box, the dialog callback receives a %WM_HELP message. This style cannot be used with the %WS_MAXIMIZEBOX and %WS_MINIMIZEBOX styles. Also see %WS_EX_CONTEXTHELP.
%DS_CONTROL | Create a dialog that works as a child control of another dialog, smoothing the keyboard focus interface across the two dialogs when the TAB key or control accelerators are used. Typically used for dialogs that form the "pages" for tab controls and property-sheets.
%DS_MODALFRAME | Create a dialog box with a modal dialog-box frame that can be combined with a title bar and System menu by specifying the %WS_CAPTION and %WS_SYSMENU styles. (default)
%DS_NOFAILCREATE | The dialog is created regardless of any errors that may occur during the creation phase. DDT dialogs are always created with this style. (default)
%DS_SETFONT | The font to be used by a DDT dialog and its controls can be predetermined with the DIALOG DEFAULT FONT statement. If the DIALOG DEFAULT FONT statement is not used, the default font (MS Sans Serif, 8 point) is used. The size of the dialog font proportionately affects the conversion of dialog units values into pixels, so an increase in default font size will automatically create a larger dialog, even through the dialog dimensions have remained constant. As child controls are added to a %DS_SETFONT dialog, they will be sent a %WM_SETFONT message to ensure they also make use of the specified dialog font. DDT dialogs are always created with this style. (default)
%DS_SETFOREGROUND | Bring the dialog box to the foreground. Internally, Windows calls the SetForegroundWindow API function for the dialog box.
%DS_SYSMODAL | Create a system-modal dialog box. This style causes the dialog box to have the %WS_EX_TOPMOST style, but otherwise has no effect on the dialog box or the behavior of other applications and windows when the dialog box is displayed.
%WS_BORDER | Create a dialog that has a thin-line border.
%WS_CAPTION | Create a dialog that has a title bar. Includes the %WS_BORDER and %WS_DLGFRAME styles. When this style is used, the xx& and yy& parameters specify the size of the client area of the dialog; otherwise, they specify the outer dimensions of the dialog. (default)
%WS_CHILD | Create a child dialog. Cannot be used with the %WS_POPUP style. Typically used with %DS_CONTROL for tab control and property sheet "pages".
%WS_CLIPCHILDREN | Exclude the area occupied by child controls when drawing occurs on the dialog background. FRAME and LINE controls on a dialog with this style usually use the extended style %WS_EX_TRANSPARENT so the background of those controls is drawn by the dialog before the controls are drawn. %WS_CLIPCHILDREN is commonly used to reduce redraw flicker when a %WS_THICKFRAME style dialog is being resized.
%WS_CLIPSIBLINGS | Child controls are clipped (not overdrawn) by one another when the dialog window is repainted. (default)
%WS_DISABLED | Create a dialog that is initially disabled. A disabled dialog cannot receive input from the user.
%WS_DLGFRAME | Create a window that has a border of the style typically used with dialog boxes. (default)
%WS_HSCROLL | Dialog contains a horizontal scroll bar.
%WS_ICONIC | Create a dialog that is initially minimized, the same as the %WS_MINIMIZE style.
%WS_MAXIMIZE | Create a dialog that is initially maximized.
%WS_MAXIMIZEBOX | Create a dialog that has a Maximize button. Use with the %WS_SYSMENU style.
%WS_MINIMIZE | Create a dialog that is initially minimized, the same as the %WS_ICONIC style.
%WS_MINIMIZEBOX | Create a dialog that has a Minimize button. Use with the %WS_SYSMENU style.
%WS_OVERLAPPED | Create an overlapped window. An overlapped window has a title bar (caption) and a border. Synonym of the obsolete style %WS_TILED.
%WS_OVERLAPPEDWINDOW | Combination style producing an overlapping dialog. Comprises %WS_CAPTION, %WS_SYSMENU, %WS_THICKFRAME, %WS_MINIMIZEBOX, %WS_MAXIMIZEBOX, and %WS_OVERLAPPED styles.
%WS_POPUP | Create a popup dialog. When used by itself, a flat dialog is created with no caption or borders. Combine with %DS_MODALFRAME to create a 3D border. A popup dialog can overlap another window or dialog. (default)
%WS_POPUPWINDOW | Create a popup dialog but with a border and system menu. Comprises %WS_BORDER, %WS_POPUP and %WS_SYSMENU. Combine %WS_POPUPWINDOW with %WS_CAPTION to make the Window menu visible.
%WS_SYSMENU | Create a dialog that has a System-menu box in its title bar. Must be used with the %WS_CAPTION style.
%WS_THICKFRAME | Create a dialog that has a sizing border. That is, the dialog will be resizable.
%WS_VSCROLL | Dialog contains a vertical scroll bar. Also see %WS_EX_LEFTSCROLLBAR.

exstyle&

An optional extended style bitmask describing how the dialog should be displayed. The default extended dialog style comprises %WS_EX_LEFT with %WS_EX_LTRREADING and %WS_EX_RIGHTSCROLLBAR. The default extended style is used only if there are no explicit primary or extended styles parameters in the DIALOG NEW statement.

An explicit extended style value can be a combination of any values below, combined together with the OR operator to form a bitmask:

%WS_EX_ACCEPTFILES | The dialog accepts drag+drop files. The dialog Callback Function receives a %WM_DROPFILES message when files have been dropped onto the dialog.
%WS_EX_APPWINDOW | Force a top-level dialog onto the application taskbar when the window is minimized.
%WS_EX_CLIENTEDGE | Dialog has a border with a sunken edge.
%WS_EX_CONTEXTHELP | Include a question mark in the title bar of the dialog. When the user clicks the question mark, the cursor changes to a question mark with a pointer. If the user then clicks a child window, the child receives a %WM_HELP message. Also see %DS_CONTEXTHELP.
%WS_EX_CONTROLPARENT | The user may navigate among the child dialogs of the window by using the TAB key. See %DS_CONTROL.
%WS_EX_LEFT | Dialog has generic "left-aligned" properties. (default)
%WS_EX_LEFTSCROLLBAR | If present, the vertical scroll bar is positioned to the left of the client area. Also see %WS_VSCROLL.
%WS_EX_LTRREADING | Display the dialog text using Left to Right reading-order properties. (default)
%WS_EX_NOPARENTNOTIFY | Suppress %WM_PARENTNOTIFY messages when dialog is created or destroyed.
%WS_EX_OVERLAPPEDWINDOW | Comprised of the %WS_EX_CLIENTEDGE and %WS_EX_WINDOWEDGE styles.
%WS_EX_PALETTEWINDOW | Comprised of the %WS_EX_WINDOWEDGE, %WS_EX_TOOLWINDOW and %WS_EX_TOPMOST styles.
%WS_EX_RIGHT | Dialog has generic "right-aligned" properties that depend on the window class. This style has an effect only if the shell language is Hebrew, Arabic, or another language that supports reading order alignment. Otherwise, the style is ignored.
%WS_EX_RIGHTSCROLLBAR | If present, the vertical scroll bar is positioned to the right of the client area. See %WS_VSCROLL. (default)
%WS_EX_RTLREADING | If the shell language is Hebrew, Arabic, or another language that supports reading order alignment, the dialog text is displayed using Right to Left reading-order properties. For other languages, the style is ignored.
%WS_EX_STATICEDGE | Dialog has a 3D border. Primarily used for dialogs that do not require user-input.
%WS_EX_TOOLWINDOW | Create a tool window (a window intended to be used as a floating toolbar). A tool window has a shorter than normal caption area and the dialog caption is drawn using a smaller font. A tool window does not appear in the task bar, or in the window that appears when the user presses ALT+TAB. The hybrid versions of Windows (95/98/ME) may require this extended style to be added after creation, using the SetWindowLong API function.
%WS_EX_TOPMOST | Place dialog above all non-topmost windows and keep it above them, even while the dialog is deactivated.
%WS_EX_TRANSPARENT | Controls/windows beneath the dialog are drawn before the dialog is drawn. The dialog is deemed transparent because elements behind the dialog have already been painted - the dialog itself is not drawn differently. True transparency is achieved by using Regions - see MSDN for more information.
%WS_EX_WINDOWEDGE | Dialog has a border with a raised edge.

hDlg

Long-integer Variable where the Windows window handle of the dialog is stored after it has been created and assigned by Windows. This handle should be used with subsequent DIALOG and CONTROL statements, and may be directly used with Windows API calls.

If the dialog could not be created (i.e., due to low Windows resources), zero is returned.

See also | Dynamic Dialog Tools, CONTROL ADD, DIALOG DOEVENTS, DIALOG END, DIALOG HIDE, DIALOG MAXIMIZE, DIALOG MINIMIZE, DIALOG NONSTABLE, DIALOG NORMALIZE, DIALOG SET COLOR, DIALOG SHOW MODAL, DIALOG SHOW MODELESS, DIALOG STABILIZE, DIALOG SHOW STATE, TXT pseudo-object