From 93e20da6bbedf4d631c45290a55745b13d229c74 Mon Sep 17 00:00:00 2001 From: Steve Fryatt Date: Fri, 24 Dec 2021 23:34:21 +0000 Subject: [PATCH] Properly rename Chapter 2, so that all references are ToolBox. --- ...de-toolbar.xml => ch02-a-side-toolbox.xml} | 74 +++++++++--------- .../!PaneDemo/!Boot,feb | 0 .../{SideBar1 => SideBox1}/!PaneDemo/!Run,feb | 0 .../!PaneDemo/!RunImage,ffb | Bin .../!PaneDemo/Templates,fec | Bin .../!PaneDemo/!Boot,feb | 0 .../{SideBar2 => SideBox2}/!PaneDemo/!Run,feb | 0 .../!PaneDemo/!RunImage,ffb | Bin .../!PaneDemo/Templates,fec | Bin ...e-bar-browser.png => side-box-browser.png} | Bin ...bar-complete.png => side-box-complete.png} | Bin ...screen.png => side-box-draw-offscreen.png} | Bin .../{side-bar-draw.png => side-box-draw.png} | Bin ...{side-bar-flags.png => side-box-flags.png} | Bin ...{side-bar-loose.png => side-box-loose.png} | Bin ...r-offscreen.png => side-box-offscreen.png} | Bin ...r-pos-plane.png => side-box-pos-plane.png} | Bin ...bar-template.png => side-box-template.png} | Bin panes.xml | 2 +- 19 files changed, 38 insertions(+), 38 deletions(-) rename Chapters/{ch02-a-side-toolbar.xml => ch02-a-side-toolbox.xml} (91%) rename Downloads/Chapter02/{SideBar1 => SideBox1}/!PaneDemo/!Boot,feb (100%) rename Downloads/Chapter02/{SideBar1 => SideBox1}/!PaneDemo/!Run,feb (100%) rename Downloads/Chapter02/{SideBar1 => SideBox1}/!PaneDemo/!RunImage,ffb (100%) rename Downloads/Chapter02/{SideBar1 => SideBox1}/!PaneDemo/Templates,fec (100%) rename Downloads/Chapter02/{SideBar2 => SideBox2}/!PaneDemo/!Boot,feb (100%) rename Downloads/Chapter02/{SideBar2 => SideBox2}/!PaneDemo/!Run,feb (100%) rename Downloads/Chapter02/{SideBar2 => SideBox2}/!PaneDemo/!RunImage,ffb (100%) rename Downloads/Chapter02/{SideBar2 => SideBox2}/!PaneDemo/Templates,fec (100%) rename Images/Chapter02/{side-bar-browser.png => side-box-browser.png} (100%) rename Images/Chapter02/{side-bar-complete.png => side-box-complete.png} (100%) rename Images/Chapter02/{side-bar-draw-offscreen.png => side-box-draw-offscreen.png} (100%) rename Images/Chapter02/{side-bar-draw.png => side-box-draw.png} (100%) rename Images/Chapter02/{side-bar-flags.png => side-box-flags.png} (100%) rename Images/Chapter02/{side-bar-loose.png => side-box-loose.png} (100%) rename Images/Chapter02/{side-bar-offscreen.png => side-box-offscreen.png} (100%) rename Images/Chapter02/{side-bar-pos-plane.png => side-box-pos-plane.png} (100%) rename Images/Chapter02/{side-bar-template.png => side-box-template.png} (100%) diff --git a/Chapters/ch02-a-side-toolbar.xml b/Chapters/ch02-a-side-toolbox.xml similarity index 91% rename from Chapters/ch02-a-side-toolbar.xml rename to Chapters/ch02-a-side-toolbox.xml index ff3985f..99367b0 100644 --- a/Chapters/ch02-a-side-toolbar.xml +++ b/Chapters/ch02-a-side-toolbox.xml @@ -32,7 +32,7 @@ - A Side Toolbox --> - + Chapter02 Chapter02 @@ -46,33 +46,33 @@

If one were to survey members of the RISC OS community to find out what a “toolbox” looked like, the answer which came back would probably be along the lines of “like the one in Draw”. Draw’s toolbox has been present as standard on all systems since the days of RISC OS 2, and is still functional to this day. It’s also one of the easiest panes to implement, so let’s start by making one of our own.

- +
Making our first pane -

The first thing that we need to do is design the pane itself. As far as the Wimp is concerned, panes are just normal windows, so we’ll go back to our template editor of choice (here I’m using WinEd) and add a new window called “Toolbox”. We can see that window in the browser in , although the screenshot shows it after editing is complete – WinEd (and probably most other template editors) will give it a full set of scroll bars by default.

