ARM Club 1/ARM_CLUB_CD.iso/contents/apps/languages/progs/shell/!Help

Text File | 1994-07-08 | 12.1 KB | 312 lines

              The Shell library
              -----------------


________________________________________________________________________





1. About Shell
--------------


Shell is a set of C routines which allow you to easily make multi-tasking
programs which can display complicated items like arrays, bar-graphs,
blocks of text etc in windows. It uses the routines in the DeskLib C
lbrary. I wrote the Shell library to enable easy development of
neural-network simulation programs for my PhD, so it is probably of most
use to    people wanting to display large amounts of data in windows. It
also provides lots of example code for writing wimp applications.

Most of the routines are not optimised for speed, but for ease of use - for
instance, there are routines which print text in a window using
workarea coordinates, so that window-redrawing routines can work
exclusively in workarea coordinates. There are similar routines (some
macros) for drawing lines/circles/rectangles etc.

The header files are fairly well commented, and the example program ShellEG
should provide a clear idear of what Shell routines can do, and how to
use them.


How Shell works:

When you use Shell, you open one or more Shell-windows. The redrawing of
these windows is done entirely by the Shell library using DeskLib's Event_
library - you don't have to worry about redraw rectangles etc.

Each Shell window can have any number of rectangle inside it. Each
rectangle has a structure assciated with it, which contains all the
information needed to redraw the rectangle, i.e. a pointer to a
redrawing function, and various other data like the rectangle's
dimensions. Some simple rectangle redrawing functions are already part
of Shell, to draw a 2D array of text, a bar graph, a block of text etc.
etc.

When a redrawing function is called, it can work in coords relative to
the rectangle, not the window workarea coords or the screen's coords; to
do this, use the supplied strucure Shell_convertpoint 'convert', which
actually represents the screen coords of the bottom-left of the
rectangle. To plot things, use Shell_Plot( plotcode, x, y, convert), or
Shell_Circle( x, y, r, convert) etc. These are macros which will use
'convert' to find the screen coors. See some of the supplied redraw
functions for examples of using these, e.g. sources.c.BarGraph,
sources.c.TextRect, sources.c.Label.

You can add a rectangle to a window with Shell_AddRectangle, supplying a
function which Shell will call when this rectangle needs redrawing. If,
instead, you just want a standard rectangle type, call Shell_Add2DArray,
Shell_AddBarGraph, Shell_AddTextRect or Shell_AddGeneralArray etc. Many
of these higher-level still require a simple function from you; e.g.
Shell_AddGeneralArray needs a function which, given an x and y, returns
a string to display at location (x,y) in the rectangle.

The TextRect functions allow you to print to a rectangle using the same
syntax as 'printf'. Thus you can have large amounts of text in a block
in a window providing the functionality of running a program in a
taskwindow, but also allowing the use of the more graphical displays
such as arrays and bar-graphs.

You can also force rectangles/arrays etc. to be redrawn, for instance if
their contents have changed.

You can still open windows independantly of Shell if you wish - Shell
uses DeskLib's Event_Poll function, so any such window should be redrawn
etc using Event_ handlers. Also, if you register a handler for
event_REDRAW, you can do your own redrawing inside Shell windows.

You can use Shell_ to help debug a Wimp application, as long as the
application uses DeskLib's Event_ library. For example, you can output
diagnostic information to a window using Shell_Printf( ...) from within
your code. You shouldn't do this in the middle of redrawing code, for
example, as this will confuse the Wimp. There is now a function
Shell_WaitPrintf( ...) which you can use for this purpose. It is very
useful if you want to find out why your redrawing is not working.


I wrote Shell for use with programs which are basically mathematical models,
that take hours to run, which I wanted to run in the background. i.e. they
aren't conventional event-driven Wimp application. Because of this, I've
written a very simple front-end to Event_Poll called Shell_Poll which
repeatedly calls Event_Poll until an event_NULL is received. To make a
program multi-tasking, just sprinkle a few Shell_Poll's through a program.
Thus by calling Shell_Poll frequently in your program, the system multitasks
nicely, but your program gets time when there are event_NULL's available.
There is also a macro Shell_PollSlow which calls Shell_Poll only if
sufficient time has elapsed since the last call to Shell_Poll. This time
interval is set with Shell_SetPollInterval. Using small values will
result in a smooth desktop, while larger values will result in fewer
calls to Wimp_Poll giving a jerky desktop but a faster program.

You don't have to use Shell_Poll - if your application is a conventional
event-driven one, you should just call Event_Poll directly.


You can also set the frequency with which rects are updated so that you
can tell Shell that a rect's contents have changed very frequently, but
Shell won't call Wimp_ForceRedraw each time. This speeds up your program
significantly as it means it's not continually readrawing a window.

Many rectangles can be saved in the desktop by Shift-Menu clicking on
them. e.g. you can save the times-table in the example program as text.

One very useful feature is a PlainRect. This is just a rectangle inside
a window, but when you save it, it saves its contents as a sprite,
allowing you to extract bar graphs/blockrects etc directly without
grabbing bits of the screen with !Paint.

