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