| 1 | ///////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: dialog.h |
| 3 | // Purpose: interface of wxDialog |
| 4 | // Author: wxWidgets team |
| 5 | // RCS-ID: $Id$ |
| 6 | // Licence: wxWindows licence |
| 7 | ///////////////////////////////////////////////////////////////////////////// |
| 8 | |
| 9 | /** |
| 10 | Modes used for wxDialog::SetLayoutAdaptationMode(). |
| 11 | */ |
| 12 | enum wxDialogLayoutAdaptationMode |
| 13 | { |
| 14 | wxDIALOG_ADAPTATION_MODE_DEFAULT = 0, ///< Use global adaptation enabled status. |
| 15 | wxDIALOG_ADAPTATION_MODE_ENABLED = 1, ///< Enable this dialog overriding global status. |
| 16 | wxDIALOG_ADAPTATION_MODE_DISABLED = 2 ///< Disable this dialog overriding global status. |
| 17 | }; |
| 18 | |
| 19 | #define wxDEFAULT_DIALOG_STYLE (wxCAPTION | wxSYSTEM_MENU | wxCLOSE_BOX) |
| 20 | |
| 21 | /** |
| 22 | @class wxDialog |
| 23 | |
| 24 | A dialog box is a window with a title bar and sometimes a system menu, |
| 25 | which can be moved around the screen. It can contain controls and other |
| 26 | windows and is often used to allow the user to make some choice or to |
| 27 | answer a question. |
| 28 | |
| 29 | Dialogs can be made scrollable, automatically, for computers with low |
| 30 | resolution screens: please see @ref overview_dialog_autoscrolling for |
| 31 | further details. |
| 32 | |
| 33 | Dialogs usually contains either a single button allowing to close the |
| 34 | dialog or two buttons, one accepting the changes and the other one |
| 35 | discarding them (such button, if present, is automatically activated if the |
| 36 | user presses the "Esc" key). By default, buttons with the standard wxID_OK |
| 37 | and wxID_CANCEL identifiers behave as expected. Starting with wxWidgets 2.7 |
| 38 | it is also possible to use a button with a different identifier instead, |
| 39 | see SetAffirmativeId() and SetEscapeId(). |
| 40 | |
| 41 | Also notice that the CreateButtonSizer() should be used to create the |
| 42 | buttons appropriate for the current platform and positioned correctly |
| 43 | (including their order which is platform-dependent). |
| 44 | |
| 45 | @section dialog_modal Modal and Modeless |
| 46 | |
| 47 | There are two kinds of dialog, modal and modeless. A modal dialog blocks |
| 48 | program flow and user input on other windows until it is dismissed, whereas |
| 49 | a modeless dialog behaves more like a frame in that program flow continues, |
| 50 | and input in other windows is still possible. To show a modal dialog you |
| 51 | should use the ShowModal() method while to show a dialog modelessly you |
| 52 | simply use Show(), just as with frames. |
| 53 | |
| 54 | Note that the modal dialog is one of the very few examples of |
| 55 | wxWindow-derived objects which may be created on the stack and not on the |
| 56 | heap. In other words, while most windows would be created like this: |
| 57 | |
| 58 | @code |
| 59 | void AskUser() |
| 60 | { |
| 61 | MyAskDialog *dlg = new MyAskDialog(...); |
| 62 | if ( dlg->ShowModal() == wxID_OK ) |
| 63 | // ... |
| 64 | //else: dialog was cancelled or some another button pressed |
| 65 | |
| 66 | dlg->Destroy(); |
| 67 | } |
| 68 | @endcode |
| 69 | |
| 70 | You can achieve the same result with dialogs by using simpler code: |
| 71 | |
| 72 | @code |
| 73 | void AskUser() |
| 74 | { |
| 75 | MyAskDialog dlg(...); |
| 76 | if ( dlg.ShowModal() == wxID_OK ) |
| 77 | // ... |
| 78 | |
| 79 | // no need to call Destroy() here |
| 80 | } |
| 81 | @endcode |
| 82 | |
| 83 | An application can define a wxCloseEvent handler for the dialog to respond |
| 84 | to system close events. |
| 85 | |
| 86 | @beginStyleTable |
| 87 | @style{wxCAPTION} |
| 88 | Puts a caption on the dialog box. |
| 89 | @style{wxDEFAULT_DIALOG_STYLE} |
| 90 | Equivalent to a combination of wxCAPTION, wxCLOSE_BOX and |
| 91 | wxSYSTEM_MENU (the last one is not used under Unix). |
| 92 | @style{wxRESIZE_BORDER} |
| 93 | Display a resizable frame around the window. |
| 94 | @style{wxSYSTEM_MENU} |
| 95 | Display a system menu. |
| 96 | @style{wxCLOSE_BOX} |
| 97 | Displays a close box on the frame. |
| 98 | @style{wxMAXIMIZE_BOX} |
| 99 | Displays a maximize box on the dialog. |
| 100 | @style{wxMINIMIZE_BOX} |
| 101 | Displays a minimize box on the dialog. |
| 102 | @style{wxTHICK_FRAME} |
| 103 | Display a thick frame around the window. |
| 104 | @style{wxSTAY_ON_TOP} |
| 105 | The dialog stays on top of all other windows. |
| 106 | @style{wxNO_3D} |
| 107 | This style is obsolete and doesn't do anything any more, don't use |
| 108 | it in any new code. |
| 109 | @style{wxDIALOG_NO_PARENT} |
| 110 | By default, a dialog created with a @NULL parent window will be |
| 111 | given the @ref wxApp::GetTopWindow() "application's top level window" |
| 112 | as parent. Use this style to prevent this from happening and create |
| 113 | an orphan dialog. This is not recommended for modal dialogs. |
| 114 | @style{wxDIALOG_EX_CONTEXTHELP} |
| 115 | Under Windows, puts a query button on the caption. When pressed, |
| 116 | Windows will go into a context-sensitive help mode and wxWidgets |
| 117 | will send a @c wxEVT_HELP event if the user clicked on an application |
| 118 | window. Note that this is an extended style and must be set by |
| 119 | calling SetExtraStyle() before Create is called (two-step |
| 120 | construction). |
| 121 | @style{wxDIALOG_EX_METAL} |
| 122 | On Mac OS X, frames with this style will be shown with a metallic |
| 123 | look. This is an extra style. |
| 124 | @endStyleTable |
| 125 | |
| 126 | Under Unix or Linux, MWM (the Motif Window Manager) or other window |
| 127 | managers recognizing the MHM hints should be running for any of these |
| 128 | styles to have an effect. |
| 129 | |
| 130 | |
| 131 | @beginEventEmissionTable{wxCloseEvent} |
| 132 | @event{EVT_CLOSE(func)} |
| 133 | The dialog is being closed by the user or programmatically (see wxWindow::Close). |
| 134 | The user may generate this event clicking the close button |
| 135 | (typically the 'X' on the top-right of the title bar) if it's present |
| 136 | (see the @c wxCLOSE_BOX style) or by clicking a button with the |
| 137 | @c wxID_CANCEL or @c wxID_OK ids. |
| 138 | @event{EVT_INIT_DIALOG(func)} |
| 139 | Process a @c wxEVT_INIT_DIALOG event. See wxInitDialogEvent. |
| 140 | @endEventTable |
| 141 | |
| 142 | @library{wxcore} |
| 143 | @category{cmndlg} |
| 144 | |
| 145 | @see @ref overview_dialog, wxFrame, @ref overview_validator |
| 146 | */ |
| 147 | class wxDialog : public wxTopLevelWindow |
| 148 | { |
| 149 | public: |
| 150 | /** |
| 151 | Default constructor. |
| 152 | */ |
| 153 | wxDialog(); |
| 154 | /** |
| 155 | Constructor. |
| 156 | |
| 157 | @param parent |
| 158 | Can be @NULL, a frame or another dialog box. |
| 159 | @param id |
| 160 | An identifier for the dialog. A value of -1 is taken to mean a |
| 161 | default. |
| 162 | @param title |
| 163 | The title of the dialog. |
| 164 | @param pos |
| 165 | The dialog position. The value wxDefaultPosition indicates a |
| 166 | default position, chosen by either the windowing system or |
| 167 | wxWidgets, depending on platform. |
| 168 | @param size |
| 169 | The dialog size. The value wxDefaultSize indicates a default size, |
| 170 | chosen by either the windowing system or wxWidgets, depending on |
| 171 | platform. |
| 172 | @param style |
| 173 | The window style. |
| 174 | @param name |
| 175 | Used to associate a name with the window, allowing the application |
| 176 | user to set Motif resource values for individual dialog boxes. |
| 177 | |
| 178 | @see Create() |
| 179 | */ |
| 180 | wxDialog(wxWindow* parent, wxWindowID id, const wxString& title, |
| 181 | const wxPoint& pos = wxDefaultPosition, |
| 182 | const wxSize& size = wxDefaultSize, |
| 183 | long style = wxDEFAULT_DIALOG_STYLE, |
| 184 | const wxString& name = wxDialogNameStr); |
| 185 | |
| 186 | /** |
| 187 | Destructor. |
| 188 | |
| 189 | Deletes any child windows before deleting the physical window. |
| 190 | |
| 191 | See @ref overview_windowdeletion for more info. |
| 192 | */ |
| 193 | virtual ~wxDialog(); |
| 194 | |
| 195 | /** |
| 196 | Adds an identifier to be regarded as a main button for the |
| 197 | non-scrolling area of a dialog. |
| 198 | |
| 199 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 200 | */ |
| 201 | void AddMainButtonId(wxWindowID id); |
| 202 | |
| 203 | /** |
| 204 | Returns @true if this dialog can and should perform layout adaptation |
| 205 | using DoLayoutAdaptation(), usually if the dialog is too large to fit |
| 206 | on the display. |
| 207 | |
| 208 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 209 | */ |
| 210 | virtual bool CanDoLayoutAdaptation(); |
| 211 | |
| 212 | /** |
| 213 | Centres the dialog box on the display. |
| 214 | |
| 215 | @param direction |
| 216 | May be wxHORIZONTAL, wxVERTICAL or wxBOTH. |
| 217 | */ |
| 218 | void Centre(int direction = wxBOTH); |
| 219 | |
| 220 | /** |
| 221 | Used for two-step dialog box construction. |
| 222 | |
| 223 | @see wxDialog() |
| 224 | */ |
| 225 | bool Create(wxWindow* parent, wxWindowID id, const wxString& title, |
| 226 | const wxPoint& pos = wxDefaultPosition, |
| 227 | const wxSize& size = wxDefaultSize, |
| 228 | long style = wxDEFAULT_DIALOG_STYLE, |
| 229 | const wxString& name = wxDialogNameStr); |
| 230 | |
| 231 | /** |
| 232 | Creates a sizer with standard buttons. @a flags is a bit list of the |
| 233 | following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP, |
| 234 | wxNO_DEFAULT. |
| 235 | |
| 236 | The sizer lays out the buttons in a manner appropriate to the platform. |
| 237 | |
| 238 | This function uses CreateStdDialogButtonSizer() internally for most |
| 239 | platforms but doesn't create the sizer at all for the platforms with |
| 240 | hardware buttons (such as smartphones) for which it sets up the |
| 241 | hardware buttons appropriately and returns @NULL, so don't forget to |
| 242 | test that the return value is valid before using it. |
| 243 | */ |
| 244 | wxSizer* CreateButtonSizer(long flags); |
| 245 | |
| 246 | /** |
| 247 | Creates a sizer with standard buttons using CreateButtonSizer() |
| 248 | separated from the rest of the dialog contents by a horizontal |
| 249 | wxStaticLine. |
| 250 | |
| 251 | @note Just like CreateButtonSizer(), this function may return @NULL if |
| 252 | no buttons were created. |
| 253 | |
| 254 | This is a combination of CreateButtonSizer() and |
| 255 | CreateSeparatedSizer(). |
| 256 | */ |
| 257 | wxSizer* CreateSeparatedButtonSizer(long flags); |
| 258 | |
| 259 | /** |
| 260 | Returns the sizer containing the given one with a separating |
| 261 | wxStaticLine if necessarily. |
| 262 | |
| 263 | This function is useful for creating the sizer containing footer-like |
| 264 | contents in dialog boxes. It will add a separating static line only if |
| 265 | it conforms to the current platform convention (currently it is not |
| 266 | added under Mac where the use of static lines for grouping is |
| 267 | discouraged and is added elsewhere). |
| 268 | |
| 269 | @since 2.9.2 |
| 270 | |
| 271 | @param sizer The sizer to wrap, must be non-@NULL. |
| 272 | @return The sizer wrapping the input one or possibly the input sizer |
| 273 | itself if no wrapping is necessary. |
| 274 | */ |
| 275 | wxSizer *CreateSeparatedSizer(wxSizer *sizer); |
| 276 | |
| 277 | /** |
| 278 | Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a |
| 279 | bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, |
| 280 | wxCLOSE, wxHELP, wxNO_DEFAULT. |
| 281 | |
| 282 | The sizer lays out the buttons in a manner appropriate to the platform. |
| 283 | */ |
| 284 | wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags); |
| 285 | |
| 286 | /** |
| 287 | Performs layout adaptation, usually if the dialog is too large to fit |
| 288 | on the display. |
| 289 | |
| 290 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 291 | */ |
| 292 | virtual bool DoLayoutAdaptation(); |
| 293 | |
| 294 | /** |
| 295 | This function is called when the titlebar OK button is pressed |
| 296 | (PocketPC only). A command event for the identifier returned by |
| 297 | GetAffirmativeId() is sent by default. You can override this function. |
| 298 | If the function returns @false, wxWidgets will call Close() for the |
| 299 | dialog. |
| 300 | |
| 301 | @onlyfor{wxmsw} |
| 302 | */ |
| 303 | virtual bool DoOK(); |
| 304 | |
| 305 | /** |
| 306 | A static function enabling or disabling layout adaptation for all |
| 307 | dialogs. |
| 308 | |
| 309 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 310 | */ |
| 311 | static void EnableLayoutAdaptation(bool enable); |
| 312 | |
| 313 | /** |
| 314 | Ends a modal dialog, passing a value to be returned from the |
| 315 | ShowModal() invocation. |
| 316 | |
| 317 | @param retCode |
| 318 | The value that should be returned by ShowModal. |
| 319 | |
| 320 | @see ShowModal(), GetReturnCode(), SetReturnCode() |
| 321 | */ |
| 322 | virtual void EndModal(int retCode); |
| 323 | |
| 324 | /** |
| 325 | Gets the identifier of the button which works like standard OK button |
| 326 | in this dialog. |
| 327 | |
| 328 | @see SetAffirmativeId() |
| 329 | */ |
| 330 | int GetAffirmativeId() const; |
| 331 | |
| 332 | /** |
| 333 | Override this to return a window containing the main content of the |
| 334 | dialog. This is particularly useful when the dialog implements pages, |
| 335 | such as wxPropertySheetDialog, and allows the |
| 336 | @ref overview_dialog "layout adaptation code" to know that only the |
| 337 | pages need to be made scrollable. |
| 338 | */ |
| 339 | virtual wxWindow* GetContentWindow() const; |
| 340 | |
| 341 | /** |
| 342 | Gets the identifier of the button to map presses of @c ESC button to. |
| 343 | |
| 344 | @see SetEscapeId() |
| 345 | */ |
| 346 | int GetEscapeId() const; |
| 347 | |
| 348 | /** |
| 349 | Returns @true if the dialog has been adapted, usually by making it |
| 350 | scrollable to work with a small display. |
| 351 | |
| 352 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 353 | */ |
| 354 | bool GetLayoutAdaptationDone() const; |
| 355 | |
| 356 | /** |
| 357 | Gets a value representing the aggressiveness of search for buttons and |
| 358 | sizers to be in the non-scrolling part of a layout-adapted dialog. Zero |
| 359 | switches off adaptation, and 3 allows search for standard buttons |
| 360 | anywhere in the dialog. |
| 361 | |
| 362 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 363 | */ |
| 364 | int GetLayoutAdaptationLevel() const; |
| 365 | |
| 366 | /** |
| 367 | Gets the adaptation mode, overriding the global adaptation flag. |
| 368 | |
| 369 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 370 | */ |
| 371 | wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const; |
| 372 | |
| 373 | /** |
| 374 | A static function getting the current layout adapter object. |
| 375 | |
| 376 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 377 | */ |
| 378 | static wxDialogLayoutAdapter* GetLayoutAdapter(); |
| 379 | |
| 380 | /** |
| 381 | Returns an array of identifiers to be regarded as the main buttons for |
| 382 | the non-scrolling area of a dialog. |
| 383 | |
| 384 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 385 | */ |
| 386 | wxArrayInt& GetMainButtonIds(); |
| 387 | |
| 388 | /** |
| 389 | Gets the return code for this window. |
| 390 | |
| 391 | @remarks A return code is normally associated with a modal dialog, |
| 392 | where ShowModal() returns a code to the application. |
| 393 | |
| 394 | @see SetReturnCode(), ShowModal(), EndModal() |
| 395 | */ |
| 396 | int GetReturnCode() const; |
| 397 | |
| 398 | /** |
| 399 | On PocketPC, a dialog is automatically provided with an empty toolbar. |
| 400 | This function allows you to access the toolbar and add tools to it. |
| 401 | Removing tools and adding arbitrary controls are not currently |
| 402 | supported. |
| 403 | |
| 404 | This function is not available on any other platform. |
| 405 | |
| 406 | @onlyfor{wxmsw} |
| 407 | */ |
| 408 | wxToolBar* GetToolBar() const; |
| 409 | |
| 410 | /** |
| 411 | Iconizes or restores the dialog. Windows only. |
| 412 | |
| 413 | @param iconize |
| 414 | If @true, iconizes the dialog box; if @false, shows and restores it. |
| 415 | |
| 416 | @remarks Note that in Windows, iconization has no effect since dialog |
| 417 | boxes cannot be iconized. However, applications may need to |
| 418 | explicitly restore dialog boxes under Motif which have |
| 419 | user-iconizable frames, and under Windows calling |
| 420 | Iconize(@false) will bring the window to the front, as does |
| 421 | Show(@true). |
| 422 | */ |
| 423 | virtual void Iconize(bool iconize = true); |
| 424 | |
| 425 | /** |
| 426 | Returns @true if the dialog box is iconized. Windows only. |
| 427 | |
| 428 | @remarks Always returns @false under Windows since dialogs cannot be |
| 429 | iconized. |
| 430 | */ |
| 431 | virtual bool IsIconized() const; |
| 432 | |
| 433 | /** |
| 434 | A static function returning @true if layout adaptation is enabled for |
| 435 | all dialogs. |
| 436 | |
| 437 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 438 | */ |
| 439 | static bool IsLayoutAdaptationEnabled(); |
| 440 | |
| 441 | /** |
| 442 | Returns @true if @a id is in the array of identifiers to be regarded as |
| 443 | the main buttons for the non-scrolling area of a dialog. |
| 444 | |
| 445 | @onlyfor{wxmsw} |
| 446 | |
| 447 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 448 | */ |
| 449 | bool IsMainButtonId(wxWindowID id) const; |
| 450 | |
| 451 | /** |
| 452 | Returns @true if the dialog box is modal, @false otherwise. |
| 453 | */ |
| 454 | virtual bool IsModal() const; |
| 455 | |
| 456 | /** |
| 457 | Sets the identifier to be used as OK button. When the button with this |
| 458 | identifier is pressed, the dialog calls wxWindow::Validate() and |
| 459 | wxWindow::TransferDataFromWindow() and, if they both return @true, |
| 460 | closes the dialog with the affirmative id return code. |
| 461 | |
| 462 | Also, when the user presses a hardware OK button on the devices having |
| 463 | one or the special OK button in the PocketPC title bar, an event with |
| 464 | this id is generated. |
| 465 | |
| 466 | By default, the affirmative id is wxID_OK. |
| 467 | |
| 468 | @see GetAffirmativeId(), SetEscapeId() |
| 469 | */ |
| 470 | void SetAffirmativeId(int id); |
| 471 | |
| 472 | /** |
| 473 | Sets the identifier of the button which should work like the standard |
| 474 | "Cancel" button in this dialog. When the button with this id is |
| 475 | clicked, the dialog is closed. Also, when the user presses @c ESC key |
| 476 | in the dialog or closes the dialog using the close button in the title |
| 477 | bar, this is mapped to the click of the button with the specified id. |
| 478 | |
| 479 | By default, the escape id is the special value wxID_ANY meaning that |
| 480 | wxID_CANCEL button is used if it's present in the dialog and otherwise |
| 481 | the button with GetAffirmativeId() is used. Another special value for |
| 482 | @a id is wxID_NONE meaning that @c ESC presses should be ignored. If |
| 483 | any other value is given, it is interpreted as the id of the button to |
| 484 | map the escape key to. |
| 485 | */ |
| 486 | void SetEscapeId(int id); |
| 487 | |
| 488 | /** |
| 489 | Sets the icon for this dialog. |
| 490 | |
| 491 | @param icon |
| 492 | The icon to associate with this dialog. |
| 493 | |
| 494 | @see wxIcon |
| 495 | */ |
| 496 | void SetIcon(const wxIcon& icon); |
| 497 | |
| 498 | /** |
| 499 | Sets the icons for this dialog. |
| 500 | |
| 501 | @param icons |
| 502 | The icons to associate with this dialog. |
| 503 | |
| 504 | @see wxIconBundle |
| 505 | */ |
| 506 | void SetIcons(const wxIconBundle& icons); |
| 507 | |
| 508 | /** |
| 509 | Marks the dialog as having been adapted, usually by making it |
| 510 | scrollable to work with a small display. |
| 511 | |
| 512 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 513 | */ |
| 514 | void SetLayoutAdaptationDone(bool done); |
| 515 | |
| 516 | /** |
| 517 | Sets the aggressiveness of search for buttons and sizers to be in the |
| 518 | non-scrolling part of a layout-adapted dialog. Zero switches off |
| 519 | adaptation, and 3 allows search for standard buttons anywhere in the |
| 520 | dialog. |
| 521 | |
| 522 | @see @ref overview_dialog_autoscrolling (for more on layout adaptation) |
| 523 | */ |
| 524 | void SetLayoutAdaptationLevel(int level); |
| 525 | |
| 526 | /** |
| 527 | Sets the adaptation mode, overriding the global adaptation flag. |
| 528 | |
| 529 | @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling |
| 530 | (for more on layout adaptation) |
| 531 | */ |
| 532 | void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode); |
| 533 | |
| 534 | /** |
| 535 | A static function for setting the current layout adapter object, |
| 536 | returning the old adapter. If you call this, you should delete the old |
| 537 | adapter object. |
| 538 | |
| 539 | @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling |
| 540 | */ |
| 541 | static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter); |
| 542 | |
| 543 | /** |
| 544 | @deprecated This function doesn't work for all ports, just use |
| 545 | ShowModal() to show a modal dialog instead. |
| 546 | |
| 547 | Allows the programmer to specify whether the dialog box is modal |
| 548 | (Show() blocks control until the dialog is hidden) or modeless (control |
| 549 | returns immediately). |
| 550 | |
| 551 | @param flag |
| 552 | If @true, the dialog will be modal, otherwise it will be modeless. |
| 553 | */ |
| 554 | void SetModal(bool flag); |
| 555 | |
| 556 | /** |
| 557 | Sets the return code for this window. |
| 558 | |
| 559 | A return code is normally associated with a modal dialog, where |
| 560 | ShowModal() returns a code to the application. The function EndModal() |
| 561 | calls SetReturnCode(). |
| 562 | |
| 563 | @param retCode |
| 564 | The integer return code, usually a control identifier. |
| 565 | |
| 566 | @see GetReturnCode(), ShowModal(), EndModal() |
| 567 | */ |
| 568 | void SetReturnCode(int retCode); |
| 569 | |
| 570 | /** |
| 571 | Hides or shows the dialog. The preferred way of dismissing a modal |
| 572 | dialog is to use EndModal(). |
| 573 | |
| 574 | @param show |
| 575 | If @true, the dialog box is shown and brought to the front, |
| 576 | otherwise the box is hidden. If @false and the dialog is modal, |
| 577 | control is returned to the calling program. |
| 578 | */ |
| 579 | virtual bool Show(bool show = 1); |
| 580 | |
| 581 | /** |
| 582 | Shows an application-modal dialog. |
| 583 | |
| 584 | Program flow does not return until the dialog has been dismissed with |
| 585 | EndModal(). |
| 586 | |
| 587 | Notice that it is possible to call ShowModal() for a dialog which had |
| 588 | been previously shown with Show(), this allows to make an existing |
| 589 | modeless dialog modal. However ShowModal() can't be called twice |
| 590 | without intervening EndModal() calls. |
| 591 | |
| 592 | Note that this function creates a temporary event loop which takes |
| 593 | precedence over the application's main event loop (see wxEventLoopBase) |
| 594 | and which is destroyed when the dialog is dismissed. |
| 595 | This also results in a call to wxApp::ProcessPendingEvents(). |
| 596 | |
| 597 | @return The value set with SetReturnCode(). |
| 598 | |
| 599 | @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode() |
| 600 | */ |
| 601 | virtual int ShowModal(); |
| 602 | |
| 603 | /** |
| 604 | Shows a dialog modal to the parent top level window only. |
| 605 | |
| 606 | Unlike ShowModal(), dialogs shown with this function only prevent the |
| 607 | user from interacting with their parent frame only but not with the |
| 608 | rest of the application. They also don't block the program execution |
| 609 | but instead return immediately, as Show(), and generate a |
| 610 | wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed. |
| 611 | |
| 612 | Currently this function is only fully implemented in wxOSX ports, under |
| 613 | the other platforms it behaves like ShowModal() (but also sends the |
| 614 | above mentioned event). |
| 615 | |
| 616 | @since 2.9.0 |
| 617 | */ |
| 618 | void ShowWindowModal(); |
| 619 | }; |
| 620 | |
| 621 | |
| 622 | |
| 623 | /** |
| 624 | @class wxDialogLayoutAdapter |
| 625 | |
| 626 | This abstract class is the base for classes that help wxWidgets perform |
| 627 | run-time layout adaptation of dialogs. Principally, this is to cater for |
| 628 | small displays by making part of the dialog scroll, but the application |
| 629 | developer may find other uses for layout adaption. |
| 630 | |
| 631 | By default, there is one instance of wxStandardDialogLayoutAdapter which |
| 632 | can perform adaptation for most custom dialogs and dialogs with book |
| 633 | controls such as wxPropertySheetDialog. |
| 634 | |
| 635 | @library{wxcore} |
| 636 | @category{winlayout} |
| 637 | |
| 638 | @see @ref overview_dialog_autoscrolling |
| 639 | */ |
| 640 | class wxDialogLayoutAdapter |
| 641 | { |
| 642 | public: |
| 643 | /** |
| 644 | Default constructor. |
| 645 | */ |
| 646 | wxDialogLayoutAdapter(); |
| 647 | |
| 648 | /** |
| 649 | Override this to returns @true if adaptation can and should be done. |
| 650 | */ |
| 651 | virtual bool CanDoLayoutAdaptation(wxDialog* dialog) = 0; |
| 652 | |
| 653 | /** |
| 654 | Override this to perform layout adaptation, such as making parts of the |
| 655 | dialog scroll and resizing the dialog to fit the display. Normally this |
| 656 | function will be called just before the dialog is shown. |
| 657 | */ |
| 658 | virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0; |
| 659 | }; |
| 660 | |
| 661 | |
| 662 | class wxWindowModalDialogEvent : public wxCommandEvent |
| 663 | { |
| 664 | public: |
| 665 | wxWindowModalDialogEvent (wxEventType commandType = wxEVT_NULL, int id = 0); |
| 666 | |
| 667 | wxDialog *GetDialog() const; |
| 668 | int GetReturnCode() const; |
| 669 | virtual wxEvent *Clone() const; |
| 670 | }; |