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