geos-4.html

cc65 的编译器文档

<P><CODE>SUB_MENU</CODE> - <CODE>pointer</CODE> points to next menu descriptor - a submenu</P>
<P>Both of them can be ORed with <CODE>DYN_SUB_MENU</CODE> and then the <CODE>pointer</CODE> points to a function
which will return in <CODE>r0</CODE> needed pointer (to function to execute or a submenu).</P>
<P>For creating nested menus (you can have at most 8 levels of submenus) you need to declare such
structure for each submenu and top level menu.</P>

<H3>DoDlgBox command string</H3>

<P><CODE>DoDlgBox</CODE> is together with <CODE>DoMenu</CODE> one of the most powerful routines in GEOS. It is
responsible for creating dialog boxes, that is windows which task is to interact with user.
Format of the command string is following:
<BLOCKQUOTE><CODE>
<PRE>
    (window size and position)
    (commands and parameters)
    NULL
</PRE>
</CODE></BLOCKQUOTE>

There is custom type defined for the command string: <CODE>dlgBoxStr</CODE>.</P>

<H3>Size and position</H3>

<P>The first element can be specified in two ways - by using default size and position or specifying
own. The first case results in
<BLOCKQUOTE><CODE>
<PRE>
const dlgBoxStr example = {
        DB_DEFPOS (pattern_of_shadow),
        ...             // commands
        DB_END };
</PRE>
</CODE></BLOCKQUOTE>

And the own size and position would be:
<BLOCKQUOTE><CODE>
<PRE>
const dlgBoxStr example = {
        DB_SETPOS (pattern, top, bottom, left, right)
        ...             // commands
        DB_END };
</PRE>
</CODE></BLOCKQUOTE>
</P>

<H3>Commands</H3>

<P>The next element of <CODE>DoDlgBox</CODE> command string are commands themselves. First six commands are
default icons and the number of selected icon will be returned from window processor. The icons are
<CODE>OK, CANCEL, YES, NO, OPEN</CODE>, and <CODE>DISK</CODE>. You can use predefined macros for use them, e.g.:
<BLOCKQUOTE><CODE>
<PRE>
        ...
        DB_ICON(OK, DBI_X_0, DBI_Y_0),
        ...
</PRE>
</CODE></BLOCKQUOTE>

Note that the position is counted from top left corner of window, not entire screen and that the 'x'
position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
<CODE>DBI_X_0</CODE> and <CODE>DBI_Y_0</CODE> are predefined (see <CODE>gdlgbox.h</CODE> for more), default positions
which will make icons to appear on default window exactly where you would expect them.</P>
<P><CODE>DB_TXTSTR (x, y, text)</CODE> will cause to show given text in the window.</P>
<P><CODE>DB_VARSTR (x, y, ptr)</CODE> works as above, but here you are passing a pointer to a zero page location
where the address of text is stored. This is useful for information windows where only text content
is variable. Consider following:
<BLOCKQUOTE><CODE>
<PRE>
char text = "foo";
        ...
        r15=(unsigned)text;             // in code just before call to DoDlgBox
        ...
        DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &amp;r15),
        ...
</PRE>
</CODE></BLOCKQUOTE>

will cause to appear the word ``foo'' in the window, but you may store the pointer to any text in
<CODE>r15</CODE> (in this case) before call to DoDlgBox.</P>
<P><CODE>DB_GETSTR(x, y, ptr, length)</CODE> - will add input from keyboard feature. <CODE>ptr</CODE> works as in
previous example and points to place where text is to be stored. Note that the contents of this
place will be shown upon creating window. <CODE>length</CODE> is the maximum number of characters to input.</P>
<P><CODE>DB_SYSOPV(ptr)</CODE> - this sets <CODE>otherPressVec</CODE> to given pointer. It is called on every keypress.</P>
<P><CODE>DB_GRPHSTR(ptr)</CODE> - data for this command is the pointer for <CODE>GraphicsString</CODE> commands.</P>
<P><CODE>DB_GETFILES(x, y)</CODE> - for standard window you should pass 4 for both x and y. This function
draws file selection box and searches current drive for files. Before call to <CODE>DoDlgBox</CODE> you
must load <CODE>r7L</CODE> with GEOS filetype of searched files and <CODE>r10</CODE> with class text. In <CODE>r5</CODE>
you have to load pointer to a <CODE>char[17]</CODE> where selected filename will be copied. It works
like <CODE>FindFTypes</CODE> but is limited to first 16 files.</P>
<P><CODE>DB_OPVEC(ptr)</CODE> - this sets the new pointer for button press function, if you pass
<CODE>RstrFrmDialogue</CODE> here you will cause the window to close after pressing mouse button.</P>
<P><CODE>DB_USRICON(x, y, ptr)</CODE> - places single user icon (click box) on window, <CODE>ptr</CODE> points at a
<CODE>struct icondef</CODE> but fields <CODE>x</CODE> and <CODE>y</CODE> are not used here. You can have at most 8 click
boxes in a window, this is internal limit of GEOS Kernal.</P>
<P><CODE>DB_USRROUT(ptr)</CODE> - this command causes to immediately call user routine pointed by <CODE>ptr</CODE>.</P>

