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

@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.

@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.

@gstring

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

The @gstring keyword lets you declare a chunk containing GString data 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. This is actually a series of bytes. Normally, the GS...() macros are used to specify the bytes.

An example:

@gstring MultPrimContentOneGraphic = {
	GSSetGStringBounds(10,10,48,64),
	GSSetTextColorIndex(C_VIOLET),
	GSSetFont(FID_DTC_URW_SANS, 54.0),
	GSSetTextStyle(TS_ITALIC, ~TS_ITALIC),
	GSDrawText(10, 10), "1",
	GSEndString()
};

The GSSetGStringBounds() command has been set up to optimize use of this GString: the programmer has pre-computed the drawing bounds of the GString. The graphics system will use the pre-computed bounds to speed up clipping.

The GSEndString() command signals that the GString is done. In all but the rarest cases, all GStrings should end with an end-gstring command.

@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;

@header MyLMemBlockHeader = 10, 12;

@end MyDataResource;

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

@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

@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

@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

@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

@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 "Art/mkrGenDoc"

See Also: @extern

@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

@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

@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

@localize

@localize { <string> <min>-<max> };
@localize { <string> <length> };
@localize { <string> };
@localize <string>;
@localize not;

This keyword is used to specify instructions for translators. When appearing under a @visMoniker or @chunk construction, this keyword specifies a string which the ResEdit program will show to translators localizing the geode.

For example:

@visMoniker FakeItemMoniker = "Data:";

@localize "This string will appear at the head of the list";

The arguments of this keyword are as follows:

string

The explanatory string.

min

The minimum length of the moniker or chunk's text.

max

The maximum length of the moniker or chunk's text.

length

The length of the moniker or chunk's text.

not

Keyword specifying that the moniker or chunk can not be localized.

@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

@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

@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.

@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.

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 MyObjectResource;

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

@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.

@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;
@endc
	@protominor MyVersion20
	@message void MSG_M_DO_THAT(void);

You would also need to add an "incminor" line to the end of your .gp file:

incminor 	MyVersion20

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

See Also: @protoreset

@protoreset

@protoreset

The @protoreset keyword signals that the rest of a file should ignore any previous @protominor statements.

@class MyFirstClass, SuperClass;
	@message void MSG_M1_DO_THIS(void);
	@vardata void TEMP_M1_DONE_FLAG;
@endc
	@protominor MyVersion20
	@message void MSG_M1_DO_THAT(void);
	@protoreset

@class MySecondClass, SuperClass;
	@instance word M2I_token;
	@vardata void ATTR_M2_IGNORE_TOKEN;
	@protominor MyVersion20
	@vardata word ATTR_M2_ALTERNATE_TOKEN;
@endc

@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

@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

@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

_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.

@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

@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

@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

@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

@start

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

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 flag. 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 MenuResource;

@start MyDialogResource, notDetachable;
@end MenuResource;

@start MyStringResource, data;
@end MyStringResource;

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

@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

@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

@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

@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.

@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

@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 .