Designator: Declare an Object Block.

OBJ
Symbol < [Count] > : "ObjectName" < Symbol < [Count] > : "ObjectName" >…

Symbol is the desired name for the object symbol.
Count is an optional expression, enclosed in brackets, that indicates this is an array of objects, with Count number of elements. When later referencing these elements, they begin with element 0 and end with element Count-1.
ObjectName is the filename, without extension, of the desired object. Upon compile, an object with this filename is searched for in the editor tabs, the working directory and the library directory. The object name can contain any valid filename characters; disallowed characters are \, /, :, *, ?, ", <, >, and |.

Explanation

The Object Block is a section of source code that declares which objects are used and the object symbols that represent them. This is one of six special declarations (CON, VAR, OBJ, PUB, PRI, and DAT) that provide inherent structure to the Spin language.

Object declarations begin with OBJ on a line by itself followed by one or more declarations. OBJ must start in column 1 (the leftmost column) of the line it is on and we recommend the lines following be indented by at least two spaces for readability. For example:

OBJ
  Num : "Numbers"
  Term : "TV_Terminal"

This example defines Num as an object symbol of type "Numbers" and Term as an object symbol of type "TV_Terminal". Public and Private methods can then refer to these objects using the object symbols as in the following example.

PUB Print | S
S := Num.ToStr(LongVal, Num#DEC)
Term.Str(@S)

This public method, Print, calls the Numbers' ToStr method and also the TV_Terminal's Str method. It does this by using the Num and Term object symbols followed by the Object-Method reference symbol (a period '.') and finally the name of the method to call. Num.ToStr, for instance, calls the Numbers object's public ToStr method. Term.Str calls the TV_Terminal's public Str method. In this case the Num.ToStr has two parameters, in parentheses, and Term.Str has one parameter.

Also notice that the second parameter of the Num.ToStr call is Num#DEC. The # symbol is the Object-Constant reference symbol; it gives access to an object's constants. In this case, Num#DEC refers to the DEC (decimal format) constant in the Numbers object.

See Object-Method Reference '.' and Object-Constant Reference '#' in Symbols for more information.

Multiple instances of an object can be declared with the same object symbol using array syntax and can be accessed similar to arrays as well. For example:

OBJ
  PWM[2] : "PWM"
PUB GenPWM
  PWM[0].Start
  PWM[1].Start

This example declares PWM as an array of two objects (two instances of the same object). The object itself just happens to be called "PWM" as well. The public method, GenPWM, calls the Start method of each instance using indexes 0 and 1 with the object symbol array, PWM.

Both instances of the PWM object are compiled into the application such that there is one copy of its program code (PUBs, PRIs, and DATs) and two copies of its variable blocks (VARs). This is because, for each instance, the code is the same but each instance needs its own variable space so it can operate independent of the other.

An important point to consider with multiple instances of an object is that there is only one copy of its DAT block because it may contain Propeller Assembly code. DAT blocks can also contain initialized data and regions set aside for workspace purposes, all with symbolic names. Since there is only one copy of it for multiple instances of an object, that area is shared among all instances. This provides a convenient way to create shared memory between multiple instances of a particular object.

Scope of Object Symbols

Object symbols defined in Object Blocks are global to the object in which they are defined but are not available outside of that object. This means that these object symbols can be accessed directly from anywhere within the object but their names will not conflict with symbols defined in other parent or child objects.