wxDialog Class Reference

#include </home/zeitlin/src/wx/github/interface/wx/dialog.h>

Inheritance diagram for wxDialog:

---

Detailed Description

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 often used to allow the user to make some choice or to answer a question.

Dialogs can be made scrollable, automatically, for computers with low resolution screens: please see Automatic scrolling dialogs for further details.

Dialogs 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 wxID_OK and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7 it is also possible to use a button with a different identifier instead, see SetAffirmativeId() and SetEscapeId().

Also notice that the CreateButtonSizer() 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

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 ShowModal() method while to show a dialog modelessly you simply use Show(), just as with frames.

Note that the modal dialog is one of the very few examples of wxWindow-derived objects which may be created on the stack and not on the heap. In other words, while most windows would be created like this:

    void AskUser()
    {
        MyAskDialog *dlg = new MyAskDialog(...);
        if ( dlg->ShowModal() == wxID_OK )
            // ...
        //else: dialog was cancelled or some another button pressed

        dlg->Destroy();
    }

You can achieve the same result with dialogs by using simpler code:

    void AskUser()
    {
        MyAskDialog dlg(...);
        if ( dlg.ShowModal() == wxID_OK )
            // ...

        // no need to call Destroy() here
    }

An application can define a wxCloseEvent handler for the dialog to respond to system close events.

Styles

This class supports the following styles:

• wxCAPTION:
  Puts a caption on the dialog box.
• wxDEFAULT_DIALOG_STYLE:
  Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and wxSYSTEM_MENU (the last one is not used under Unix).
• wxRESIZE_BORDER:
  Display a resizable frame around the window.
• wxSYSTEM_MENU:
  Display a system menu.
• wxCLOSE_BOX:
  Displays a close box on the frame.
• wxMAXIMIZE_BOX:
  Displays a maximize box on the dialog.
• wxMINIMIZE_BOX:
  Displays a minimize box on the dialog.
• wxTHICK_FRAME:
  Display a thick frame around the window.
• wxSTAY_ON_TOP:
  The dialog stays on top of all other windows.
• wxNO_3D:
  This style is obsolete and doesn't do anything any more, don't use it in any new code.
• wxDIALOG_NO_PARENT:
  By default, a dialog created with a NULL parent window will be given the application's top level window as parent. Use this style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.
• wxDIALOG_EX_CONTEXTHELP:
  Under Windows, puts a query button on the caption. When pressed, Windows will go into a context-sensitive help mode and wxWidgets will send a wxEVT_HELP event if the user clicked on an application window. Note that this is an extended style and must be set by calling SetExtraStyle() before Create is called (two-step construction).
• wxDIALOG_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.

Events emitted by this class

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCloseEvent& event)

Event macros for events emitted by this class:

• EVT_CLOSE(func):
  The dialog is being closed by the user or programmatically (see wxWindow::Close). The user may generate this event clicking the close button (typically the 'X' on the top-right of the title bar) if it's present (see the wxCLOSE_BOX style) or by clicking a button with the wxID_CANCEL or wxID_OK ids.
• EVT_INIT_DIALOG(func):
  Process a wxEVT_INIT_DIALOG event. See wxInitDialogEvent.

Library:  wxCore

Category:  Common Dialogs

参照:

wxDialog Overview, wxFrame, wxValidator Overview

Public Member Functions
	wxDialog ()
	Default constructor.
	wxDialog (wxWindow *parent, wxWindowID id, const wxString &title, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxDEFAULT_DIALOG_STYLE, const wxString &name=wxDialogNameStr)
	Constructor.
virtual	~wxDialog ()
	Destructor.
void	AddMainButtonId (wxWindowID id)
	Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.
virtual bool	CanDoLayoutAdaptation ()
	Returns true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display.
void	Centre (int direction=wxBOTH)
	Centres the dialog box on the display.
