Figure 2-0

Display 2-0

SwatDisplay 2-0

Table 2-0
1Goc Keywords

n	@alias

@alias(<protoMsg>) <messageDef>;

The @alias keyword is used for messages which take conditional parameters in 
an assembly handler. For example, if the assembly handler takes a word 
parameter normally and a dword only if a certain flag is set, you will need to 
have two C messages with the two different parameters. The @alias keyword 
allows this. Its arguments are shown below:

protoMsg	The name of the existing message that the alias will reference.

messageDef	The new message definition. This is a standard message 
definition as would follow the @message keyword.

@message void MSG_MY_MSG(word par);
@alias(MSG_MY_MSG) void MSG_MY_SECOND_MSG(dword par);

See Also:	@message

n	@call

<ret> = @call [,<flags>] [{<cast_ret>}] \
<obj>::[{<cast_par>}]<msg>(<param>*);

The @call keyword sends the specified message to the specified object and 
makes the caller wait until the message is processed before continuing. The 
arguments of @call are shown below:

ret	A variable for receiving the return value of the message as 
defined by @message. This has the same usage as a typical 
function return value.

flags	Flags that determine how the message affects the recipient's 
event queue. The allowable flags are shown below. (The comma 
is required before each flag.) 

cast_ret	A message to cast the message return value to. When Goc 
determines what type of value should be returned, it uses the 
return value of the cast_ret message if this field is used. The curly 
braces are required around this field.

obj	The name of the recipient object, or a variable representing the 
optr of the recipient.

cast_par 	A message to cast the message parameters to. When Goc 
determines what type of values should be passed to the message, 
should be returned, it uses the parameters of the cast_par 
message if this field is used. The curly braces are required around 
this field.

msg	The name of the message to be sent, or an expression 
representing the message number. If an expression is used, you 
must cast the message to a certain type with the cast parameter.

param	Expressions or constants passed to the message. Parameters 
passed to messages are specified in the same way as if they were 
being passed directly to a function or routine in C.

The flags allowed with @call are shown below:

forceQueue
This flag will cause the message to be placed in the recipient's 
event queue, even if it could have been handled by a direct call.

checkDuplicate
This flag makes the kernel check if a message of the same name 
is already in the recipient's event queue. For this flag to work, 
forceQueue must also be passed. Note that due to implementation 
constraints, events will be checked from last to first rather than 
from first to last.

checkLastOnly
This flag works like checkDuplicate, above, except that it checks 
only the last message in the event queue.

replace	This flag modifies checkDuplicate and checkLastOnly by 
superseding the duplicate (old) event with the new one. The new 
event will be put in the duplicate's position in the event queue. If 
a duplicate is found but the replace flag is not passed, the 
duplicate will be dropped and the new event will be put at the end 
of the queue.

insertAtFront
This puts the message at the front of the recipient's event queue. 
Note that this flag will supersede the replace flag.

canDiscardIfDesperate
This flag indicates that this event may be discarded if the system 
is running extremely low on handles and requires more space 
immediately.

Additionally, @call alows the use of several special expressions in place of the 
recipient:

self	Send the message to the object issuing the @call command. e.g.

@call self::MSG_VIS_DRAW(flags, gstate);

process	Send the message to the object's associated Process object. e.g.

@call process::MSG_HELLO_RESPOND();

application	Send the message to the object's associated GenApplication 
object.

attr = @call application::MSG_GEN_GET_ATTRIBUTES();

@genParent	Send the message to the object's generic parent in a generic 
object tree.

@visParent	Send the message to the object's visible parent in a visible object 
tree.

If you need to send a message to an object's superclass, use the @callsuper 
keyword rather than @call.

gstate = @call myObj::MSG_META_CUT();
retVal = @call {MSG_MY_MSG} myObj::MSG_OTHER_MSG();
retVal = @call myObj::MSG_MY_MSG(10, param1);

See Also:	@send, @callsuper, @message, @method, @object

n	@callsuper

<ret> = @callsuper [{<cast_ret>}] \
<obj>::<class>::[{<cast_par>}]<msg>(<param>*) [<flags>]+;

@callsuper;

The @callsuper keyword does two things: The most useful is to pass a received 
message on to the superclass to ensure default behavior is preserved; the 
second, and less used, acts just like @call but sends the message to the 
recipient's superclass rather than the recipient's class. This is rarely used but 
can be used if only default behavior is required of the message. Its arguments 
are shown below:

ret	Same as @call.

obj	Same as @call.

cast_ret	Same as @call.

class	The name of the object's superclass that should receive the 
message. It is possible to send the message to the highest 
superclass.

cast_par 	Same as @call.

msg	Same as @call.

param	Same as @call.

flags	Same as @call.

(void) @callsuper myObj::MySupClass::MSG_MY_MSG();

See Also:	@call, @send, @message, @method

n	@chunk

@chunk	<type> <name> [= <init>];

