This appendix covers the various resources used in PowerPlant. There are three principal areas to cover:
PowerPlant has several specific resource formats, including PPob, RidL, Mcmd, and Txtr. We have discussed each of these resources at various places in this manual.
For general information on all of these resources, and how to install resource templates for 3rd party resource editors, see "Installing Resource Templates."
For more information on the PPob resource, especially the text
format of PPobs, see the PowerPlant.r file. We discussed various aspects of the PPob resource throughout
this manual.
For more on the RidL resource, see "Linking broadcasters to listeners."
For more on the Mcmd resource, see "Menu-Related Resources."
For more on the Txtr resource, see "UTextTraits."
PowerPlant provides a variety of resources in several files. Most of these resources are standard resources in the Mac OS. A few are custom resource types.
In this section we look at the contents of those files. All of these files are in the PowerPlant Resources folder.
This file is copied, renamed, and used as part of the PowerPlant stationery projects. In typical use, you open and rename this file, and use it as the basis for further development. You can add resources to this file, modify the existing resources, or create additional resource files for your project.
Standard resource for specifying the MENUs in a Menu Bar.
The default constructor for LApplication uses this resource to create the initial menu bar for a program. You should change this resource to contain the ID numbers of the MENUs contained in your program's menu bar.
Standard resource for Toolbox Menus.
Custom resource type for specifying the command numbers associated with menu items. An Mcmd contains a list of 32-bit numbers corresponding to the items in the MENU with the same ID number.
Common strings used by PowerPlant.
Change this to the name of your program. PowerPlant uses this string when it displays the program's name in a dialog box.
This is the prompt string displayed in the standard file dialog box for saving a file.
PowerPlant text traits resources.
This file is copied, renamed, and used as part of the PowerPlant stationery projects. In typical use, you open and rename this file, and use it as the basis for further development. You can add resources to this file, modify the existing resources, or create additional resource files for your project.
This is a standard resource that defines the natural language syntax of Apple events supported by a program. This information is used by script editors.
You need to have a separate aete for each human language you wish to support, such as English. The ID number of the resource specifies the language. Check the Apple events documentation from Apple for a list of ID numbers and the languages to which they correspond.
We provide an aete for the English language (ID = 0) that specifies the terminology for all Apple events supported by PowerPlant. To properly support script editors, you must change this resource to reflect the Apple events actually supported by your program.
LApplication::ShowAboutBox() displays this Alert when the user chooses the About item from
the Apple menu. If you wish to use a simple Alert for your About Box, change
this resource (and its associated DITL) as appropriate.
You do not need this resource if you override LApplication::ShowAboutBox() to display your program's About Box and use some other alert,
dialog, or window.
There is an additional alert for a low-memory warning.
Standard resource for items in the Alert described above.
Resource file with STR# resources for "undo" and "redo." These
strings are used by LAction and LUndoer to change the text of
the Undo menu item.
This file is included in the PowerPlant stationery. If you do not use stationery when you make a new project and you use LEditField, add this file to your project.
Contains ALRT and associated DITL resources used during debugging.
Alert displayed when an exception is thrown, Debug_Throw is defined and gDebugThrow == debugAction_Alert.
Alert displayed when a signal is raised, Debug_Signal is defined and gDebugSignal == debugAction_Alert.
For more information, see "Set Debugging Options."
This file is included in the PowerPlant stationery. If you do not use stationery when you make a new project, add this file to your project.
Contains ALRT and associated DITL resources for confirmation dialogs used in the LDocument classes. Be sure to add this file to your project if you use these classes. The PP_Resources.h file contains the defines for these resources.
Contains the aedt resource that are required for full Apple Event support. Note that this file does not contain the aete resource.
This is a custom resource type (also used by MacApp) for associating a 32-bit number with a particular Apple event. The Toolbox identifies Apple events with a pair of 32-bit numbers (Class ID, Event ID). It is inconvenient to use two numbers to identify Apple events in code, so we use an aedt to map from the two numbers to just one.
It's not necessary, but we use a separate aedt for each Apple event suite. You should define new aedt resources if your program supports additional Apple events.
UAppleEventsMgr::InstallAEHandlers() installs an Apple event handler for every entry in every aedt
resource included in the program.
You can add this resource file to any program and it will colorize the standard alert icons.
These icons are color versions of the standard System icons displayed by the Alert calls. If you include these cicn resources in your program, the System will use them when displaying Alerts on color screens. If you don't include them, the System uses the standard black and white icons. We think the color icons are more attractive. However, each cicn is about 1K in size, so there is some space penalty for using them.
This section describes how to use Rez and DeRez to work with PowerPlant resource files. To install Rez and Toolserver, see the CodeWarrior User's Guide and the Rez Documentation folder on the CodeWarrior CD. CodeWarrior also has a plug-in Rez compiler.
You run ToolServer by choosing Start ToolServer from the Tools menu in the CodeWarrior IDE. This will launch the ToolServer
program and display a ToolServer worksheet window within CodeWarrior.
ToolServer has a command line interface. You type commands into the ToolServer Worksheet. To execute a command (or several commands) select the lines containing the command(s) and press the Enter key or Command-Return. Just pressing Return creates a new line (as with a normal text editing window).
Alternatively, you can create a text file that contains ToolServer
commands. Then you can execute all those commands by opening that
text file in CodeWarrior and choosing Execute as a Script from the ToolServer menu.
Rez is a tool that compiles text representations of resource data into actual resources. For examples of defining resources as text, see the various .r files in the "PowerPlant Cookbook" folder.
You will normally use Rez only for resources that have convenient text representations. This includes all resources whose data is primarily strings or numbers. Graphical resources-icons and pictures for example-are best edited with visual tools such as ResEdit and Resorcerer. However, PowerPlant's PPob resources fit quite nicely into the Rez text format.
A typical Rez command line looks like this:
Rez -o "HD:Projects:MyProgram.µ.rsrc" -a "HD:Projects:MyProgram.r"
In this command, -o "HD:Projects:MyProgram.µ.rsrc" specifies the output file for the Rez operation. The "-a" option means to append or merge the resources into an existing
file. Without the -a option, Rez will overwrite the output file. Finally, "HD:Projects:MyProgram.r" is the input file containing the text defining the resources.
By convention, files containing Rez resource definitions have a ".r" extension.
The above command line does not specify the files that define the format of the resource types, such as Types.r or PowerPlant.r. It is assumed that the necessary definition files are included at the top of the MyProgram.r file.
#define SystemSevenOrLater
#include $$Shell("RIncludes") "PowerPlant.r"
#include $$Shell("RIncludes") "Types.r"
#include $$Shell("RIncludes") "SysTypes.r"
inside MyProgram.r will include the proper files. ToolServer defines
the Shell variable RIncludes to be the full path name to the folder containing the Rez interface
files. See the file "StartupTS" in the ToolServer folder to see
how it defines its Shell variables. Defining the symbol "SystemSevenOrLater"
lets you use certain System 7 specific resource formats.
The file "Rez Script" contains a simple script that uses the GetFileName tools to prompt the user for the input and output files for Rez (as opposed to having to specify the full path names).
For a more complex example, use the "Build Resource Files" script file in the "PowerPlant Cookbook" folder.
DeRez is the inverse of Rez. DeRez decompiles resources into text representations of the resource data.
A typical DeRez command line looks like this:
DeRez "HD:Projects:MyProgram.µ.rsrc" -only PPob "PowerPlant.r" > "HD:Projects:MyDeRez.r"
This command decompiles resources of type PPob in the "HD:Projects:MyProgram.µ.rsrc" resource file. It uses
the resource definitions in "PowerPlant.r" to interpret the resource
data. It places the output text data in the file "HD:Projects:MyDeRez.r".
If the output file does not exist, it is created. If the output
file already exists, it is overwritten.
The -only PPob option specifies that only PPob resources in the input file are
decompiled by DeRez. You can specify as many -only options and resource definition files as you want. For example,
DeRez "ResFile" -only vers -only MENU "Types.r" "SysTypes.r" > "MyDerezFile.r"
If you don't include any -only parameters, then all resource types in the input file are decompiled
by DeRez.