+

The first thing that we need to do is design the pane itself. As far as the Wimp is concerned, panes are just normal windows, so we’ll go back to our template editor of choice (here I’m using WinEd) and add a new window called “Toolbox”. We can see that window in the browser in , although the screenshot shows it after editing is complete – WinEd (and probably most other template editors) will give it a full set of scroll bars by default.

- + -

Opening the window template up for editing, we can change the window title to something short like “TB” – although this doesn’t really matter, since the title will never be shown to the user. To make it look like a toolbox, we’ve also added four action buttons which are each 92 × 92 OS Units and offset by 4 OS Units from each edge of the window: the visible area is the adjusted to be 100 × 388 OS Units. The end result can be seen in ; the buttons are just for show, as we won’t be using them for anything in this demonstration.

+

Opening the window template up for editing, we can change the window title to something short like “TB” – although this doesn’t really matter, since the title will never be shown to the user. To make it look like a toolbox, we’ve also added four action buttons which are each 92 × 92 OS Units and offset by 4 OS Units from each edge of the window: the visible area is the adjusted to be 100 × 388 OS Units. The end result can be seen in ; the buttons are just for show, as we won’t be using them for anything in this demonstration.

- + -

Next, we must adjust the window’s flags and parameters to meet the requirements of a toolbox pane, as seen in . This is the Edit window dialogue in WinEd; other template editors will have a close equivalent.

+

Next, we must adjust the window’s flags and parameters to meet the requirements of a toolbox pane, as seen in . This is the Edit window dialogue in WinEd; other template editors will have a close equivalent.

The first action is to turn off all of the window furniture – including the title bar. The pane won’t be able to move independently of the window that it’s attached to, so there’s no need to give the user the option of trying! Under the heading of Window behaviour, the Moveable flag is also unset – this corresponds to the ‘window is moveable’ flag in bit 1 of the window flags, and indicates that the user can’t initiate window movement – the application still can, though.

- +

The other flag which we have set is Pane, which corresponds to the ‘window is a pane’ flag at bit 5 of the window flags. The Programmer’s Reference Manual is a little vague about what this flag does, but most developers will probably have discovered that what it doesn’t do is cause the window follow its parent around the screen automatically! In fact it does a few important things, which we’ll discuss later in this chapter.

Down at the bottom of the dialogue, all of the scroll events are off, since we don’t need the pane to scroll. In addition, all of the window colours have been left at their default, Style Guide compliant values.

-

With the toolbox window design added to the templates and the file saved back into our application, we can add a couple of lines to PROCinitialise to load it and create a window for us to work with, as shown in .

+

With the toolbox window design added to the templates and the file saved back into our application, we can add a couple of lines to PROCinitialise to load it and create a window for us to work with, as shown in .

-PROCtemplate_load("ToolBox", b%, buffer_size%, -1) +PROCtemplate_load("ToolBox", b%, buffer_size%, -1) SYS "Wimp_CreateWindow",,b% TO ToolBoxWindow%

This follows the same pattern as used for the other two templates: creating the window, and placing the resulting handle into the ToolBoxWindow% variable for future reference.

@@ -89,9 +89,9 @@ SYS "Wimp_CreateWindow",,b% TO ToolBoxWindow% WHEN 2 : SYS "Wimp_OpenWindow",,b% WHEN 3 : SYS "Wimp_CloseWindow",,b% -

These just pass the requests straight back to the Wimp to handle, which is all that’s necessary for a simple application. If we want to adjust the position of the toolbox pane whenever the main window moves, however, then we will need to do a bit more work. To keep PROCpoll tidy, we will define two new event handling procedures – PROCopen_window_request() and PROCclose_window_request() – and use these to replace the calls to Wimp_OpenWindow and Wimp_CloseWindow, as seen in .

+

These just pass the requests straight back to the Wimp to handle, which is all that’s necessary for a simple application. If we want to adjust the position of the toolbox pane whenever the main window moves, however, then we will need to do a bit more work. To keep PROCpoll tidy, we will define two new event handling procedures – PROCopen_window_request() and PROCclose_window_request() – and use these to replace the calls to Wimp_OpenWindow and Wimp_CloseWindow, as seen in .

-DEF PROCpoll +DEF PROCpoll LOCAL reason% SYS "Wimp_Poll", &3C01, b% TO reason% @@ -107,9 +107,9 @@ ENDPROC

