Complete first draft of Chapter 4.

Chapters/ch03-a-top-toolbar.xml

@@ -46,7 +46,7 @@
 <section>
 <p>An alternative to a toolbox at the side of a window, as we <reference id="chap-side-box">created in the last chapter</reference>, is a toolbar across the top of a window. Which to go for is more of a stylistic question than a technical one, and it&rsquo;s possible to have both at the same time. <cite>Ovation&nbsp;Pro</cite> does just this, as seen in <reference id="fig-top-bar-ovation"/>.</p>
 
-<image id="fig-top-bar-ovation" file="top-bar-ovation.png" title="Ovation Pro has both a side toolbox and a toolbar at the same time."/>
+<image id="fig-top-bar-ovation" file="top-bar-ovation.png" title="Ovation Pro has both a side toolbox and a toolbar at the same time"/>
 
 <p>In this chapter, we&rsquo;ll add such a toolbar to our own window, to complement the existing toolbox.</p>
 </section>

Chapters/ch04-column-headings.xml

@@ -44,13 +44,182 @@
 <summary>So far our toolbar has ignored the main window contents; what if we want it to remain in step with the work area?</summary>
 
 <section>
-<p>An alternative to a toolbox at the side of a window, as we <reference id="chap-side-box">created in the last chapter</reference>, is a toolbar across the top of a window. Which to go for is more of a stylistic question than a technical one, and it&rsquo;s possible to have both at the same time. <cite>Ovation&nbsp;Pro</cite> does just this, as seen in <reference id="fig-top-bar-ovation"/>.</p>
+<p>Now that we have added both a <reference id="chap-side-box">toolbox</reference> and a <reference id="chap-top-bar">toolbar</reference> to our example application in the past two chapters, it&rsquo;s time to look a subtle way of altering the configuration.</p>
 
-<!--image id="fig-top-bar-ovation" file="top-bar-ovation.png" title="Ovation Pro has both a side toolbox and a toolbar at the same time."/ -->
+<p>So far, both of our panes have used &lsquo;fixed&rsquo; work areas which don&rsquo;t scroll: their X and Y scroll offsets were set to zero in the window templates, and remained at that value as the main window moved around. However, there&rsquo;s no reason why panes can&rsquo;t scroll in sympathy with their parent windows: a spreadsheet might need to do this if it was using a pane to show the column headings in a document, for example. In fact <cite>Fireworkz</cite>, seen in <reference id="fig-col-head-fireworkz"/>, does exactly this.</p>
 
-<p>In this chapter, we&rsquo;ll add such a toolbar to our own window, to complement the existing toolbox.</p>
+<image id="fig-col-head-fireworkz" file="col-head-fireworkz.png" title="A spreadsheet like Fireworkz can use toolbars for column headings"/>
 
+<p>It&rsquo;s worth noting here that in the screenshot above, the <cite>Fireworkz</cite> window is actually composed of multiple panes. There&rsquo;s a pane with a fixed work area containing the button and status bars (the latter containing the text &ldquo;Page 1&rdquo;), which &ndash; just like the one that we have already created &ndash; does not scroll with the work area. Below it is a separate pane containing just the column headings for the sheet (from &ldquo;b&rdquo; through to &ldquo;e&rdquo; here), which <em>does</em> scroll: ensuring that the headings remain lined up with the associated cells in the main window.</p>
 