Shell has quite a few rough edges - for e.g. the maximum nuber of
windows is #defined as 4, which is ample for my programs but might not
be enough for everyone. The windows are stored in an array, but they
should really be a linked list (like the rectangles in each window,
which use DeskLib's LinkList functions).

Other things which aren't perfect are:

FontLabel.c    the font handle is not updated when a mode-change occurs,
        and the colours don't work very well in 256-colour modes.
BarGraph.c    No facility for negative-height bars.
TextRect.c    The text is not formated - you need to put '\n' in
        occasionaly if you want the text to be multiline. This is
        not too bad as printf behaves in the same way.
PlainRect.c    This saves an area of a Shell window as a sprite by
        redirecting to a sprite, and forcing a redraw of the area.
        Text is half-size (in square pixel modes) and the outlines
        of Shell rectangles (which are created with Wimp_PlotIcon)
        don't show up for some reason.

No facilities are provided for deleting rectangles and free-ing the memory
they took up.

And some more which I've forgotton about.


The TextRect.c file deals with redrawing text which contains line-feeds
etc. It took a fair while for me to work out how to do this!


One thing which might make the source files difficult to read for users of
!Edit is the profusion of Tabs. The solution is to use the excellent
freeware !Zap text editor - you won't want to use !Edit again after seeing
!Zap. For users of other text editors, the tabs in Zap tab to 8 spaces so
any other value will result in strange non-aligned text.

Any application which uses Shell has to have a window called 'ShellWindow'
in its template file - Shell_OpenGFXWindow assumes this name.


One of the main uses of Shell is to show how to cope with redrawing windows
in the Wimp enviroment - I found this quite difficult to start with.
Hopefully, the Shell sources will help people understand how the Wimp
redrawing system works.


_________________________________________________________________________


2. Installation.
----------------

You should simply move the whole Shell library directory into your C path.
Don't move any headers into an existing .h. directory. Shell has many header
files, some of which might be the same name as ones you already have; thus
Shell source files have lines like:

#include "Shell.Array.h"

which should also be used by any of your code which uses Shell.

e.g.., if <C$Path> = ADFS:4.$.CLibs., ...other.libraries...

then you should put the entire Shell directory in ADFS:4.$.CLibs to get a
tree that looks like:

ADFS:4.$.CLibs.
               h.
                 header1      /* your existing headers */
                 header2
                 ...

               o.
                 RISC_OSLib   /* your existing libraries */
                 ...

               Shell.
                     h.
                       Shell
                       Array
                       ...

                     o.ShellLib

                     Sources.
                             c.
                               Array
                               Label
                               ...

                             MakeFile

                             o.
                               Array
                               Label
                               ...

You should link with C:Shell.o.ShellLib

An alternative to this is to create a Shell application which sets
<Shell$Path> and change all #include lines to #include "Shell:Array.h",
while linking with 'Shell:o.ShellLib'. This approach is used by DeskLib.

If you recompile the Shell-lib, or the example program ShellEG, you might
have to alter the makefile so that the the dynamic dependances section points
to the right place on your system, and also change the list of libraries to
again point to where your libraries are.

Note that ShellEG requires the extra DeskLib library 'Save' which comes
with DeskLib 2.10. This enables you to save the contents of certain
rectangles as a file or directly into running applications, by clicking
Shift-Menu over a Shell window. See the ShellEG code to see how this is
set up.





___________________________________________________________________________


3. Things to do
---------------


What would be really nice would be to have a command-line input, so that
commands could be typed in and read by a function like Shell_scanf, with
other functions such as Shell_getc etc. You could have input from different
input rectangles, so Shell_scanf( Shell_rectblock *rectblock, "%i", &x).
There could also be a general input rectangle attatched to the general
output textrect, which would be read by Shell_scanf( NULL, ...). This would
make Shell_ completely implement a standard textual input/output system
like taskwindows, but with easy to use graphics facilities as well.

Simple x-y graphs. I've got code to do this but it's a bit messy at the mo.

Add a saver for blockrects to save as a sprite - Done that now.

Add a saver for bargraphs.

Have a rect which displays a sprite - I have a messy version of this.

At the moment, rectangles have colours and can have an icon-style border.
The default routines add various borders automatically, using
Shell_MakeRectIcon. An alternative way of doing this would be to put a set
of icons in the 'ShellWindow' in the Templates file, called 'Array',
'RectBlock' ... etc, so that any RectBlocks would have icon charateristics
(such as colours, border) from the templates file.

Add facilities to delete rectangles, freeing allocated space etc. I've
never actually needed to do this, but these functions should really be
included in the library.



___________________________________________________________________________


4. Other things
---------------

Shell is freeware. Feel free to distribute it, but please distribute the
original, not altered copies.

If you write any routines for extra rectangle types (e.g. to draw a
sprite in a window, or a drawfile in a window), please send them to me
so they can be included in the next release.

If you have any queries/suggestions/good ideas/extra routines/complaints
relating to Shell, feel free to contact me at the address below:


 Julian Smith


 ------------------------
 [e-mail]
 ------------------------

 or:

 ------------------------
 Department of Psychology
 University of Edinburgh
 7 George Square
 Edinburgh
 EH8 9JZ
 UK
 ------------------------