The @chunk keyword declares a resource chunk containing data of some kind. 
Data can be of any GEOS or C data type or structure, including a string of 
characters. The chunk must be declared between the resource delimiters 
@start and @end. Its arguments are described below:

type	The data type or structure type of the chunk.

name	The name of the chunk-how it will be referenced by other 
entities.

init	Initializer data, if any, to initialize the chunk to.

If you will need to access the chunk from another executable file, you must 
declare it in the other file with @extern. Objects are declared with @object.

typedef struct {
    int     a;
    int     b;
} MyStruct;

char    MyString[8];

@start MyDataResource, data, notDetachable;
@chunk word			MyWordChunk;
@chunk MyStruct			MyMSChunk = {5, 10};
@chunk MyString			MyStringChunk = "My string";
@end;

See Also:	@start, @end, @object, @extern

n	@chunkArray



@chunkArray 	<stype> <aname> [= {<init>}];

The @chunk keyword declares a Chunk Array, a special kind of chunk. Only 
uniform-element-size chunk arrays may be declared with this keyword. It has 
the following arguments:

stype	This is the type of each element in the Chunk Array. It may be 
any standard C or Goc type, or any derived type.

aname	This is the name of the Chunk Array.

init	You may declare the initializer values for a chunk array. If you do 
not set any initial values, the Chunk Array will be created with 
no elements.

@chunkArray int			someints;

@chunkArray dword			somedwords = {123456789, 
					6021023, 
					31415926};

See Also:	@chunk, @elementArray

n	@class

@class	<cname>, <super> [, master [, variant]];

The @class keyword begins a class definition. All instance data and messages 
for the class are declared between @class and @endc. The arguments of @class 
are listed below:

cname	Name of the class being declared.

super	Name of the superclass.

master	Use of this term designates this class as a master class.

variant	Use of this term designates this class as a variant class.

@class MyTriggerClass, GenTriggerClass;
@endc

@class MyMasterVarClass, MetaClass, master, variant;
@endc

See Also:	@endc, @classdecl

n	@classdecl

@classdecl <cname> [, neverSaved];

The @classdecl keyword defines a given class structure in memory. Every new 
class that will be used by an application must appear in an @classdecl 
declaration. The arguments for this keyword are shown below:

cname	The name of the class being declared.

neverSaved	Using this term indicates that objects of this class are never 
saved along with state information.

@classdecl MyTriggerClass;
@classdecl MyProcessClass, neverSaved;

See Also:	@class

n	@composite

@instance @composite <iname> = <linkFieldName>;

The @composite keyword appears as a subcommand of @instance. It is a type 
of instance data-it indicates that an object of this class can have several 
children and that the @composite instance data field will be an optr to the first 
of its children. The arguments of the @composite keyword are given below:

iname	The name of the instance data field.

linkFieldName
The name of the @link instance data field for this class.

@class GenTrigWithKidsClass, GenTriggerClass;
    /* GI_link is the GenClass sibling link field. */
    @instance @composite GTWKI_comp = GI_link;
@endc

See Also:	@instance, @link

n	@default

<fname> = @default [<op> [~]<attr>]*; /* to use default value of
                          instance data field */

@default <varRoot> = <super>; /* to specify default superclass of 
                 a variant class */

@default <fname> = <value>; /* to specify a default value for an instance
data field defined by a superclass. */

<fname> = @default;

The @default keyword can be used in several ways: to specify the default calue 
of an instance data field, to represent the default value of an object's instance 
data field, or to specify the default superclass of a variant class. It may also be 
used when defining a class to specify a default value to use with an instance 
data field defined by a superclass.

The @default keyword is most commonly used when modifying default instance 
data values of bitfield-type fields. The defaults are set in the @class definition 
and may be modified in the @object declaration. The arguments of @default are 
shown below:

fname	The name of the instance data field. Typically, this is a record.

op	A bitwise operator character. If setting certain bits, use the OR 
operator (|); if removing certain bits, use the AND operator (&).

attr	The name of the attribute bit to set or remove. If removing 
attribute bits, place the logical NOT character (~) in front of the 
attribute.

@object GenPrimaryClass MyPrimary {
    GI_states = @default & ~GENS_MAXIMIZED;
    GI_attrs = @default | GENA_TARGETABLE;
}

The @default keyword can also be used to specify the default superclass of a 
variant class. In this case, it has the following arguments:

varRoot	The name of the variant class, with the word "Class" removed. 
(e.g. the root of "MyVariantClass" is "MyVariant".)

super	The default superclass for this variant class.

To specify a class' default value for an instance data field when that instance 
data field is defined by a superclass, @default has the following arguments:

fname	The name of the instance data field.

value	The class' default value for the field.

To represent an object's default value for an instance data field, @default has 
the following arguments:

fname	The name of the instance data field.

See Also:	@object, @instance, @class

n	@define

@define <mname>[(<pdef>)] <macro>

The @define directive defines a Goc macro. You can define C macros with the 
#define directive; macros that use Goc operators, keywords, or code must be 
defined with @define. Similarly, macros defined with @define must be later 
used with the "@" marker preceeding them; otherwise, the Goc processor will 
scan over the macro and will not evaluate it. The arguments of @define are 
listed below:

