1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: wxDialog Overview</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title"><a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a> Overview </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_dialog_autoscrolling">Automatic Scrolled Dialogs</a><ul><li class="level2"><a href="#overview_dialog_autoscrolling_custom">Customising Scrolling Adaptation</a></li>
<li class="level2"><a href="#overview_dialog_autoscrolling_fail">Where Scrolling Adaptation May Fail</a></li>
<li class="level2"><a href="#overview_dialog_propertysheet">wxPropertySheetDialog and wxWizard</a></li>
</ul>
</li>
</ul>
</div>
<div class="textblock"><p>Classes: <a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a>, <a class="el" href="classwx_dialog_layout_adapter.html" title="This abstract class is the base for classes that help wxWidgets perform run-time layout adaptation of...">wxDialogLayoutAdapter</a></p>
<p>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:</p>
<ul>
<li>A surrounding frame is implicitly created. </li>
<li>Extra functionality is automatically given to the dialog box, such as tabbing between items (currently Windows only). </li>
<li>If the dialog box is <em>modal</em>, the calling program is blocked until the dialog box is dismissed.</li>
</ul>
<p>For a set of dialog convenience functions, including file selection, see <a class="el" href="group__group__funcmacro__dialog.html">Dialogs</a>.</p>
<p>See also <a class="el" href="classwx_top_level_window.html" title="wxTopLevelWindow is a common base class for wxDialog and wxFrame.">wxTopLevelWindow</a> and <a class="el" href="classwx_window.html" title="wxWindow is the base class for all windows and represents any visible object on screen.">wxWindow</a> for inherited member functions. Validation of data in controls is covered in <a class="el" href="overview_validator.html">wxValidator Overview</a>.</p>
<h1><a class="anchor" id="overview_dialog_autoscrolling"></a>
Automatic Scrolled Dialogs</h1>
<p>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. <a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a> therefore supplies a global <a class="el" href="classwx_dialog_layout_adapter.html" title="This abstract class is the base for classes that help wxWidgets perform run-time layout adaptation of...">wxDialogLayoutAdapter</a> class that implements automatic scrolling adaptation for most sizer-based custom dialogs.</p>
<p>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 <a class="el" href="classwx_dialog.html#a016cfd686f75bcfc5f7b6f127be74c7c" title="A static function enabling or disabling layout adaptation for all dialogs.">wxDialog::EnableLayoutAdaptation</a> passing <span class="literal">true</span>. You can also adjust adaptation on a per-dialog basis by calling <a class="el" href="classwx_dialog.html#a9f949c545ca70571cec8cd2fcbfc0991" title="Sets the adaptation mode, overriding the global adaptation flag.">wxDialog::SetLayoutAdaptationMode</a> with one of <code>wxDIALOG_ADAPTATION_MODE_DEFAULT</code> (use the global setting), <code>wxDIALOG_ADAPTATION_MODE_ENABLED</code> or <code>wxDIALOG_ADAPTATION_MODE_DISABLED</code>.</p>
<p>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 <a class="el" href="classwx_dialog_layout_adapter.html#adb59c3238b594b88faa4aab892b9bdd8" title="Override this to perform layout adaptation, such as making parts of the dialog scroll and resizing th...">wxDialogLayoutAdapter::DoLayoutAdaptation</a> called from within <a class="el" href="classwx_dialog.html#ae8e5fa98d473b812b8d1c2f163b65c67" title="Hides or shows the dialog.">wxDialog::Show</a> or <a class="el" href="classwx_dialog.html#a6e078c3d0653f75ad3c34a37c0b54637" title="Shows an application-modal dialog.">wxDialog::ShowModal</a>:</p>
<ul>
<li>If <a class="el" href="classwx_dialog.html#aee73457b69fb24e29a9039b6506eb92e" title="Override this to return a window containing the main content of the dialog.">wxDialog::GetContentWindow</a> returns a window derived from <a class="el" href="classwx_book_ctrl_base.html" title="A book control is a convenient way of displaying multiple pages of information, displayed one page at...">wxBookCtrlBase</a>, the pages are made scrollable and no other adaptation is done. </li>
<li>wxWidgets looks for a <a class="el" href="classwx_std_dialog_button_sizer.html" title="This class creates button layouts which conform to the standard button spacing and ordering defined b...">wxStdDialogButtonSizer</a> and uses it for the non-scrolling part. </li>
<li>If that search failed, wxWidgets looks for a horizontal <a class="el" href="classwx_box_sizer.html" title="The basic idea behind a box sizer is that windows will most often be laid out in rather simple basic ...">wxBoxSizer</a> with one or more standard buttons, with identifiers such as <code>wxID_OK</code> and <code>wxID_CANCEL</code>. </li>
<li>If that search failed too, wxWidgets finds 'loose' standard buttons (in any kind of sizer) and adds them to a <a class="el" href="classwx_std_dialog_button_sizer.html" title="This class creates button layouts which conform to the standard button spacing and ordering defined b...">wxStdDialogButtonSizer</a>. If no standard buttons were found, the whole dialog content will scroll. </li>
<li>All the children apart from standard buttons are reparented onto a new <a class="el" href="group__group__class__miscwnd.html#ga695bec5996cd4d5512d1a01cfdcf96a5" title="Scrolled window derived from wxPanel.">wxScrolledWindow</a> 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>
</ul>
<h2><a class="anchor" id="overview_dialog_autoscrolling_custom"></a>
Customising Scrolling Adaptation</h2>
<p>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 <a class="el" href="classwx_dialog.html#a9eaef1625f225bc25f8c92449d123a67" title="Sets the aggressiveness of search for buttons and sizers to be in the non-scrolling part of a layout-...">wxDialog::SetLayoutAdaptationLevel</a>. 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 <a class="el" href="classwx_std_dialog_button_sizer.html" title="This class creates button layouts which conform to the standard button spacing and ordering defined b...">wxStdDialogButtonSizer</a>.</p>
<p>You can use <a class="el" href="classwx_dialog.html#af3a75b9d24abe5c79d1bb5397c67b108" title="Adds an identifier to be regarded as a main button for the non-scrolling area of a dialog...">wxDialog::AddMainButtonId</a> to add identifiers for buttons that should also be treated as standard buttons for the non-scrolling area.</p>
<p>You can derive your own class from <a class="el" href="classwx_dialog_layout_adapter.html" title="This abstract class is the base for classes that help wxWidgets perform run-time layout adaptation of...">wxDialogLayoutAdapter</a> or wxStandardDialogLayoutAdapter and call <a class="el" href="classwx_dialog.html#a371e3d760ea9beb49b74c5ffee52a0ee" title="A static function for setting the current layout adapter object, returning the old adapter...">wxDialog::SetLayoutAdapter</a>, deleting the old object that this function returns. Override the functions CanDoLayoutAdaptation and DoLayoutAdaptation to test for adaptation applicability and perform the adaptation.</p>
<p>You can also override <a class="el" href="classwx_dialog.html#a233dd280efa8ee93c61792e439904731" title="Returns true if this dialog can and should perform layout adaptation using DoLayoutAdaptation(), usually if the dialog is too large to fit on the display.">wxDialog::CanDoLayoutAdaptation</a> and <a class="el" href="classwx_dialog.html#a919613599a9e919913146e21d09b44c0" title="Performs layout adaptation, usually if the dialog is too large to fit on the display.">wxDialog::DoLayoutAdaptation</a> in a class derived from <a class="el" href="classwx_dialog.html" title="A dialog box is a window with a title bar and sometimes a system menu, which can be moved around the ...">wxDialog</a>.</p>
<h2><a class="anchor" id="overview_dialog_autoscrolling_fail"></a>
Where Scrolling Adaptation May Fail</h2>
<p>Because adaptation rearranges your sizer and window hierarchy, it is not fool-proof, and may fail in the following situations:</p>
<ul>
<li>The dialog doesn't use sizers. </li>
<li>The dialog implementation makes assumptions about the window hierarchy, for example getting the parent of a control and casting to the dialog class. </li>
<li>The dialog does custom painting and/or event handling not handled by the scrolled window. If this problem can be solved globally, you can derive a new adapter class from wxStandardDialogLayoutAdapter and override its CreateScrolledWindow function to return an instance of your own class. </li>
<li>The dialog has unusual layout, for example a vertical sizer containing a mixture of standard buttons and other controls. </li>
<li>The dialog makes assumptions about the sizer hierarchy, for example to show or hide children of the top-level sizer. However, the original sizer hierarchy will still hold until Show or ShowModal is called.</li>
</ul>
<p>You can help make sure that your dialogs will continue to function after adaptation by:</p>
<ul>
<li>avoiding the above situations and assumptions; </li>
<li>using <a class="el" href="classwx_std_dialog_button_sizer.html" title="This class creates button layouts which conform to the standard button spacing and ordering defined b...">wxStdDialogButtonSizer</a>; </li>
<li>only making assumptions about hierarchy immediately after the dialog is created; </li>
<li>using an intermediate sizer under the main sizer, a <span class="literal">false</span> top-level sizer that can be relied on to exist for the purposes of manipulating child sizers and windows; </li>
<li>overriding <a class="el" href="classwx_dialog.html#aee73457b69fb24e29a9039b6506eb92e" title="Override this to return a window containing the main content of the dialog.">wxDialog::GetContentWindow</a> to return a book control if your dialog implements pages: wxWidgets will then only make the pages scrollable.</li>
</ul>
<h2><a class="anchor" id="overview_dialog_propertysheet"></a>
wxPropertySheetDialog and wxWizard</h2>
<p>Adaptation for <a class="el" href="classwx_property_sheet_dialog.html" title="This class represents a property sheet dialog: a tabbed dialog for showing settings.">wxPropertySheetDialog</a> is always done by simply making the pages scrollable, since <a class="el" href="classwx_dialog.html#aee73457b69fb24e29a9039b6506eb92e" title="Override this to return a window containing the main content of the dialog.">wxDialog::GetContentWindow</a> returns the dialog's book control and this is handled by the standard layout adapter.</p>
<p><a class="el" href="classwx_wizard.html" title="wxWizard is the central class for implementing 'wizard-like' dialogs.">wxWizard</a> uses its own CanDoLayoutAdaptation and DoLayoutAdaptation functions rather than the global adapter: again, only the wizard pages are made scrollable. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
