interface/wx/dialog.h

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