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