docs/doxygen/overviews/dialog.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dialog.h
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10
  11 @page overview_dialog wxDialog Overview
  12
  13 @tableofcontents
  14
  15 Classes: wxDialog, wxDialogLayoutAdapter
  16
  17 A dialog box is similar to a panel, in that it is a window which can be used
  18 for placing controls, with the following exceptions:
  19
  20 @li A surrounding frame is implicitly created.
  21 @li Extra functionality is automatically given to the dialog box, such as
  22     tabbing between items (currently Windows only).
  23 @li If the dialog box is @e modal, the calling program is blocked until the
  24     dialog box is dismissed.
  25
  26 For a set of dialog convenience functions, including file selection, see
  27 @ref group_funcmacro_dialog.
  28
  29 See also wxTopLevelWindow and wxWindow for inherited member functions.
  30 Validation of data in controls is covered in @ref overview_validator.
  31
  32
  33
  34 @section overview_dialog_autoscrolling Automatic Scrolled Dialogs
  35
  36 As an ever greater variety of mobile hardware comes to market, it becomes more
  37 imperative for wxWidgets applications to adapt to these platforms without
  38 putting too much burden on the programmer. One area where wxWidgets can help is
  39 in adapting dialogs for the lower resolution screens that inevitably accompany
  40 a smaller form factor. wxDialog therefore supplies a global
  41 wxDialogLayoutAdapter class that implements automatic scrolling adaptation for
  42 most sizer-based custom dialogs.
  43
  44 Many applications should therefore be able to adapt to small displays with
  45 little or no work, as far as dialogs are concerned. By default this adaptation
  46 is off. To switch scrolling adaptation on globally in your application, call
  47 the static function wxDialog::EnableLayoutAdaptation passing @true. You can
  48 also adjust adaptation on a per-dialog basis by calling
  49 wxDialog::SetLayoutAdaptationMode with one of
  50 @c wxDIALOG_ADAPTATION_MODE_DEFAULT (use the global setting),
  51 @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
  52
  53 The last two modes override the global adaptation setting. With adaptation
  54 enabled, if the display size is too small for the dialog, wxWidgets (or rather
  55 the standard adapter class wxStandardDialogLayoutAdapter) will make part of the
  56 dialog scrolling, leaving standard buttons in a non-scrolling part at the
  57 bottom of the dialog. This is done as follows, in
  58 wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or
  59 wxDialog::ShowModal:
  60
  61 @li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
  62     the pages are made scrollable and no other adaptation is done.
  63 @li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the
  64     non-scrolling part.
  65 @li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one
  66     or more standard buttons, with identifiers such as @c wxID_OK and
  67     @c wxID_CANCEL.
  68 @li If that search failed too, wxWidgets finds 'loose' standard buttons (in any
  69     kind of sizer) and adds them to a wxStdDialogButtonSizer. If no standard
  70     buttons were found, the whole dialog content will scroll.
  71 @li All the children apart from standard buttons are reparented onto a new
  72     ::wxScrolledWindow object, using the old top-level sizer for the scrolled
  73     window and creating a new top-level sizer to lay out the scrolled window
  74     and standard button sizer.
  75
  76
  77 @subsection overview_dialog_autoscrolling_custom Customising Scrolling Adaptation
  78
  79 In addition to switching adaptation on and off globally and per dialog, you can
  80 choose how aggressively wxWidgets will search for standard buttons by setting
  81 wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above
  82 will be performed but by setting the level to 1, for example, you can choose to
  83 only look for wxStdDialogButtonSizer.
  84
  85 You can use wxDialog::AddMainButtonId to add identifiers for buttons that
  86 should also be treated as standard buttons for the non-scrolling area.
  87
  88 You can derive your own class from wxDialogLayoutAdapter or
  89 wxStandardDialogLayoutAdapter and call wxDialog::SetLayoutAdapter, deleting the
  90 old object that this function returns. Override the functions
  91 CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation
  92 applicability and perform the adaptation.
  93
  94 You can also override wxDialog::CanDoLayoutAdaptation and
  95 wxDialog::DoLayoutAdaptation in a class derived from wxDialog.
  96
  97
  98 @subsection overview_dialog_autoscrolling_fail Where Scrolling Adaptation May Fail
  99
 100 Because adaptation rearranges your sizer and window hierarchy, it is not
 101 fool-proof, and may fail in the following situations:
 102
 103 @li The dialog doesn't use sizers.
 104 @li The dialog implementation makes assumptions about the window hierarchy,
 105     for example getting the parent of a control and casting to the dialog class.
 106 @li The dialog does custom painting and/or event handling not handled by the scrolled window.
 107     If this problem can be solved globally, you can derive a new adapter class from
 108     wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return
 109     an instance of your own class.
 110 @li The dialog has unusual layout, for example a vertical sizer containing a mixture of
 111     standard buttons and other controls.
 112 @li The dialog makes assumptions about the sizer hierarchy, for example to show or hide
 113     children of the top-level sizer. However, the original sizer hierarchy will still hold
 114     until Show or ShowModal is called.
 115
 116 You can help make sure that your dialogs will continue to function after
 117 adaptation by:
 118
 119 @li avoiding the above situations and assumptions;
 120 @li using wxStdDialogButtonSizer;
 121 @li only making assumptions about hierarchy immediately after the dialog is created;
 122 @li using an intermediate sizer under the main sizer, a @false top-level sizer that
 123     can be relied on to exist for the purposes of manipulating child sizers and windows;
 124 @li overriding wxDialog::GetContentWindow to return a book control if your dialog implements
 125     pages: wxWidgets will then only make the pages scrollable.
 126
 127
 128 @subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard
 129
 130 Adaptation for wxPropertySheetDialog is always done by simply making the pages
 131 scrollable, since wxDialog::GetContentWindow returns the dialog's book control
 132 and this is handled by the standard layout adapter.
 133
 134 wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions
 135 rather than the global adapter: again, only the wizard pages are made
 136 scrollable.
 137
 138 */