The Musmus Configuration Program  V1.24 (c) Musus Umbra 1997/8
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~  ~~~~~

(The name Musmus is taken from a mispelling of "Musus" in the newsgroup
argonet.acorn.voyager, in case you were wondering :-)

Permission is granted for unlimited personal use & modification.

Permission is granted for redistribution (by any method) provided that:
        No charge is made for this software.  A reasonable charge may be
                made for media / handling / etc. This software is *free*.
        Any distributed copy of this software must be unaltered and entire.
                You may not distribute modified / imcomplete copies of this
                software.  If you fix a bug / add a feature, let me know so
                that I can update the master copy.

As usual with freeware, there is no warranty of any kind.  The author cannot
be held responsible for any loss/damage arising from the use/inability to
use this software.  It is the user's responsibility to determine the fitness
of this software for any purpose they put it to.

(But if it doesn't work, I will try to help :-)


What's New
~~~~~~~~~~
1.24 (26 Oct 1998)
        Slight tweak to allow Musmus to be used with the new, new !Boot
        (eg. the one on the AU CD4) under RO3.1

        Wow; Musmus is nearly a year old :)


1.23 (10 Feb 1998)
        Added 'debug' mode (run with Alt pressed).  Basically, if Musmus
        bombs out on you when you try to 'Set' the configuration, try again
        whilst holding down the Alt key.  This will write a textfile called
        "DEBUGOUT" inside !Musmus that says what it's doing.  Hopefully
        this will help me to fix any problems :)

        Improvements and twiddles (especially to the Drag patches).


1.22 (26 Jan 1998)
        More flexible font size selection, including a menu of common
        sizes, and ability to 'fine tune' font sizes.

        Font preview window to give an indication of whether the font size
        and width are 'good'.

        No longer configures ROM fonts in CMOS (always uses Wimp$Font vars),
        mainly for the sake of IconThang :)

        Slight change to the way the textures, etc.  are changed when 'Set' is
        clicked on (now uses Wimp_StartTask rather than OS_CLI)


1.20 (12 Nov 1997)
        Minor fixes for pre-RiscPCs (now forces a screen redraw after
        changing the texture/etc. in the boot)

        Now uses an application directory to store the configuration
        stuff - it seems that the preRPC "repeat" works differently
        to the RPC one causing plain directories in Choices.Boot.Tasks
        to be opened rather than run...

        Improved solid/transparent drag code


1.10 (31 Oct 1997)
        Solid icon drags option

        Improvements & twiddles


Requirements
~~~~~~~~~~~~
        This application is suitable for use on any machine with RISC OS 3.10
or later providing that it is also using the new Acorn !Boot system (as used
for RiscPCs).  Some options only apply to machines running newer versions of
the Window Manager than those supplied in the RISC OS 3.10 ROMs.

        Basically, !Musmus is aimed at the following two groups of users:

                (1) People who use RiscPCs and wish to alter some of the
                    configuration options that the standard !Configure
                    ignores.

                (2) Argonauts,etc  who have installed the new !Boot and beta
                    test version of the new web browser and suddenly
                    find themselves able to use fonts/textures on the
                    desktop  la RiscPC.  Perhaps they too would like to
                    alter some configuration options !Configure ignores.

        Musmus can still be used without the new Window Manager, but there is
little point in doing so as there are better configuration programs available
for such use.



Upgrading from previous versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Copy this !Musmus over your previous one.  When you first run !Musmus
it will update the old configuration directory to be compatible with the
current version, if necessary.



What it lets you configure
~~~~~~~~~~~~~~~~~~~~~~~~~~
        In the following descriptions, an asterisk in the left margin
indicates a section that only applies to the new window manager.  Musmus can
still be useful without the new window manager but these options will produce
no useful effect.

