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
 129     @beginEventTable{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     @endEventTable
 137
 138     @library{wxcore}
 139     @category{cmndlg}
 140
 141     @see @ref overview_dialog, wxFrame, @ref overview_validator
 142 */
 143 class wxDialog : public wxTopLevelWindow
 144 {
 145 public:
 146     /**
 147         Default constructor.
 148     */
 149     wxDialog();
 150     /**
 151         Constructor.
 152
 153         @param parent
 154             Can be @NULL, a frame or another dialog box.
 155         @param id
 156             An identifier for the dialog. A value of -1 is taken to mean a
 157             default.
 158         @param title
 159             The title of the dialog.
 160         @param pos
 161             The dialog position. The value wxDefaultPosition indicates a
 162             default position, chosen by either the windowing system or
 163             wxWidgets, depending on platform.
 164         @param size
 165             The dialog size. The value wxDefaultSize indicates a default size,
 166             chosen by either the windowing system or wxWidgets, depending on
 167             platform.
 168         @param style
 169             The window style.
 170         @param name
 171             Used to associate a name with the window, allowing the application
 172             user to set Motif resource values for individual dialog boxes.
 173
 174         @see Create()
 175     */
 176     wxDialog(wxWindow* parent, wxWindowID id, const wxString& title,
 177              const wxPoint& pos = wxDefaultPosition,
 178              const wxSize& size = wxDefaultSize,
 179              long style = wxDEFAULT_DIALOG_STYLE,
 180              const wxString& name = wxDialogNameStr);
 181
 182     /**
 183         Destructor.
 184
 185         Deletes any child windows before deleting the physical window.
 186
 187         See @ref overview_windowdeletion for more info.
 188     */
 189     virtual ~wxDialog();
 190
 191     /**
 192         Adds an identifier to be regarded as a main button for the
 193         non-scrolling area of a dialog.
 194
 195         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 196     */
 197     void AddMainButtonId(wxWindowID id);
 198
 199     /**
 200         Returns @true if this dialog can and should perform layout adaptation
 201         using DoLayoutAdaptation(), usually if the dialog is too large to fit
 202         on the display.
 203
 204         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 205     */
 206     virtual bool CanDoLayoutAdaptation();
 207
 208     /**
 209         Centres the dialog box on the display.
 210
 211         @param direction
 212             May be wxHORIZONTAL, wxVERTICAL or wxBOTH.
 213     */
 214     void Centre(int direction = wxBOTH);
 215
 216     /**
 217         Used for two-step dialog box construction.
 218
 219         @see wxDialog()
 220     */
 221     bool Create(wxWindow* parent, wxWindowID id, const wxString& title,
 222                 const wxPoint& pos = wxDefaultPosition,
 223                 const wxSize& size = wxDefaultSize,
 224                 long style = wxDEFAULT_DIALOG_STYLE,
 225                 const wxString& name = wxDialogNameStr);
 226
 227     /**
 228         Creates a sizer with standard buttons. @a flags is a bit list of the
 229         following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY, wxCLOSE, wxHELP,
 230         wxNO_DEFAULT.
 231
 232         The sizer lays out the buttons in a manner appropriate to the platform.
 233
 234         This function uses CreateStdDialogButtonSizer() internally for most
 235         platforms but doesn't create the sizer at all for the platforms with
 236         hardware buttons (such as smartphones) for which it sets up the
 237         hardware buttons appropriately and returns @NULL, so don't forget to
 238         test that the return value is valid before using it.
 239     */
 240     wxSizer* CreateButtonSizer(long flags);
 241
 242     /**
 243         Creates a sizer with standard buttons using CreateButtonSizer()
 244         separated from the rest of the dialog contents by a horizontal
 245         wxStaticLine.
 246
 247         @note Just like CreateButtonSizer(), this function may return @NULL if
 248               no buttons were created.
 249     */
 250     wxSizer* CreateSeparatedButtonSizer(long flags);
 251
 252     /**
 253         Creates a wxStdDialogButtonSizer with standard buttons. @a flags is a
 254         bit list of the following flags: wxOK, wxCANCEL, wxYES, wxNO, wxAPPLY,
 255         wxCLOSE, wxHELP, wxNO_DEFAULT.
 256
 257         The sizer lays out the buttons in a manner appropriate to the platform.
 258     */
 259     wxStdDialogButtonSizer* CreateStdDialogButtonSizer(long flags);
 260
 261     /**
 262         Performs layout adaptation, usually if the dialog is too large to fit
 263         on the display.
 264
 265         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 266     */
 267     virtual bool DoLayoutAdaptation();
 268
 269     /**
 270         This function is called when the titlebar OK button is pressed
 271         (PocketPC only). A command event for the identifier returned by
 272         GetAffirmativeId() is sent by default. You can override this function.
 273         If the function returns @false, wxWidgets will call Close() for the
 274         dialog.
 275
 276         @onlyfor{wxmsw}
 277     */
 278     virtual bool DoOK();
 279
 280     /**
 281         A static function enabling or disabling layout adaptation for all
 282         dialogs.
 283
 284         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 285     */
 286     static void EnableLayoutAdaptation(bool enable);
 287
 288     /**
 289         Ends a modal dialog, passing a value to be returned from the
 290         ShowModal() invocation.
 291
 292         @param retCode
 293             The value that should be returned by ShowModal.
 294
 295         @see ShowModal(), GetReturnCode(), SetReturnCode()
 296     */
 297     virtual void EndModal(int retCode);
 298
 299     /**
 300         Gets the identifier of the button which works like standard OK button
 301         in this dialog.
 302
 303         @see SetAffirmativeId()
 304     */
 305     int GetAffirmativeId() const;
 306
 307     /**
 308         Override this to return a window containing the main content of the
 309         dialog. This is particularly useful when the dialog implements pages,
 310         such as wxPropertySheetDialog, and allows the
 311         @ref overview_dialog "layout adaptation code" to know that only the
 312         pages need to be made scrollable.
 313     */
 314     virtual wxWindow* GetContentWindow() const;
 315
 316     /**
 317         Gets the identifier of the button to map presses of @c ESC button to.
 318
 319         @see SetEscapeId()
 320     */
 321     int GetEscapeId() const;
 322
 323     /**
 324         Returns @true if the dialog has been adapted, usually by making it
 325         scrollable to work with a small display.
 326
 327         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 328     */
 329     bool GetLayoutAdaptationDone() const;
 330
 331     /**
 332         Gets a value representing the aggressiveness of search for buttons and
 333         sizers to be in the non-scrolling part of a layout-adapted dialog. Zero
 334         switches off adaptation, and 3 allows search for standard buttons
 335         anywhere in the dialog.
 336
 337         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 338     */
 339     int GetLayoutAdaptationLevel() const;
 340
 341     /**
 342         Gets the adaptation mode, overriding the global adaptation flag.
 343
 344         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 345     */
 346     wxDialogLayoutAdaptationMode GetLayoutAdaptationMode() const;
 347
 348     /**
 349         A static function getting the current layout adapter object.
 350
 351         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 352     */
 353     static wxDialogLayoutAdapter* GetLayoutAdapter();
 354
 355     /**
 356         Returns an array of identifiers to be regarded as the main buttons for
 357         the non-scrolling area of a dialog.
 358
 359         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 360     */
 361     wxArrayInt& GetMainButtonIds();
 362
 363     /**
 364         Gets the return code for this window.
 365
 366         @remarks A return code is normally associated with a modal dialog,
 367                  where ShowModal() returns a code to the application.
 368
 369         @see SetReturnCode(), ShowModal(), EndModal()
 370     */
 371     int GetReturnCode() const;
 372
 373     /**
 374         On PocketPC, a dialog is automatically provided with an empty toolbar.
 375         This function allows you to access the toolbar and add tools to it.
 376         Removing tools and adding arbitrary controls are not currently
 377         supported.
 378
 379         This function is not available on any other platform.
 380
 381         @onlyfor{wxmsw}
 382     */
 383     wxToolBar* GetToolBar() const;
 384
 385     /**
 386         Iconizes or restores the dialog. Windows only.
 387
 388         @param iconize
 389             If @true, iconizes the dialog box; if @false, shows and restores it.
 390
 391         @remarks Note that in Windows, iconization has no effect since dialog
 392                  boxes cannot be iconized. However, applications may need to
 393                  explicitly restore dialog boxes under Motif which have
 394                  user-iconizable frames, and under Windows calling
 395                  Iconize(@false) will bring the window to the front, as does
 396                  Show(@true).
 397     */
 398     virtual void Iconize(bool iconize = true);
 399
 400     /**
 401         Returns @true if the dialog box is iconized. Windows only.
 402
 403         @remarks Always returns @false under Windows since dialogs cannot be
 404                  iconized.
 405     */
 406     virtual bool IsIconized() const;
 407
 408     /**
 409         A static function returning @true if layout adaptation is enabled for
 410         all dialogs.
 411
 412         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 413     */
 414     static bool IsLayoutAdaptationEnabled();
 415
 416     /**
 417         Returns @true if @a id is in the array of identifiers to be regarded as
 418         the main buttons for the non-scrolling area of a dialog.
 419
 420         @onlyfor{wxmsw}
 421
 422         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 423     */
 424     bool IsMainButtonId(wxWindowID id) const;
 425
 426     /**
 427         Returns @true if the dialog box is modal, @false otherwise.
 428     */
 429     virtual bool IsModal() const;
 430
 431     /**
 432         The default handler for wxEVT_SYS_COLOUR_CHANGED.
 433
 434         @param event
 435             The colour change event.
 436
 437         @remarks Changes the dialog's colour to conform to the current settings
 438                  (Windows only). Add an event table entry for your dialog class
 439                  if you wish the behaviour to be different (such as keeping a
 440                  user-defined background colour). If you do override this
 441                  function, call wxEvent::Skip() to propagate the notification
 442                  to child windows and controls.
 443
 444         @see wxSysColourChangedEvent
 445     */
 446     void OnSysColourChanged(wxSysColourChangedEvent& event);
 447
 448     /**
 449         Sets the identifier to be used as OK button. When the button with this
 450         identifier is pressed, the dialog calls wxWindow::Validate() and
 451         wxWindow::TransferDataFromWindow() and, if they both return @true,
 452         closes the dialog with wxID_OK return code.
 453
 454         Also, when the user presses a hardware OK button on the devices having
 455         one or the special OK button in the PocketPC title bar, an event with
 456         this id is generated.
 457
 458         By default, the affirmative id is wxID_OK.
 459
 460         @see GetAffirmativeId(), SetEscapeId()
 461     */
 462     void SetAffirmativeId(int id);
 463
 464     /**
 465         Sets the identifier of the button which should work like the standard
 466         "Cancel" button in this dialog. When the button with this id is
 467         clicked, the dialog is closed. Also, when the user presses @c ESC key
 468         in the dialog or closes the dialog using the close button in the title
 469         bar, this is mapped to the click of the button with the specified id.
 470
 471         By default, the escape id is the special value wxID_ANY meaning that
 472         wxID_CANCEL button is used if it's present in the dialog and otherwise
 473         the button with GetAffirmativeId() is used. Another special value for
 474         @a id is wxID_NONE meaning that @c ESC presses should be ignored. If
 475         any other value is given, it is interpreted as the id of the button to
 476         map the escape key to.
 477     */
 478     void SetEscapeId(int id);
 479
 480     /**
 481         Sets the icon for this dialog.
 482
 483         @param icon
 484             The icon to associate with this dialog.
 485
 486         @see wxIcon
 487     */
 488     void SetIcon(const wxIcon& icon);
 489
 490     /**
 491         Sets the icons for this dialog.
 492
 493         @param icons
 494             The icons to associate with this dialog.
 495
 496         @see wxIconBundle
 497     */
 498     void SetIcons(const wxIconBundle& icons);
 499
 500     /**
 501         Marks the dialog as having been adapted, usually by making it
 502         scrollable to work with a small display.
 503
 504         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 505     */
 506     void SetLayoutAdaptationDone(bool done);
 507
 508     /**
 509         Sets the aggressiveness of search for buttons and sizers to be in the
 510         non-scrolling part of a layout-adapted dialog. Zero switches off
 511         adaptation, and 3 allows search for standard buttons anywhere in the
 512         dialog.
 513
 514         @see @ref overview_dialog_autoscrolling (for more on layout adaptation)
 515     */
 516     void SetLayoutAdaptationLevel(int level);
 517
 518     /**
 519         Sets the adaptation mode, overriding the global adaptation flag.
 520
 521         @see wxDialogLayoutAdaptationMode, @ref overview_dialog_autoscrolling
 522              (for more on layout adaptation)
 523     */
 524     void SetLayoutAdaptationMode(wxDialogLayoutAdaptationMode mode);
 525
 526     /**
 527         A static function for setting the current layout adapter object,
 528         returning the old adapter. If you call this, you should delete the old
 529         adapter object.
 530
 531         @see wxDialogLayoutAdapter, @ref overview_dialog_autoscrolling
 532     */
 533     static wxDialogLayoutAdapter* SetLayoutAdapter(wxDialogLayoutAdapter* adapter);
 534
 535     /**
 536         @deprecated This function doesn't work for all ports, just use
 537                     ShowModal() to show a modal dialog instead.
 538
 539         Allows the programmer to specify whether the dialog box is modal
 540         (Show() blocks control until the dialog is hidden) or modeless (control
 541         returns immediately).
 542
 543         @param flag
 544             If @true, the dialog will be modal, otherwise it will be modeless.
 545     */
 546     void SetModal(bool flag);
 547
 548     /**
 549         Sets the return code for this window.
 550
 551         A return code is normally associated with a modal dialog, where
 552         ShowModal() returns a code to the application. The function EndModal()
 553         calls SetReturnCode().
 554
 555         @param retCode
 556             The integer return code, usually a control identifier.
 557
 558         @see GetReturnCode(), ShowModal(), EndModal()
 559     */
 560     void SetReturnCode(int retCode);
 561
 562     /**
 563         Hides or shows the dialog. The preferred way of dismissing a modal
 564         dialog is to use EndModal().
 565
 566         @param show
 567             If @true, the dialog box is shown and brought to the front,
 568             otherwise the box is hidden. If @false and the dialog is modal,
 569             control is returned to the calling program.
 570     */
 571     virtual bool Show(bool show = 1);
 572
 573     /**
 574         Shows a modal dialog.
 575
 576         Program flow does not return until the dialog has been dismissed with
 577         EndModal().
 578
 579         Notice that it is possible to call ShowModal() for a dialog which had
 580         been previously shown with Show(), this allows to make an existing
 581         modeless dialog modal. However ShowModal() can't be called twice
 582         without intervening EndModal() calls.
 583
 584         @return The value set with SetReturnCode().
 585
 586         @see EndModal(), GetReturnCode(), SetReturnCode()
 587     */
 588     virtual int ShowModal();
 589 };
 590
 591
 592
 593 /**
 594     @class wxDialogLayoutAdapter
 595
 596     This abstract class is the base for classes that help wxWidgets peform
 597     run-time layout adaptation of dialogs. Principally, this is to cater for
 598     small displays by making part of the dialog scroll, but the application
 599     developer may find other uses for layout adaption.
 600
 601     By default, there is one instance of wxStandardDialogLayoutAdapter which
 602     can perform adaptation for most custom dialogs and dialogs with book
 603     controls such as wxPropertySheetDialog.
 604
 605     @library{wxcore}
 606     @category{winlayout}
 607
 608     @see @ref overview_dialog_autoscrolling
 609 */
 610 class wxDialogLayoutAdapter
 611 {
 612 public:
 613     /**
 614         Default constructor.
 615     */
 616     wxDialogLayoutAdapter();
 617
 618     /**
 619         Override this to returns @true if adaptation can and should be done.
 620     */
 621     virtual bool CanDoLayoutAdaptation(wxDialog* dialog) = 0;
 622
 623     /**
 624         Override this to perform layout adaptation, such as making parts of the
 625         dialog scroll and resizing the dialog to fit the display. Normally this
 626         function will be called just before the dialog is shown.
 627     */
 628     virtual bool DoLayoutAdaptation(wxDialog* dialog) = 0;
 629 };
 630