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