| 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 | */ |