
What's going on here?

  Rather than simply overwriting your favourite icons with mine, this
  program supports multiple sets of icons, and auto-sensing to adapt
  to the Theme or OS in use.

Isn't there a simpler way?

  Some programs force RISC OS 3 style icons on RO4 users, or vice versa.
  This is obviously counter-intuitive. Others supply RO3 and RO4 sprites
  and choose which to use depending on your OS - which is fine, *if* you
  haven't replaced the appalling RO4 icons with the superior RO3 ones,
  or are using a Theme Manager to change the entire look of the desktop.
  Neither approach will cope with a further change in OS style without
  official updates or requiring YOU to change Obey files, etc.

But I don't use a Theme Manager!

  That's OK, they are not necessary. If you are using one, the program
  will try to adapt to the Theme in use. If not, it will adapt to the OS
  in use, but you can override this.

Which sprites are used?

  The Default scheme is ALWAYS loaded, then a Theme or OS specific file
  is loaded, potentially changing some or all of the Default icons. In
  the absence of a Theme Manager or a manual override, icons suitable for
  your OS version will be used. However, if a Theme Manager is running,
  it will have set a system variable Theme$Current, which will hold the
  name of the Theme in use. A Theme Manager will also set Theme$Path to
  point at the Theme's directory, which can contain sprites for other
  applications in its Apps directory.
  
You said I could override these hateful sprites?

  If you don't have a Theme Manager, you can STILL set Theme$Current to
  the name of the Theme to use. If you don't want RO4 icons, you just
  need to add "Set Theme$Current RO3" to an Obey file in your boot
  sequence somewhere. If you have a calibrated monitor, use "RO3_Linear"
  or "RO4_Linear".

Why oh why?

  People change icons, fact. The supplied sprites may clash with your
  curtains, or not match your carefully contrived blockbuster-tie-in
  Theme. If you change the sprites in the program, then any upgrade is
  going to destroy them again. If you don't copy the upgrade's sprite
  file you will miss any new sprites that were added and dreadful things
  will happen. Having carefully adapted this program's sprites to your
  cat-in-the-coal-cellar Theme you might want to share them with your
  wide circle of friends, but you can't copy the program (please don't)
  so what CAN you do..?

Where to put new sprites

  Given the command *IconTheme <program> <spritefile>, sprites are loaded
  from the following locations:

    <Obey$Dir>.Theme.Default.<spritefile>
    <Obey$Dir>.Theme.<ThemeOrOS>.<spritefile>
    Theme:Apps.<program>.<spritefile>
  
  Firstly, this ensures that the default sprites are always loaded -
  if a program update adds a sprite, you won't lose that icon when
  using an older Theme - you'll just get a sprite that doesn't match.
  
  Secondly, Theme and OS sprites can be distributed within the program.
  If you want to create your own customised sprites, you can create a
  directory inside <Program>.Theme with a unique name, eg "MyTheme". Put
  your sprite files in there - they only have to include the sprites you
  have changed which saves disc space. Now set Theme$Current to "MyTheme".
  
  Thirdly, a Theme author can include sprites for this program within
  the Theme itself - totally external from the program. Again, if this
  program is updated before the Theme, things will still work fine. Even
  if you are not using a Theme Manager, you can point Theme$Path at a
  suitable directory containing an Apps.<program> directory, and put
  your customised sprites in there to keep them separate from the
  application directory. Where both are present, the application's
  Theme sprites are used in preference to the theme's program sprites.

  Fourthly, if there is no Theme, or an unrecognised Theme for which
  the program has no theme directory *and* the Theme has no program
  directory, sprites suitable for your OS version will be used. The
  latest version present in the Theme directory not greater than your
  OS version will be used from this list:

    RO2, RO201, RO3, RO310, RO350, RO360, RO370, RO4, RO420, RO5.

  So, if you are running Select, and the program has no Theme.RO420
  directory but does have a Theme.RO4 directory, the RO4 icons will
  be used.

I want a Theme Manager!

  The good Mr Richard Goodwin can help you, go to:
  
    <http://www.houseofmabel.com/programs/winthemes/index.html>

Can I do the same in my program?

  The IconTheme utility is copyright  nemo 2002-2013. You are hereby
  granted a licence to include this utility within your application if
  and only if:

    It is stored as !App.IconTheme.
    This file is stored as !App.Theme.!ReadMe.
    !App.Theme.Default contains ALL your sprites, not just !Sprites.
    Your default sprites are RO3 style, preferably 16 colours no palette.
    If you supply 256 colour unpaletted sprites (eg RO4), you supply
     linear versions (eg RO4_Linear) by running them through ChangeFSI
     with a 0.454 gamma correction. Sprite palettes can be gamma
     corrected directly.
  
Title:   Theme.!ReadMe
Version: 1.20 (28 Feb 2013)
Author:  nemo
Twitter: @nemo20000