*       Desktop Font
*               Versions of the Window Manager (Wimp) module later than 3.20
*               (AFAIK) are capable of rendering the desktop using an outline
*               font in place of the system font.  RiscPCs have such a Wimp in
*               ROM, and now earlier machines have access to the latest Wimp
*               (it is installed by the !Install application that is supplied
*               with the beta of the new browser).
*
*               This section allows you to specify what font you would like
*               the desktop to be displayed with and what point size should be
*               used.
*
*               When adjusting the font size/width, you can press shift to
*               'fine tune' the font size.  The sizes shown may look odd,
*               but they are the actual font sizes attainable.  Some common
*               sizes can be quickly selected by clicking on the font
*               size/width instead of the arrows.
*
*               You can also now test your selected font using the button
*               at the bottom of the window.  If you want to change the
*               test messages, alter the !Musmus.Messages file.
*               NB: DO NOT distribute !Musmus with a modified messages file!

        2D window borders
                The RiscPC configuration utility allows you to set 'old-style'
                2D window tools if you so desire.   Older machines would
                normally load 3D window borders as part of their boot sequence.
                The new window manager automatically installs 3D window borders
                when it loads so this option is provided to allow users of
                older machines to turn 3D borders off.  (It still works with
                RiscPCs, by the way).

*       Textured Windows
*               The newer Window Manager modules are also capable of 'tiling'
*               the grey background of windows with a 'texture' sprite.  It is
*               principally this and the outline font support that makes the
*               RiscPC desktop look different to that of earlier machines.
*
*               Turning textured windows on gives you a choice of two
*               textures:
*                       RiscPC is the standard texture used by RiscPCs.
*                       Musmus is a texture that I created for use on my
*                               RiscPC.  I rather like it as it's somewhat
*                               subtler than the RiscPC standard.

        Solid icon drags
                This option turns the use of the DragASprite module (which is
                part of RISC OS) on/off.
                When on, applications that are aware of the DragASprite module
                will let you drag icons rather than the flashing boxes around
                (particularly in Save As windows).
                Please note that the Filer won't use solid icon drags on
                pre-RiscPC machines unless you have installed some sort of
                patch to make it.

        3D look desktop
                Many applications provide two different sets of windows:
                one set is a 3D effect set and the other is a plainer 2D look
                set.  This option allows you to set which 'look' applications
                that are aware of this configuration option will use.
                Note that there are also many applications that simply ignore
                (or are unaware of) this option and always use 2D/3D as their
                authors saw fit.  Indeed, !Musmus always uses 3D windows :-)

        More dithering of colours
                The sixteen standard desktop colours are tailored for 16
                colour screen modes.  Indeed they cannot be exactly displayed
                in standard 256 colour modes, and clearly the 1- and 4-greys
                screen modes cannot display them!
                The desktop overcomes this by choosing the closest available
                colour and using that.  It is possible to make the desktop
                'dither' two colours to produce a closer match and this option
                controls whether the desktop performs this dithering.

*       Toggle size won't hide iconbar
*               The normal behaviour of the desktop when trying to make a
*               window as large as it will go is to not care if the iconbar is
*               covered by the resized window.  By shift-clicking on the
*               toggle size icon the desktop would make sure that the iconbar
*               wasn't covered.
*               When this option is on the situation is reversed, ie. shift-
*               clicking can obscure the iconbar but plain clicking won't.



Setting the configuration
~~~~~~~~~~~~~~~~~~~~~~~~~
        Unlike !Configure, !Musmus doesn't set options as soon as you click on
the relevant buttons.  To actually set the options you must click on the 'Set'
button at the bottom of the window.  If you click with Select, the options
will be set and then !Musmus will quit ( la RiscPC configure).  If you click
with Adjust, !Musmus will remain running after setting the options.


        Some options are held in the machine's CMOS RAM, others have to be set
by the !Boot sequence so that they are enforced each time the machine is
started.  It is because !Musmus needs to be able to place some options in
!Boot that it will refuse to run if your !Boot isn't the new RiscPC style
!Boot.



