Machine Code Made Easy - Part 23b
Author
Publisher
Description
From Fred 35, note that same number was used twice!
Well, twist my nipple nuts and send me to Alaska. Here I am
again: that makes TWO months in a row. Sheesh, anyone would
think I was a sad lifeless git. (Just shut your mouth).
Anyway, welcome to a Fred Guide to Machine Code "Special". Over
the next couple of months this column's gonna be dedicated to
the technical (ish) documentation for "Driver", the new SAM
Wimp environment thingy. Basically, all you lucky Fred readers
will be the first people in the entire Universe to learn how to
write Driver Applications! Yummy.
Let's start at the beginning. Driver is a program. It's 32k in
length with a further 16k of graphics and data. And it runs on
any SAM. (With MasterDOS - a SAMDOS version is difficult but I'm
looking into it). This fabulous bit of software provides a user
interface for other software, in the form of a Windows, Icons,
Mouse and Pull-down menus environment.
{ NB. If you don't have a mouse, cursor keys can be be used }
WHO ARE YOU CALLING A WIMP?
A WIMP environment is designed to be completely user-friendly.
The screen is divided into windows (which can overlap), each of
which displays a task, an application program or some data
attached to an application. Various options are listed in menus,
but are only displayed when the user requests them. Applications
or tasks can be reduced to an icon, a small symbol which
represents the item. For example, a word processor could be
represented by a picture of a pencil.
Now, the user controls the environment using a mouse to direct a
pointer around the screen, and the mouse buttons to select
items. eg. clicking on an icon or pulling down a menu.
(I could say that Driver is the SAM version of Windows, but of
course that would be breach of copyright so I won't.)
Driver is important in a lot of ways: It pages itself into
memory and allocates the stuff using the official guidelines -
making sure it's 100% compatible with other things (eg.
MasterBASIC, the dump utility etc). Being 100% machine code, it
can co-exist with a BASIC program too.
It also handles the memory management of resident applications.
You can have up to 8 fully blown Driver applications sitting in
your Coupe similtaneously. Despite the fact that there isn't any
real multitasking between them, you can quite happily switch
between applications without affecting the state of the files
you're editing.
In fact, the applications themselves don't have to worry about
the amount of memory your SAM has - Driver allocates memory
pages as they are needed, with full use being made of external
megs. In theory, you can have files up to 128 16k pages long!!!
WHY DO I WANT TO WRITE A DRIVER APPLICATION?
A good question, mes amis. In a non-commercial situation you can
make use of the following advantages:
* A common user-interface, meaning that the user doesn't have to
learn lots of new commands from a manual or whatever, and
because I've spent a lot of time developing this "front end" it
looks much better and is more advanced than that of other SAM
applications.
* You don't have to write routines for mundane things like
cursor/ pointer movement, menus etc.
* Full compatibility with all SAMs, meaning that there's no need
to write seperate versions for 256, 512, meg etc.
* Ability to share Driver with other applications at the same
point, transfering data between them (using clipboarding)
From a more commercial viewpoint:
* Driver users are going to want more applications than the ones
they get with in package.
The main advantage that I found when writing a few applications
is the lack of need for routines - everything seems to be
provided for you.
HOW DOES IT ALL WORK, STEVE?
I'm glad you asked me that. Try and remember back to last month,
when I discussed the use of the frame interrupt for
multi-tasking. That principle is the one I've developed for
Driver.
Essentially, your application program sits and runs in lower
memory, paging the screen and data pages into upper memory.
(This arrangement is mainly to allow external RAM to be used. It
can only be paged into sections C and D).
At every frame interrupt, your program transfers control to
Driver, with does things like scanning the mouse, moving the
pointer, flashing the cursor, checking for button presses and so
on. If everything's OK control reverts back to the application.
However, if the user has clicked on a window, menu or whatever,
Driver kick starts the necessary routines.
Right. I think I'd better start adding some detail, 'cos this is
sounding kinda sketchy. At any one time, Driver is running in
one of 5 modes:
0 Wimp mode - all window and menu name gadgets are active.
1 Menu mode A - a menu gadget has been clicked, but there is
no highlighted "bar"
2 Menu mode B - as above, except that the bar is present.
3 Dialogue mode - Only gadgets in a dialogue box are active.
4 Sleeper mode - No gadgets are active.
Gadgets? Just an umbrella term for the things that can be
clicked.
Notice that this splits things up nicely into three sections.
And that's just what I'll do.
MODE 0 - WIMP MODE
Your application can be allocated up to 256 windows. Window 0 is
ALWAYS the desktop, covering the whole screen.
Windows posess several gadgets for controlling and manipulating
them. The available gadgets are as follows:-
Name Can't be clicked.
Move Can be clicked and dragged to move the window around.
Size Can be clicked and dragged to change the size of the
window.
Close Can be clicked to close the window.
X Scroll A horizontal scroll bar, with left and right arrows
and a little square indicating the current scroll
position.
Y Scroll As above, but for vertical scrolling.
Any combination of the above gadgets is possible. The desktop is
given, as a default, name and close gadgets only. (You shouldn't
change these, except to add scroll bars).
Each window's "type" can be fully specified using 8 bits. D0 is
set if you don't want the window area to be cleared before its
contents are printed. (For example, if the window contains a
large graphic image).
D7 is used to specify whether the window is Selectively-Active
or Permanently-Active. A SAW (Selectively-Active-Window) must be
clicked to "activate" it, unless it is currently active. A PAW
does not. The distinction is made to provide for situations
where windows can overlap (the active window is brought to the
front). Incidentally, PAWs are always displayed on top of SAWs.
NB. The desktop (window 0) has an additional gadget, a menu bar.
It is also permanently active, but is displayed behind all other
windows.
The full 8 bit description for each window is as follows:-
D0 Set to avoid window-clearing.
D1 Set for name gadget.
D2 Set for close gadget.
D3 Set for move gadget.
D4 Set for size gadget.
D5 Set for x scroll bar.
D6 Set for y scroll bar.
D7 Set for SAW, reset for PAW.
Driver has a 256 byte long table holding this type for each
window, called wintype_tab.
In addition to the gadgets/ type of each window, there are also
256 byte long tables for x coords, y coords, x sizes, y sizes, x
scroll positions and y scroll positions.
16 bytes are allocated for each window's name, and there is one
further table - 256 bytes holding the order that the windows are
displayed on screen. (The entries in this table are the window
numbers, with the first byte 0 for the desktop, followed by the
next displayed window, then the next etc.)
All these tables are held in the 16k data page I mentioned
previously, at the following offsets within the page:
Address (hex) Name Comments
----------------------------------------------------------------
1000 wintab Order of windows.
1100 wintype_tab Types.
1200 winx_tab X coords.
1300 winy_tab Y coords.
1400 winxsize_tab X sizes.
1500 winysize_tab Y sizes.
1600 winscrollx_tab X scroll positions.
1700 winscrolly_tab Y scroll positions.
1800 winnames Window names. 16 bytes for
->27FF each.
Note that the lsb of the address corresponds to the window
number.
I should also mention here the coordinate system. Driver uses
mode 3 (hi-res), but with "fat" coordinates. ie. in the x axis,
0 is at the left and 255 is at the far right. Also, in the y
axis, 0 is at the TOP with 191 at the bottom.
The text characters used are based on a 6x7 thin pixel grid. In
other words, each character uses 3 coords horizontally and 7
coords vertically. This allows 85x26 characters on screen. (I
use my own font, not the ROM's)
Finally, the scroll bar tables' entries represent the scroll bar
position as a fraction of 255. This means that 0 indicates that
the bar is far left (or top), and 255 is far right (or bottom).
The scroll bars on screen are scaled to retain this. Your
application must translate these values into things like the
position through a text file, for example.
MODES 1 AND 2 - MENU MODES
The menus are seperated from WIMP mode for simplicity. And they
are very simple indeed. On your application desktop you have a
menu bar strip thingy that, when clicked, pulls down the
appropriate menu. I'll start by describing the menu
representation in your application.
* Each menu as stored as the following sequence of bytes:
name + carriage return.
number of options
coords (x,y)
option 1, option 2, option 3... etc.
The name is stored as ASCII. It can be as long as you like,
finishing with a carriage return (0D hex).
The number of options is simply a byte with, um, the number of
menu options.
Coordinates are ABSOLUTE (using 0,0 at top left of the screen)
* Each option is stored as:
type
data
text + carriage return.
The type, similiar to that for windows, indicates what the
option does. A menu option can be on or off (if it's off, it is
printed as yellow on white and can't be selected). It can also
run a routine when selected, open a sub-menu, toggle a flag or
do absolutely nothing at all except split up bits of the menu as
a line.
The data is always 8 bytes long: addresses for the routine (or 0
if not applicable), for the sub-menu (0 if N/A) for the flag and
finally values for flag on/off.
Note that even if the option doesn't toggle a flag you can still
assign one - use 0000 as the flag address to avoid this. If the
byte at the flag address matchs the "flag on" value a little
tick is placed at the left of the option.
Finally, the text is in simple ASCII format, again with 0D hex
to terminate. The text is padded out (when it is printed) to be
24 chars long - it mustn't exceed 24 characters.
There is a little bit extra detail I could give you here,
connected with sort cut keypresses, but I'll leave that 'til
later.
NB. If the "option" is actually a line, just use 0D hex as the
text.
One more thing - sub menus are represented in exactly the same
way, except that their name is never printed anywhere, so you
might as well just use 0D hex.
Okay, that's yer lot for this month. Next time - dialogue boxes,
application interfacing and the file manager.
See you in Fred 36,
Stevie T.