wxRuby Documentation Home

# Wx::Dialog

A dialog box is a window with a title bar and sometimes a system menu, which
can be moved around the screen. It can contain controls and other windows and
is usually used to allow the user to make some choice or to answer a
question.

Many common interactions such as choosing a file or entering a
password are encapsulated in subclasses of Wx::Dialog, and will be
displayed using native dialogs.

## Derived from

TopLevelWindow

Window

EvtHandler

Object

## Dialog Buttons

The dialog usually contains either a single button allowing to close the
dialog or two buttons, one accepting the changes and the other one
discarding them (such button, if present, is automatically activated if
the user presses the `"Esc"` key). By default, buttons with the standard
`ID_OK` and `ID_CANCEL` identifiers behave as expected. It is also
possible to use a button with a different identifier nstead, see
set_affirmative_id and
set_escape_id.

Also notice that the create_button_sizer
should be used to create the buttons appropriate for the current platform and
positioned correctly (including their order which is
platform-dependent).

## Modal and modeless dialogs

There are two kinds of dialog — modal and modeless_. A modal dialog
blocks program flow and user input on other windows until it is dismissed,
whereas a modeless dialog behaves more like a frame in that program flow
continues, and input in other windows is still possible. To show a modal dialog
you should use the show_modalshowmodal method while to show
a dialog modelessly you simply use show, just as with
frames.

These methods return a value representing the user’s choice from the
dialog, such as ‘OK’ or ‘Cancel’. To test these, do:

dlg = MyAskDialog.new(…) case dlg.show_modal when Wx::ID_OK # user clicked ok … when Wx::ID_CANCEL # user clicked cancel or closed the dialog … end

As well as handling the ending of dialogs this way, an application can
also define a CloseEvent handler for the dialog to
respond to system close events, by calling `evt_close`.

## Window styles

`CAPTION` | Puts a caption on the dialog box.
`DEFAULT_DIALOG_STYLE` | Equivalent to a combination of CAPTION, CLOSE_BOX and SYSTEM_MENU (the last one is not used under Unix)
`RESIZE_BORDER` | Display a resizeable frame around the window.
`SYSTEM_MENU` | Display a system menu.
`CLOSE_BOX` | Displays a close box on the frame.
`MAXIMIZE_BOX` | Displays a maximize box on the dialog.
`MINIMIZE_BOX` | Displays a minimize box on the dialog.
`THICK_FRAME` | Display a thick frame around the window.
`STAY_ON_TOP` | The dialog stays on top of all other windows.
`NO_3D` | Under Windows, specifies that the child controlsshould not have 3D borders unless specified in the control.
`DIALOG_NO_PARENT` | By default, a dialog created with a `nil` parent window will be given the application’s top level window as parent. Use thisstyle to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.
`DIALOG_EX_CONTEXTHELP` | Under Windows, puts a query button on thecaption. When pressed, Windows will go into a context-sensitive help mode and Widgets will senda EVT_HELP event if the user clicked on an application window. Note that this is an extendedstyle and must be set by calling set_extra_style before Create is called (two-step construction).
`DIALOG_EX_METAL` | On Mac OS X, frames with this style will be shown with a metallic look. This is an extra style.

Under Unix or Linux, MWM (the Motif Window Manager) or other window managers
recognizing the MHM hints should be running for any of these styles to have an
effect.

See also Generic window styles.

## See also

Dialog overview, Frame, Validator overview

## Methods

- Dialog.new
- Dialog#centre
- Dialog#create
- Dialog#create_button_sizer
- Dialog#create_separated_button_sizer
- Dialog#create_std_dialog_button_sizer
- Dialog#destroy
- Dialog#do_ok
- Dialog#end_modal
- Dialog#get_affirmative_id
- Dialog#get_escape_id
- Dialog#get_return_code
- Dialog#get_tool_bar
- Dialog#iconize
- Dialog#is_iconized
- Dialog#is_modal
- Dialog#on_sys_colour_changed
- Dialog#set_affirmative_id
- Dialog#set_escape_id
- Dialog#set_icon
- Dialog#set_icons
- Dialog#set_modal
- Dialog#set_return_code
- Dialog#show
- Dialog#show_modal

### Dialog.new

Dialog.new() Dialog.new(%(arg-type)Window% parent, Integer id, String title, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer style = DEFAULT_DIALOG_STYLE, String name = “dialogBox”)