mname	The macro name. This can be used later as @mname to invoke 
the macro.

pdef	The optional parameter definition, as with C macros.

macro	The macro.

@define MyChunk(a) @chunk char[] a = "text";
@define MyText(a,b) @chunk char[] a = "b";

/* You can later use these macros as follows: */

@MyChunk(Text1)
@MyText(Text2, newText)

/* This will evaluate to the following: */

@chunk char[] Text1 = "text";
@chunk char[] Text2 = "newText";

n	@deflib



@deflib <libName>

Most Goc libraries will have a .goh header file. This file should begin with a 
@deflib directive. This will see to it that no library header file is included more 
than once in a given compilation. The file must end with an @endlib directive. 
The @deflib directive takes the following argument:

libName	This is the name of the header file, with the .goh extension 
stripped off. For example, if the library's header file is 
hellolib.goh, the file would begin with

@deflib		hellolib

See Also:	@endlib

n	@dispatch

@dispatch [noFree] [{<cast>}] <nObj>::<nMsg>::<event>;

The @dispatch keyword sends a previously-encapsulated message to the 
specified object. This keyword is analogous to @send; use @dispatchcall if the 
event must be processed immediately. The encapsulated event must have been 
defined with @record. The arguments of @dispatch are given below:

noFree	A flag indicating the event will not be freed after it is handled.

cast	A message to cast the parameters to.

nObj	An override recipient object for the event. Encapsulated 
messages can store recipients; this will override the stored value. 
If no override is desired, specify this as null.

nMsg	An override message to be sent. Encapsulated messages can 
store the message number to be sent; this will override the stored 
value. If no override is desired, specify this as null.

event	The name of the encapsulated event, defined earlier with 
@record.

@dispatch null::null::myEvent;
@dispatch newObject::null::myEvent;
@dispatch null::MSG_NEW_MSG::myEvent;

See Also:	@record, @send, @dispatchcall

n	@dispatchcall

<ret> = @dispatchcall [noFree] [{<cast>}] <nObj>::<nMsg>::<event>;

The @dispatchcall keyword sends a previously-encapsulated message to the 
specified object. This keyword is analogous to @call; use @dispatch if the event 
can be sent with no return values. The encapsulated event must have been 
defined with @record. The arguments of @dispatchcall are given below:

ret	A variable to receive the returned value.

noFree	A flag indicating the event will not be freed after it is handled.

cast	A message to cast the parameters and return value to.

nObj	An override recipient object for the event. Encapsulated 
messages can store recipients; this will override the stored value. 
If no override is desired, specify this as null.

nMsg	An override message to be sent. Encapsulated messages can 
store the message number to be sent; this will override the stored 
value. If no override is desired, specify this as null.

event	The name of the encapsulated event, defined earlier with 
@record.

retVal = @dispatchcall null::null::myEvent;
retVal = @dispatchcall newObject::null::myEvent;
(void) @dispatchcall null::MSG_NEW_MSG::myEvent;

See Also:	@record, @send, @dispatchcall

n	@elementArray



@elementArray 	<stype> <aname> [= {<init>}];

The @chunk keyword declares a Element Array, a special kind of Chunk Array. 
It has the following arguments:

stype	This is the type of each element in the Element Array. It may be 
any standard C or Goc type, or any derived type.

aname	This is the name of the Element Array.

init	You may declare the initializer values for a chunk array. If you do 
not set any initial values, the Element Array will be created with 
no elements.

See Also:	@chunk, @chunkArray

n	@end

@end	<segname>

The @end keyword denotes the end of a resource block definition that had been 
started with @start. Its one argument is the name of the resource segment.

@start MenuResource;
@end

See Also:	@start, @header, @object, @chunk

n	@endc

@endc

The @endc keyword denotes the end of a class definition begun with @class. It 
has no arguments.

See Also:	@class

n	@endif

@endif

The @endif directive denotes the end of a block of conditionally-compiled code. 
It is used with @if, @ifdef, and @ifndef.

See Also:	@if, @ifdef, @ifndef

n	@endlib



@endlib

Most Goc libraries will have a .goh header file. This file should end with an 
@endlib directive. This will see to it that no library header file is included more 
than once in a given compilation. The file must begin with an @deflib directive.

See Also:	@deflib

n	@exportMessages

@exportMessages <expname>, <num>;

The @exportMessages keyword sets aside a number of message spots so the 
messages may be declared elsewhere. This allows users of the class to declare 
messages that are guaranteed to be unique across all subclasses. Exported 
messages are declared with the @importMessage keyword. The arguments of 
@exportMessages are shown below:

expname	Name of the range being exported.

num	Number of message spots to be exported.

@exportMessages MetaUIMessages, 50;
@exportMessages MyExportedMessages, 12;

See Also:	@importMessage, @reserveMessages, @message

n	@extern