+<p>Although we won&rsquo;t be assembling a composite set-up like <cite>Fireworkz</cite>, in this chapter, we&rsquo;ll see what is required to make a pane scroll with its parent window.</p>
+
+</section>
+
+
+<section>
+<title>Updating the templates</title>
+
+<p>Following the now familiar pattern, we&rsquo;ll begin by updating the window templates for our new example. As our code was starting to get a little unwieldy, we will begin by losing the toolbox to the left of the window, leaving just the toolbar at the top. The &ldquo;Toolbox&rdquo; template can therefore be deleted from the template file, leaving just the three templates for the main window, toolbar and program information window as seen in <reference id="fig-col-head-template"/>.</p>
+
+<image id="fig-col-head-template" file="col-head-template.png" title="Adding the column headings to the toolbar in WinEd"/>
+
+<p>The toolbar window itself has also been updated, removing the pair of action buttons and the writeable field. In their place are four &lsquo;heading&rsquo; icons, which should line up with the columns of coloured squares in the main window. The buttons are now passive &ndash; neither visibly pressing nor generating <name>Mouse_Click</name> events &ndash; although as before this is merely cosmetic.</p>
+
+<p>For the code itself, we have gone back to <reference id="dl-top-bar-2"/> and stripped out all of the code relating to the toolbox pane. First, we no longer need to load or the window, reducing the template code in <function>PROCinitialise</function> to loading the remaining three windows as seen in <reference id="list-col-head-load"/>.</p>
+
+<code id="list-col-head-load" lang="bbcbasic" title="Loading the three window templates">REM Load the window templates
+
+DIM TemplateName% 12
+
+SYS &quot;Wimp_OpenTemplate&quot;,,&quot;&lt;PaneDemo$Dir&gt;.Templates&quot;
+
+PROCtemplate_load(&quot;Main&quot;, b%, buffer_size%, -1)
+SYS &quot;Wimp_CreateWindow&quot;,,b% TO MainWindow%
+WindowWidth% = b%!8 - b%!0    : REM Width is Visible Area Maximum X - Minimun X
+WindowHeight% = b%!12 - b%!4  : REM Height is Visible Area Maximum Y - Minimun Y
+
+PROCtemplate_load(&quot;Toolbar&quot;, b%, buffer_size%, -1)
+SYS &quot;Wimp_CreateWindow&quot;,,b% TO ToolBarWindow%
+
+PROCtemplate_load(&quot;ProgInfo&quot;, b%, buffer_size%, -1)
+SYS &quot;Wimp_CreateWindow&quot;,,b% TO InfoWindow%
+
+SYS &quot;Wimp_CloseTemplate&quot;</code>
+
+<p>Since there is no longer a toolbox to close when the main window closes, <function>PROCclose_window_request()</function> can be reduced to the code shown in <reference id="list-col-head-close"/>.</p>
+
+<code id="list-col-head-close" lang="bbcbasic" title="Handling Close_Window_Request events for the main window">DEF PROCclose_window_request(b%)
+IF !b% = MainWindow% THEN
+  !q% = ToolBarWindow%
+  SYS &quot;Wimp_CloseWindow&quot;,,q%
+ENDIF
+
+SYS &quot;Wimp_CloseWindow&quot;,,b%
+ENDPROC</code>
+
+<p>Finall, <function>PROChandle_pane_windows()</function> can be simplified again; it is now as shown in <reference id="list-col-head-handle"/>.</p>
+
+<code id="list-col-head-handle" lang="bbcbasic" title="Opening the toolbar in the correct place">DEF PROChandle_pane_windows(main%)
+LOCAL toolbar%, bar_height%
+
+REM Get the Window State block for the toolbar pane, using more of the
+REM spare space above the data for the state of the main window.
+
+toolbar% = main% + 64
+
+!toolbar% = ToolBarWindow%
+SYS &quot;Wimp_GetWindowState&quot;,,toolbar%
+
+REM Find the height of the toolbar pane's visible area.
+
+bar_height% = toolbar%!16 - toolbar%!8  : REM Visible Area Maximum Y - Minimum Y
+
+REM Move the toolbar pane so that it's in the correct X and Y position
+REM relative to where the main window is to go.
+
+toolbar%!4 = main%!4                    : REM Visible Area Minimum X
+toolbar%!8 = main%!16 - bar_height%     : REM Visible Area Minimum Y
+toolbar%!12 = main%!12                  : REM Visible Area Maximum X
+toolbar%!16 = main%!16                  : REM Visible Area Maximum Y
+
+REM Unless the main window is to be opened behind the toolbar pane, and the
+REM toolbar pane is already behind the toolbox pane, meaning that all three
+REM windows must already be in the correct place in the stack, set the toolbox's
+REM Open Behind so that it appears in the stack where the main window is to go.
+
+IF main%!28 &lt;&gt; ToolBarWindow% THEN toolbar%!28 = main%!28
+
+SYS &quot;Wimp_OpenWindow&quot;,,toolbar%
+
+REM Set the main window's Open Behind so that it opens behind the toolbar.
+
+main%!28 = ToolBarWindow%
+
+SYS &quot;Wimp_OpenWindow&quot;,,main%
+ENDPROC</code>
+
+<p>The code here should be comparable to that found in <reference id="dl-side-box-1"/> &ndash; a single pane, but attached in a toolbar style instead of a toolbox. When run, the window should appear as seen in <reference id="fig-col-head-initial"/>, with the new column headings lining up with the coloured grid squares below.</p>
+
+<image id="fig-col-head-initial" file="col-head-initial.png" title="The example application with a column heading bar over the grid"/>
+
+<p>The updated example code can be found in <reference id="dl-col-head-1"/>; it would be a good idea to check through it and ensure that you are comfortable with how relates to the earlier examples.</p>
+
+<download id="dl-col-head-1" file="ColHead1" title="Changing the toolbar to show column headings" compatibility="armv7"/>
+</section>
+
+
+<section>
+<title>Out of alignment</title>
+
+<p>Unfortunately, any satisfaction with our new example is likely to be short-lived. If the width of the main window is reduced, and then the horizontal scroll bar used to shift the work area, we can quickly see that things go out of alignment as shown in <reference id="fig-col-head-alignment"/>. The main window&rsquo;s work area moves with the scroll bars as expected, but the toolbar&rsquo;s content remains where it was.</p>
+
+<image id="fig-col-head-alignment" file="col-head-alignment.png" title="The column headings in the toolbar don&rsquo;t stay aligned with the main window"/>
+
+<p>The problem that we have is that moving the scroll bars alters the scroll offsets for the main window&rsquo;s work area, but &ndash; as we noted above &ndash; the the scroll offsets for the work areas of our panes have always been left at zero. Up to now this has been the required behaviour, but this new example is calling for something different.</p>
+
+<p>To keep the pane&rsquo;s contents in alignment with that of the main window, we will need to ensure that its scroll offsets are updated correctly whenever we change its position in <function>PROChandle_pane_windows()</function>. We only want the pane to track the main window&rsquo;s horizontal scrolling, so we can simply copy the X scroll offset from the main window block to the pane.</p>
+
+<code lang="bbcbasic">toolbar%!20 = main%!20                  : REM X Scroll Offset</code>
+
+<p>Things to consider here are that both the main window and the toolbar are the same width (we copy the <maths>X0</maths> and <maths>X1</maths> across unchanged as part of the pane positioning), and their horizontal extents are identical (both are set to 1040 in their window templates). As such, copying the X scroll offset across from one window to the other will have no unexpected effects.</p>
+
+<p>If the pane were up the side of the window instead of across the top, and the vertical extents were the same, it would be possible to copy the vertical scroll offset (at offset 24 into the window state block) across to the pane instead. This might be useful for a pane containing row numbers, as seen in the <reference id="fig-col-head-fireworkz"><cite>Fireworkz</cite> window above</reference>, for example.</p>
+
+<p>Putting the code together for the last time gives us <reference id="list-col-head-align"/>, showing <function>PROChandle_pane_windows()</function> copying the horizontal scroll offset over to the pane.</p>
+
+<code id="list-col-head-align" lang="bbcbasic" title="Opening the toolbar in the correct place">DEF PROChandle_pane_windows(main%)
+LOCAL toolbar%, bar_height%
+
+REM Get the Window State block for the toolbar pane, using more of the
+REM spare space above the data for the state of the main window.
+
+toolbar% = main% + 64
+
+!toolbar% = ToolBarWindow%
+SYS &quot;Wimp_GetWindowState&quot;,,toolbar%
+
+REM Find the height of the toolbar pane's visible area.
+
+bar_height% = toolbar%!16 - toolbar%!8  : REM Visible Area Maximum Y - Minimum Y
+
+REM Move the toolbar pane so that it's in the correct X and Y position
+REM relative to where the main window is to go.
+
+toolbar%!4 = main%!4                    : REM Visible Area Minimum X
+toolbar%!8 = main%!16 - bar_height%     : REM Visible Area Minimum Y
+toolbar%!12 = main%!12                  : REM Visible Area Maximum X
+toolbar%!16 = main%!16                  : REM Visible Area Maximum Y
+
+REM Align the toolbar pane's scroll offset with the main window.
+
+toolbar%!20 = main%!20                  : REM X Scroll Offset
+
+REM Unless the main window is to be opened behind the toolbar pane, and the
+REM toolbar pane is already behind the toolbox pane, meaning that all three
+REM windows must already be in the correct place in the stack, set the toolbox's
+REM Open Behind so that it appears in the stack where the main window is to go.
+
+IF main%!28 &lt;&gt; ToolBarWindow% THEN toolbar%!28 = main%!28
+
+SYS &quot;Wimp_OpenWindow&quot;,,toolbar%
+
+REM Set the main window's Open Behind so that it opens behind the toolbar.
+
+main%!28 = ToolBarWindow%
+
+SYS &quot;Wimp_OpenWindow&quot;,,main%
+ENDPROC</code>
+
+<p>Loading this version of the application, we can now scroll around the main window&rsquo;s work area with the column headings in the toolbar remaining in step as seen in <reference id="fig-col-head-align-fixed"/>.</p>
+
+<image id="fig-col-head-align-fixed" file="col-head-align-fixed.png" title="Scrolling horizontally with the scroll offsets held in step"/>
+
+<p>The complete example code can be found in <reference id="dl-col-head-2"/>.</p>
+
+<download id="dl-col-head-2" file="ColHead2" title="Synchronising horizontal scroll offsets" compatibility="armv7"/>
+
+<p>With this example, we have completed our look at how panes can be handed using nothing more than the standard Wimp to help us. However, in 1997 Acorn added a new system for controlling panes, known as the Nested Wimp. In the coming chapters, we will look at this in more detail and see how it compares to the original approach.</p>
 </section>
 </chapter>
 </manual>

