<document title="Windows Scroll">
<define name="version" value="0.60">
<define name="date" value="12 October 2003" length=30 align="right">





<literal mode="Text">
=============================================================================
Windows Scroll - Scroll around windows using the mouse           Version $$version$$

(C) Stephen Fryatt, 2002-2014                  $$date$$
=============================================================================

</literal>







<chapter title="Licence" file="Licence">

<cite>Windows Scroll</cite> is licensed under the EUPL, Version&nbsp;1.1 only (the &ldquo;Licence&rdquo;); you may not use this work except in compliance with the Licence.

You may obtain a copy of the Licence at <link ref="#url http://joinup.ec.europa.eu/software/page/eupl">http://joinup.ec.europa.eu/software/page/eupl</link>

Unless required by applicable law or agreed to in writing, software distributed under the Licence is distributed on an &ldquo;<strong>as is</strong>&rdquo; basis, <strong>without warranties or conditions of any kind</strong>, either express or implied.

See the Licence for the specific language governing permissions and limitations under the Licence.

The source for <cite>Windows Scroll</cite> can be found alongside this binary download, at <link ref="#url http://www.stevefryatt.org.uk/software">http://www.stevefryatt.org.uk/software</link>

The necessary libraries and build tools can be found at <link ref="#url http://www.stevefryatt.org.uk/software/build">http://www.stevefryatt.org.uk/software/build</link>

</chapter>




<chapter title="Introduction" file="Introduction">

<cite>Windows Scroll</cite> is a small module for RISC&nbsp;OS to provide the kind of scrolling that is available on <cite>MS Windows</cite> when the wheel button of the mouse is pressed.  It does not, however, need a wheel mouse to work.

There are still things to be done to <cite>Windows Scroll</cite>: see <link ref="Issues">Known issues</link> for details.

</chapter>




<chapter title="Installation and use" file="Using">

To install <cite>Windows Scroll</cite>, copy the <file>!WinScroll</file> application on to your hard disc and then double-click on it to run it.  If you want to use <cite>Windows Scroll</cite> permanently, add it to your machine&rsquo;s boot sequence.

The <file>!WinScroll.!Run</file> file inside the application can be modified if you wish to change the <cite>WinScroll</cite> configuration (speed, key-presses or sprites). Double-click on <file>!WinScroll</file> with <key>shift</key> held down to open the application folder, then double-click on <file>!Run</file> with <key>shift</key> held down to load it into a text editor. The comments in the file, in conjunction with the <link ref="Config">Configuration and options</link> section below, should explain the possibilities. Save the file and double-click on <file>!WinScroll</file> again to use the settings.

Once installed, clicking <key>ctrl</key>-<mouse>menu</mouse> over a window with scroll-bars will open a small <window>arrow window</window> under the mouse pointer.  This contains a &lsquo;centre point&rsquo; and a set of arrows indicating which scroll directions are possible (this depends on which scroll bars are present on the original window).  Moving the mouse away from the point in the direction of one of the arrows will cause the window to scroll in that direction; the further the mouse is moved, the faster the scroll.

To stop the scrolling, click the mouse (doing this over the <window>arrow window</window> will prevent the mouse click being registered anywhere else).

</chapter>




<chapter title="Configuration and options" file="Config">

Various configuration options are available for <cite>Windows Scroll</cite>.

Most configuration of <cite>Windows Scroll</cite> is done via the command line, using the <command>*WinScrollConfigure</command> command.  This takes a number of parameters, that allow the various options to be set.  It is not necessary to supply all of the parameters each time.  If the command is used with no parameters, the current settings are displayed.


<comdef target="*WinScrollConfigure" params="[options]">

The <command>WinScrollConfigure</command> command is used to configure the WinScroll module.  It takes a number of parameters, depending upon which aspects of operation are to be configured.

The options available are as follows:

<definition target="-Button &lt;button&gt;">
The <command>-button &lt;number&gt;</command> option sets the mouse button used to invoke the scrolling (when pressed along with the modifier key).  The value passed is one of:

<list>
<li>4 &ndash; <mouse>select</mouse>
<li>2 &ndash; <mouse>menu</mouse>
<li>1 &ndash; <mouse>adjust</mouse>
</list>

For example: <code>-Button 2</code> would set the <mouse>menu</mouse> button.

The default button is <mouse>menu</mouse>.  Using other buttons is not recommended, since it may not always be possible for <cite>Windows Scroll</cite> to see them.
</definition>

<definition target="-Modifier">
The <command>-modifier &lt;key number&gt;</command> option sets the key that must be pressed with the chosen mouse button to start a scroll.  The value passed is an &lsquo;Internal key number&rsquo;, a list of which can be found in the PRMs or StrongHelp Manuals; the most useful codes are:

<list>
<li>0 &ndash; <key>shift</key> (either, but 3 &ndash; left, 6 &ndash; right)
<li>1 &ndash; <key>ctrl</key> (either, but 4 &ndash; left, 7 &ndash; right)
<li>2 &ndash; <key>alt</key> (either, but 5 &ndash; left, 8 &ndash; right)
<li>9 &ndash; <mouse>select</mouse>
<li>10 &ndash; <mouse>menu</mouse>
<li>11 &ndash; <mouse>adjust</mouse>
</list>