@extern	<type> <name>;

@extern	method <cname>, <manme>+

The @extern keyword allows code in a given compilation session to access 
objects, chunks, monikers, and methods defined in another compilation 
session. The compiler will assume the element exists and will be linked by the 
Glue linker. If Glue is unable to locate and link the external resource element, 
it will respond with an error. The arguments of @extern are given below:

type	The type of resource element being referenced. This must be one 
of object, chunk, visMoniker, or method.

name	The name of the element being referenced.

@extern chunk MyChunk;
@extern object MyBlueTrigger;
@extern visMoniker GAL_visMoniker;

If @extern is being used to declare a method which is in a different file from the 
class declaration, it has the following arguments:

cname	The name of the class for which the method is defined.

mname+	The name of the message which invokes the method. As with 
normal method declarations, there must be at least one message 
which invokes the method.



Some confusion has arisen about when to use @extern. The following notes 
will hopefully prove useful.

		Classes

Your class' definition should not be broken up over files. If you wish to keep 
your class definition in a file separate from your other code, this file should be 
a .goh file.

If your class is declared (@classdecl) in a file other than where it is defined 
(@class), then the declaring file should @include the defining file.

Normally the declaring file contains all method definitions for the class. If any 
method definitions are in another file, then both files will need an @extern 
keyword like so:

In file containing class declaration:

 @extern method MyClass, MSG_MY_DO_SOMETHING;

In file containing method code:

@extern method MyClass,
			MSG_MY_DO_SOMETHING(word myArg)
{ /* Method code here */ }

		Object Trees

