geos-3.html

cc65 的编译器文档

defined as a screen area filled with a bitmap, but if you would setup icons and erase the
screen they are still active and clicking in the place where formerly an icon was will cause
an effect. Similary if you would setup icons and then turn them off with <CODE>ClearMouseMode</CODE>
the bitmap will be still on the screen but clicking on it would not cause any action.
There is only one, but powerful icon function.</P>

<H3>DoIcons</H3>

<P><CODE>void DoIcons (struct icontab *myIconTab)</CODE></P>
<P>This function initializes all icons that are present on the screen at once. For more information
look at <CODE>Icons</CODE> chapter in this manual.</P>

<H2><A NAME="ss3.3">3.3</A> <A HREF="geos.html#toc3.3">DialogBoxes</A>
</H2>

<P>This chapter covers the most powerful GEOS user interface function - <CODE>DoDlgBox</CODE>.</P>

<H3>GEOS standard</H3>

<H3>DoDlgBox</H3>

<P><CODE>char DoDlgBox (char *dialogString)</CODE></P>
<P>DialogBox returns one byte. It can be the value of one of six standard icons (see <CODE>gdlgbox.h</CODE>)
or whatever closing routine passes. Register <CODE>r0L</CODE> also contains this value.</P>
<P>Read structures chapter for the specs of the <CODE>dialogString</CODE>.</P>

<H3>RstrFrmDialogue</H3>

<P><CODE>char RstrFrmDialogue</CODE></P>
<P>This function called from within DialogBox event immediately closes the DialogBox and returns
the owner ID (or whatever caller has in the .A register).</P>

<H3>GEOSLib extensions</H3>

<P>To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox,
with predefined data. In one word - these are standard DialogBoxes you can see in almost every
GEOS application.</P>

<H3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk</H3>

<P><CODE>char DlgBoxYesNo (char *line1, char *line2)</CODE></P>
<P><CODE>char DlgBoxOkCancel (char *line1, char *line2)</CODE></P>
<P><CODE>void DlgBoxOk (char *line1, char *line2)</CODE></P>
<P>These function show two lines of text in standard-sized DialogBox. You can read the code of
pressed icon from return value. E.g. for <CODE>DlgBoxYesNo</CODE> it can only be <CODE>YES</CODE> or <CODE>NO</CODE>.
You can pass an empty string or NULL to get a blank line.</P>

<H3>DlgBoxGetString</H3>

<P><CODE>char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)</CODE></P>
<P>This function prompts user for entering a string of at most <CODE>strlen</CODE> characters. It is returned
in <CODE>string</CODE>. The two given lines of text are shown above the input line. Please remember
that there is also <CODE>CANCEL</CODE> icon in the DialogBox and you should test if user confirmed his
input or gave up. The <CODE>string</CODE> is also shown so you can place default input there or remember
to place <CODE>NULL</CODE> at start.</P>

<H3>DlgBoxFileSelect</H3>

<P><CODE>char DlgBoxFileSelect (char *class, char filetype, char *filename)</CODE></P>
<P>This routine is the standard file selector. It can return <CODE>OPEN</CODE>, <CODE>CANCEL</CODE> or disk error
on reading the directory or opening the disk.
There is also <CODE>DISK</CODE> icon shown, but it is handled internally. You pass as input parameters
<CODE>filetype</CODE> and pointer to string containing the first part of file's class. If this string is
empty (<CODE>NULL</CODE> at the start), then all files with given filetype will be shown.</P>
<P>At present this file selector handles only first 16 files of given type and supports only one
(current) drive.</P>

<H3>MessageBox</H3>

<P><CODE>char MessageBox (char mode, const char *format, ...)</CODE></P>
<P>This function is a more general one. It works very much like <CODE>printf</CODE> in a
box. The only difference is <CODE>mode</CODE> parameter which allows for placing
default icons (see <CODE>gdlgbox.h</CODE> for list of possible <CODE>MB_</CODE> values).
Any too wide text will be clipped to the size of the default window. If mode
parameter is invalid or equal to <CODE>MB_EMPTY</CODE> then the window will be closed
after a click. Otherwise the user must choose an icon.</P>
<P>Note: use it if you really need (or if you will use it in many places) as
it adds quite amount of code to your program.</P>
<P>Note: the formatted text <EM>cannot exceed</EM> 255 bytes in length, there is no check
for that.</P>

