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