The Datafile PD-CD 5/DATAFILE_PDCD5.iso/utilities/a/armedit/Docs/Banner

Text File | 1997-01-20 | 9.2 KB | 235 lines

File        : Banner
Date        : 20-Jan-97
Author      : © A.Thoukydides, 1995, 1997
Description : Description of the "Banner" application.


INTRODUCTION

The "Banner" application displays a banner window in the desktop, either for
a predetermined length of time or until it is clicked on with the mouse.
It is intended to be used while an application is loading, but it may also be
used for other purposes. The layout of the window is specified by a templates
file, which may include requests for text substitution from an optional
messages file. Anti-aliased fonts are fully supported, and sprites are loaded
into the application sprite area rather than the shared wimp pool.

This application is FreeWare; it may be freely used and copied. However, I
retain full copyright. See the section on "LEGAL MATTERS" for more details.


USAGE

The syntax is:

    Banner [<time>] [-Messages <messagesfile>] [-Sprites <spritefile>]
           [-Templates <templatesfile>]

where

    <time>          - The time in centi-seconds for which the window should
                      be left open. If no value is specified then the window
                      will remain open until the pointer is clicked on it.
                      A reasonable value is 250 (for 2½ seconds).

    <messagesfile>  - The pathname of the messages file to use. The default
                      filename is <Obey$Dir>.Resources.Messages.

    <spritefile>    - The pathname of the sprites file to use. The default
                      filename is <Obey$Dir>.Resources.Sprites.

    <templatesfile> - The pathname of the templates file to use. The default
                      filename is <Obey$Dir>.Resources.Templates.

All of the keywords may be abbreviated to their first letter. The files
are used as follows:

    Messages    - A MessageTrans file containing text to replace indirected
                  text only icons with. The text following an "M" command in
                  an icon validation string, up to the next semi-colon or
                  terminator, is used as a token to pass to
                  MessageTrans_Lookup. If a match is found then the icon text
                  is replaced by the specified string, otherwise the icon
                  text is unchanged. This can be used, for example, to
                  display the program version number of licence details.

    Sprites     - A sprite file to be loaded into the application sprite area.
                  The program first checks whether a file more suitable for
                  current mode is present (e.g. Sprites23, Sprites22 etc)
                  using the same rules as for IconSprites. If a high-res
                  monochrome mode is being used then Sprites23 is tried,
                  otherwise the file SpritesXY is tried (where X and Y are
                  the number of OS units per pixel in the two directions).

    Templates   - A wimp template file which must contain a window
                  definition called "banner" to be displayed.

Only the Templates file is actually required; the other two are optional.

These files can be shared with the main application; in fact it is quite a
good idea to do so, e.g. a Version token in the messages file can be used for
both the ProgInfo window and the banner.

It is up to the user of this program to ensure that it is given a suitably
sized wimpslot. The memory required is given approximately by:

    Size of the Banner executable
  + Combined sizes of the three resource files
  + 6 kbytes of extra workspace

If you have alternative sprite file remember to use the size of the largest
file when deciding how much memory to allocate. If there is insufficient
memory to load the high-res sprites file then the standard resolution version
is tried instead.

Probably the best way of using this program in the start-up of an application
is to have two Obey files. The first one, "!Run", is started when the
application is run:

    | > <App$Dir>.!Run

    | Set a system variable to the application directory
    Set App$Dir <Obey$Dir>

    | Load the application sprites
    IconSprites <App$Dir>.!Sprites

    | Check that there is likely to be sufficient memory for both programs
    WimpSlot -min 576K -max 576K

    | Start the next part of the program loading once "Banner" has initialised
    Filer_Run <App$Dir>.!Run2

    | Ensure that there is sufficient memory for the "Banner" program
    WimpSlot -min 64K -max 64K

    | Run the banner program, leaving window open for 2.5 seconds
    Run <App$Dir>.Banner 250

