Fix example code and improve optimisation example.

Chapters/ch05-does-order-matter.xml

@@ -83,7 +83,6 @@ SYS &quot;Wimp_OpenWindow&quot;,,toolbox%</code>
 
 <p>The full code for our new <function>PROChandle_pane_windows()</function> can be seen in <reference id="list-order-single-pane"/>, and it&rsquo;s a lot simpler than the version seen in <reference id="list-side-box-update"/>.</p>
 
-
 <code id="list-order-single-pane" lang="bbcbasic" title="An alternative way to position the toolbox pane">DEF PROChandle_pane_windows(main%)
 LOCAL toolbar%
 
@@ -112,7 +111,14 @@ toolbar%!28 = main%!28
 SYS &quot;Wimp_OpenWindow&quot;,,toolbar%
 ENDPROC</code>
 
-<p>A complete copy of the new application can be found in <reference id="dl-order-single-pane"/>. When run, it might perform in a very similar way to <reference id="dl-col-head-2"/> from the previous chapter... or it might not.</p>
+<p>Now that <function>PROChandle_pane_windows()</function> doesn&rsquo;t open the main window, we will also need to make a small change to <function>PROCopen_main_window</function> so that it does that task for itself. The change is simply adding a call to <swi>Wimp_OpenWindow</swi> before the call to <function>PROChandle_pane_windows()</function>, at the end of the procedure.</p>
+
+<code lang="bbcbasic">q%!28 = -1 : REM Window to open behind (-1 is top of stack)
+
+SYS &quot;Wimp_OpenWindow&quot;,,q%
+PROChandle_pane_windows(q%)</code>
+
+<p>With all of these changes in place, a complete copy of the new application can be found in <reference id="dl-order-single-pane"/>. When run, it might perform in a very similar way to <reference id="dl-col-head-2"/> from the previous chapter... or it might not.</p>
 
 <download id="dl-order-single-pane" file="ColHead3" title="Simplifying the pane handling" compatibility="armv7"/>
 </section>
@@ -152,16 +158,37 @@ ENDPROC</code>
 
 
 <section>
-<title>A question of optimisation</title>
+<title>A question of efficiency</title>
 
-<p>The small difference described in the previous section matters, because of a small change introduced as part of the Nested Wimp. A couple of the changes documented in the <cite><link href="http://www.vigay.com/inet/acorn/nested.html">Nested Window Manager Functional Specification</link></cite> are &ldquo;Redraw Optimisation&rdquo; and improvements to the &ldquo;Invalid Rectangle Handling&rdquo;. Between them, these have a big impact on the handling of panes.</p>
+<p>The difference described in the previous section matters, because of a small improvement introduced as part of the Nested Wimp. A couple of the changes documented in the <cite><link href="http://www.vigay.com/inet/acorn/nested.html">Nested Window Manager Functional Specification</link></cite> are &ldquo;Redraw Optimisation&rdquo; and improvements to the &ldquo;Invalid Rectangle Handling&rdquo;. Between them, these have a big impact on the handling of panes.</p>
 
 <p>When an application calls <swi>Wimp_OpenWindow</swi>, the window in question isn&rsquo;t immediately opened. Instead, the details are logged in a list of pending updates along with any other windows to be opened or closed &ndash; which are all actioned after the application next calls <swi>Wimp_Poll</swi>. This means that when our application opens its main window and toolbar pane, both windows will be updated together after control has returned to the Wimp.</p>
 
 <p>Prior to the Nested Wimp, all of these pending actions would be carried out in full, in the order that they were specified. In contrast, the Nested Wimp scans the whole list and optimises out any inefficiencies, before carrying out the minimum number of actions required to achieve the end result.</p>
 
 <p>What this means in practice is that the Nested Wimp will notice that despite the toolbar pane ending up behind the main window in <reference id="fig-order-new-2"/>, it ends up back in from in <reference id="fig-order-new-3"/> &ndash; and so there&rsquo;s no point redrawing the main window during the short period that it is on top.</p>
 
+<p>On earlier versions of the Wimp, however, our new optimised approach will result in the main window and its toolbar pane following the sequence shown in <reference id="fig-order-pane-switch"/> on <em>every</em> <name>Open_Window_Request</name> event. This produces a very visible flickering effect.</p>
+
+<image id="fig-order-pane-switch" file="order-pane-switch.png" title="The main window and toolbar pane swapping over"/>
+</section>
+
+
+<section>
+<title>Is it any use?</title>
+
+<p>Given all of this, is the optimisation described in this chapter of any use? The answer is &ldquo;yes,&rdquo; but probably not in all circumstances.</p>
+
+<p>If an application needs the Nested Wimp for some other reason, and will not run without it, then there&rsquo;s no harm in relying on the redraw optimisation in order to simplify the pane handling code. However, it&rsquo;s also worth remembering that the Nested Wimp will deal with many pane requirements &ndash; including those in this chapter &ndash; directly, with no need for any custom event handling; we&rsquo;ll see how this works in <reference id="chap-nest-wimp">the next chapter</reference>. The main omission is for panes which fall outside the outline of the parent window, such as the side toolbox that we created in <reference id="chap-side-box"/>.</p>
+
+<p>For applications which do not need the Nested Wimp for other reasons, and would otherwise work fine back to RISC&nbsp;OS&nbsp;3 or earlier, it seems a shame to restrict their compatibility for no good reason. Save for the situation when the window first opens, the more compatible solution is no less efficient than this optimised one: they both call <swi>Wimp_OpenWindow</swi> once for the main window and once for each pane.</p> 
+
+<p>If you do use the optimisation, though, it&rsquo;s a good idea to check for its presence in the <file>!Run</file> of the application using an <command>*RMEnsure</command>.</p>
+
+<code lang="obey">RMEnsure WindowManager 3.80 Error PaneDemo requires the Nested Window Manager.</code>
+
+<!-- Add a full download here. -->
+
 </section>
 </chapter>
 </manual>