A resource file has the name extension .grc
. That is not required, but
it will make for an easier recognition of the file's purpose. Also, cl65
recognizes those files. grc65's parser is very weak at the moment; so,
read the comments carefully, and write resources exactly as they are written
here. Look out for CAPS and small letters. Everything after a ';
'
until the end of the line is considered as a comment and ignored. See the
included
commented example .grc file for a
better view of the situation.
MENU menuName leftx,topy <ORIENTATION> {
"item name 1" <MENU_TYPE> pointer
...
"item name x" <MENU_TYPE> pointer
}
The definition starts with the keyword MENU
, then comes the menu's name,
which will be represented in C as const void
. Then are the co-ordinates
of the top left corner of the menu box. The position of the bottom right
corner is estimated, based on the length of item names and the menu's
orientation. It means that the menu box always will be as large as it should
be. Then, there's the orientation keyword; it can be either HORIZONTAL
or
VERTICAL
. Between {
and }
, there's the menu's
content. It consists of item definitions. First is an item name -- it has to
be in quotes. Next is a menu-type bit. It can be MENU_ACTION
or
SUB_MENU
; either of them can be combined with the DYN_SUB_MENU
bit
(see
the GEOSLib documentation for descriptions of
them). You can use C logical operators in expressions, but you have to do it
without spaces. So a dynamically created submenu will be something like:
"dynamic" SUB_MENU|DYN_SUB_MENU create_dynamic
The last part of the item definition is a pointer which can be any name that is
present in the C source code that includes the generated header. It can point
to a function or to another menu definition.
If you are doing sub(sub)menu definitions, remember to place the lowest level definition first, and the top-level menu as the last one. That way the C compiler won't complain about unknown names.
HEADER <GEOS_TYPE> "dosname" "classname" "version" {
author "Joe Schmoe"
info "This is my killer-app!"
date yy mm dd hh ss
dostype SEQ
mode any
structure SEQ
icon "sprite.raw"
}
The header definition describes the GEOS header sector which is unique to
each file. The definition starts with the keyword HEADER
, then goes the
GEOS file-type. You can use only APPLICATION
here at the moment. Then,
there are (each one in quotes) the DOS file-name (up to 16 characters), the GEOS
Class name (up to 12 characters), and the version info (up to 4 characters).
The version should be written as "V
x.y", where x is the
major, and y is the minor, version number. Those fields, along with both
braces, are required. The lines between braces are optional, and will be replaced
by default and current values. The keyword author
and its value in quotes name
the programmer, and can be up to 63 bytes long. info
(in the same format) can
have up to 95 characters. If the date
field is omitted, then the time of
that compilation will be placed into the header. Note that, if you do specify
the date, you have to write all 5 numbers. The dostype
can be SEQ
,
PRG
, or USR
. USR
is used by default; GEOS usually doesn't care.
The mode
can be any
, 40only
, 80only
, or c64only
; and,
it describes system requirements. any
will work on both 64-GEOS and
128-GEOS, in 40- and 80-column modes. 40only
will work on 128-GEOS in
40-column mode only. 80only
will work on only 128-GEOS in 80-column mode,
and c64only
will work on only 64-GEOS. The default value for
structure
is SEQ
(sequential). You can put VLIR
there, too; but
then, you also have to put in a third type of resource -- a memory definition.
The value of icon
is a quoted file-name. The first 63 bytes of this file
are expected to represent a standard monochrome VIC sprite. The file gets accessed
when the generated assembly source is being processed by ca65. Examples for
programs generating such files are Sprite Painter, SpritePad and the
sp65 sprite and bitmap utility. The default icon
is an empty frame internally represented in the generated assembly file.
MEMORY {
stacksize 0x0800
overlaysize 0x2000
overlaynums 0 1 2 4 5
}
The memory definition is unique to each file and describes several attributes related
to the memory layout. It consists of the keyword MEMORY
followed by braces which
contain optional lines. The value of stacksize
can be either decimal (e.g.
4096
) or hexadecimal with a 0x
prefix (e.g. 0x1000
). The default value
of 0x400 comes from the linker configuration file. The value of backbuffer
can be
either yes
or no
. The further means that the application uses the system-supplied
background screen buffer while the latter means that the program uses the memory of the
background screen buffer for own purposes. The default value of yes
comes from the
linker configuration file. If the structure
in the header definition is set to the
value VLIR
then it is possible and necessary to provide here the attributes of the
VLIR overlays. overlaysize
defines the maximal size for all VLIR records but number
0. It can be either decimal (e.g. 4096
) or hexadecimal with a 0x
prefix (e.g.
0x1000
). overlaynums
defines the VLIR record numbers used by the application.
Skipped numbers denote empty records. In the example, record number 3 is missing. Read
this description for details.