Creating, Opening, and Saving Documents

When Icon Builder starts, it creates one new Icon Builder window using the default Preferences settings. You can create additional Icon Builder windows as you need them, as described in "Creating a New Document" on page 5-2.

Creating a New Document

To create a new document, choose the New command in the Document menu. This creates a document with the default attributes. Typically, the document contains a single 48-pixel by 48-pixel, non-alpha, 2-bit gray image with a white background. You can change the attributes of the document after it's been created, as described in "Changing the Attributes of a Document" on page 5-17.

To create a new document with nondefault attributes, do the following:

1. Bring up the New Document panel shown in Figure 5-1 by choosing the New Layout command in the Document menu.

Figure 5-1

2. Set options in the New Document panel, and then click on OK to create a new document. If you want to change the default attributes for all documents created with the New command, click on Set Default instead.

For example, if you want to create an icon for use on both color and black and white displays, you would check the 2 bit gray box as well as the 12 bit color box (8 bit gray and 24 bit color could also be used). Check the Has alpha box if you will be using alpha. (Alpha means transparency, so that some of the

background color shows through an image.) To change the background color, choose Colors on the Tools menu to bring up the Colors panel, pick a color in the Colors panel, and drag the color into the Background Color color well.

Opening an Existing Document

To open an existing document, choose the Open command in the Document menu and use the Open panel to find the document.

The document you open may be an icon you are working on, or it may simply contain an image that you want to copy a selection from in order to paste it into another document. In addition to TIFF files, Icon Builder can open GIF and EPS files.

Saving a Document

To save a document to a file, choose the Save command in the Document menu. If the document has not been saved yet, a Save panel is displayed prompting you to specify a name and location for the file.

Even if the file you are saving was opened as something other than a TIFF file (a GIF file, for instance), it will be saved as a TIFF file.

Icon Builder saves TIFF files in uncompressed format, so before making the file part of your application project, you should use the tiffutil utility to compress the file. See the tiffutil(1) UNIX manual page for more information.

Editing Icon Documents

This section describes various ways to edit an icon document, including the set of Icon Builder tools and an inspector for fine-tuning those tools. Other editing techniques involve zooming in and out, changing the attributes of a document, and working with multiple-icon documents.

You can also use standard cut, copy, and paste techniques; these are not described here.

Using Icon Builder Tools

A variety of drawing tools are available and accessible from the Tools panel, shown in Figure 5-2, which is displayed automatically when you start Icon Builder. If you close or misplace the panel, you can retrieve it by choosing the Tools command in the Tools menu.

Figure 5-2

To use a tool, select it by clicking on its icon in the Tools panel. Once you have selected a tool, use it to edit the contents of the document window.

---

Note - When using the Tools panel, you should have the Colors panel open as well. All the drawing tools use the color that is currently displayed in the Colors panel. You can also use the Colors panel to specify the degree of alpha coverage (that is, opacity), as well as whether or not painting is done in overlay mode.

---

The Brush Tool

The Brush tool, shown in Figure 5-3, is useful for filling in large areas with a particular color. Click once to deposit a brushful of color, or click and drag to cover a larger surface area.

Figure 5-3

The Line Tool

The Line tool, shown in Figure 5-4, draws straight lines. Click to mark the start point, and drag to the endpoint. The line you see being drawn as you drag is only for guidance--the final line is drawn only when you release the button.

Figure 5-4

The Oval Tool

The Oval tool, shown in Figure 5-5, draws circles and ovals. Click and drag to determine the position, size, and shape. It is hard to predict the startpoint and endpoint with accuracy, so you may want to use another document window as a scratch area and then copy and paste the oval once you are satisfied with it.

Figure 5-5

The PaintBucket Tool

The PaintBucket tool, shown in Figure 5-6, changes the color of a contiguous, identically colored group of pixels. The color to which they are changed is the color that is currently in the Colors panel. Before using the Paint Bucket tool, you may want to use the ObeseBits panel to be sure that all the pixels are in fact identical in color--if minor gradations in color are used to achieve the appearance of a particular shade, the new color will not spread from pixel to pixel.

Figure 5-6

The Pencil Tool

The Pencil tool, shown in Figure 5-7, draws freehand lines. Click to start the line, and drag to indicate the path of the line. Unlike the line tool, the Pencil tool draws the final line as you drag. If you do not like the result, use the Undo command in the Edit menu to undo it.

Figure 5-7

The Rectangle Tool

The Rectangle tool, shown in Figure 5-8, draws squares and rectangles. Click to position a corner point, and then drag in any direction to form the rectangle.

Figure 5-8

The Selection Tool

The Selection tool, shown in Figure 5-9, selects a rectangular area for further editing. For example, after selecting an area you might go on to copy the selection to the pasteboard, or even delete the selection. You can deselect the selection by clicking anywhere in the document window.

Figure 5-9

The Text Tool

