Fixed appearance images to use Doxygen @image command (Doxygen will now copy files automatically), and cleaned up some more overviews.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@72871 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
@@ -10,92 +10,95 @@
|
||||
|
||||
@page overview_dialog wxDialog Overview
|
||||
|
||||
@tableofcontents
|
||||
|
||||
Classes: wxDialog, wxDialogLayoutAdapter
|
||||
|
||||
A dialog box is similar to a panel, in that it is a window which can
|
||||
be used for placing controls, with the following exceptions:
|
||||
A dialog box is similar to a panel, in that it is a window which can be used
|
||||
for placing controls, with the following exceptions:
|
||||
|
||||
@li A surrounding frame is implicitly created.
|
||||
@li Extra functionality is automatically given to the dialog box,
|
||||
such as tabbing between items (currently Windows only).
|
||||
@li If the dialog box is @e modal, the calling program is blocked
|
||||
until the dialog box is dismissed.
|
||||
@li Extra functionality is automatically given to the dialog box, such as
|
||||
tabbing between items (currently Windows only).
|
||||
@li If the dialog box is @e modal, the calling program is blocked until the
|
||||
dialog box is dismissed.
|
||||
|
||||
For a set of dialog convenience functions, including file selection, see
|
||||
@ref group_funcmacro_dialog.
|
||||
|
||||
See also wxTopLevelWindow and wxWindow for inherited
|
||||
member functions. Validation of data in controls is covered in @ref overview_validator.
|
||||
|
||||
|
||||
@li @ref overview_dialog_autoscrolling
|
||||
|
||||
|
||||
<hr>
|
||||
See also wxTopLevelWindow and wxWindow for inherited member functions.
|
||||
Validation of data in controls is covered in @ref overview_validator.
|
||||
|
||||
|
||||
|
||||
@section overview_dialog_autoscrolling Automatic scrolling dialogs
|
||||
@section overview_dialog_autoscrolling Automatic Scrolled Dialogs
|
||||
|
||||
As an ever greater variety of mobile hardware comes to market, it becomes more
|
||||
imperative for wxWidgets applications to adapt to these platforms without putting
|
||||
too much burden on the programmer. One area where wxWidgets can help is in adapting
|
||||
dialogs for the lower resolution screens that inevitably accompany a smaller form factor.
|
||||
wxDialog therefore supplies a global wxDialogLayoutAdapter class that implements
|
||||
automatic scrolling adaptation for most sizer-based custom dialogs.
|
||||
imperative for wxWidgets applications to adapt to these platforms without
|
||||
putting too much burden on the programmer. One area where wxWidgets can help is
|
||||
in adapting dialogs for the lower resolution screens that inevitably accompany
|
||||
a smaller form factor. wxDialog therefore supplies a global
|
||||
wxDialogLayoutAdapter class that implements automatic scrolling adaptation for
|
||||
most sizer-based custom dialogs.
|
||||
|
||||
Many applications should therefore be able to adapt to small displays with little
|
||||
or no work, as far as dialogs are concerned.
|
||||
By default this adaptation is off. To switch scrolling adaptation on globally in
|
||||
your application, call the static function wxDialog::EnableLayoutAdaptation passing @true.
|
||||
You can also adjust adaptation on a per-dialog basis by calling
|
||||
wxDialog::SetLayoutAdaptationMode with one of @c wxDIALOG_ADAPTATION_MODE_DEFAULT
|
||||
(use the global setting), @c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
|
||||
Many applications should therefore be able to adapt to small displays with
|
||||
little or no work, as far as dialogs are concerned. By default this adaptation
|
||||
is off. To switch scrolling adaptation on globally in your application, call
|
||||
the static function wxDialog::EnableLayoutAdaptation passing @true. You can
|
||||
also adjust adaptation on a per-dialog basis by calling
|
||||
wxDialog::SetLayoutAdaptationMode with one of
|
||||
@c wxDIALOG_ADAPTATION_MODE_DEFAULT (use the global setting),
|
||||
@c wxDIALOG_ADAPTATION_MODE_ENABLED or @c wxDIALOG_ADAPTATION_MODE_DISABLED.
|
||||
|
||||
The last two modes override the global adaptation setting.
|
||||
With adaptation enabled, if the display size is too small for the dialog, wxWidgets (or rather the
|
||||
standard adapter class wxStandardDialogLayoutAdapter) will make part of the dialog scrolling,
|
||||
leaving standard buttons in a non-scrolling part at the bottom of the dialog.
|
||||
This is done as follows, in wxDialogLayoutAdapter::DoLayoutAdaptation called from
|
||||
within wxDialog::Show or wxDialog::ShowModal:
|
||||
The last two modes override the global adaptation setting. With adaptation
|
||||
enabled, if the display size is too small for the dialog, wxWidgets (or rather
|
||||
the standard adapter class wxStandardDialogLayoutAdapter) will make part of the
|
||||
dialog scrolling, leaving standard buttons in a non-scrolling part at the
|
||||
bottom of the dialog. This is done as follows, in
|
||||
wxDialogLayoutAdapter::DoLayoutAdaptation called from within wxDialog::Show or
|
||||
wxDialog::ShowModal:
|
||||
|
||||
@li If wxDialog::GetContentWindow returns a window derived from wxBookCtrlBase,
|
||||
the pages are made scrollable and no other adaptation is done.
|
||||
@li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the non-scrolling part.
|
||||
@li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one or more
|
||||
standard buttons, with identifiers such as @c wxID_OK and @c wxID_CANCEL.
|
||||
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer)
|
||||
and adds them to a wxStdDialogButtonSizer.
|
||||
If no standard buttons were found, the whole dialog content will scroll.
|
||||
@li All the children apart from standard buttons are reparented onto a new ::wxScrolledWindow
|
||||
object, using the old top-level sizer for the scrolled window and creating a new top-level
|
||||
sizer to lay out the scrolled window and standard button sizer.
|
||||
@li wxWidgets looks for a wxStdDialogButtonSizer and uses it for the
|
||||
non-scrolling part.
|
||||
@li If that search failed, wxWidgets looks for a horizontal wxBoxSizer with one
|
||||
or more standard buttons, with identifiers such as @c wxID_OK and
|
||||
@c wxID_CANCEL.
|
||||
@li If that search failed too, wxWidgets finds 'loose' standard buttons (in any
|
||||
kind of sizer) and adds them to a wxStdDialogButtonSizer. If no standard
|
||||
buttons were found, the whole dialog content will scroll.
|
||||
@li All the children apart from standard buttons are reparented onto a new
|
||||
::wxScrolledWindow object, using the old top-level sizer for the scrolled
|
||||
window and creating a new top-level sizer to lay out the scrolled window
|
||||
and standard button sizer.
|
||||
|
||||
|
||||
@subsection overview_dialog_autoscrolling_custom Customising scrolling adaptation
|
||||
@subsection overview_dialog_autoscrolling_custom Customising Scrolling Adaptation
|
||||
|
||||
In addition to switching adaptation on and off globally and per dialog,
|
||||
you can choose how aggressively wxWidgets will search for standard buttons by setting
|
||||
wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above will be
|
||||
performed but by setting the level to 1, for example, you can choose to only look for
|
||||
wxStdDialogButtonSizer.
|
||||
In addition to switching adaptation on and off globally and per dialog, you can
|
||||
choose how aggressively wxWidgets will search for standard buttons by setting
|
||||
wxDialog::SetLayoutAdaptationLevel. By default, all the steps described above
|
||||
will be performed but by setting the level to 1, for example, you can choose to
|
||||
only look for wxStdDialogButtonSizer.
|
||||
|
||||
You can use wxDialog::AddMainButtonId to add identifiers for buttons that should also be
|
||||
treated as standard buttons for the non-scrolling area.
|
||||
You can use wxDialog::AddMainButtonId to add identifiers for buttons that
|
||||
should also be treated as standard buttons for the non-scrolling area.
|
||||
|
||||
You can derive your own class from wxDialogLayoutAdapter or wxStandardDialogLayoutAdapter and call
|
||||
wxDialog::SetLayoutAdapter, deleting the old object that this function returns. Override
|
||||
the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability
|
||||
and perform the adaptation.
|
||||
You can derive your own class from wxDialogLayoutAdapter or
|
||||
wxStandardDialogLayoutAdapter and call wxDialog::SetLayoutAdapter, deleting the
|
||||
old object that this function returns. Override the functions
|
||||
CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation
|
||||
applicability and perform the adaptation.
|
||||
|
||||
You can also override wxDialog::CanDoLayoutAdaptation and wxDialog::DoLayoutAdaptation
|
||||
in a class derived from wxDialog.
|
||||
You can also override wxDialog::CanDoLayoutAdaptation and
|
||||
wxDialog::DoLayoutAdaptation in a class derived from wxDialog.
|
||||
|
||||
|
||||
@subsection overview_dialog_autoscrolling_fail Situations where automatic scrolling adaptation may fail
|
||||
@subsection overview_dialog_autoscrolling_fail Where Scrolling Adaptation May Fail
|
||||
|
||||
Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof,
|
||||
and may fail in the following situations:
|
||||
Because adaptation rearranges your sizer and window hierarchy, it is not
|
||||
fool-proof, and may fail in the following situations:
|
||||
|
||||
@li The dialog doesn't use sizers.
|
||||
@li The dialog implementation makes assumptions about the window hierarchy,
|
||||
@@ -110,7 +113,8 @@ and may fail in the following situations:
|
||||
children of the top-level sizer. However, the original sizer hierarchy will still hold
|
||||
until Show or ShowModal is called.
|
||||
|
||||
You can help make sure that your dialogs will continue to function after adaptation by:
|
||||
You can help make sure that your dialogs will continue to function after
|
||||
adaptation by:
|
||||
|
||||
@li avoiding the above situations and assumptions;
|
||||
@li using wxStdDialogButtonSizer;
|
||||
@@ -124,11 +128,11 @@ You can help make sure that your dialogs will continue to function after adaptat
|
||||
@subsection overview_dialog_propertysheet wxPropertySheetDialog and wxWizard
|
||||
|
||||
Adaptation for wxPropertySheetDialog is always done by simply making the pages
|
||||
scrollable, since wxDialog::GetContentWindow returns the dialog's book control and
|
||||
this is handled by the standard layout adapter.
|
||||
scrollable, since wxDialog::GetContentWindow returns the dialog's book control
|
||||
and this is handled by the standard layout adapter.
|
||||
|
||||
wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather
|
||||
than the global adapter: again, only the wizard pages are made scrollable.
|
||||
wxWizard uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions
|
||||
rather than the global adapter: again, only the wizard pages are made
|
||||
scrollable.
|
||||
|
||||
*/
|
||||
|
||||
|
Reference in New Issue
Block a user