interface/dialog.h

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