fouts@AMES-NAS.ARPA (07/27/86)
This file contains the readme for my OSS Pascal demo
----- CUT HERE -----
pager.pas is a simple application in OSS Personal Pascal for the Atari
ST. I wrote it on a monochrome 1040, but it should work on any system at
any resolution.
My intent was to experiment with the GEM interface from Pascal, and try
to write some kind of "template" program I could use as a basis for more
sophisticated programs later.
Pager is a multiple window file viewer. Files may be opened or closed,
and viewing can scroll forward or backward. Pager is organized around the
simplest possible event driven loop:
Initialize
While still running
get an event
deal with it
Clean up
Pager will handle all of the events returned by Get_Event, although it
ignores the right mouse button, only performs limited menu service, and only
pays attention to the first cursor rectangle event.
Pager also uses built in dialogs, as well as alert boxes, and responds
to menu entries. It also demonstrates XBIOS calls as well as timer events.
It does not build it's own dialogs, and doesn't use mouse position
information.
Pager starts by offering the user an alert box which allows him to
immediately abort the program. If he chooses to continue, pager opens the
first file, using the built in "Item Selector" dialog.
In order to spread the overhead of reading files around, the entire
file is not read in immediatly, but rather only enough to fill the default
window, which is full screen size.
Pager than enters it's procesing loop, which consists mostly of waiting
for events to occur and then responding to them.
An unusual event that pager responds to is a ten second interval. If
no activity has happened within the last ten seconds, pager will put an
alert box up indicating how long it has been since pager has started.
This alert is simply a demonstration of the interval timer, as well as
using XBIOS calls to access supervisor memory.
The events which pager responds to are message events, keyboard events,
timer events, 'rectangle' events, and button pushed events.
Since pager is a template, I made up a silly use for the rectangle and
button events. The cursor takes one of four shapes, depending on the mouse
being in or out of the front window, and the left mouse button being down or
up. In pager, these cursor shapes don't have any real meaning, they are
just window dressing.
Most keyboard events (key strokes) are ignored. However, the HELP key
causes a HELP alert box to be posted, which would contain something a litte
more useful in a serious program, and the UNDO key causes the quit alert box
to be posted.
Most of the work occurs in message events, which fall into several
catagories. There are selection events, redraw events, top events, close
events, fulled events, arrowed events, horizontal events, veritical events,
size events, and move events.
A selection event occurs when the mouse is clicked on a menu selection.
Pager allows desk accessories to work and has four menu entries of its own.
A menu event can be used to open a new file, to close an open file (and it's
window,) to quit the program, or to get an "about pager" alert box.
A close event occurs when the close box has been clicked, and causes
pager to close the file, close the window, and free up any related storage.
A full event occurs when the full box has been clicked. Pager uses the
full box as a toggle event. If the window is already full, than it is
resized to be the last size it was set to by other than a full. If it's not
full, then it's set to cover the entire screen.
Since windows start out as full screen size, pager starts with the
assumption that the first 'small' size for a window should be 1/4 the screen
size, located in the upper left hand quarter of the window.
Size events simply cause the window to grow or shrink, in response to
clicking the size box and dragging. Pager allows the window to assume any
size.
Move events simply cause the window to be displaced, in response to
clicking the title bar and dragging. Pager will allow the window to be
placed anywhere GEM will put it.
Arrow events occur from clicking in the elevator bar, or on the arrows
at the ends of the elevator bar. Pager responds to arrow clicks by moving
the page up or down one line, or by moving the display left or right one
character. Pager responds to elevator bar clicks by moving the page up,
down, left or right one window full, as appropriate.
Because files are only read as needed, the code for keeping track of
the position in the file is a fairly crude, although it appears to be bug
free.
However, the code for calculating the position and size of the elevator
cars is slightly buggy, suffering from some calculation round off errors
which cause the cars to sometimes do nonintuitive things.
Also, until the file has been entirely input, it is not possible to
know the full size of the file, so a heuristic is used for the vertical
elevator. One full window size is added to the currently known size of the
file when calculating the postion and offset of the elevator, so there will
always be room to click on either side of the bar until the entire file has
been read. Once the entire file is read, the actual file size is used.
Horizontal and Vertical events occur when the elevator car has been
clicked and drug to a new location. In this event, Pager calculates the
correct viewing offset according to the new positions of the elevator cars
and redisplays accordingly.
There is room for much improvement in this area, since "scrolling"
consists of erasing and redrawing the entire window, rather than moving the
still visible part and adding new data.
The most interesting event Pager has to deal with is the Redraw event,
which occurs when a portion of a window which was previously invisible
becomes visible.
As you are probably aware, GEM keeps lists of 'visible' rectangles
which make up each of the windows. The most efficent way to update a window
would be to only redraw the portions which weren't visible before, but which
are now.
Unfortunately, what Pager does is to go through the list of visible
rectangles, setting the clipping region to the part just made visible and
redrawing the entire window. This is the second area where there is much
room for improvement.
Pager tries to be relitively bug free and robust, and seems to succede
moderately well, (except for the elevator calculations mentioned before.)
However, one are where I systematically did an unsafe bit of coding was in
obtaining memory. None of the places where new is called to obtain more
memory, is there a check for failure. This will probably lead to
unpleasentness eventually, and I will probably fix it one of these days.
In writing pager, I discovered that the built in read procedure will
not read character data from other than a text type. Since I was
considering using random file access to facilitate memory management, I
wrote a "Get_string" routine, which will allow me to expand to random access
if I need it.
Overall, I have been very impressed with Personal Pascal. I have
managed to fairly sophisticated programming using only it, it's manual, and
the ABACUS "Internals" manual. It is reasonably bug free; I only found two
problems with it while writing pager. It is reasonably easy to learn; I've
only had it for two weeks, and pager is only about six hours work.
(Although I have had a lot of pascal experience before.) It runs reasonably
quickly; pager only takes about fifty seconds to compile and link using a
ram disk on my 1040ST. The support from OSS is good. and the price is
right.
I've also been very impressed with the 1040ST. I've got a MacUgly
(used to have a girl's name) sitting on my desk at work, complete with full
blown Aztec C, and I still haven't managed to get anything as complete at
pager working using it's interface. (I also have a lot of C experience,
since hacking Unix kernels is my living.)
All in all, I'm glad I've got the beasty.
Marty