Downloads/Chapter04/ColHead1/!PaneDemo/!Boot,feb

@@ -0,0 +1,24 @@
+| >!Boot
+|
+| Copyright 2021, Stephen Fryatt (info@stevefryatt.org.uk)
+|
+| This file is part of PaneDemo:
+|
+|   http://www.stevefryatt.org.uk/risc-os/panes
+|
+| Permission is hereby granted, free of charge, to any person obtaining
+| a copy of this software and associated documentation files (the
+| "Software"), to deal in the Software without restriction, including
+| without limitation the rights to use, copy, modify, merge, publish,
+| distribute, sublicense, and/or sell copies of the Software, and to
+| permit persons to whom the Software is furnished to do so.
+|
+| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+| OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+| IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+| CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+| TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+| SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+If "<PaneDemo$Dir>"="" Then Set PaneDemo$Dir <Obey$Dir>

Downloads/Chapter04/ColHead1/!PaneDemo/!Run,feb

@@ -0,0 +1,27 @@
+| >!Run
+|
+| Copyright 2021, Stephen Fryatt (info@stevefryatt.org.uk)
+|
+| This file is part of PaneDemo:
+|
+|   http://www.stevefryatt.org.uk/risc-os/panes
+|
+| Permission is hereby granted, free of charge, to any person obtaining
+| a copy of this software and associated documentation files (the
+| "Software"), to deal in the Software without restriction, including
+| without limitation the rights to use, copy, modify, merge, publish,
+| distribute, sublicense, and/or sell copies of the Software, and to
+| permit persons to whom the Software is furnished to do so.
+|
+| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+| OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+| IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+| CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+| TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+| SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Set PaneDemo$Dir <Obey$Dir>
+
+WimpSlot -min 96K -max 96K
+Run <PaneDemo$Dir>.!RunImage