All objects declared in a static tree (e.g. your application's generic tree) should 
be in the same source file. If they are in different files, then they may be joined 
into a single tree only by dynamically adding objects from one file as children 
to objects of the other.

Note that if one file contains a tree of objects, then you may incorporate the 
whole tree by simply dynamically adding the top object in the file to the main 
tree. You won't have to add each object individually.

If an object declared in one source file will send a message to an object in 
another source file, you must include an @extern line in the source file 
containing the sending object: 

@extern object ReceivingObjectName;

The message itself should be sent in the following manner (with variations 
possible if you will be using @call, passing arguments, or what have you):

optr ROOptr;
ROOptr = GeodeGetOptrNS(@ReceivingObjectName);
@send ROOptr::MSG_DO_SOMETHING(0, 0);

See Also:	@chunk, @object, @visMoniker

n	gcnList

gcnList(<manufID>,<lname>) = <oname> [, <oname>]*;

The gcnList keyword, which does not have the keyword marker @ preceeding 
it, puts the listed objects onto the specified notification list. GCN lists are 
specified by both manufacturer ID and list type. The arguments of the gcnList 
keyword are given below:

manufID	The manufacturer ID number of the GCN list type. Often this will 
be MANUFACTURER_ID_GEOWORKS.

lname	The list type, or list name, of the GCN list.

oname	A listing of all the objects that will be included on the GCN list. 
Separate objects with commas.

@object GenApplicationClass HelloApp = {
    GI_comp = HelloPrimary;
    gcnList(MANUFACTURER_ID_GEOWORKS, GAGCNLT_WINDOWS) =
						HelloPrimary;
}

See Also:	@object

n	@genChildren



@send @genChildren::<msg>(<params>);

Any composite object in a generic object tree (therefore a subclass of 
GenClass) can send a message that will be dispatched at once to all of its 
children. Note that any message sent with @genChildren as the destination 
must be dispatched with the @send keyword and therefore can have no return 
value and can not pass pointers in its parameters.

n	@genParent



[@send | @call]@genParent::<msg>(<params>);

Any composite object in a generic object tree (therefore a subclass of 
GenClass) can use the @genParent address to send a message to its generic 
parent. This can be used with either @send or @call.

n	@gstring



@gstring <gsname> = {[<command> [, <command>]+]}

The @gstring keyword lets you declare a GString in Goc source code.

gsname	The name of the chunk which will contain the GString.

command	This may be any command which could be put in a GString.

n	@header

@header	<type> [= <init>];

The @header keyword sets the header of an object or data resource segment to 
a custom structure. The structure must begin with an LMemBlockHeader or 
ObjLMemBlockHeader. The arguments of @header are given below:

type	The name of the structure set as the new header type.

init	Any initializer data for the fields added to your structure.

typedef struct {
    LMemBlockHeader  meta;
    int     a;
    int     b;
} MyLMemBlockHeader;

@start MyDataResource, data, notDetachable;

@header MyLMemBlockHeader = 10, 12;

@end;

See Also:	@start, @end, @object, @chunk

n	@if

@if (<cond>)

The @if directive denotes the beginning of a conditionally-compiled block of 
code. If the expression detailed in cond equates to true, then the code between 
the @if directive and the first corresponding @endif directive will be compiled 
with the rest of the code.

cond	The expression determining whether the code is to be compiled or 
not. This expression is based on numerical values, names of 
macros, and Boolean operators (|| and &&).

@if 0
	/* code not compiled */
@endif

@if MyMacro
	/* code compiled if MyMacro is defined */
@endif

@if defined(MyMacro) || MY_CONDITION
	/* code compiled either if MyMacro is defined or
	 * if MY_CONDITION is non-zero */
@endif

See Also:	@ifdef, @ifndef, @endif

n	@ifdef

@ifdef <item>

The @ifdef directive is similar to the @if directive in use, except the condition 
it evaluates is based solely on whether the item is defined or not (if item is 
defined, the following code is compiled).

See Also:	@if, @ifndef, @endif

n	@ifndef

@ifndef <item>

The @ifndef directive is similar to the @ifdef directive in use, except the 
condition it evaluates is based solely on whether item is not defined (if item is 
not defined, the following code is compiled).

See Also:	@if, @ifdef, @endif

n	@importMessage

@importMessage <expname>, <messageDef>;

The @importMessage keyword declares a message with a reserved message 
number set aside earlier by @exportMessages. The arguments of this keyword 
are given below:

expname	Name of the range exported with @exportMessages.

messageDef	Standard message definition-exactly the same as would follow 
the @message keyword for message declaration.

@importMessage MyExportedMessages, word MSG_MY_MSG(
					byte param1, byte param2);

See Also:	@exportMessages, @reserveMessages, @message

n	@include

@include <fname>

The @include directive is used to include Goc files into a code file. It is similar 
to the #include directive in C. Its only argument is a file name (fname) enclosed 
in either angled brackets or quotation marks. If you use quotation marks, the 
compiler will look first in the file's own directory; if you use angled brackets, it 
will look first in the standard include directories.

@include <stdapp.goh>
@include <uitsctrl.goh>
@include "Art/mkrGenDoc"

n	@instance

@instance <insType> <iname> = <default>;

The @instance keyword declares an instance data field for a class. This 
keyword will appear between the class delimeters @class and @endc. Its 
arguments are shown below:

insType	The data type of the instance data field. Must be a valid C data 
type or data structure. (Note-special types may also be used; see 
discussion below.)

iname	The name of the instance data field.

default	The default value of the field if it is not declared explicitly in the 
instance of the class.

The Goc preprocessor allows the use of several special types of instance data 
fields. To use these special types, insert the proper keyword (type name) in 
place of the insType argument above and do not include a default value for the 
field (default). The possible special types and their meanings are given in the 
list below (see the individual keyword entries for more detail):

@composite
This field will point to the first child in an object hierarchy. Note 
that this keyword has a special format. Rather than being 
allowed a default value, set the default argument in the 
declaration to be the same as the name of the corresponding 
@link field. This is important; otherwise, your program will not 
compile properly.

@link	This field will point to the next sibling object in an object 
hierarchy or will point to the parent.

@visMoniker
This field will contain a visual moniker or a pointer to a visual 
moniker resource chunk.

@kbdAccelerator
This field will contain a keyboard accelerator character.

Note that if you want to declare instance data fields for variable-sized data, you 
should use the @vardata keyword rather than @instance.

@instance int				myInteger = 10;

typedef struc {
    int     a;
    int     b;
} MyStruc;
@instance MyStruc				strucField = {7, 11};

@instance @visMoniker 				GI_moniker;

@instance @link				VI_link;
@instance @composite 				VCI_comp = VI_link;

@instance @kbdAccelerator GI_kbdAcc;

See Also:	@vardata, @visMoniker, @link, @composite, @kbdAccelerator

n	@kbdAccelerator

@instance @kbdAccelerator <iname>;

The @kbdAccelerator keyword follows @instance to create an instance data 
field that will contain a keyboard accelerator. The iname argument is the name 
of the instance data field.

@instance @kbdAccelerator GI_kbdAcc;

See Also:	@instance

n	@link

@instance @link <iname>;

The @link keyword follows @instance to define a link instance data field 
pointing to the object's next sibling in the object hierarchy. The iname 
argument is the name of the instance data field. Note that the name of the link 
field must be set as the default value of the corresponding @composite field.

@instance @link GI_link;
@instance @composite GI_comp = GI_link;

See Also:	@instance, @composite

n	@message

@message	<retType> <mname>([@stack] <param>*);

The @message keyword defines a message and its parameters and return 
values. This keyword will appear within a class definition (i.e., between @class 
and @endc). The message defined with @message will automatically be valid 
for the class for which it is defined as well as for subclasses of that class. The 
arguments of this keyword are shown below:

retType	The data type of the value returned by this message. This must 
be a standard C or GEOS data type or pointer.

mname	The name of the message. Typically, this will be the prefix "MSG_" 
followed by a shortened version of the class name, followed by a 
short name for the message.

@stack	This keyword may be used if the message might be sent from 
assembly language code instead of Goc. It indicates that the 
arguments will be passed on the stack; the handler will pop them 
off the stack in reverse order from the way they are listed in the 
declaration.

param*	The parameters for this message, of which there may be none or 
several. All the parameters must appear inside the parentheses. 
Parameters are defined in a similar manner as for functions and 
routines; each one consists of a data type followed by the name of 
the parameter of that type.

@message void MSG_TRIGGER_PUSHED(int push1);

@message word MSG_MY_MSG(byte firstParam, word secParam,
					long thirdParam);

See Also:	@method, @reserveMessages, @exportMessages, @importMessage, @record

n	@method

@method	[<hname>,] <cname>, <mname>+ [{<code>}];

The @method keyword begins definition of a method (message handler). Its 
arguments are listed below:

hname	The method name, if any. If no method name is given, one will be 
created by removing "Class" from the class name and "MSG_" 
from the message name and concatenating the two.

cname	The name of the class to which the method belongs. Each method 
belongs to only one class.

mname+	The name(s) of the message(s) handled by this method. There 
must be at least one message which invokes this method. There 
may be more than one, as long as they all have the same 
parameters.

code	Goc procedural code to handle the message. If there is no code, 
hname is assumed to be the name of an existing routine which 
should be used as the method.

@method   MyClass, MSG_MY_MSG {
    /* method code goes here */
}

@method   MyClassMethod, MyClass, MSG_MY_MSG {
    /* method code goes here */
}

See Also:	@message

n	@noreloc



@noreloc <iname>;

The @noreloc keyword specifies that an instance data field (defined in the 
previous program statement) is not relocatable. Normally optr fields are 
assumed to be relocatable and will be automatically relocated by the system 
when shutting down and coming back from a shutdown; by means of the 
@noreloc, this automatic behavior can be turned off for a given field.

n	@object

@object	<class> <name> <flags>* = {

    [<fieldName> = <init>;]*

    [<varName> [= <init>];]*

}

The @object keyword defines an object in an object resource block. It must 
appear between @start and @end. Its arguments are defined below:

class	The name of the class of the object.

name	The name of the object.

flags	Flags associated with the object; currently only ignoreDirty is 
supported. When set, this flag indicates that changes to the 
object should not be saved to a state file. Note, however, that 
ignoreDirty should never be set for generic objects.

fieldName	The name of an instance data field defined with @instance. Any 
number of such fields may be specified.

varName	The name of an instance data field defined with @vardata. Any 
number of such fields may be specified.

init	Initializer data for a normal instance data field or for the extra 
data of a variable data field. If a variable data field has no extra 
data, no initializer should be specified.

Many fields may be specified in the object declaration. Each field reference 
must be defined in a class in the object's class ancestry. Additionally, not all 
fields must be set. If a field is not specified within the @object declaration, the 
field will be set to its default value as defined by the class.

@start MyObjectResource;

@object GenTriggerClass MyTrigger ignoreDirty = {
    GI_visMoniker = "MyTrigger's Moniker";
}

@object GenApplicationClass MyApp = {
    GI_comp = MyPrimary;
    gcnList(MANUFACTURER_ID_GEOWORKS, GAGCNLT_WINDOWS) =
							MyPrimary;
}

@object GenPrimaryClass MyPrimary = {
    GI_comp = MyMenu, MyInteraction, MyView;
    GI_visMoniker = "My Primary's Moniker";

}

@object MyClass NewObject = {
    NO_instance1 = 1;
    NO_instance6 = `C';
}

@end

See Also:	@start, @end, @extern, @class, @instance, @vardata

n	@optimize



@optimize

This directive may be placed at the top of a .goh file. The directive instructs 
Goc to generate a specially processed .poh file which contains all the 
information of the .goh file, but is somewhat faster to compile. This .poh file is 
automatically regenerated if the corresponding .goh file has been changed 
since the last compilation.

n	@protominor



@protominor <prototypeName>

When creating a new version of an existing library, use the @protominor 
keyword to declare new messages and variable data fields for a class. Suppose 
your original class declaration looked like so:

@class MyClass, SuperClass;
	@message void MSG_M_DO_THIS(void);
	@vardata void TEMP_M_DONE_FLAG;
@endc

Having released this version of your class, you wished to release another 
version in which this class handled another message. You wanted to specify 
that this new message would only work with this new version of the library. 
This would be set up like so:

@class MyClass, SuperClass;
	@message void MSG_M_DO_THIS(void);
	@vardata void TEMP_M_DONE_FLAG;

	@protominor MyVersion20
	@message void MSG_M_DO_THAT(void);
@endc

To do the equivalent version control with routines, use the incminor .gp file 
directive.

n	@prototype

@prototype <messageDef>;

The @prototype keyword allows multiple messages to have the same pass and 
return parameters. Use @prototype to define the pass and return values, then 
use @message to declare the messages that have these parameters. The 
messages defined with @message will have different message numbers and 
will invoke different methods. The messageDef argument is a standard 
message definition.

@prototype word MSG_MY_PROTO(byte param1);

@message(MSG_MY_PROTO) MSG_MY_MSG;
@message(MSG_MY_PROTO) MSG_MY_SECOND_MSG;

See Also:	@alias, @message

n	@record

<event> = @record <obj>::<msg>(<param>*);

The @record keyword encapsulates an event for later use with @dispatch or 
@dispatchcall. The arguments of @record are as follows:

event	The name of the event. This name will be used with @dispatch 
and @dispatchcall later.

obj	The name of the object, or an expression representing the object 
that will receive the message. This may be set to null to indicate 
that the recipient will be determined when the message is sent.

msg	The name of the message, or an expression representing the 
message that will be sent. This may be set to null to indicate that 
the message will be determined when it it sent.

param	This is a list of parameters that will be sent with the message 
when it is dispatched.

myEvent = @record myObj::MSG_VIS_VUP_CREATE_GSTATE();

See Also:	@dispatch, @dispatchcall, @call, @send

n	@reloc

@reloc	<iname>, [(<count>, <struct>)] <ptrType>;

@reloc	<iname>, <fn>, [(<count>, <struct>)] <ptrType>;

The @reloc keyword designates an instance data field that contains data 
requiring relocation on startup. Note that this does not include instance fields 
declared with the @composite and @link fields, but it does include any handle 
or pointer fields you may have. Note that there are two different formats for the 
use of @reloc. The first represents a normal instance field; the second 
represents a variable data instance field (see @vardata). This is not used with 
@instance or @vardata but stands alone.

The arguments of @reloc are shown below:

iname	The name of the relocatable instance data field.

count	If the instance variable is an array of relocatable data or 
structures containing relocatable fields, this is the number of 
elements in the array.

struct	If the relocatable data is an array of structures, this represents 
the name of the field within each structure that requires 
relocation.

ptrType	This is the type of pointer in the relocatable field. This must be 
one of optr (object pointer), ptr (far pointer), or handle.

fn	This is the name of the field within the extra data of the variable 
data. If no extra data will be associated with this relocatable 
field, then put a zero (0) rather than a field name.

@reloc MO_myHandle, handle;
@reloc MO_myVarHandle, 0, handle;
@reloc MO_myTable, (10, MyStruct), ptr;

See Also:	@instance, @vardata

n	_reloc



@method [<hname>,] <cname>, _reloc { <code>};

The _reloc keyword is used to write relocation handlers for classes, if you need 
to relocate-unrelocate instance data when it's either read in or saved to state.

The arguments of _reloc are show below:

code	Code to execute when the object block is loaded in or saved out to 
state.	, in which case instance data may need to be relocated or 
unrelocated by hand.	

n	@reserveMessages

@reserveMessages <number>;

The @reserveMessages keyword reserves the given number of message spots. 
Messages are numbered sequentially according to the order of their 
declaration; this keyword allows one or more numbers to be skipped in the 
numbering process, allowing application upgrades without making earlier 
versions obsolete. The single argument is the number of message spots to skip.

@reserveMessages 25;

See Also:	@exportMessages, @importMessage, @message

n	@send

@send	[<flags>+] [(<cast_ret>)] <obj>::[{<cast_par>}]<msg>(<param>*);

The @send keyword sends a given message to the specified object. The message 
will be sent and the sender's thread will continue executing without waiting for 
a response. If return values or synchronization is important, use the @call 
keyword. The parameters of @send are shown below:

flags	Flags that determine how the message affects the recipient's 
event queue. The allowable flags are shown below. (The comma 
is required before each flag.)

cast_ret	A message to cast the message return value to. When Goc 
determines what type of value should be returned, it uses the 
return value of the cast_ret message if this field is used. The curly 
braces are required around this field.

obj	The name of the recipient object, or an optr to the object.

cast_par 	A message to cast the message parameters to. When Goc 
determines what type of values should be passed to the message, 
should be returned, it uses the parameters of the cast_par 
message if this field is used. The curly braces are required 
around this field.

msg	The name of the message to be sent, or an expression 
representing the message number. If an expression is used, you 
must cast the message to a certain type with the cast argument .

param	Expressions or constants passed to the message. Parameters 
passed to messages are specified in the same way as if they were 
being passed directly to a function or routine in C. Note that 
pointers may not be passed with @send but handles may; if you 
must pass a pointer, use @call.

The flags allowed with @send are shown below:

forceQueue
This flag will cause the message to be placed in the recipient's 
event queue, even if it could have been handled by a direct call.

checkDuplicate
This flag makes the kernel check if a message of the same name 
is already in the recipient's event queue. For this flag to work, 
forceQueue must also be passed. Note that due to implementation 
constraints, events will be checked from last to first rather than 
from first to last.

checkLastOnly
This flag works like checkDuplicate, above, except that it checks 
only the last message in the event queue.

replace	This flag modifies checkDuplicate and checkLastOnly by 
superseding the duplicate (old) event with the new one. The new 
event will be put in the duplicate's position in the event queue. If 
a duplicate is found but the replace flag is not passed, the 
duplicate will be dropped and the new event will be put at the end 
of the queue.

insertAtFront
This puts the message at the front of the recipient's event queue. 
Note that this flag will supersede the replace flag.

canDiscardIfDesperate
This flag indicates that this event may be discarded if the system 
is running extremely low on handles and requires more space 
immediately.

@send, forceQueue MyObj::MSG_MY_MSG(10, x);
@send MyObj::MSG_SET_ATTR(attributesParam);

See Also:	@call, @callsuper, @message, @method

n	@specificUI

<fname>	= [@specificUI] <mod>* <key>;

The @specificUI keyword is used when setting a keyboard accelerator instance 
field in an object declaration. It tells the UI to allow the use of the keystrokes 
specified, even if they are normally reserved for the specific UI. The keyword 
itself takes no arguments; those shown are for the GenClass instance data 
field GI_kbdAccelerator. These are

fname	The name of the instance data field defined with @instance.

mod	Modifier keys; must be one or more of control, ctrl, shift, alt.

key	The accelerator character. Must be either a numeric value of a 
keyboard key or a letter enclosed in single quotation marks.

@object MyClass MyObject {
    GI_kbdAccelerator = ctrl shift `k';
}

See Also:	GenClass, @kbdAccelerator, @instance

n	@stack



@message	<retType> <mname>([@stack] <param>*);

This keyword may be used if the message might be sent from assembly 
language code instead of Goc. It indicates that the arguments will be passed on 
the stack; the handler will pop them off the stack in reverse order from the way 
they are listed in the declaration.

See Also:	@message

n	@start

@start	<segname> [, <flags>];

The @start keyword indicates the beginning of a resource block. The end of the 
block is denoted by the keyword @end. The arguments of @start are listed 
below:

segname	The name of the resource segment.

flags	Optional flags. The flag data, when set, indicates the block will 
be a data resource rather than an object resource. The flag 
notDetachable, when set, indicates the block should not be saved 
to a state file.

@start MenuResource;
@end

@start MyDataResource, data, notDetachable;
@end

See Also:	@end, @header, @object, @chunk

n	@uses



@uses <class>;

If you know that a variant class will always be resolved to be a subclass of some 
particular class, you can declare this with the @uses keyword. This will let the 
variant class define handlers for the "used" superclass. The keyword uses the 
following argument:

class	A class which will always be a superclass of the defined variant 
class.

Warnings:	You must make sure that the variant class's inheritance is always resolved 
such that the used class is one of its ancestor classes.

See Also:	@class

n	@vardata

@vardata	<type> <vname>;

The @vardata keyword creates a vardata data type for a class. Each type 
created with @vardata can be simply the name of the type, or it can have 
additional data (a single structure). The arguments of @vardata are given 
@defaultbelow:

type	This is the data type or structure type of the data field. If no extra 
data is to be associated with this field, then put the word void in 
place of a type.

vname	This is the name of the variable data instance field.

@vardata		dword		MY_FIRST_VAR_DATA;

typedef struc {
    int     a;
    int     b;
} MyStruc;

@vardata		MyStruc		MY_SECOND_VAR_DATA;
@vardata		void		MY_THIRD_VAR_DATA;

See Also:	@vardataAlias, @instance

n	@vardataAlias

@vardataAlias (<origName>) <newType> <newName>;

The @vardataAlias keyword allows you to set up variable data fields with 
varying amounts of extra data. That is, a single variable data field in the 
instance chunk could have two different sizes and two different names. The 
arguments of @vardataAlias are listed below:

origName	The name of the original variable data field defined with 
@vardata.

newType	The new type or structure associated with this variable data 
field. If no extra data is to be associated with this alias, then put 
the word void instead of a type.

newName	The new name of the variable data field that uses the new type.

/* defined in GenTriggerClass */

@vardata word ATTR_GEN_TRIGGER_ACTION_DATA;

/* A special GenTrigger that uses a different data
 * type is defined in the application: */

@object GenTriggerClass MyTrigger = {
    GTI_actionMsg = MSG_MY_APPS_MESSAGE;
    GTI_destination = process;
    @vardataAlias (ATTR_GEN_TRIGGER_ACTION_DATA)
			dword ATTR_MY_TRIGGER_SPECIAL_DATA;

See Also:	@vardata, @instance

n	@visChildren



@send @visChildren::<msg>(<params>);

Any composite object in a visible object tree (therefore a subclass of 
VisCompClass) can send a message that will be dispatched at once to all of its 
children. Note that any message sent with @visChildren as the destination 
must be dispatched with the @send keyword and therefore can have no return 
value.

n	@visParent



@send @visParent::<msg>(<params>);

Any object in a visible tree can use @visParent as the destination of an @call 
command. The message will be sent to the object's parent in the visible object 
tree. The remainder of the command is the same as a normal @call.

n	@visMoniker

@instance @visMoniker <iname>;

The @visMoniker keyword follows @instance to create an instance data field 
for a visual moniker. The iname argument is the name of the instance data 
field.

@instance @visMoniker GI_visMoniker;

See Also:	@instance, GenClass
