
    ####             #    #     # #
    #   #            #    #       #         The FreeWare C library for 
    #   #  ##   ###  #  # #     # ###            RISC OS machines
    #   # #  # #     # #  #     # #  #  ___________________________________
    #   # ####  ###  ##   #     # #  #                                      
    #   # #        # # #  #     # #  #   Please refer to the accompanying
    ####   ### ####  #  # ##### # ###   documentation for conditions of use
    _______________________________________________________________________

    Note that although this software is supplied free of charge, copyright
    applies to it. All rights are reserved, except for the following:

    This software may be copied and distributed without restriction so long
    as the following conditions are met:
      a) The copyright messages and these conditions are distributed intact
         in all such copies
      b) Only original, unaltered copies of this software are to be
         distributed (so that this library remains consistent over time)
         -PLEASE DON'T alter the library and pass it on: Alter it and
         send alterations back to the moderator (see below) so that
         your code becomes an official update rather than a hack.
      c) No profit is made through such distribution

    This software may be used in the production of any piece of software so
    long as the authors acknowledge in the final product distribution that
    DeskLib (or parts thereof) was used.

 
    ***********************************************************************
    * This program is distributed in the hope that it will be useful,     *
    * but WITHOUT ANY WARRANTY; without even the implied warranty of      *
    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                *
    * Bug reports, fixes, or any extra code may be sent to the moderator, *
    * who may or may not act on them as he deems fit.                     *
    ***********************************************************************
    _______________________________________________________________________

    NOTE ALSO that DeskLib is totally unaffiliated to anyone or anything.
    Just because I now work for Computer Concepts does not mean that this
    product is in any way related to Computer Concepts Ltd.
    All comments about people and companies in this product are either
    personal opinion or were factual at the time of writing. Most such
    comments are included only so that the user knows the REASON for
    things having been done as they were.
    _______________________________________________________________________

 About DeskLib
 =============

 After some bad experiences with Acorn's RISC OS Lib, I decided that a new,
 well written, professionally-finished library would be very useful. Acorn
 appeared to be uninterested in fixing RISC OS Lib for me, so I managed to
 rustle up a band of merry programmers to help me write a completely new
 library, from scratch, and design things before they were written.

 The result is (or will be ?!) DeskLib.

 DeskLib is a set of ANSI C and ARM assembler sources intended to add to or
 replace PARTS of the libraries supplied with Acorn Desktop C. Many parts of
 DeskLib replace parts of the Acorn Libraries, but many portions of the
 library code can be used in conjunction with Acorn's libraries, or as a base
 from which you will be able to more easily write code for use with Acorn's
 Libraries, so don't go away just yet!
 This library is intended both as an alternative to Acorn's RISC OS Lib as
 well as a useful source of fragments of code to include into your own
 sources.

 All efforts have been spent to make the library code as generic, robust,
 and useful as possible, as well as attempting to provide a comprehensive
 range of function calls, from basic SWI-level support to high-level
 functions such as automatic dialogue-box creation, handling and
 result-return in a single function.

 Where possible, routines have been optimised (to some extent) for
 efficiency, but the primary goals are high-level interfaces that make WIMP
 programming quick and easy. (If the user wants to specifically do something
 special, and wants it fast, the source code for DeskLib is available, so any
 functions can be adapted for the user's needs as necessary...)

 All possible action is taken to keep code size down without adversely
 affecting the functionality of the library: Individual functions are added
 to the library separately, so that including one function in your code
 does NOT include the (unwanted and unneeded) code for several others.

 Where possible, code is written as a standalone unit to avoid pulling in
 too much other DeskLib code when you include a function.

 Attempts have also been made to rationalise the naming conventions used,
 while keeping as much compatibility with the Acorn libraries as possible.
 Thus, data structures are as similar to acorn conventions as possible, but
 with occasional names altered to improve readability and/or consistency.
 We have reverted back to basing our naming on Acorn's very well designed
 SWI interfaces and their use, rather than sticking with Acorn's RISC OS Lib
 abstractions to keep this environment closer to it's Assembler and BASIC
 cousins, which will make it easier to port programmers between environments.

 As a result, DeskLib has been developed by individual programmers working
 to some basic guidelines, with me, the moderator, taking in the code,
 tidying up any "loose ends" I find, and then including the final code in
 the Library. This has helped to keep everything as consistent as possible
 throughout the library. (Though I can't guarantee that the library is
 perfect, I believe it is far superior to RISC OS Lib in the areas it
 currently covers)

 The code has been written to provide a high-level interface that supports,
 encourages, and all BUT forces programmers to use a more consistent
 interface design, which will be brought into line with the Acorn Style
 Guide as soon as Acorn make up their minds...
 The programmer using DeskLib is encouraged to use our more generic template
 and menu routines, so that the END USER of the product has more control 
 of the look, feel, layout, and hotkeys used in the program.

 However, another important concept is that YOU are in charge, and DeskLib
 is just a tool for you to use, so it should not force you against your will
 if possible. Thus, we provide unrestricted low-level access as well. And by
 providing the sources, we make it possible for you to do low-level "tweaks"
 on our high-level data structures without the fear that you might be
 treading on the toes of some other code...

 We also feel it is important to distribute the library sources freely, so
 that you may improve or alter the library to suit your own needs, and
 hopefully send back any improvements or bug fixes to me so that they may be
 officially incorporated into the DeskLib distribution. Also, you can SEE
 what functions do, and thus KNOW what they do, and therefore be able to
 cope with what they do, rather than tripping over low-level implementation
 details/bugs that the author didn't bother to make you aware of.

 We have absolutely NO objection to including SEVERAL DIFFERENT code modules
 that do essentially the same thing, so that you may CHOOSE the one that
 suits you best.



The future
 As well as growing to include more and more code resources, three important
 goals for the future of this Library are:
  * Conversion to assembler. Small and simple functions (Icon_Select, etc)
    are extremely easy to convert to assembler. This also has the advantage
    of reducing their size at the same time as increasing efficiency. The goal
    is to convert as much of the library as possible to a more efficient
    implementation over time. This will not affect the interface, so existing
    applications can benefit from the conversion by simply relinking with
    the new functions.

  * Support for Glazier's 'Glass' template format, including menu, window, icon
    and hotkey templates, and special creatures such as 'meta-icons' (things
    like slider icons which are made up of more than one Wimp icon, but can
    be treated by the main program as a single entity)

  * Production of a shared DeskLib code library relocatable module, along
    similar lines to the existing ANSI SharedCLibrary. This will basically move
    the most important small functions into a SMALL relocatable module so that
    the code resources may be shared by all desktop tasks, including ones
    written in C, assembler, and (hopefully) BASIC.



Authors
 If code you have written is incorporated into this library, you still
 retain your copyright for it. However, if you wish to retract
 copy-permission for a part of DeskLib you have written, then it will be
 removed from *future* releases of the distribuion, and the retraction will
 not affect previous release versions of the library, or any software
 product that used them. Probably an equivalent bit of code will then be
 written by somebody else to fill the gap.

 If DeskLib is updated by someone writing code based upon your suggestions
 and/or code, then they retain copyright for that which they have written,
 though you will be credited in the updated file(s).

 If you write any FreeWare using the DeskLib libraries, it would be really
 nice of you to send me a copy of the sources and final application to
 possibly be included in future DeskLib releases as tutorial/demonstration
 code, or at least distribute your sources (or parts thereof) with your
 application so that they may serve as example code for others.

 For documentation on using DeskLib in your own programming projects, and
 submitting your own code/ideas for inclusion in DeskLib, please read the
 files in the Docs directory. Note that most of the documentation of
 function calls is provided in the form of comments in the relevant header
 (.h) files at present.

 The last point is that although we are trying to provide complete useful
 code, some bugs are bound to fall through the net... Some decisions on
 naming or data structures may seem bad to you (some do to me), but we
 have our reasons (usually consistency) for doing things this way.
 We are doing our best: Constructive criticism is welcome, but please
 don't winge at us - If you don't like something, then don't bother me - go
 away and spend a year writing the code yourself... I don't welcome
 criticism from people who are unwilling to write the code themselves.

 Now please go back and read the conditions that you skipped at the top of
 this file, because they are important ;-)

 ---------------------------------------------------------------------------

 Authors:
   This library has been built up by a group of authors. Individual files
   contain copyright notices for the author(s) who created them. The
   authors (and other contributors) I've remembered to write down here
   are (alphabetically):

    Peter Arnold
    Matthew Astley
    Lee Atkinson
    Philip Banks
    Shaun Blackmore
    Cy Booker
    Tim Browse
    Tony Bryant
    Philip Colmer
    Erik de Kort
    Keith Hall
    Tony Houghton
    Jason Howat
    Tony Howat
    Peter Gaunt
    Tom Kirby-Green
    David Leftley
    David Lenthall
    Keith Marlow
    Stuart Martin
    Sergio Monesi
    Ernest Ong
    Ainsley Pereira
    David Pilling
    Edouard Poor
    Andrew Sellors
    Julian Smith
    Ben Summers
    Neil Tarrent
    William Waghorn
    Robin Watts
    Jason Williams
    Mark H. Wilkinson
    John Winters

   Thanks also to the numerous others who have offered suggestions, etc.
   Thanks to Acorn for designing the machine and the compiler.
   And for RISC OS Lib??  I guess so, or this would never have appeared, and
   I would be forced to relax in the weekends ;-)

 -----------------------------------------------------------------------------