For example: <code>-Modifier 4</code> would set the left <key>ctrl</key> key as the modifier.

The default key is <key>ctrl</key>.  Since the key-presses are not masked out from other tasks, be careful which keys you use.  Mouse buttons are possible, with the problems that the clicks will still be registered and that PS/2 mice do not register more than one button at a time.
</definition>

<definition target="-Speed">
The <command>-speed &lt;speed&gt;</command> option sets the speed of the scrolling and is used in conjunction with the <command>-square</command> and <command>-linear</command> options.  The &lt;speed&gt; parameter is used as a divider: the lower the value, the faster the scrolling for a given mouse movement.

For example: <code>-Speed 4</code> would set the set the speed to half the default.

The default speed is 2 (linear).
</definition>

<definition target="-square and -linear">
The <command>-square</command> and <command>-linear</command> options set whether the speed increase is linear compared to the distance between the centre point and the mouse or if it goes up according to the square of the distance.  When using square control, the speed parameter should be set higher, say 40 to 50.

The default is for linear control.
</definition>

An example command might be

<codeblock>
*WinScrollConfigure -Speed 40 -Square
</codeblock>

to set &lsquo;square-response&rsquo; scrolling at a sensible speed factor, or

<codeblock>
*WinScrollConfigure -Modifier 9
</codeblock>

to set the modifier key to be <mouse>Select</mouse>.

</comdef>

<subhead title="Sprite files">

It is possible to change the sprites that are used by <cite>Windows Scroll</cite>.  On loading, the system variable &lt;WinScroll$Sprites&gt; is checked.  If this is set and pointing to a valid sprite file, the appropriate file (based on the usual Wimp suffixes) is used in preference to the default sprites stored in the module.

See the sprite files in the <file>Source</file> directory for details about what sprites are required.  When creating a new file, make sure that all the sprites keep the same dimensions and colour depth.

</chapter>



<chapter title="Known issues" file="Issues">

<cite>Windows Scroll</cite> is still in development, and there are a number of known problems.  If anyone finds the application useful, I will deal with these.

In addition, the interface (in particular the invocation keys) are up for alternative suggestions.  I would also appreciate bug reports or suggestions for improvements.  My email address is at the end of this file.

The issues I am aware of at present are:

<list>
<li>Scroll area bounds are not checked before Open Window requests are sent to applications.  This is not an issue on RISC&nbsp;OS&nbsp;4, but I have not tested it on earlier versions.  It is easily fixable.

<li>The way in which menus from Toolbox applications are dealt with is still not ideal (simply calling <code>Wimp_CreateMenu,-1</code> to close them when the open).

<li>Changes to the mouse pointer can be overridden by other applications as the mouse passes over their windows.

<li>Composite windows, where the scroll bars are on a separate window to the one containing the document, will not work as <cite>Windows Scroll</cite> can not see the scroll bars and so will not agree to scroll the window.  <cite>Impression</cite> and <cite>Personal Accounts</cite> are two &lsquo;offenders&rsquo; that I know of.

<li>Mouse clicks should be filtered out while the scroll is active, so that the terminating click does not affect the window below the pointer.
</list>

</chapter>




<chapter title="Version history" file="History">

The following is a list of all the versions of <cite>Windows Scroll</cite>.

<subhead title="0.10 (28 September 2002)">

<list>
<li>First publicly released version.
</list>


<subhead title="0.20 (30 September 2002)">

This version was not released.

<list>
<li>Added error trapping so that WinScroll task does not crash if the window being scrolled disappears for whatever reason.
</list>


<subhead title="0.30 (7 October 2002)">

<list>
<li>Added low and hi-res sprites and changed design to be all-black arrows.
<li>The &lt;WinScroll$Sprites&gt; system variable is added, to allow for user-defined sprites at run-time.
<li>&lsquo;Linear&rsquo; and &lsquo;Square&rsquo; speed controls added.
<li>*WinScrollConfigure added, with support for -Key, -Modifier, -Speed and -Linear/-Square.
<li>Any mouse-click now terminates the scroll function.
<li>Menus opened by the ToolBox are now closed.
<li>Mouse pointer changes during drags.
</list>


<subhead title="0.51 (6 December 2002)">

Public Beta release.

<list>
<li>Module converted to new format and checked for 32-bit compatibility.
</list>


<subhead title="0.52 (2 February 2014)">

<list>
<li>Corrected window stack flags to work properly on Select and RISC&nbsp;OS&nbsp;5.
<li>Converted source to ObjAsm format and checked for ARMv7 compatibility.
<li>Restructured archive contents into application format for ease of installation.
</list>

</chapter>




<literal mode="Text">

Updates and Contacting Me
-------------------------

  If you have any comments about Windows Scroll, or would like to report any
  bugs that you find, you can email me at the address below.

  Updates to Windows Scroll and more programs for RISC OS computers can be
  found on my website at http://www.stevefryatt.org.uk/software/

  Stephen Fryatt
  email: steve@stevefryatt.org.uk
</literal>
