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