bool	Create (wxWindow *parent, wxWindowID id, const wxString &title, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, long style=wxDEFAULT_DIALOG_STYLE, const wxString &name=wxDialogNameStr)
	Used for two-step dialog box construction.
wxSizer *	CreateButtonSizer (long flags)
	標準ボタンを含むサイザーを作成します。
wxSizer *	CreateSeparatedButtonSizer (long flags)
	Creates a sizer with standard buttons using CreateButtonSizer() separated from the rest of the dialog contents by a horizontal wxStaticLine.
wxSizer *	CreateSeparatedSizer (wxSizer *sizer)
	Returns the sizer containing the given one with a separating wxStaticLine if necessarily.
wxStdDialogButtonSizer *	CreateStdDialogButtonSizer (long flags)
	Creates a wxStdDialogButtonSizer with standard buttons.
wxSizer *	CreateTextSizer (const wxString &message)
	Splits text up at newlines and places the lines into wxStaticText objects in a vertical wxBoxSizer.
virtual bool	DoLayoutAdaptation ()
	レイアウトの適応を行います。これは通常、画面サイズに対してダイアログが大きすぎる場合に行われます。
virtual bool	DoOK ()
	This function is called when the titlebar OK button is pressed (PocketPC only).
virtual void	EndModal (int retCode)
	Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.
int	GetAffirmativeId () const
	Gets the identifier of the button which works like standard OK button in this dialog.
virtual wxWindow *	GetContentWindow () const
	ダイアログのメインコンテンツを含むウィンドウを返却するためにこの関数をオーバーライドしてください。
int	GetEscapeId () const
	Gets the identifier of the button to map presses of ESC button to.
bool	GetLayoutAdaptationDone () const
	Returns true if the dialog has been adapted, usually by making it scrollable to work with a small display.
int	GetLayoutAdaptationLevel () const
	Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
wxDialogLayoutAdaptationMode	GetLayoutAdaptationMode () const
	Gets the adaptation mode, overriding the global adaptation flag.
wxArrayInt &	GetMainButtonIds ()
	Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
int	GetReturnCode () const
	Gets the return code for this window.
wxToolBar *	GetToolBar () const
	On PocketPC, a dialog is automatically provided with an empty toolbar.
virtual void	Iconize (bool iconize=true)
	Iconizes or restores the dialog.
virtual bool	IsIconized () const
	Returns true if the dialog box is iconized.
bool	IsMainButtonId (wxWindowID id) const
	Returns true if id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.
virtual bool	IsModal () const
	Returns true if the dialog box is modal, false otherwise.
void	SetAffirmativeId (int id)
	Sets the identifier to be used as OK button.
void	SetEscapeId (int id)
	Sets the identifier of the button which should work like the standard "Cancel" button in this dialog.
void	SetIcon (const wxIcon &icon)
	Sets the icon for this dialog.
void	SetIcons (const wxIconBundle &icons)
	Sets the icons for this dialog.
void	SetLayoutAdaptationDone (bool done)
	Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.
void	SetLayoutAdaptationLevel (int level)
	Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.
void	SetLayoutAdaptationMode (wxDialogLayoutAdaptationMode mode)
	適応モードを設定し、グルーバルな適応フラグを上書きします。
void	SetModal (bool flag)
void	SetReturnCode (int retCode)
	このウィンドウの戻り値を設定します。
virtual bool	Show (bool show=1)
	ダイアログの表示・非表示を切り替えます。
virtual int	ShowModal ()
	モーダルダイアログを表示します。
void	ShowWindowModal ()
	Shows a dialog modal to the parent top level window only.
Static Public Member Functions
static void	EnableLayoutAdaptation (bool enable)
	すべてのダイアログに対してレイアウトの適応を有効化・無効化する静的関数です。
static wxDialogLayoutAdapter *	GetLayoutAdapter ()
	A static function getting the current layout adapter object.
static bool	IsLayoutAdaptationEnabled ()
	A static function returning true if layout adaptation is enabled for all dialogs.