<H2><A NAME="ss3.4">3.4</A> <A HREF="geos.html#toc3.4">Mouse, Sprites and Cursors</A>
</H2>

<P>You will find here functions related to sprite and mouse drawing and handling.</P>

<H3>Mouse related functions</H3>

<P>These cover mouse - as a general pointing device, but expect user to utilize as different devices
as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).</P>

<H3>StartMouseMode</H3>

<P><CODE>void StartMouseMode (void)</CODE></P>
<P>This function initializes mouse vectors - <CODE>mouseVector</CODE> and <CODE>mouseFaultVec</CODE>, and then
calls <CODE>MouseUp</CODE>.</P>

<H3>ClearMouseMode</H3>

<P><CODE>void ClearMouseMode (void)</CODE></P>
<P>This function disables all mouse actitivies - icons and menus stop to respond to mouse events,
but they are not cleared from the screen.</P>

<H3>MouseUp and MouseOff</H3>

<P><CODE>void MouseUp (void)</CODE></P>
<P><CODE>void MouseOff (void)</CODE></P>
<P>The first function turns the mouse pointer on. It will appear on next IRQ. The second one does
the opposite - it turns off the pointer, but its position is still updated by input driver.</P>

<H3>IsMseInRegion</H3>

<P><CODE>char IsMseInRegion (struct window *myWindow)</CODE></P>
<P>This function tests if mouse pointer is actually in given range of screen. See <CODE>gsprite.h</CODE> for
description of bits in return values - they describe the position in detail.</P>

<H3>Sprites</H3>

<P>You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
pointer and sprite 1 can be overwritten when using text prompt. You don't have to worry about
40/80 column issues because GEOS128 has pretty good sprite emulator for VDC.</P>

<H3>DrawSprite</H3>

<P><CODE>void DrawSprite (char sprite, char *mySprite)</CODE></P>
<P>This function initializes the sprite data. <CODE>mySprite</CODE> is a 63-byte table with bitmap data, which
is copied to system sprite area (at <CODE>sprpic</CODE> - see <CODE>gsym.h</CODE>). Hardware sprite registers are
not initialized and sprite is not yet visible.</P>

<H3>PosSprite</H3>

<P><CODE>void PosSprite (char sprite, struct pixel *myPixel)</CODE></P>
<P>This function positions the sprite on the screen. Given coordinates are screen ones - they are
converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your
sprite off the left or top to the screen.</P>

<H3>EnablSprite and DisablSprite</H3>

<P><CODE>void EnablSprite (char sprite)</CODE></P>
<P><CODE>void DisablSprite (char sprite)</CODE></P>
<P>These two functions are responsible for making the sprite visible or not.</P>

<H3>Cursors and Console</H3>

<H3>InitTextPrompt</H3>

<P><CODE>void InitTextPrompt (char height)</CODE></P>
<P>This function initializes sprite 1 for text prompt with given <CODE>height</CODE>. This parameter can be in
range 1-48.</P>

<H3>PromptOn and PromptOff</H3>

<P><CODE>void PromptOn (struct pixel *myPixel)</CODE></P>
<P><CODE>void PromptOff (void)</CODE></P>
<P>The first function places text prompt in given place and enables blinking.
The second one is pretty self-explanatory.</P>

<H3>GetNextChar</H3>

<P><CODE>char GetNextChar (void)</CODE></P>
<P>This function gets next character from the keyboard queue. If the queue is empty it returns
<CODE>NULL</CODE>, otherwise you receive true ASCII code of a character or value of special (function)
key. See <CODE>gsprite.h</CODE> for list of them.</P>

<H2><A NAME="ss3.5">3.5</A> <A HREF="geos.html#toc3.5">Disk</A>
</H2>

