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