static wxDialogLayoutAdapter *	SetLayoutAdapter (wxDialogLayoutAdapter *adapter)
	A static function for setting the current layout adapter object, returning the old adapter.

List of all members.

---

Constructor & Destructor Documentation

wxDialog::wxDialog

(

)

Default constructor.

wxDialog::wxDialog	(	wxWindow *	parent,
		wxWindowID	id,
		const wxString &	title,
		const wxPoint &	pos = wxDefaultPosition,
		const wxSize &	size = wxDefaultSize,
		long	style = wxDEFAULT_DIALOG_STYLE,
		const wxString &	name = wxDialogNameStr
	)

Constructor.

Parameters:

parent	Can be NULL, 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. The value wxDefaultPosition indicates a default position, chosen by either the windowing system or wxWidgets, depending on platform.
size	The dialog size. The value wxDefaultSize indicates a default size, chosen by either the windowing system or wxWidgets, depending on platform.
style	The window style.
name	Used to associate a name with the window, allowing the application user to set Motif resource values for individual dialog boxes.

参照:

Create()

virtual wxDialog::~wxDialog

(

)

[virtual]

Destructor.

Deletes any child windows before deleting the physical window.

See Window Deletion for more info.

---

Member Function Documentation

void wxDialog::AddMainButtonId

(

wxWindowID

id

)

Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

virtual bool wxDialog::CanDoLayoutAdaptation

(

)

[virtual]

Returns true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

void wxDialog::Centre

(

int

direction = wxBOTH

)

Centres the dialog box on the display.

Parameters:

direction

May be wxHORIZONTAL, wxVERTICAL or wxBOTH.

Reimplemented from wxWindow.

bool wxDialog::Create	(	wxWindow *	parent,
		wxWindowID	id,
		const wxString &	title,
		const wxPoint &	pos = wxDefaultPosition,
		const wxSize &	size = wxDefaultSize,
		long	style = wxDEFAULT_DIALOG_STYLE,
		const wxString &	name = wxDialogNameStr
	)

Used for two-step dialog box construction.

参照:

wxDialog()

Reimplemented from wxTopLevelWindow.

Reimplemented in wxPropertySheetDialog.

wxSizer* wxDialog::CreateButtonSizer

(

long

flags

)

標準ボタンを含むサイザーを作成します。

flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT.

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

This function uses CreateStdDialogButtonSizer() 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 NULL, so don't forget to test that the return value is valid before using it.

wxSizer* wxDialog::CreateSeparatedButtonSizer

(

long

flags

)

Creates a sizer with standard buttons using CreateButtonSizer() separated from the rest of the dialog contents by a horizontal wxStaticLine.

注:

Just like CreateButtonSizer(), this function may return NULL if no buttons were created.

This is a combination of CreateButtonSizer() and CreateSeparatedSizer().

wxSizer* wxDialog::CreateSeparatedSizer

(

wxSizer *

sizer

)

Returns the sizer containing the given one with a separating wxStaticLine if necessarily.

This function is useful for creating the sizer containing footer-like contents in dialog boxes. It will add a separating static line only if it conforms to the current platform convention (currently it is not added under Mac where the use of static lines for grouping is discouraged and is added elsewhere).

Since:

2.9.2

Parameters:

sizer

The sizer to wrap, must be non-NULL.

Returns:

The sizer wrapping the input one or possibly the input sizer itself if no wrapping is necessary.

wxStdDialogButtonSizer* wxDialog::CreateStdDialogButtonSizer

(

long

flags

)

Creates a wxStdDialogButtonSizer with standard buttons.

flags is a bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, wxNO_DEFAULT.

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

wxSizer* wxDialog::CreateTextSizer

(

const wxString &

message

)

Splits text up at newlines and places the lines into wxStaticText objects in a vertical wxBoxSizer.

virtual bool wxDialog::DoLayoutAdaptation

(

)

[virtual]