Clashes with other configure utilities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Desktop font:
        If you have used a different utility to configure the desktop font, it
        is possible that this utility will override the choices you make with
        !Musmus, or vice-versa.

        This is only really likely to happen with RiscPCs where !Musmus will
        override !Configure (however, !Configure will show the settings you
        have made with !Musmus).  This is for the best as !Configure doesn't
        allow you to specify the font size (it assumes 12pt) but !Musmus does.

        There are other desktop font configuring programs (eg. Henry Morgan's
        excellent !WimpFont) which !Musmus may or may not override.

Window texture:
        If you have window textures turned on it's possible that some other
        utility will override the texture you have chosen, and vice-versa
        of course.
        The actual on/off should not clash however.

2D window borders:
        Oh, you know the form by now...


These clashes may occur because it is these options that are set in the !Boot
sequence rather than in the CMOS RAM.



Other Notes
~~~~~~~~~~~

It's probably best to choose one of the fonts that is supplied in ROM with
RISC OS, ie. Trinity, Homerton or Corpus.  These fonts are faster to load as
no disc access is required.

Acorn recommend choosing between Trinity.Medium, Homerton.Medium (both at
12pt) and the system font.

The principal problems with using fonts are:

        1. Many applications were designed with the system font in mind and
           consequently their windows may look different when a proportional
           font is used.  Typically this results in lines of text being clipped
           at one or more edges or being out of alignment.
           Some applications have been designed properly with fonts in mind
           but still suffer if the font you are using is different to the font
           the designer was using.  Ironically, this tends to happen when
           newer applications are used on a machine that displays the desktop
           in the system font.
        2. Not all fonts have the full latin-1 character set.  This can be
           a real nuisance as some applications use such characters as  (the
           1/4 character) in their windows.  Indeed, !Musmus uses the 
           characters in it's font size icons.  Check (using !Chars) whether
           the font you intend to use is 'complete'.

Both these problems are largely alleviated by using one of the two standard
fonts Acorn recommend.  Problem 1 can be alleviated by using a size of 12pt
and a suitably smaller/larger width.  Experimentation is the key here.  Note
that some characters are always taken from the WimpSymbol font and so don't
need to be in the font you use.

Do make sure that you have set a reasonable font cache using !Configure :-)


Version History
~~~~~~~~~~~~~~~
        1.02    Initial release

        1.10    Improved detection of current Wimp font
                Now writes configuration to <Boot$ToBeTasks> rather than
                        <Choices$Write>.Boot.Tasks
                New option to force 'solid' icon drags with DragASprite

        1.20    Now uses !Musmus dir in Tasks to store the startup stuff
                Screen redraw is forced after changing font/texture/etc
                        during boot.
                Recoded the solid/transparent drag patches

        1.21    Added font preview, extended font size selection
                and changed OS_CLI calls to Wimp_StartTask for issuing
                *commands.

        1.22    Added hourglass for font menu
                Shift key for fine tuning font size

        1.23    Alt key debug mode
                Drag patches now Wimp_StartTasked rather than Filer_Run
                Drag patches now set their own slot size and use
                        Wimp_ReportError if something goes wrong


Tools & Libraries
~~~~~~~~~~~~~~~~~
        This section managed to get missed out of the previous release :(

        !Musmus was built using DeskLib, "the freeware C library for RISCOS
        machines".

        Other free/shareware tools used in the creation of Musmus included:
                 StrongED 4.50
                 StrongHelp 2.50
                        http://login.eunet.no/~guttorvi/strong.html
                 ASM
                        ftp://micros.hensa.ac.uk/micros/arch/riscos/f/f029

                Desklib is available from:
                        ftp://micros.hensa.ac.uk/micros/arch/riscos/a/a129

        I heartily recommend all of the above :)



TTFN, Adny (that isn't a typo BTW).

Contact:
        e-mail:         musus@argonet.co.uk
        WWW:            http://www.argonet.co.uk/users/musus/
        Snail:          c/o 23 Baronsway, Whitkirk, Leeds, LS15 7AW, ENGLAND.
