MACINTOSH INTERFACE
RMAKER INPUT FILES
An RMaker input file is a text file, as created using the Editor.
By convention, RMaker input files have the extension .R. If you follow this convention you will easily be able to tell which text files on your disk are resource text files.
RMaker ignores all comment lines and blank lines between resource definitions. It also ignores leading and em bedded spaces (except in lines defined to be strings). Comment lines begin with an asterisk. To put comments at the end of other RMaker lines, precede the comment with two consecutive semicolons (;;).
6-2 1200301:06B
RMAKER INPUT FILES
Creating New Resource Files
The first non-blank and non-comment line of the input file specifies the name of the resource file to be created. The file should have the extension .RSRC. The line following the file name should either specify the file type and creator bytes for the Finder, or be blank. For example, the first two lines below designate the file NewResFile.Rsrc as the output file. The file is an application (type APPL) with a creator of PROG. The standard file type and creator for all UCSD Pascal programs is , APPLPROG'. If you do not specify the type and creato.r, they default to 0 (a null string).
NewResFi le.Rsrc APPLPROG
• The fol lowing include statement wi I I read in the
• resources that are required by al I UCSO Pascal programs.
INCLUDE UCSO Pascal l:Empty Program
• Program specific resources go here
The- RMaker output file NewResFile.Rsrc, created by the above input file, can be used as input to the UCSD Pascal compiler.
Appending to an Existing Resource File
The other type of resource input file starts with an exclamation point, followed by the name of the existing resource file that you wish to change. For example
!MyProgram.Code I I must be fol lowed by • blank line.
• New resource definitions go here
tells RMaker to add new resources to the UCSD Pascal program called MyProgram.Code.
WARNING: You may not follow a file name with a comment (the above example is illegal.)
RMAKER Chapter 6
Include Statements
The rest of the resource input text file consists of INCLUDE statements and TYPE statements.
INCLUDE statements are used to read in existing resource files.
An INCLUDE statement looks like this:
Ne..,ResF i Ie. Rsrc APPLPROG
.. The fol lowing include s~a~emen~ wi I I read in
• ~he resources that are required by al I UCSD Pascal .. programs.
INCLUDE UCSD Pascal l:Emp~y Program .. Program specific: resources go here
Typically you will use an INCLUDE statement to include the standard UCSD Pascal resources into a resource file that contains resources specific to your application program. Standard UCSD Pascal resources are in the file Empty Program on the disk UCSD Pascal 1.
Type Statements
TYPE statements consist of the word "TYPE!! followed by the resource type and, below that, one or more resource definitions.
The resource type must be capitalized to match a predefined resource type.
The following statement creates three resources of type 'STR '.
TYPE STR ,1
This is a s~ring
,2
Ano~hel" St.l"ing ,3
Ano~her s~l"ing resoul"ee
6-4 1200301:06B
R~1AKER INPUT FILES
It is not necessary for all resources of a given type to be declared together. However, all resources of a type must have unique resource ID's. If you specify a resource ID that is already in use, the new resource replaces the old one.
A resource definition looks like this:
[I"esouI"ce neme) ,I"eSOUl"ce IO [CI"esouI"ce et.t.I"ibut.e byt.e)]
t.ype-specific dat.a
The square brackets indicate that the resource name and resource attribute bytes are optional. Don't place these brackets in your input file. The comma before the resource ID is mandatory.
Attribute byte numbers are given in decimal. Attribute byte values are defined in the Resource Manager chapter of Inside Macintosh. The default attribute byte value is O. Here are some sample resource definitions:
TYPE STR
NewSt.I" ,4 (32) ;; 32 means I"esoul"ce is pUI"geable This I"eSOuI"ce has a name and.an at.t.I"ibut.e byt.e!!
,6 (32)
This one hes only an at.t.I"ibut.e byt.e.
MyNewSt.I",6
This one haa only a name (t.he at.t.I"ibut.e byt.e is 0).
The type-specific data is different for each resource type. As you have probably guessed, the type specific data for a 'STR ' resource is simply a string. The next section describes the type specific data for the resource types defined by RMaker.
DEFINED RESOURCE TYPES
RMaker has 11 defined resource types: ALRT, BNDL, CNTL, DITL, DLOG, FREF, GNRL, MENU, STR , STR# and WIND.
The format of the type-specific data for each type is shown by example, below. The type GNRL is used to define your own resource types. It is explained later.
R~1AKER Chapter 6
Syntax of RMaker Lines
There are just a few general rules that apply to lines read by RMaker.
• Leading and embedded blanks are ignored, except when necessary to separate multiple numbers on a line, or when they are part of a string.
• Blank lines should not be placed inside a resource definition, unless required (the exceptions are poin ted out below).
• Numbers are decimal, unless specified otherwise.
• RMaker is sensitive to line breaks. Thus if a type description shows four values on a single line, you must put four values on a single line.
Two special symbols can be used in resource definitions: the continuation symbol (++) and the enter ASCII symbol (\).
++
\
goes at tne end of a line tnat i . eontinued on tne next line.
p~eeede. two nexadeeimal digit.. Tnat ASCII
ena~aeter j . ente~ed into the ~e.ouree
definition.
Look at the description of the 'STR ' type for examples of these special sym bois.
The use of most of the TYPEs listed below are described in the appropriate chapter in Inside Macintosh. For example, the use of the type DLOG is described in the Dialog Manager chapter of Inside Macintosh.
6-6 1200301:06B
DEFINED RESOURCE TYPES the resulting output file will have its bundle bit set.
CNTL--Control Resource
R\1AKER Chapter 6
NOTE: Controls can be defined to be Visible or Invisible. Only the first character (V or I) is significant.
DITL--Dialog or Alert Item List Resource
TYPE DITL Editable text, Radio Buttons, CheckBoxes, and Buttons. These items are assumed to be enabled. Otherwise you may specify
Only the first characters (V,I,G,N) are significant.
6-8 1200301:06B
DEFINED RESOURCE TYPES
FREF--File Reference Resource
The FREF resource is used to associate file types with icons.
Used in conjunction with the BNDL resource, the FREF resource allows applications to define their own desktop icons. For more information see the section APPLICATION INTERFACE TO THE FINDER in the chapter GENERAL OPERATIONS.
TYPE FREF
RMAKER Chapter 6
T ... t-ing, \31, \32, \33 ;; 'T .. st-ing, 1 , 2 , 3 ' t-h .. hard way
STR#--String List Resource
This resource type allows you define a number of strings using one resource identifier. The procedure GetlndString in the Oslltilities unit (listed in Appendix A) can be used to index into a string list.
TYPE STR#
,1 4
This is .t-~ing on ..
And st-rin$! t-wo Th i rd st-,. I ng Bench warmer
;; resource IO
;; numb .. ~ of st-rings i i and t-h .. st-rings .•.
WIND-- Window Resource
TYPE WIND ,129 Wonder Window 40 90 120 300 Invisible GoAway
o o
; i t-it-I ..
;; t-op I .. ft, bot-t-om Fight,
;; window st-at-u. ( ... not-.. ) j; ProcIO (window definit.ion
;; R .. fCon (r .. f .. rence value) IO)
NOTE: A Window can be Visible or Invisible; GoAway and NoGoAway determine whether or not the window has a close box. Only the first character of each option (V,I,G,N) is significant.
CREATING YOUR OWN TYPES
There are two ways to create your own resource types. The first is to equate a new type to an existing type. For example, you can create a resource of type ERRM like this:
6-10 1200301:06B
TYPE ERRI.A
=
STR ,17 (32)Sad input fi Ie name
CREATING YOUR OWN TYPES
;l type ERRI.A i . j~.t I ike STR
j j ~esou~ce 10, att~ibute byte
ii ~ne error message
In the example, we have defined type ERRM to be an STR type.
This allows us to avoid resource identifier conflicts at runtime with other resources of type STR .
The other way to create your own type is to equate the new type to GNRL, and then to specify the precise format of the resource.
A set of element type designators lets you define the type of each element that is to be placed in the resource.
Here are the element type designators:
.P pascal st~ing
.S .t~ing without length byte .1 decimal intege~
.L decimal long intege~
.H heKadecimal
.R Read re.Ou~ce f~om fi Ie. Fol lowed by three
paramete~.: fi Ie name type 10
For example, to define a resource of type CHRG consisting of the integer 57 followed by the Pascal string 'Finance charges', you could use the following type statement:
TYPE CHRG
=
GNRL ,200.1 67 .P
Finance cha~ges
j ; define type CHRG
j j resource 10
j j a decimal integer
j ; a pascal string
j j MUST be fol lowed by a blank line.
A more practical example: An application that has its own icon must define an icon list, and reference it using FREF (described above). Such an icon list can be defined as follows:
RMAKER
USING RMAKER
If there are no errors in the RMaker input file, a resource file with the specified name is created.
WARNING: The TRANSFER menu is not supported. Trying to transfer out of RMaker could cause unpredictable results.
UCSD Pascal Compiler Input
Most of the time you will want to generate resource files that can be used as input to the UCSD Pascal compiler. UCSD Pascal programs require a minimum set of resources. These resources are in the file Empty Program on the UCSD PascalI disk. A typical application resource text file would be:
progrem.rsre:
APPLPROG i; Out.put. f i Ie neme i; Type I C .. eet.or INCLUDE UCSD Pese:el l:Empt.y Progrem
• Your progrem's resource TYPEs go here.
Note the use of the volume prefix on the file Empty Program.
The volume prefix is not needed if Empty Program is on the same disk as RMaker (the default volume). Volume prefixes must follow Macintosh file naming conventions, as defined in the chapter GENERAL OPERATIONS.
Errors in the Input File
If an error occurs, the line containing the error is the last line on the screen. RMaker then displays a box with an error message in it. These are the possible error messages. A brief description accompanies the error messages that are not self-explanatory.
RMAKER
Chapter 6• An Input/Output error has occured.
• Can't open the output file.
• Can't create the output file.
• Syntax error in source file.
• Bad type or item declaration.
• Bad ID Number.
• Bad Attributes Parameter.
• Can't load INCLUDE file.
• Bad format resource designator in G NRL type. This IS
any error in a user-defined resource type.
• Out of memory.
• Can't add to the file - - disk protected or full.
• Bad bundle definition.
• Unknown type. Specified resource type is undefined.
• Bad Object definition. This can happen if the specified file is of the wrong type.
• Bad item type.
• Bad format number.
6-14 1200301:06B
7
LIBRARIAN
The Librarian is a utility program that allows you to manipulate code segments within library files. Libraries are a useful means of grouping the separate code pieces needed by a program or group of programs. Libraries generally contain routines relating to a certain area of application; they can be used for functional groupings much as units can. Thus, you might want to maintain a math library, a data file-management library, and so forth-each of these libraries containing routines general enough to be used by many programs over a long period of time.
Maintaining units in well organized libraries is more convenient than maintaining a larger number of separate files. It allows you
• to manipulate an en tire collection of units easily.
• to reduce the number of library files you must specify in the Library Files list for a program (see the Set Options utility).
• to reduce the number of files that are open when the program is executing (each library file will be an open file).
• to think of your application in a more organized way.
Individual programs may also take advantage of the library construct. If a program uses several units suitable for compiling separately, but the units logically belong within the program, you may want to construct a single library containing the program and all of those units.
Library files created by the Librarian have the same structure as code files created by the compiler. Thus, a library file which contains a single unit is equivalent to the code file produced by
LIBRARIA..N Chapter 7
the compiler for that unit.
NOTE: The Librarian is useful for determining what units and segments are in the Pascal Runtime and Debug Runtime library files. However, it cannot be used to change these files. Changing them will make them unusable.
This chapter uses the term compilation unit to refer to a program or unit and all the segments declared inside it. The segment for the program or unit is called the host segment of the compilation unit. Segment routines declared inside the host are called subsidiary segments. Information in the host segment called segment references referes to units used by the compilation unit.
The segment references contain the names of all segments referenced by a compilation unit. When a program is executed, the runtime system searches all the library files specified in the program's Library Files list to find the referenced segments.
Some routines called from hosts exist in units in the Runtime Support Library and therefore appear in segment references, even though there is no explicit uses declaration for them. For example, writeln resides in the Runtime Support Library unit P ASCALIO, so the name PASCALIO appears in the segment references of any host that calls writeln.