<P>This chapter covers slightly low-level disk routines. You should use them with care, because
you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various
devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
dangerous.</P>
<P>For some purposes you might consider using <CODE>dio.h</CODE> interface to disk access. It is native.</P>
<P>All GEOS disk functions return error code in X register. In some cases this is returned by
GEOSLib function (if its type is <CODE>char</CODE>), but in all cases last error is saved in <CODE>__oserror</CODE>
location. If it is nonzero - an error occured. See <CODE>gdisk.h</CODE> for the list of possible errorcodes.
You need to include <CODE>errno.h</CODE> to get <CODE>__oserror</CODE>, together with standard <CODE>errno</CODE>. The
latter gives less verbose, but still usable information and can be used with <CODE>strerror</CODE>.
Probably you will get more information using <CODE>_stroserror</CODE> in similar way.</P>
<P>For passing parameters use almost always pointer to your data e.g. <CODE>ReadBuff (&amp;myTrSe)</CODE>.</P>

<H3>Buffer functions</H3>

<P>These functions are taking single data sector (256 bytes) to read or write on a disk.</P>

<H3>ReadBuff and Writebuff</H3>

<P><CODE>char ReadBuff (struct tr_se *myTrSe)</CODE></P>
<P><CODE>char WriteBuff (struct tr_se *myTrSe)</CODE></P>
<P>These functions read and write sector placed at <CODE>diskBlkBuf</CODE>.</P>

<H3>GetBlock and ReadBlock</H3>

<P><CODE>char GetBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char ReadBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P>These two functions are reading a single block directly at 256 byte array placed at <CODE>buffer</CODE>.
The difference between them is that <CODE>GetBlock</CODE> will initialize TurboDos in drive if it was not
enabled. <CODE>ReadBlock</CODE> assumes that it is already enabled thus being slightly faster.</P>

<H3>PutBlock, WriteBlock, VerWriteBlock</H3>

<P><CODE>char PutBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char WriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char VerWriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P>Similar to previous but needed for writting the disk. <CODE>VerWriteBlock</CODE> verifies the data after
writting. In case of error five tries are attempted before error code is returned.</P>

<H3>Directory header</H3>

<P>Functions described here are operating on <CODE>curDirHeader</CODE> where current disk header is stored.
On larger capacity drives (than 1541) the second part of directory header in <CODE>dir2Head</CODE>.</P>

<H3>GetPtrCurDkNm</H3>

<P><CODE>void GetPtrCurDkNm (char *diskName)</CODE></P>
<P>This function fills given character string with the name of current disk. It is converted to C
standard - string is terminated with <CODE>NULL</CODE> character instead of code 160 as in Commodore DOS.
Note that passed pointer must point to an array of at least 17 bytes.</P>

<H3>GetDirHead and PutDirHead</H3>

<P><CODE>char GetDirHead (void)</CODE></P>
<P><CODE>char PutDirHead (void)</CODE></P>
<P>These functions are reading and writting the directory header. You should use <CODE>GetDirHead</CODE> before
using any functions described below, and you should use <CODE>PutDirHead</CODE> to save the changes on the
disk. Otherwise they will be lost. Operating area is the <CODE>curDirHead</CODE>.</P>

<H3>CalcBlksFree</H3>

<P><CODE>unsigned CalcBlksFree (void)</CODE></P>
<P>This function returns the number of free blocks on current disk. It is counted using data in
<CODE>curDirHead</CODE> so you must initialize the disk before calling it.</P>

<H3>ChkDskGEOS</H3>

<P><CODE>char ChkDskGEOS (void)</CODE></P>
<P>This functions checks <CODE>curDirHead</CODE> for GEOS Format identifier. It returns either true or false,
and also sets <CODE>isGEOS</CODE> properly. You must initialize the disk before using this.</P>

<H3>SetGEOSDisk</H3>

<P><CODE>char SetGEOSDisk (void)</CODE></P>
<P>This function initializes disk for use with GEOS. It sets indicator in directory header and
allocates a sector for the directory of border files. You don't need to initialize the disk before
using.</P>

<H3>FindBAMBit</H3>

<P><CODE>char FindBAMBit (struct tr_se *myTrSe)</CODE></P>
<P>This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is
set if the sector is free to use. Returned value is always zero if the sector is already allocated.
In fact, this function could be used in a following way:
<BLOCKQUOTE><CODE>
<PRE>
#define BlockInUse FindBAMBit
...
if (!BlockInUse(&amp;myTrSe)) {
... block not allocated ...
}
</PRE>
</CODE></BLOCKQUOTE>
</P>