interface/wx/dialog.h

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