The Text tool, shown in Figure 5-10, is used to add text to an image. If you select the Text tool and then click the cursor in a document window, the contents of the TextTool inspector (by default, the word Text--probably not what you want in your icon) are copied to the cursor location. As long as you do not release the mouse button you can drag the text to reposition it, but once you let go the text becomes fixed in that position.

Figure 5-10

In order to use the Text tool effectively, you should first enter the desired text in the TextTool inspector. To make changes to the font of the text, choose Font on the Format menu, and then choose Font Panel from the Font menu. Use the font panel to set the font attributes and font size as you want. Then use the Text tool to insert the text in the document window, or--to be on the safe side--insert the text first in a temporary scratch document, and then cut and paste the text into the document window.

Other tools besides the Text tool have default attributes that you can change using the Tools Inspector, as described in "Using the Tools Inspector" on page 5-8.

Using the Tools Inspector

The Tools inspector is a panel that gives you greater control over the characteristics of the tools available in the Tools panel.

To bring up the Tools inspector, choose the Inspector command from the Tools menu. To display the inspector for a particular tool, click on the tool's icon in the Tools panel.

---

Note - There is no inspector available for the PaintBucket tool.

---

The Brush Inspector

The Brush inspector, shown in Figure 5-11, is displayed in the Tools inspector panel when you select the Brush tool in the Tools panel.

Figure 5-11

Click on a button to change the shape and orientation of the brushstrokes you make.

The Line Inspector

The Line inspector, shown in Figure 5-12, is displayed in the Tools inspector panel when you select the Line tool in the Tools panel. You can use this inspector to change the width and end shape of the lines you draw.

Figure 5-12

Use the slider or the text field to set the line width to any value between 1 and 50 pixels.

Click on one of the three Line Cap buttons to determine how the ends of lines are drawn. The setting becomes less critical as the line width decreases--a one-pixel line is drawn the same no matter what style of line cap is selected.

The Oval Inspector

The Oval inspector, shown in Figure 5-13 on page 5-10, is displayed in the Tools inspector panel when you select the Oval tool in the Tools panel.

Figure 5-13

Click on one of the five buttons to change the appearance of the circles and ovals you draw.

The Pencil Inspector

The Pencil inspector, shown in Figure 5-14 on page 5-11, is displayed in the Tools inspector panel when you select the Pencil tool in the Tools panel. You can use this inspector to change the width of the freehand lines you draw.

Figure 5-14

Use the slider or the text field to set the line width to any value between 1 and 50 pixels. Thicker lines cause the drawing speed to decrease, so you may need to move the mouse more slowly in order for the drawing process to keep up with it.

The Rectangle Inspector

The Rectangle inspector, shown in Figure 5-15 on page 5-12, displayed in the Tools inspector panel when you select the Rectangle tool in the Tools panel. You can use this inspector to change the appearance of the squares and rectangles you draw.

Figure 5-15

Click on one of the seven buttons to change the appearance of the squares and rectangles you draw.

The Selection Inspector

The Selection inspector, shown in Figure 5-16 on page 5-13, is displayed in the Tools inspector panel when you select the Selection tool in the Tools panel. You can use this inspector to change the orientation of (that is, flip or rotate) the current selection.

Figure 5-16

Choose Flip or Rotate in the pop-up list at the top of the panel. The available options vary depending on which you choose.

If you choose Flip, you will see the Flip filter attributes shown in Figure 5-17. Click on either the Vertical or Horizontal button to indicate the direction in which you want the selection to be flipped.

Figure 5-17

If you choose Rotate, you will see the Rotate filter attributes shown in Figure 5-18 on page 5-14. Specify a value between 0 and 360 using either the slider or the text field. This value represents the number of degrees the selection will be flipped in a clockwise direction.

Figure 5-18

Once you have selected the options, click on one of the buttons shown in Figure 5-19. Click on Apply to flip or rotate the selection. If you do not like the results, click on Revert to return the selection to its former orientation.

Figure 5-19

The TextTool Inspector

The TextTool inspector, shown in Figure 5-20 on page 5-15, is displayed in the Tools inspector panel when you select the Text tool in the Tools panel. You use this inspector to input the text to be inserted in the document window, as well as to change the font attributes and formatting of the text prior to inserting it.

Figure 5-20

Type the text you want to insert in the document window. Use the Font panel to set the font attributes and size of the text. You may also want to use commands in the Text menu to format the text. Then select the Text tool and click in the document window to insert the text in the document.

Zooming In on a Document

When you are doing detail work on an image that is only 48 pixels across, you may find yourself wishing you had a magnifying glass. If you start feeling this way, choose the ObeseBits command in the Tools menu to bring up the ObeseBits panel shown in Figure 5-21 on page 5-16.

Figure 5-21

This panel magnifies the image in the main window, and lets you zoom in or out (that is, increase or decrease the degree of magnification). The buttons along the top of the panel give you the control you need--use the plus and minus buttons to zoom in or out, and the arrow buttons to change the portion of the image being displayed.