<H3>GraphicsString command string</H3>

<P><CODE>GraphicsString</CODE> is a very powerful routine to initialize whole screen at once. There are
predefined macros for all commands, names are self-explanatory, see them in <CODE>ggraph.h</CODE>. Last
command have to be <CODE>GSTR_END</CODE>. There is custom type defined for the command string: <CODE>graphicStr</CODE>.</P>
<P>Here is an example for clearing the screen:
<BLOCKQUOTE><CODE>
<PRE>
const graphicStr example = {
        MOVEPENTO(0,0),
        NEWPATTERN(0),
        RECTANGLETO(319,199)
        GSTR_END };
</PRE>
</CODE></BLOCKQUOTE>
</P>

<H3>InitRam table</H3>

<P>This type of data is used to initialize one or more bytes in many places at once. The format is
as following:
<BLOCKQUOTE><CODE>
<PRE>
void example = {
    (unsigned)address_to_store_values_at,
    (char)number_of_bytes_that_follow,
    (char)data,(char)data (...)
    // more such definitions
    (unsigned)NULL // address of 0 ends the table
    };
</PRE>
</CODE></BLOCKQUOTE>
</P>

<H3>Intercepting system vectors</H3>

<P>It is possible to intercept and hook in the GEOS Kernal using vectors. Here is a little example:
<BLOCKQUOTE><CODE>
<PRE>
void_func oldVector;

void NewVectorHandler(void) {
        // do something and at the end call the old vector routine
        oldVector();
}

void hook_into_system(void) {
        oldVector = mouseVector;
        mouseVector = NewVectorHandler;
}

void remove_hook(void) {
        mouseVector = oldVector;
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>In your <CODE>main</CODE> function you should call <CODE>hook_into_system()</CODE> but <EM>after</EM> all calls to GEOS
kernal (like <CODE>DoMenu</CODE>, <CODE>DoIcons</CODE>, etc.) - right before passing control to the <CODE>MainLoop()</CODE>.
Be warned that vectors are most likely to be changed by GEOS kernal also by other functions (like
<CODE>GotoFirstMenu</CODE>, <CODE>DoDlgBox</CODE> and its derivatives etc.). It depends on what kernal functions
you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete
list for GEOS 1.x can be found in A. Boyce's Programmers' Referenece Guide mentioned before. Most of
information contained there should be still valid for GEOS 2.0. When calling a function that restores
the vector you should add a <CODE>hook_into_system()</CODE> call right after it.</P>
<P>It is critical to restore old vector values before exiting the program. If you have more than one
place where you call <CODE>exit()</CODE> then it might be worth to register <CODE>remove_hook</CODE> function to
be called upon exiting with <CODE>atexit(&amp;remove_hook);</CODE> call. This way you will ensure that
such destructor will be always called.</P>
<P>That little example above intercepts <CODE>mouseVector</CODE>. The <CODE>NewVectorHandler</CODE> function will be
called every time the mouse button changes status. Other important vectors you should know about
are:
<UL>
<LI><CODE>appMain</CODE> - this is called from within <CODE>MainLoop</CODE> system loop</LI>
<LI><CODE>keyVector</CODE> - called whenever a keypress occurs</LI>
<LI><CODE>intTopVector</CODE> - called at the start of IRQ routine</LI>
<LI><CODE>intBotVector</CODE> - called at the end of IRQ routine</LI>
</UL>
</P>

<HR>
Next
<A HREF="geos-3.html">Previous</A>
<A HREF="geos.html#toc4">Contents</A>
</BODY>
</HTML>