Constructors. A Dialog may be attached to a particular parent frame, in
which case it will be automatically destroyed when that parent is
closed. However, the parent argument may be `nil` – indeed it is
possible to create an application that consists only of Dialogs. If a
Dialog is created with a `nil` parent, you must be sure to call
destroy on the dialog once it is no longer being
used. Otherwise, your application may hang when it exits because there
is a window still remaining in use, even if it is not visible.

The zero-argument form is only useful when loading dialog subclasses
using XRC.

#### Parameters

- parent Can be nil, a frame or another dialog box.
- id An identifier for the dialog. A value of -1 is taken to mean a default.
- title The title of the dialog.
- pos The dialog position. A value of (-1, -1) indicates a default position, chosen by either the windowing system or wxRuby, depending on platform.
- size The dialog size. A value of (-1, -1) indicates a default size, chosen by either the windowing system or wxRuby, depending on platform.
- style The window style. See Dialog.
- name Used to associate a name with the window,
  allowing the application user to set Motif resource values for
  individual dialog boxes.

#### See also

Dialog#create

destructor()

Destructor. Deletes any child windows before deleting the physical window.

### Dialog#centre

centre(%(arg-type)Integer% direction = BOTH)

Centres the dialog box on the display.

#### Parameters

- direction May be `HORIZONTAL`, `VERTICAL` or `BOTH`.

### Dialog#create

Boolean create(%(arg-type)Window% parent, Integer id, String title, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer style = DEFAULT_DIALOG_STYLE, String name = “dialogBox”)

Used for two-step dialog box construction. See Dialog.new for details.

### Dialog#create_button_sizer

Sizer create_button_sizer(%(arg-type)Integer% flags)

Creates a sizer with standard buttons. flags is a bit list
of the following flags: OK, CANCEL, YES, NO, HELP, NO_DEFAULT.

The sizer lays out the buttons in a manner appropriate to the platform.

This function uses create_std_dialog_button_sizer
internally for most platforms but doesn’t create the sizer at all for the
platforms with hardware buttons (such as smartphones) for which it sets up the
hardware buttons appropriately and returns , so don’t forget to test that
the return value is valid before using it.

### Dialog#create_separated_button_sizer

Sizer create_separated_button_sizer(%(arg-type)Integer% flags)

Creates a sizer with standard buttons using
create_button_sizer separated from the rest
of the dialog contents by a horizontal StaticLine.

Please notice that just like CreateButtonSizer() this function may return
if no buttons were created.

### Dialog#create_std_dialog_button_sizer

StdDialogButtonSizer create_std_dialog_button_sizer(%(arg-type)Integer% flags)

Creates a StdDialogButtonSizer with standard buttons. flags is a bit list
of the following flags: OK, CANCEL, YES, NO, HELP, NO_DEFAULT.

The sizer lays out the buttons in a manner appropriate to the platform.

### Dialog#destroy

Boolean destroy()

Tells wxRuby that this Dialog can be disposed of. This is normally only
required if the Dialog was created with no parent frame (see
new). Dialogs that are associated with a parent frame will
be automatically destroyed by wxRuby when the frame is closed.

### Dialog#do_ok

Boolean do_ok()

This function is called when the titlebar OK button is pressed (PocketPC only).
A command event for the identifier returned by get_affirmative_id is sent by
default. You can override this function. If the function returns false, Widgets
will call close for the dialog.

### Dialog#end_modal

end_modal(%(arg-type)Integer% ret_code)

Ends a modal dialog, passing a value to be returned from the Dialog#show_modal invocation.

#### Parameters

- ret_code The value that should be returned by show_modal.

#### See also

Dialog#show_modal, Dialog#get_return_code, Dialog#set_return_code

### Dialog#get_affirmative_id

Integer get_affirmative_id()

Gets the identifier of the button which works like standard OK button in this
dialog.

#### See also

Dialog#set_affirmative_id

### Dialog#get_escape_id

Integer get_escape_id()

Gets the identifier of the button to map presses of `ESC`
button to.

#### See also

Dialog#set_escape_id

### Dialog#get_return_code

Integer get_return_code()

Gets the return code for this window.

#### Remarks

A return code is normally associated with a modal dialog, where Dialog#show_modal returns
a code to the application.

#### See also

Dialog#set_return_code, Dialog#show_modal, Dialog#end_modal

### Dialog#get_tool_bar

ToolBar get_tool_bar()

On PocketPC, a dialog is automatically provided with an empty toolbar. get_tool_bar
allows you to access the toolbar and add tools to it. Removing tools and adding
arbitrary controls are not currently supported.