レイアウトの適応を行います。これは通常、画面サイズに対してダイアログが大きすぎる場合に行われます。

参照:

Automatic scrolling dialogs (for more on layout adaptation)

virtual bool wxDialog::DoOK

(

)

[virtual]

This function is called when the titlebar OK button is pressed (PocketPC only).

A command event for the identifier returned by GetAffirmativeId() is sent by default. You can override this function. If the function returns false, wxWidgets will call Close() for the dialog.

Availability:  only available for the wxMSW port.

static void wxDialog::EnableLayoutAdaptation

(

bool

enable

)

[static]

すべてのダイアログに対してレイアウトの適応を有効化・無効化する静的関数です。

参照:

Automatic scrolling dialogs (for more on layout adaptation)

virtual void wxDialog::EndModal

(

int

retCode

)

[virtual]

Ends a modal dialog, passing a value to be returned from the ShowModal() invocation.

Parameters:

retCode

The value that should be returned by ShowModal.

参照:

ShowModal(), GetReturnCode(), SetReturnCode()

int wxDialog::GetAffirmativeId

(

)

const

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

参照:

SetAffirmativeId()

virtual wxWindow* wxDialog::GetContentWindow

(

)

const [virtual]

ダイアログのメインコンテンツを含むウィンドウを返却するためにこの関数をオーバーライドしてください。

This is particularly useful when the dialog implements pages, such as wxPropertySheetDialog, and allows the layout adaptation code to know that only the pages need to be made scrollable.

int wxDialog::GetEscapeId

(

)

const

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

参照:

SetEscapeId()

bool wxDialog::GetLayoutAdaptationDone

(

)

const

Returns true if the dialog has been adapted, usually by making it scrollable to work with a small display.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

int wxDialog::GetLayoutAdaptationLevel

(

)

const

Gets a value representing the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.

Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

wxDialogLayoutAdaptationMode wxDialog::GetLayoutAdaptationMode

(

)

const

Gets the adaptation mode, overriding the global adaptation flag.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

static wxDialogLayoutAdapter* wxDialog::GetLayoutAdapter

(

)

[static]

A static function getting the current layout adapter object.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

wxArrayInt& wxDialog::GetMainButtonIds

(

)

Returns an array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

int wxDialog::GetReturnCode

(

)

const

Gets the return code for this window.

注意:

A return code is normally associated with a modal dialog, where ShowModal() returns a code to the application.

参照:

SetReturnCode(), ShowModal(), EndModal()

wxToolBar* wxDialog::GetToolBar

(

)

const

On PocketPC, a dialog is automatically provided with an empty toolbar.

This function 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.

Availability:  only available for the wxMSW port.

virtual void wxDialog::Iconize

(

bool

iconize = true

)

[virtual]

Iconizes or restores the dialog.

Windows only.

Parameters:

iconize

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

注意:

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 Show(true).

Reimplemented from wxTopLevelWindow.

virtual bool wxDialog::IsIconized

(

)

const [virtual]

Returns true if the dialog box is iconized.

Windows only.

注意:

Always returns false under Windows since dialogs cannot be iconized.

Reimplemented from wxTopLevelWindow.

static bool wxDialog::IsLayoutAdaptationEnabled

(

)

[static]

A static function returning true if layout adaptation is enabled for all dialogs.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

bool wxDialog::IsMainButtonId

(

wxWindowID

id

)

const

Returns true if id is in the array of identifiers to be regarded as the main buttons for the non-scrolling area of a dialog.

Availability:  only available for the wxMSW port.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

virtual bool wxDialog::IsModal

(

)

const [virtual]

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

void wxDialog::SetAffirmativeId

(

int

id

)

Sets the identifier to be used as OK button.

When the button with this identifier is pressed, the dialog calls wxWindow::Validate() and wxWindow::TransferDataFromWindow() and, if they both return true, closes the dialog with the affirmative id 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 wxID_OK.

参照:

GetAffirmativeId(), SetEscapeId()

void wxDialog::SetEscapeId

(

int

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 wxID_ANY meaning that wxID_CANCEL button is used if it's present in the dialog and otherwise the button with GetAffirmativeId() is used. Another special value for id is wxID_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.

void wxDialog::SetIcon

(

const wxIcon &

icon

)

Sets the icon for this dialog.

Parameters:

icon	The icon to associate with this dialog.

参照:

wxIcon

Reimplemented from wxTopLevelWindow.

void wxDialog::SetIcons

(

const wxIconBundle &

icons

)

[virtual]

Sets the icons for this dialog.

Parameters:

icons

The icons to associate with this dialog.

参照:

wxIconBundle

Reimplemented from wxTopLevelWindow.

void wxDialog::SetLayoutAdaptationDone

(

bool

done

)

Marks the dialog as having been adapted, usually by making it scrollable to work with a small display.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

void wxDialog::SetLayoutAdaptationLevel

(

int

level

)

Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-adapted dialog.

Zero switches off adaptation, and 3 allows search for standard buttons anywhere in the dialog.

参照:

Automatic scrolling dialogs (for more on layout adaptation)

void wxDialog::SetLayoutAdaptationMode

(

wxDialogLayoutAdaptationMode

mode

)

適応モードを設定し、グルーバルな適応フラグを上書きします。

参照:

wxDialogLayoutAdaptationMode, Automatic scrolling dialogs (for more on layout adaptation)

static wxDialogLayoutAdapter* wxDialog::SetLayoutAdapter

(

wxDialogLayoutAdapter *

adapter

)

[static]

A static function for setting the current layout adapter object, returning the old adapter.

If you call this, you should delete the old adapter object.

参照:

wxDialogLayoutAdapter, Automatic scrolling dialogs

void wxDialog::SetModal

(

bool

flag

)

Deprecated:

This function doesn't work for all ports, just use ShowModal() to show a modal dialog instead.

Allows the programmer to specify whether the dialog box is modal (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.

void wxDialog::SetReturnCode

(

int

retCode

)

このウィンドウの戻り値を設定します。

A return code is normally associated with a modal dialog, where ShowModal() returns a code to the application. The function EndModal() calls SetReturnCode().

Parameters:

retCode

The integer return code, usually a control identifier.

参照:

GetReturnCode(), ShowModal(), EndModal()

virtual bool wxDialog::Show

(

bool

show = 1

)

[virtual]

ダイアログの表示・非表示を切り替えます。

The preferred way of dismissing a modal dialog is to use EndModal().

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.

Reimplemented from wxWindow.

virtual int wxDialog::ShowModal

(

)

[virtual]

モーダルダイアログを表示します。

Program flow does not return until the dialog has been dismissed with EndModal().

Notice that it is possible to call ShowModal() for a dialog which had been previously shown with Show(), this allows to make an existing modeless dialog modal. However ShowModal() can't be called twice without intervening EndModal() calls.

Note that this function creates a temporary event loop which takes precedence over the application's main event loop (see wxEventLoopBase) and which is destroyed when the dialog is dismissed. This also results in a call to wxApp::ProcessPendingEvents().

Returns:

The value set with SetReturnCode().

参照:

ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode()

Reimplemented in wxMultiChoiceDialog, wxSingleChoiceDialog, wxColourDialog, wxDirDialog, wxFileDialog, wxFontDialog, wxMessageDialog, and wxTextEntryDialog.

void wxDialog::ShowWindowModal

(

)

Shows a dialog modal to the parent top level window only.

Unlike ShowModal(), dialogs shown with this function only prevent the user from interacting with their parent frame only but not with the rest of the application. They also don't block the program execution but instead return immediately, as Show(), and generate a wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed.

Currently this function is only fully implemented in wxOSX ports, under the other platforms it behaves like ShowModal() (but also sends the above mentioned event).

Since:

2.9.0