The above was mostly written by Jason Williams, the original DeskLib moderator

 -----------------------------------------------------------------------------


 Contacting the moderators:

 If you find any bugs or problems in DeskLib, or if you can supply
 suggestions or code for alterations, additions, or tutorial applications,
 then please write to either of:
 
   Julian Smith
   Department of Experimental Psychology
   University of Oxford
   South Parks Road
   Oxford
   OX1 3UD
   UK
   
   Craig Beech
   c/o Echelon Software
   30 The Deerings
   Harpenden
   Hertfordshire
   AL5 2PE.
   UK

(including a small lump of cash (1 british pound would suffice) to cover
return postage would be appreciated!)

 or email either of:
   julians@festival.ed.ac.uk
   c-beech@csm.uwe.ac.uk

 A set of DeskLib web pages is reachable from:
 http://cogsci1.psych.ox.ac.uk/~julians/
 This site may also have beta versions of DeskLib.
 

 These addresses were valid as of the release date.
 If you fail to reach us at any of them, then we can also generally be
 contacted by posting an article onto usenet's comp.sys.acorn newsgroup,
 which we (or someone) will be watching regardless of where we happen to be
 living.

 Updates to this library are likely to be distributed over comp.sources.acorn,
 various Archive servers, selected "PD" Libraries, and by high velocity llama.

 If you wish to use DeskLib in a commercial product (or ANY important or
 global-release software for that matter), then PLEASE write to us at the
 above addresses enclosing a blank 3.5" disc, and I will endeavour to answer
 any queries you have, and forward you the latest version of the library
 sources. It is in your own best interests! The only way to get support is
 by contacting us.