Before either of these two new procedures will do anything, they will check the handle of the window to which the event applies. If it’s the handle of the main window, then they will need to do the work required to handle the pane as well; for any other window, they can simply call the appropriate Wimp SWI as before.

-

In the case of PROCopen_window_request(), we will change the code so that any Open_Window_Request events relating to the main window are passed on again to another new procedure: PROChandle_pane_windows(). Events for other windows will simply be passed on to the Wimp_OpenWindow SWI. This code to do this can be seen in ; We’ll worry about what PROChandle_pane_windows() looks like later on.

+

In the case of PROCopen_window_request(), we will change the code so that any Open_Window_Request events relating to the main window are passed on again to another new procedure: PROChandle_pane_windows(). Events for other windows will simply be passed on to the Wimp_OpenWindow SWI. This code to do this can be seen in ; We’ll worry about what PROChandle_pane_windows() looks like later on.

-DEF PROCopen_window_request(b%) +DEF PROCopen_window_request(b%) IF !b% = MainWindow% THEN PROChandle_pane_windows(b%) ELSE @@ -117,9 +117,9 @@ ELSE ENDIF ENDPROC -

Of course, if the main window and its toolbox should be acting as one, then in addition to moving when the main window moves, the pane should be closed when the main window closes. We can look after this in a very similar way with our new PROCclose_window_request(), seen in . If the window being closed is the main window, then the toolbox window will be closed first; either way, the window referenced by the event is closed afterwards.

+

Of course, if the main window and its toolbox should be acting as one, then in addition to moving when the main window moves, the pane should be closed when the main window closes. We can look after this in a very similar way with our new PROCclose_window_request(), seen in . If the window being closed is the main window, then the toolbox window will be closed first; either way, the window referenced by the event is closed afterwards.

-DEF PROCclose_window_request(b%) +DEF PROCclose_window_request(b%) IF !b% = MainWindow% THEN !q% = ToolBoxWindow% SYS "Wimp_CloseWindow",,q% @@ -135,9 +135,9 @@ ENDPROC q%!28 = -1 : REM Open window at top of stack SYS "Wimp_OpenWindow",,q% -

Fortunately, this is just another call to Wimp_OpenWindow, so we should just be able to replace it with a call to PROChandle_pane_windows() in the same was as we did in the Open_Window_Request event handler. This means that our new PROCopen_main_window() will look as seen in .

+

Fortunately, this is just another call to Wimp_OpenWindow, so we should just be able to replace it with a call to PROChandle_pane_windows() in the same was as we did in the Open_Window_Request event handler. This means that our new PROCopen_main_window() will look as seen in .

-DEF PROCopen_main_window +DEF PROCopen_main_window LOCAL screen_width%, screen_height%, window_size% REM Get the window details. @@ -198,11 +198,11 @@ SYS "Wimp_GetWindowState",,pane% width% = pane%!12 - pane%!4 : REM Visible Area Maximum X - Minimum X height% = pane%!16 - pane%!8 : REM Visible Area Maximum Y - Minimum Y -

As already noted, we know where the main window should be on screen. We also know the relationship that we want to have between the main window and its pane, as shown in . We can therefore move the pane so that it is in the correct position relative to the main window, update the main window’s position if necessary, then call Wimp_OpenWindow for both windows in turn.

+

As already noted, we know where the main window should be on screen. We also know the relationship that we want to have between the main window and its pane, as shown in . We can therefore move the pane so that it is in the correct position relative to the main window, update the main window’s position if necessary, then call Wimp_OpenWindow for both windows in turn.

- + -

shows the relationship between the main window and its pane. The tops of the two windows (y1 for the two visible areas) should be level, so we can copy the y1 value from the main window to the pane. The bottom of the pane (its y0) is the height of the pane below the top of the main window.

+

shows the relationship between the main window and its pane. The tops of the two windows (y1 for the two visible areas) should be level, so we can copy the y1 value from the main window to the pane. The bottom of the pane (its y0) is the height of the pane below the top of the main window.

pane%!16 = main%!16 : REM Visible Area Maximum Y pane%!8 = main%!16 - height% : REM Visible Area Minimum Y @@ -218,9 +218,9 @@ pane%!4 = main%!4 - width% : REM Visible Area Minimum X

The code above deals with the position of the pane in the X and Y dimensions, but what about the Z dimension – its position in the window stack? The Wimp requires that panes appear directly above their parent window; however, this is still left up to the application to manage.

-