There are actually two ObeseBits panels, as shown in Figure 5-21. The larger panel is for editing; the small panel sits over the document window and shows the exact portion of the image that is contained in the large panel. You can drag the small panel by its title bar, thereby changing the portion of the image being displayed in the panel.

The ObeseBits panel associates itself with whatever window is the main window. Clicking on the document containing the Mail icon in the figure, for example, would cause the small ObeseBits panel to jump to that document window. The contents of the big panel would change accordingly.

---

Note - Although the drawing tools in the Tools panel can be used directly in the ObeseBits panel, the result is not always intuitive. For example, the size of the Brush cursor does not accurately represent the brush size that's used when stroking the brush. Use the Undo command in the Edit menu to undo any changes that you regret making.

---

Changing the Attributes of a Document

After you have created a document or opened an existing document, you may find it necessary to change its size, format, or other characteristics. For example, you might decide to add alpha (image transparency) to a document that does not have it.

To make such changes, first click on the document window to make sure it is the main window. Then open the Document Layout panel by choosing the Document Layout command in the Format menu.

The Document Layout panel is identical to the New Document layout panel (see Figure 5-1 on page 5-2). The only difference is that this panel is used to change the attributes of an existing document, rather than determine the attributes of a new document.

---

Note - If you set new default attributes in the Document Layout panel, these become the default attributes for the New Document layout panel as well.

---

Working with Multiple-Icon Documents

One Icon Builder document (that is, one TIFF file) can contain more than one icon. This is typically the case, for example, when you want to have one icon for color monitors and another for gray-scale monitors--if the two icons are in the same TIFF file, the appropriate icon is displayed automatically on each type of monitor, without any work on your part.

To create a multiple-icon document (or to change an existing single-icon document to a multiple-icon document), select the desired depth settings in the New Document panel (or the Document Layout panel). Then click on OK.

Use the pop-up list that is displayed in the lower right corner of a multiple-icon document window to access the various icons.

If you create a multiple-icon document, remember that you have to edit each icon. When you save the document, all the icons in the document are saved--not just the one that is currently visible in the document window.

Icon Builder Command Reference

This section describes the application-specific menus and commands available in Icon Builder. For descriptions of standard menus and commands, see Using the OpenStep Desktop.

Commands in the Main Menu

Icon Builder's main menu contains the standard Edit, Windows, Print, Services, Hide, and Quit commands. The Document, Format, and Tools commands display submenus that are described in Table 5-1 and the sections that follow.

Table 5-1

Submenu	Description
Document	Displays a submenu of commands for creating, opening, and saving document windows. See "Commands in the Document Menu."
Format	Displays a submenu of commands for opening the standard Font and Text submenus, plus the Document Layout command for specifying the layout of the document in the main window. See "Commands in the Format Menu" on page 5-19.
Tools	Contains commands for opening a panel containing the tools available for use in creating an icon. See "Commands in the Tools Menu" on page 5-20.

Commands in the Document Menu

Icon Builder's Document menu provides the commands described in Table 5-2 on page 5-19.

Table 5-2

Command	Description
Open	Opens an existing document window. See "Opening an Existing Document" on page 5-3.
New	Opens a new document window using the default attributes. See "Creating a New Document" on page 5-2.
New Layout	Displays a panel that lets you change the default attributes used in creating a new document. See "Creating a New Document" on page 5-2.
Save, Save As	Saves a document (consisting of one or more TIFF images) to a TIFF file. See "Saving a Document" on page 5-3.
Revert to Saved	Undoes the changes that have been made since the last time the document was saved.

Commands in the Format Menu

Icon Builder's Format menu, described in Table 5-3, contains submenus of standard font and text commands, which you can use to affect the appearance of text used in Icon Builder, as well as the Document Layout command.

Table 5-3

Command	Description
Font	Opens a menu of standard Font commands, which you use to set the font characteristics of the selected text in the TextTool inspector.
Text	Opens a menu of standard Text commands, which you use to set the attributes of the selected text in the TextTool inspector.
Document Layout	Displays the Document Layout panel, which you use to change the attributes of a document window. See "Changing the Attributes of a Document" on page 5-17.

Commands in the Tools Menu

The Tools menu, described in Table 5-4, contains commands for accessing the primary tools provided in Icon Builder.

Table 5-4

Command	Description
Inspector	Opens the Inspector panel, which you use to change the appearance and behavior of the available tools. See "Using the Tools Inspector" on page 5-8.
Tools	Opens the Tools panel, which you use to select among available tools. See "Using Icon Builder Tools" on page 5-4.
Colors	Opens the standard Colors panel, which you use to choose color or gray-scale values.
Obese Bits	Opens the ObeseBits panel, which you use to magnify the contents of a document window. See "Zooming In on a Document" on page 5-15.
Load Tool	Opens the Load Tool panel, which you use to load a user-defined tool.