Remember that "Banner", unless told otherwise, will look for its resources in
"<Obey$Dir>.Resources", which in this case will be the same as
"<App$Dir>.Resources". The second Obey file, "!Run2", is started by the first
one using a "Filer_Run" command causing it to start once the "Banner"
application has started polling the wimp:

    | > !Run2

    | Load any required resources, e.g. modules

    | Check that there is still sufficient memory to run
    WimpSlot -min 512K -max 512K

    | Finally start the application
    Run <App$Dir>.!RunImage %*0

This is not the only way in which "Banner" can be used, but it is one of the
better ways as it does not significantly increase the start-up time of the
application; the application and resources can continue loading while the
banner is being displayed.


LEGAL MATTERS

The "Banner" application and documentation is supplied "as is"; no warranty,
express or implied, of the merchantability of this software or its fitness
for any particular purpose is given. In no circumstances shall the author, or
any provider or distributor of this software, be liable for any damage, loss
of profits, or any indirect or consequential loss arising out of the use of
this software or inability to use this software.

This application is FreeWare. Permission is granted for anyone to distribute
it unchanged and in its entirety, providing that no profit is made in the
process. The "Banner" application may not be distributed if modified or
incomplete; neither may it be distributed without this documentation.

To use this application, or any part of it, as part of a system or other
application that is for sale (for however much and for whatever reasons) or
released as copyright material then the author's express permission in
writing must be obtained. The author maintains copyright on all the material
supplied and reserves the right to change these conditions at any time
without notice.


CONTACTING THE AUTHOR

I would be interested in hearing of any bugs or other unexpected features in
this application, and will endeavour to correct any such problems in future
releases. Suggestions for improvements are also most welcome. Implementation
depends upon practicability and on how much spare time I have.

If you have any comments on this program, or would like to suggest ways in
which it could be improved, I can be contacted at one of the following
addresses:

    Thalna
    2 Dukes Drive
    Bearwood
    Bournemouth
    Dorset
    BH11 9SZ

    [e-mail]

If in any communication you make specific reference to the program code please:

    Quote the version number and date of the application (it is contained
    near the start of the executable binary).

    Refer only to the application as released.

    Supply as many details as possible about the problem, including the
    hardware and software configuration of the machine being used.

Please send a stamped and self addressed envelope, or give details of how to
contact via e-mail, if you would like a reply.

I hope you find this application of some use.


ACKNOWLEDGEMENTS

I would like to the thank the following people for their contributions to
the development of this application:

    Acorn Computers - The Risc PC, RISC OS and the ObjAsm assembler.
    Aidan Corey     - Good ideas for improvements.
    Dominic Symes   - The brilliant !Zap editor; get a copy immediately.
    Robin Watts     - !Larger, the greatest backdrop program ever.
    Mark Wooding    - !Glass, the best template editor.

and everyone at the Acorn User Group in Oxford.


THINGS TO DO

The following are changes that may be made to this application sometime in
the future:

    Only accept ";" as validation string separator if it is not preceded by a
    "\" character.

    Delete "M" commands from validation strings before passing the window to
    the wimp. This would protect against any later versions of the wimp
    trying to misuse "M" validation strings.


VERSION HISTORY

0.00 (16-Apr-95)    Original development version.

0.01 (21-Apr-95)    Command-line arguments added to configure display time and
                    filenames.

0.02 (22-Apr-95)    Corrected handling of fonts on mode changes. Misaligned
                    word load removed. Wimp_ReadSysInfo used to get sprite
                    file suffix for current mode, rather than generating it
                    from mode variables. Linked as a binary rather than AIF.
                    Window recentred on mode change. Improved error handling.
                    Font table moved from binary image to application
                    workspace.

0.03 (03-May-95)    Tidied up the code and improved the documentation.

1.00 (09-May-95)    First official release version.

1.01 (20-Jan-97)    Error checking improved when loading templates file.