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 #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        Splits text up at newlines and places the lines into wxStaticText
 288        objects in a vertical wxBoxSizer.
 289     */
 290     wxSizer *CreateTextSizer( const wxString& message );
 291
 292     /**
 293         Performs layout adaptation, usually if the dialog is too large to fit
 294         on the display.
 295
 296         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 297     */
 298     virtual bool DoLayoutAdaptation();
 299
 300     /**
 301         This function is called when the titlebar OK button is pressed
 302         (PocketPC only). A command event for the identifier returned by
 303         GetAffirmativeId() is sent by default. You can override this function.
 304         If the function returns @false, wxWidgets will call Close() for the
 305         dialog.
 306
 307         @onlyfor{wxmsw}
 308     */
 309     virtual bool DoOK();
 310
 311     /**
 312         A static function enabling or disabling layout adaptation for all
 313         dialogs.
 314
 315         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 316     */
 317     static void EnableLayoutAdaptation(bool enable);
 318
 319     /**
 320         Ends a modal dialog, passing a value to be returned from the
 321         ShowModal() invocation.
 322
 323         @param retCode
 324             The value that should be returned by ShowModal.
 325
 326         @see ShowModal(), GetReturnCode(), SetReturnCode()
 327     */
 328     virtual void EndModal(int retCode);
 329
 330     /**
 331         Gets the identifier of the button which works like standard OK button
 332         in this dialog.
 333
 334         @see SetAffirmativeId()
 335     */
 336     int GetAffirmativeId() const;
 337
 338     /**
 339         Override this to return a window containing the main content of the
 340         dialog. This is particularly useful when the dialog implements pages,
 341         such as wxPropertySheetDialog, and allows the
 342         @ref overview_dialog "layout adaptation code" to know that only the
 343         pages need to be made scrollable.
 344     */
 345     virtual wxWindow* GetContentWindow() const;
 346
 347     /**
 348         Gets the identifier of the button to map presses of @c ESC button to.
 349
 350         @see SetEscapeId()
 351     */
 352     int GetEscapeId() const;
 353
 354     /**
 355         Returns @true if the dialog has been adapted, usually by making it
 356         scrollable to work with a small display.
 357
 358         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 359     */
 360     bool GetLayoutAdaptationDone() const;
 361
 362     /**
 363         Gets a value representing the aggressiveness of search for buttons and
 364         sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
 365         switches off adaptation, and 3 allows search for standard buttons
 366         anywhere in the dialog.
 367
 368         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 369     */
 370     int GetLayoutAdaptationLevel() const;
 371
 372     /**
 373         Gets the adaptation mode, overriding the global adaptation flag.
 374
 375         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 376     */
 377     wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const;
 378
 379     /**
 380         A static function getting the current layout adapter object.
 381
 382         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 383     */
 384     static wxDialogLayoutAdapter* GetLayoutAdapter();
 385
 386     /**
 387         Returns an array of identifiers to be regarded as the main buttons for
 388         the non-scrolling area of a dialog.
 389
 390         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 391     */
 392     wxArrayInt& GetMainButtonIds();
 393
 394     /**
 395         Gets the return code for this window.
 396
 397         @remarks A return code is normally associated with a modal dialog,
 398                  where ShowModal() returns a code to the application.
 399
 400         @see SetReturnCode(), ShowModal(), EndModal()
 401     */
 402     int GetReturnCode() const;
 403
 404     /**
 405         On PocketPC, a dialog is automatically provided with an empty toolbar.
 406         This function allows you to access the toolbar and add tools to it.
 407         Removing tools and adding arbitrary controls are not currently
 408         supported.
 409
 410         This function is not available on any other platform.
 411
 412         @onlyfor{wxmsw}
 413     */
 414     wxToolBar* GetToolBar() const;
 415
 416     /**
 417         Iconizes or restores the dialog. Windows only.
 418
 419         @param iconize
 420             If @true, iconizes the dialog box; if @false, shows and restores it.
 421
 422         @remarks Note that in Windows, iconization has no effect since dialog
 423                  boxes cannot be iconized. However, applications may need to
 424                  explicitly restore dialog boxes under Motif which have
 425                  user-iconizable frames, and under Windows calling
 426                  Iconize(@false) will bring the window to the front, as does
 427                  Show(@true).
 428     */
 429     virtual void Iconize(bool iconize = true);
 430
 431     /**
 432         Returns @true if the dialog box is iconized. Windows only.
 433
 434         @remarks Always returns @false under Windows since dialogs cannot be
 435                  iconized.
 436     */
 437     virtual bool IsIconized() const;
 438
 439     /**
 440         A static function returning @true if layout adaptation is enabled for
 441         all dialogs.
 442
 443         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 444     */
 445     static bool IsLayoutAdaptationEnabled();
 446
 447     /**
 448         Returns @true if @a id is in the array of identifiers to be regarded as
 449         the main buttons for the non-scrolling area of a dialog.
 450
 451         @onlyfor{wxmsw}
 452
 453         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 454     */
 455     bool IsMainButtonId(wxWindowID id) const;
 456
 457     /**
 458         Returns @true if the dialog box is modal, @false otherwise.
 459     */
 460     virtual bool IsModal() const;
 461
 462     /**
 463         Sets the identifier to be used as OK button. When the button with this
 464         identifier is pressed, the dialog calls wxWindow::Validate() and
 465         wxWindow::TransferDataFromWindow() and, if they both return @true,
 466         closes the dialog with the affirmative id return code.
 467
 468         Also, when the user presses a hardware OK button on the devices having
 469         one or the special OK button in the PocketPC title bar, an event with
 470         this id is generated.
 471
 472         By default, the affirmative id is wxID_OK.
 473
 474         @see GetAffirmativeId(), SetEscapeId()
 475     */
 476     void SetAffirmativeId(int id);
 477
 478     /**
 479         Sets the identifier of the button which should work like the standard
 480         "Cancel" button in this dialog. When the button with this id is
 481         clicked, the dialog is closed. Also, when the user presses @c ESC key
 482         in the dialog or closes the dialog using the close button in the title
 483         bar, this is mapped to the click of the button with the specified id.
 484
 485         By default, the escape id is the special value wxID_ANY meaning that
 486         wxID_CANCEL button is used if it's present in the dialog and otherwise
 487         the button with GetAffirmativeId() is used. Another special value for
 488         @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
 489         any other value is given, it is interpreted as the id of the button to
 490         map the escape key to.
 491     */
 492     void SetEscapeId(int id);
 493
 494     /**
 495         Sets the icon for this dialog.
 496
 497         @param icon
 498             The icon to associate with this dialog.
 499
 500         @see wxIcon
 501     */
 502     void SetIcon(const wxIcon& icon);
 503
 504     /**
 505         Sets the icons for this dialog.
 506
 507         @param icons
 508             The icons to associate with this dialog.
 509
 510         @see wxIconBundle
 511     */
 512     void SetIcons(const wxIconBundle& icons);
 513
 514     /**
 515         Marks the dialog as having been adapted, usually by making it
 516         scrollable to work with a small display.
 517
 518         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 519     */
 520     void SetLayoutAdaptationDone(bool done);
 521
 522     /**
 523         Sets the aggressiveness of search for buttons and sizers to be in the
 524         non-scrolling part of a layout-adapted dialog. Zero switches off
 525         adaptation, and 3 allows search for standard buttons anywhere in the
 526         dialog.
 527
 528         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 529     */
 530     void SetLayoutAdaptationLevel(int level);
 531
 532     /**
 533         Sets the adaptation mode, overriding the global adaptation flag.
 534
 535         @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
 536              (for more on layout adaptation)
 537     */
 538     void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode);
 539
 540     /**
 541         A static function for setting the current layout adapter object,
 542         returning the old adapter. If you call this, you should delete the old
 543         adapter object.
 544
 545         @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling
 546     */
 547     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 548
 549     /**
 550         @deprecated This function doesn't work for all ports, just use
 551                     ShowModal() to show a modal dialog instead.
 552
 553         Allows the programmer to specify whether the dialog box is modal
 554         (Show() blocks control until the dialog is hidden) or modeless (control
 555         returns immediately).
 556
 557         @param flag
 558             If @true, the dialog will be modal, otherwise it will be modeless.
 559     */
 560     void SetModal(bool flag);
 561
 562     /**
 563         Sets the return code for this window.
 564
 565         A return code is normally associated with a modal dialog, where
 566         ShowModal() returns a code to the application. The function EndModal()
 567         calls SetReturnCode().
 568
 569         @param retCode
 570             The integer return code, usually a control identifier.
 571
 572         @see GetReturnCode(), ShowModal(), EndModal()
 573     */
 574     void SetReturnCode(int retCode);
 575
 576     /**
 577         Hides or shows the dialog. The preferred way of dismissing a modal
 578         dialog is to use EndModal().
 579
 580         @param show
 581             If @true, the dialog box is shown and brought to the front,
 582             otherwise the box is hidden. If @false and the dialog is modal,
 583             control is returned to the calling program.
 584     */
 585     virtual bool Show(bool show = 1);
 586
 587     /**
 588         Shows an application-modal dialog.
 589
 590         Program flow does not return until the dialog has been dismissed with
 591         EndModal().
 592
 593         Notice that it is possible to call ShowModal() for a dialog which had
 594         been previously shown with Show(), this allows to make an existing
 595         modeless dialog modal. However ShowModal() can't be called twice
 596         without intervening EndModal() calls.
 597
 598         Note that this function creates a temporary event loop which takes
 599         precedence over the application's main event loop (see wxEventLoopBase)
 600         and which is destroyed when the dialog is dismissed.
 601         This also results in a call to wxApp::ProcessPendingEvents().
 602
 603         @return The value set with SetReturnCode().
 604
 605         @see ShowWindowModal(), EndModal(), GetReturnCode(), SetReturnCode()
 606     */
 607     virtual int ShowModal();
 608
 609     /**
 610         Shows a dialog modal to the parent top level window only.
 611
 612         Unlike ShowModal(), dialogs shown with this function only prevent the
 613         user from interacting with their parent frame only but not with the
 614         rest of the application. They also don't block the program execution
 615         but instead return immediately, as Show(), and generate a
 616         wxEVT_WINDOW_MODAL_DIALOG_CLOSED event later when the dialog is closed.
 617
 618         Currently this function is only fully implemented in wxOSX ports, under
 619         the other platforms it behaves like ShowModal() (but also sends the
 620         above mentioned event).
 621
 622         @since 2.9.0
 623      */
 624     void ShowWindowModal();
 625 };
 626
 627
 628
 629 /**
 630     @class wxDialogLayoutAdapter
 631
 632     This abstract class is the base for classes that help wxWidgets perform
 633     run-time layout adaptation of dialogs. Principally, this is to cater for
 634     small displays by making part of the dialog scroll, but the application
 635     developer may find other uses for layout adaption.
 636
 637     By default, there is one instance of wxStandardDialogLayoutAdapter which
 638     can perform adaptation for most custom dialogs and dialogs with book
 639     controls such as wxPropertySheetDialog.
 640
 641     @library{wxcore}
 642     @category{winlayout}
 643
 644     @see @ref overview_dialog_autoscrolling
 645 */
 646 class wxDialogLayoutAdapter
 647 {
 648 public:
 649     /**
 650         Default constructor.
 651     */
 652     wxDialogLayoutAdapter();
 653
 654     /**
 655         Override this to returns @true if adaptation can and should be done.
 656     */
 657     virtual bool CanDoLayoutAdaptation(wxDialog* dialog) = 0;
 658
 659     /**
 660         Override this to perform layout adaptation, such as making parts of the
 661         dialog scroll and resizing the dialog to fit the display. Normally this
 662         function will be called just before the dialog is shown.
 663     */
 664     virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0;
 665 };
 666
 667
 668 class wxWindowModalDialogEvent  : public wxCommandEvent
 669 {
 670 public:
 671     wxWindowModalDialogEvent (wxEventType commandType = wxEVT_NULL, int id = 0);
 672
 673     wxDialog *GetDialog() const;
 674     int GetReturnCode() const;
 675     virtual wxEvent *Clone() const;
 676 };