Resources

Programming
After Dark modules

Graphics Module Resources

Only one resource is necessary in a graphics module. This is the code resource of type 'ADgm'. The rest of the resources described are optional.

After Dark makes use of several different resource types to implement its features. A few are common but the majority are new. Most of these resources are used to construct sliders, buttons, check boxes, and menus in the Control Panel. Below is a description of all the resource types used by After Dark.

Standard Resources

A graphics module may have the following two resource types, but both are optional:

Credit Line

This resource is a string that is displayed in the Control Panel when your graphics module is selected. This can be your name, the version number of your module, or any other information. Here is its format:

STR  "Credit Line"           ID = 128       String Value

Help Box

After Dark allows modules to include help or additional information that will not fit in the "Credits" area. The information is displayed when the user clicks in the "Credits" area. No programming is necessary to display text or a picture. To display text, create a resource of type 'TEXT' with ID = 1000. Enter the text you wish displayed into this resource. To display a picture, create a resource of type 'PICT' with ID = 1000. Here are the formats:

TEXT  "Help Text"           ID = 1000       String Value PICT 
      "Help Picture"             ID = 1000       Picture

Messages Supported

This resource allows your module to tell After Dark which messages it wants to receive. While your module should always request the Initialize, Blank, DrawFrame, and Close messages, it may or may not want the ModuleSelected or DoHelp messages (described in the "More About Messages" section). The resource is a byte value and each bit is a flag for a message. Bit 0 is a flag for the Initialize message. If it is 1, After Dark will send your module the message. Bit 1 is a flag for the Blank message, Bit 2 = DrawFrame, Bit 3 = Close, Bit 4 = ModuleSelected, and Bit 5 = DoHelp. Here is its format:

Cals  "Messages Supported"   ID = 1         Byte Value

Memory Needed

The 'sysz' resource tells After Dark, Randomizer, and MultiModule the number of bytes of memory a graphics module needs. To determine the amount of memory needed, add the amount of memory allocated for your structure/record, the size of your code resource (the 'ADgm' resource in your module), and any additional memory your module allocates. On startup, After Dark allocates 30K of memory for graphics modules unless a module has a 'sysz' resource requesting more. Randomizer and MultiModule use a graphics module's 'sysz' resource to determine how much memory they should allocate for it. Here is its format:

 sysz  "Memory required"     ID = 0         Long word value

Control Resources

The following resources are used to create and manage sliders, menus, text strings, check boxes, and buttons in the Control Panel. A graphics module can have any combination of up to four sliders, menus, text strings, check boxes, and buttons. The resources for controls are numbered 1000, 1001, 1002, and 1003 with 1000 representing the topmost control in the Control Panel, 1001 representing the second control from the top, etc. The current value of each control defined is passed to your graphics module in the "controlValues" field of the "params" structure.

Sliders

To create a slider, create a resource of type 'sVal'. Its resource ID determines where it appears in the Control Panel. The resources name ("Slider 1" in this case) is displayed next to the slider in the Control Panel. Slider values range from 0 to 100. The integer value of the 'sVal' resource is the slider's current value. Here is its format:

sVal   "Slider 1"            ID = 1000      Integer value

If only an 'sVal' resource is created, the numbers 0 to 100 are displayed as the slider is used. If your module needs a different number range or a label ("seconds", "pixels") for its slider, an 'sUnt' resource can be created to do this. The 'sUnt' resource has the same ID number as its associated 'sVal' resource. An 'sUnt' resource consists of pairs of integers and strings, and it is prefaced by an integer which is a count of the number of pairs. Each pair of integers and strings specifies a string that is to be displayed when the value of the slider is greater than or equal to the integer in the pair and less than the integer in the next pair. Here is its format:

sUnt   "Slider 1"            ID = 1000      Integer (count)
                                                 and pairs of
                                                 strings and integers.

Let's say you wanted a slider that would display "0 sec.", "1 sec.", and "2 sec." as the slider is moved. Create an 'sVal' resource and an 'sUnt' resource:

Note:: This is a pseudo-resource format. Use ResEdit, RMaker, or MPW Rez to create the actual resource.

sVal   "Seconds"             ID = 1000 Value = 0
sUnt   "Seconds"             ID = 1000 Count = 3
           Lower Limit = 0, String = "0 sec."
           Lower Limit = 33, String = "1 sec."
           Lower Limit = 66, String = "2 sec."

The 'sVal' resource sets the slider to 0. When the slider value is between 0 and 33, the string "0 sec." is displayed under the slider. When the slider value is between 33 and 66, the string "1 sec." is displayed and when the slider value is greater than or equal to 66, the string "2 sec." is displayed. Remember, an integer from 0 to 100 is passed to your module in the "controlValues" field as the slider's current value, not the string value being displayed or which range of the 'sUnt' resource you are in. Your module is responsible for interpreting this number in a way that is consistent with what the user sees. If your understanding of this resource is unclear, examine an 'sUnt' resource in an After Dark module with ResEdit. ResEdit templates for the After Dark resource types are provided. See the section "Resource Templates" at the end of this section for more information about them.

Popup Menus

Create an 'mVal' resource. The name of the resource ("Menu 1" in this case) is displayed next to the popup menu. Its resource ID determines where it appears in the Control Panel. The integer value of the resource is the item number of the currently selected item in the popup menu. This value ranges from 1 to the number of items in the menu. The number passed to the graphics module in the "controlValues" field is the current menu item selected. Here is its format:

mVal   "Menu 1"              ID = 1000      Integer

A standard 'MENU' resource must also be created. It must have the same resource ID number as its associated 'mVal' resource. This manual does not describe how to build a 'MENU' resource. If you are unfamiliar with this process, refer to Inside Macintosh Volume 1 for more information. Here is its format:

MENU   "Menu 1               ID = 1000      Standard menu resource

Check Boxes

Check boxes are useful when a control only needs a true/false value. When the box is checked, the associated statement is true. For example, if a module can display in color and black & white, a check box could be created with the statement "Draw in color." To create a check box, create a resource of type 'xVal'. The name of the resource is the string displayed next to the check box. Its resource ID determines where it appears in the Control Panel. The value of the resource determines if the box is checked or not. If the value is 0 it is not checked. If the value is 1 it is checked. This value is passed to your module in the "controlValues" field. Here is its format:

xVal   "Check Box 1"      ID = 1000         Integer value

Text Strings

Strings of text can also be displayed in the Control Panel. This can be used to inform the user that the module only works on a Macintosh II or that a control is not present because the monitor is not in color. To do this, two resources are created. The first is a standard 'STR#' resource. It is simply a list of strings. The second is a resource of type 'tVal'. The value of this resource determines which, if any, of the strings in the 'STR#' resource appear in the Control Panel. The value ranges from 0 to the number of strings in the 'STR#' resource. A value of 0 means no string is displayed in the Control Panel. A value of 1 or greater displays the corresponding numbered string in the 'STR#' resource. This value is passed to your module in the "controlValues" field. Both resources must have the same ID and the resource ID determines where the string appears in the Control Panel. Here are their formats:

STR#   "String List 1"       ID = 1000      List of Strings
tVal   "String List 1"       ID = 1000      Integer Value

Buttons

To implement a button in a graphics module, create a 'bVal' resource. The resource name ("Button 1" in this case) appears in the button. Its resource ID determines where it appears in the Control Panel. The message value passed to main() identifies which button was clicked. This value must be 8 or greater and unique for each button defined. Here is its format:

bVal   "Button 1"            ID = 1000      Integer value

Control Display

The last control resource allows controls to be conditionally displayed. For example, a button can be displayed only if the Macintosh has Color QuickDraw. Furthermore, a slider could be displayed if the Macintosh has a color monitor and a button could be displayed if it did not. Here is its format:

µVal   "Control 1"           ID = 1000      Integer value