There's a very practical reason for this requirement. If something like a toolbar pane goes behind its parent window in the stack, then it will very likely be obscured by its parent. Even if the pane is in front, if it isn’t immediately in front, then it’s possible for other windows to get in between as seen in (the application was deliberately broken in order to allow this to occur).

+

There's a very practical reason for this requirement. If something like a toolbar pane goes behind its parent window in the stack, then it will very likely be obscured by its parent. Even if the pane is in front, if it isn’t immediately in front, then it’s possible for other windows to get in between as seen in (the application was deliberately broken in order to allow this to occur).

- +

There are a couple of more technical reasons, too, which relate to the behaviour of the ‘window is a pane’ flag. When checking to see if our main window is at the top of the window stack, or obscured by any other windows (for the ‘window is fully visible’ flag at bit 17 of the window flags), the Wimp will ignore any windows immediately in front of it so long as they have their pane flags set. Without use of the pane flag, a window whose pane obscures any part of its work area can never be reported as being fully visible by the Wimp.

@@ -240,9 +240,9 @@ pane%!4 = main%!4 - width% : REM Visible Area Minimum X SYS "Wimp_OpenWindow",,main% -

Putting all of the code above together, PROChandle_pane_windows() will look as shown in .

+

Putting all of the code above together, PROChandle_pane_windows() will look as shown in .

-DEF PROChandle_pane_windows(main%) +DEF PROChandle_pane_windows(main%) LOCAL pane%, width%, height% REM Get the Window State block for the pane, using some of the spare @@ -281,22 +281,22 @@ main%!28 = !pane% SYS "Wimp_OpenWindow",,main% ENDPROC -

Running our new application should reveal a main window similar to that shown in . If the main window is moved, the pane should remain securely attached at all times.

+

Running our new application should reveal a main window similar to that shown in . If the main window is moved, the pane should remain securely attached at all times.

- + -

The full code can be found in .

+

The full code can be found in .

- +
A small improvement -

If you’re familiar with Draw, then there’s one small difference which you might notice in the behaviour of the toolbox in our example application compared to the toolbox in Draw. If a Draw window is moved off the left-hand edge of the screen, then the toolbox pane stops moving when it hits the edge and begins to retract over the parent window as seen in . Only when the pane is flush with the side of the main window does it begin to move off the screen again.

+

If you’re familiar with Draw, then there’s one small difference which you might notice in the behaviour of the toolbox in our example application compared to the toolbox in Draw. If a Draw window is moved off the left-hand edge of the screen, then the toolbox pane stops moving when it hits the edge and begins to retract over the parent window as seen in . Only when the pane is flush with the side of the main window does it begin to move off the screen again.

- +

Since we have complete control over the positioning of the toolbox pane, this is easy to implement in our own application. The changes needed are all in PROChandle_pane_windows(), where we set the coordinates of the pane’s visible area. Above we used the following fixed calculations:

@@ -316,9 +316,9 @@ pane%!16 = main%!16 : REM Visible Area Maximum Y
  • If the main window is off off-screen, then the pane is anchored by its left-hand edge.
    • -

    The code to implement this can be seen in .

    +

    The code to implement this can be seen in .

    -REM Move the pane so that it's in the correct X and Y position +REM Move the pane so that it's in the correct X and Y position REM relative to where the main window is to go. CASE TRUE OF @@ -336,13 +336,13 @@ ENDCASE pane%!8 = main%!16 - height% : REM Visible Area Minimum Y pane%!16 = main%!16 : REM Visible Area Maximum Y -

    With this in place, our own pane begins to behave in a more Draw-like way when it reaches the edge of the screen, as seen in .

    +

    With this in place, our own pane begins to behave in a more Draw-like way when it reaches the edge of the screen, as seen in .

    - + -

    The full code can be found in .

    +

    The full code can be found in .

    - +
    diff --git a/Downloads/Chapter02/SideBar1/!PaneDemo/!Boot,feb b/Downloads/Chapter02/SideBox1/!PaneDemo/!Boot,feb similarity index 100% rename from Downloads/Chapter02/SideBar1/!PaneDemo/!Boot,feb rename to Downloads/Chapter02/SideBox1/!PaneDemo/!Boot,feb diff --git a/Downloads/Chapter02/SideBar1/!PaneDemo/!Run,feb b/Downloads/Chapter02/SideBox1/!PaneDemo/!Run,feb similarity index 100% rename from Downloads/Chapter02/SideBar1/!PaneDemo/!Run,feb rename to Downloads/Chapter02/SideBox1/!PaneDemo/!Run,feb diff --git a/Downloads/Chapter02/SideBar1/!PaneDemo/!RunImage,ffb b/Downloads/Chapter02/SideBox1/!PaneDemo/!RunImage,ffb similarity index 100% rename from Downloads/Chapter02/SideBar1/!PaneDemo/!RunImage,ffb rename to Downloads/Chapter02/SideBox1/!PaneDemo/!RunImage,ffb diff --git a/Downloads/Chapter02/SideBar1/!PaneDemo/Templates,fec b/Downloads/Chapter02/SideBox1/!PaneDemo/Templates,fec similarity index 100% rename from Downloads/Chapter02/SideBar1/!PaneDemo/Templates,fec rename to Downloads/Chapter02/SideBox1/!PaneDemo/Templates,fec diff --git a/Downloads/Chapter02/SideBar2/!PaneDemo/!Boot,feb b/Downloads/Chapter02/SideBox2/!PaneDemo/!Boot,feb similarity index 100% rename from Downloads/Chapter02/SideBar2/!PaneDemo/!Boot,feb rename to Downloads/Chapter02/SideBox2/!PaneDemo/!Boot,feb diff --git a/Downloads/Chapter02/SideBar2/!PaneDemo/!Run,feb b/Downloads/Chapter02/SideBox2/!PaneDemo/!Run,feb similarity index 100% rename from Downloads/Chapter02/SideBar2/!PaneDemo/!Run,feb rename to Downloads/Chapter02/SideBox2/!PaneDemo/!Run,feb diff --git a/Downloads/Chapter02/SideBar2/!PaneDemo/!RunImage,ffb b/Downloads/Chapter02/SideBox2/!PaneDemo/!RunImage,ffb similarity index 100% rename from Downloads/Chapter02/SideBar2/!PaneDemo/!RunImage,ffb rename to Downloads/Chapter02/SideBox2/!PaneDemo/!RunImage,ffb diff --git a/Downloads/Chapter02/SideBar2/!PaneDemo/Templates,fec b/Downloads/Chapter02/SideBox2/!PaneDemo/Templates,fec similarity index 100% rename from Downloads/Chapter02/SideBar2/!PaneDemo/Templates,fec rename to Downloads/Chapter02/SideBox2/!PaneDemo/Templates,fec diff --git a/Images/Chapter02/side-bar-browser.png b/Images/Chapter02/side-box-browser.png similarity index 100% rename from Images/Chapter02/side-bar-browser.png rename to Images/Chapter02/side-box-browser.png diff --git a/Images/Chapter02/side-bar-complete.png b/Images/Chapter02/side-box-complete.png similarity index 100% rename from Images/Chapter02/side-bar-complete.png rename to Images/Chapter02/side-box-complete.png diff --git a/Images/Chapter02/side-bar-draw-offscreen.png b/Images/Chapter02/side-box-draw-offscreen.png similarity index 100% rename from Images/Chapter02/side-bar-draw-offscreen.png rename to Images/Chapter02/side-box-draw-offscreen.png diff --git a/Images/Chapter02/side-bar-draw.png b/Images/Chapter02/side-box-draw.png similarity index 100% rename from Images/Chapter02/side-bar-draw.png rename to Images/Chapter02/side-box-draw.png diff --git a/Images/Chapter02/side-bar-flags.png b/Images/Chapter02/side-box-flags.png similarity index 100% rename from Images/Chapter02/side-bar-flags.png rename to Images/Chapter02/side-box-flags.png diff --git a/Images/Chapter02/side-bar-loose.png b/Images/Chapter02/side-box-loose.png similarity index 100% rename from Images/Chapter02/side-bar-loose.png rename to Images/Chapter02/side-box-loose.png diff --git a/Images/Chapter02/side-bar-offscreen.png b/Images/Chapter02/side-box-offscreen.png similarity index 100% rename from Images/Chapter02/side-bar-offscreen.png rename to Images/Chapter02/side-box-offscreen.png diff --git a/Images/Chapter02/side-bar-pos-plane.png b/Images/Chapter02/side-box-pos-plane.png similarity index 100% rename from Images/Chapter02/side-bar-pos-plane.png rename to Images/Chapter02/side-box-pos-plane.png diff --git a/Images/Chapter02/side-bar-template.png b/Images/Chapter02/side-box-template.png similarity index 100% rename from Images/Chapter02/side-bar-template.png rename to Images/Chapter02/side-box-template.png diff --git a/panes.xml b/panes.xml index cdd4cdf..4766e4e 100644 --- a/panes.xml +++ b/panes.xml @@ -71,6 +71,6 @@ - +