Downloads/Chapter04/ColHead2/!PaneDemo/!Boot,feb

@@ -0,0 +1,24 @@
+| >!Boot
+|
+| Copyright 2021, Stephen Fryatt (info@stevefryatt.org.uk)
+|
+| This file is part of PaneDemo:
+|
+|   http://www.stevefryatt.org.uk/risc-os/panes
+|
+| Permission is hereby granted, free of charge, to any person obtaining
+| a copy of this software and associated documentation files (the
+| "Software"), to deal in the Software without restriction, including
+| without limitation the rights to use, copy, modify, merge, publish,
+| distribute, sublicense, and/or sell copies of the Software, and to
+| permit persons to whom the Software is furnished to do so.
+|
+| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+| OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+| IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+| CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+| TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+| SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+If "<PaneDemo$Dir>"="" Then Set PaneDemo$Dir <Obey$Dir>

Downloads/Chapter04/ColHead2/!PaneDemo/!Run,feb

@@ -0,0 +1,27 @@
+| >!Run
+|
+| Copyright 2021, Stephen Fryatt (info@stevefryatt.org.uk)
+|
+| This file is part of PaneDemo:
+|
+|   http://www.stevefryatt.org.uk/risc-os/panes
+|
+| Permission is hereby granted, free of charge, to any person obtaining
+| a copy of this software and associated documentation files (the
+| "Software"), to deal in the Software without restriction, including
+| without limitation the rights to use, copy, modify, merge, publish,
+| distribute, sublicense, and/or sell copies of the Software, and to
+| permit persons to whom the Software is furnished to do so.
+|
+| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+| OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+| MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+| IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+| CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+| TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+| SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Set PaneDemo$Dir <Obey$Dir>
+
+WimpSlot -min 96K -max 96K
+Run <PaneDemo$Dir>.!RunImage