To display a control conditionally, create a 'µVal' resource ('µ' is option - m) with the same ID number as the control it is associated with. This resource consists of boolean flags that correspond to the bits in "systemConfig" field of the GMParamBlock structure/record (see "Graphics Module Parameters"). The "systemConfig" field contains information about the configuration of the Macintosh. If you want a control to be displayed only under a certain configuration, set the appropriate flags in the 'µVal' resource for that configuration. After Dark compares the 'µVal' resource to the "systemConfig" field. If all the bits set in the 'µVal' resource are set in the "systemConfig" field, After Dark displays the control. For example, if you want a control to be displayed only if Color QuickDraw is present, set the value of the 'uVal' resource to 1. The "cqdAvail" flag is the first (lowest order) bit in "systemConfig" field. After Dark checks the first bit in the "systemConfig" field. If it is set, the control is displayed.

If you want a different control to appear depending on the configuration, construct the controls (you can have as many controls as there are configurations) and their associated 'µVal' resources. The resource ID for each control differs by 1000. One control is "ID = 1000", the next control is "ID = 2000", etc. For example if you want a "Choose Color" button to appear if all the monitors are in color mode and a "Choose Pattern" if they are not, define the following resources:

bVal   "Choose Color"        ID = 1000      Value = 8
uVal   "Choose Color"        ID = 1000      Value = 16
bVal   "Choose Pattern"      ID = 2000      Value = 9

The "Choose Color" button passes an 8 and the "Choose Pattern" button passes a 9 to your main() function in your graphics module if they are clicked. The 'µVal' resource for the "Choose Color" button is set to 16. This sets the flag that "all monitors must be in color mode." After Dark checks the "systemConfig" field to see if "all the monitors are in color mode" flag is set. If it is, the "Choose Color" button is displayed. If it is not, the "Choose Pattern" is displayed as the default since it does not have a 'uVal' resource.

If you are unclear about this use ResEdit on a copy of the "FadeAway" graphics module to see an example of a 'µVal' resource.

Sound Resources

If your module wants to use sound, it must have a 'Chnl' resource with ID = 0. This resource consists of two integer values, "Channel Kind" and "Volume". The "Channel Kind" value tells After Dark what type of sound channel your module wants. This value can be noteSynth = 1, waveTable = 3, or sampledSynth = 5. As described in the section "Using Sound", After Dark currently only supports the sampledSynth type sound channel. The "Volume" value is current volume setting of your module. This value can be an integer from 0 to 7. Here is its format:

Chnl   "Sound Channel"       ID = 0         Two integer values

Color Resources

Adding color to a graphics module can enhance it greatly. A module may want to use a specific set of colors when it is drawing. This is accomplished by creating a resource of type 'clut' (For more information about 'clut' resources, see the Color QuickDraw chapter in Inside Macintosh Volume 5.) After Dark sets this resource as the current color lookup table when your module is activated. Since different 'clut' resources are needed for different monitor pixel depths, a specific 'clut' resource can be used according to the pixel depth. The resource ID determines which 'clut' resource is used. If the monitor is set to 1 bit depth, the 'clut' resource with ID = 1001 is used. If the the monitor is set to 2 bit depth, the 'clut' resource with ID = 1002 is used. For a bit depth of 4, the resource ID = 1004 and for a bit depth of 8, the resource ID = 1008. Here is its format:

clut   "1 Bit clut"          ID = 1001      Standard 'clut' resource

There are two guidelines when using this resource. A 'clut' resource should begin with the color white and end with the color black. If this is not done, the Control Panel is displayed with random colors when the module is used in "Demo Mode". Modules should also black the screen in DoClose(). This prevents the screen from displaying a "color flash" when the color lookup table is set back the original one.

Resource Templates

Since many of the resources used by After Dark are new, resource templates for ResEdit have been created to assist in creating these resources. The file "After Dark Templates" has eight resources of type 'TMPL'. Open this file and paste these resources into your copy of ResEdit. You are now able to create and edit the resources used by After Dark more easily.

ProgrammingAfter Dark modules