This function is not available on any other platform.

### Dialog#iconize

iconize(%(arg-type)Boolean% iconize)

Iconizes or restores the dialog. Windows only.

#### Parameters

- iconize If true, iconizes the dialog box; if false, shows and restores it.

#### Remarks

Note that in Windows, iconization has no effect since dialog boxes cannot be
iconized. However, applications may need to explicitly restore dialog
boxes under Motif which have user-iconizable frames, and under Windows
calling `iconize(false)` will bring the window to the front, as does

### Dialog#is_iconized

Boolean is_iconized()

Returns true if the dialog box is iconized. Windows only.

#### Remarks

Always returns false under Windows since dialogs cannot be iconized.

### Dialog#is_modal

Boolean is_modal()

Returns true if the dialog box is modal, false otherwise.

### Dialog#on_sys_colour_changed

on_sys_colour_changed(%(arg-type)SysColourChangedEvent% event)

The default handler for EVT_SYS_COLOUR_CHANGED.

#### Parameters

- event The colour change event.

#### Remarks

Changes the dialog’s colour to conform to the current settings (Windows only). Add an event table entry for your dialog class if you wish the behaviour to be different (such as keeping a user-defined background colour). If you do override this function, call Event::skip to propagate the notification to child windows and controls.

#### See also

SysColourChangedEvent

### Dialog#set_affirmative_id

set_affirmative_id(%(arg-type)Integer% id)

Sets the identifier to be used as OK button. When the button with this identifier is pressed, the dialog calls validate and Window::transfer_data_from_window and, if they both return true, closes the dialog with ID_OK return code.

Also, when the user presses a hardware OK button on the devices having one or the special OK button in the PocketPC title bar, an event with this id is generated.

By default, the affirmative id is ID_OK.

#### See also

Dialog::get_affirmative_id, Dialog::set_escape_id

### Dialog#set_escape_id

set_escape_id(%(arg-type)Integer% id)

Sets the identifier of the button which should work like the standard CANCEL button in this dialog. When the button with this id is clicked, the dialog is closed. Also, when the user presses ESC key in the dialog or closes the dialog using the close button in the title bar, this is mapped to the click of the button with the specified id.

By default, the escape id is the special value ID_ANY meaning that ID_CANCEL button is used if it’s present in the dialog and otherwise the button with get_affirmative_id is used. Another special value for id is ID_NONE meaning that ESC presses should be ignored. If any other value is given, it is interpreted as the id of the button to map the escape key to.

### Dialog#set_icon

set_icon(%(arg-type)Icon% icon)

Sets the icon for this dialog.

#### Parameters

- icon The icon to associate with this dialog.

#### See also

Icon

### Dialog#set_icons

set_icons(%(arg-type)IconBundle% icons)

Sets the icons for this dialog.

#### Parameters

- icons The icons to associate with this dialog.

#### See also

IconBundle

### Dialog#set_modal

set_modal(%(arg-type)Boolean% flag)

NB: This function is deprecated and doesn’t work for all ports, just use show_modal to show a modal dialog instead.

Allows the programmer to specify whether the dialog box is modal (Dialog::show blocks control until the dialog is hidden) or modeless (control returns immediately).

#### Parameters

- flag If true, the dialog will be modal, otherwise it will be modeless.

### Dialog#set_return_code

set_return_code(%(arg-type)Integer% ret_code)

#### Parameters

- ret_code The integer return code, usually a control identifier.

#### Remarks

A return code is normally associated with a modal dialog, where Dialog::show_modal returns a code to the application. The function Dialog::end_modal calls set_return_code.

#### See also

Dialog::get_return_code, Dialog::show_modal, Dialog::end_modal

### Dialog#show

Boolean show(%(arg-type)Boolean% show)

Hides or shows the dialog.

#### Parameters

- show If true, the dialog box is shown and brought to the front; otherwise the box is hidden. If false and the dialog is modal, control is returned to the calling program.

#### Remarks

The preferred way of dismissing a modal dialog is to use Dialog::end_modal.

### Dialog#show_modal

Integer show_modal()

Shows a modal dialog. Program flow does not return until the dialog has been dismissed with Dialog::end_modal.

#### Return value

The return value is the value set with Dialog::set_return_code.

#### See also

Dialog::end_modal, Dialog::get_return_code, Dialog::set_return_code

[This page automatically generated from the Textile source at 2023-06-09 00:45:35 +0000]