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