Header Viewer and Header Files

Header files are indispensable to developers. They declare the programmatic interfaces to individual modules of code and, through #import and #include statements, link one header file to another. The header file is the final authority for any particular programmatic interface.

Although the final authority, header files are not always the easiest reference to use. In an object-oriented environment such as OpenStep, a large proportion of header files declare the interfaces to classes, in general, one class per header file. However, since a class inherits part of its interface from its superclass, you might have to search several files to learn the capabilities of a single class. Compounding this problem is the sheer number of classes: The Application Kit alone has over 60 classes. A more sensible approach would be to have a tool that could follow these interconnections directly.

In principle, a simple tool that performed text-based searches on the header file might do the job; however, given that the header files for the Application Kit alone contain several thousand lines of declarations, in practice such a tool would be too slow. A better approach is needed.

Precompiled Headers

Header Viewer's approach is to use OpenStep's precompiled headers. A precompiled header has been processed by the preprocessor, leaving it in a compact, binary format. During preprocessing, macros are expanded, comments removed, other headers included as indicated by #include or #import directives, and language tokens parsed from the resulting stream of text. Because it uses precompiled headers, Header Viewer can be called a language-sensitive browser.

Precompiled headers are stored in files having a .p extension. OpenStep includes precompiled headers (in /usr/openstep/Developer/include) for the Application Kit (Appkit/Appkit.p) and FoundationKit (Foundation/Foundation.p).

Upon launch, Header Viewer loads the precompiled headers by default. If you plan to scan the API's of the other libraries, you can add the headers. In addition, you can display the contents of other header files, including your own, by adding them to Header Viewer's list. See ""Adding Header Files" on page 6-12 for more information.

---

Note - This chapter refers to both .h and .p files as header files. Header Viewer accommodates both by precompiling .h files when needed.

---

Language Elements

Header Viewer scans a precompiled header for the language elements it contains and categorizes them by type. It then lets you select the category you want to display. For example, you can look at all the methods, the functions, or the constants that are declared. Table 6-1 describes the categories Header Viewer lists.

Table 6-1

Language Element	Description
class	In the Objective C language, a prototype for a particular kind of object. A class definition declares instance variables and defines methods for all members of the class. In Header Viewer, classes can be listed or browsed in a class hierarchy.
category	In the Objective C language, a set of method definitions that is segregated from the rest of the class definition. Categories can be used to organize a class definition into parts or to add methods to an existing class without creating a subclass.
protocol	In the Objective C language, a list of methods not associated with any particular class. Protocols are often used to promote reuse of a design.
method	A procedure that can be executed by an object.
function	A routine designed to accomplish a particular task. Header Viewer lists all functions, including C library functions, OpenStep NS functions, and UNIX system calls.
global data	Variables that are visible to all programming modules.
typedef	A type definition. In the C language, used to create a new variable type from existing types.

Table 6-1 (Continued)

Language Element	Description
struct	A structure data type, identified in the C language by the keyword struct.
union	A data type that allows different data names and data types to be assigned to the same storage location.
enum	The C language enumerated data type, consisting of a named set of values with an integer assigned to each member of the set.
enum constants	The constants declared within an enumeration set.
constant-like macros	A macro that is defined and treated like a constant.
function-like macros	A macro that is defined and treated like a function.
macros guard	A C language macro that is used to ensure that each header file is included only once. The Objective C #import declaration makes once-hack macros unnecessary.
predefined macros	Symbol names that are defined by the compiler. Many deal with parameters such as byte swapping and determining a machine's CPU type.
header	A file that contains programming declarations. In Header Viewer, header files can be listed or browsed in a hierarchy.

For additional information about the meaning and use of a language element, refer to Chapter 8, "The Objective C Language," Chapter 9, "The Objective C Extensions," or The C Programming Language by Kernighan and Ritchie.

Header Viewer and OpenStep Documentation

Header Viewer retrieves documentation for any OpenStep class, method, protocol, or category. It accesses files in /usr/openstep/Developer/Documentation, which correspond to chapters in OpenStep Programming Reference. It does not retrieve documentation for the other types of API elements, such as those declared in the standard C libraries.

Header Viewer retrieves only the defining passage from the developer documentation, not every reference. For example, when you use it to access the documentation for the display method of the NSView class, it shows you the description of the method found in the NSView class specification. It does not search other sources for additional references to the method.

Using Header Viewer

Header Viewer has a single main window, which can display a Browser view or a Finder view. The window displays the Browser view when the application is launched, but you can set a preference for the Finder view to appear as the default view. You can switch from one view to the other using the Utilities menu.

In either the Browser view or Finder view, you choose to view either a header file or OpenStep developer documentation. A pop-up list in the lower right corner of the Header Viewer main window offers a choice of either a Header File or Documentation. Header files are always available; if documentation is not available, the Documentation choice is grayed out.

The Browser View

The Browser view, shown in Figure 6-1 on page 6-6, outlines hierarchies of classes and lists all occurrences of language elements such as methods or functions. The Browser view helps you discover what is available to you, both in OpenStep's libraries and in code you obtain from others.

Figure 6-1

Header Viewer's Browser view resembles the Browser view of the OpenStep Workspace Manager's File Viewer. However, with Header Viewer's Browser view, you are not looking at the file system; rather, you are looking at the contents of header files. You do not see ordinary files and folders; instead, you see lists of header files or classes, methods, and other language elements.

A pop-up list above each Browser column allows you to choose what kinds of things you see in the Browser columns. You choose from a list of 14 different language elements (see "Language Elements" on page 6-3).

---

Note - The pop-up list above a Browser column changes depending on what you select in the preceding column.

---

The left-most column always shows a list of header files. The pop-up list above the column (see Figure 6-2) lets you remove header files (see "Adding Header Files" on page 6-12 for more information).

Figure 6-2

If you are browsing a Header Hierarchy and select a header that includes other headers (indicated by a pointer in the Browser column), you see a list of included headers in the neighboring column. A pop-up list above the neighboring column allows a choice of Direct Headers or All Headers (see Figure 6-3 on page 6-8). Direct headers are only those you see included in the header file. All headers are all those upon which the header is dependent, whether directly or indirectly.

Figure 6-3

If you choose Class Hierarchy and select a class listed in the column, you see a list of the subclasses that inherit from the class. Use a pop-up list above the column (see Figure 6-4 on page 6-9) to view superclasses (the parent class from which a class is derived), instance methods, class methods, or categories.

Figure 6-4

If you choose Class List and select a class listed in the column, you see a list of its instance methods in the following column. Use the pop-up list above the column to view subclasses, superclasses, class methods, or categories.

If you choose Methods and select a method listed in the column, you see a list of classes in the following column if the method is implemented by more than one class, category, or protocol. Use a pop-up list above the column to view classes, categories, or protocols. If the method is used by only one class, category, or protocol, nothing is shown in the neighboring column.

The Browser view is a powerful aid to visualizing the relationship of one header file to others, the chains of inheritance among classes, and the use of language elements in header files. Its dynamic lists present the information in compact form.

The Finder View

The Finder view lets you search header files and retrieve related documentation. In practice, you use the Finder view, shown in Figure 6-5, to look up the details you need to put any language element to good use.

Figure 6-5

The Finder view displays a text field at the top. Entering a string and clicking the Find button initiates a search for the string. Results of a search are displayed in a scrollable list see Figure 6-6 on page 6-11).

Clicking on any item in the results list displays contents of a header file or relevant documentation. The full context of the search string appears in bold when the document window displays a header file. When matching documentation is available, the document display shows the relevant passage from OpenStep Programming Reference.

Figure 6-6

You can move through the results list by clicking either of two large arrows to the left of the text field (or by using the up and down arrows on the keyboard). Two small arrows to the right of the text field let you recall search strings that you have previously used. Double-clicking on any item in the results list opens the selected header file in Edit. The search string is highlighted in the Edit window.

An Options button opens the Find Control Options panel, shown in Figure 6-7 on page 6-12) that lets you narrow searches to specific language elements and selected header files. Three buttons under the title Element Usage allow searches to include Declarations, References, or All Tokens. Ordinarily, Header Viewer confines the results of a search to actual declarations of the string. You can broaden the search to references to the string or any appearance of the string in a header file (except in a comment).

Figure 6-7

You can also narrow or broaden searches by choosing Ignore Case or Match Prefix in the Find Control Options panel.

You can alter the rank of the results by choosing Sort Order from the pop-up list in the Find Control Options panel. By manipulating the Sort Order and the Find options, you precisely tune a search to yield only the information most useful to you.

Adding Header Files

On launch, Header Viewer looks for headers that correspond to headers present in the Header Viewer list. By default, Header Viewer uses the headers that correspond to the header files Appkit.h and Foundation.h.

You add your own header files to Header Viewer by choosing Add Header in the Utilities menu and selecting a file with the standard Open panel. Header Viewer temporarily compiles the header, parses its language elements, and displays its contents in the document window.

Header Viewer retains the precompiled header in memory as long as Header Viewer is running. If you want to continue to use your own headers the next time you launch Header Viewer, you must first recompile the header. Header Viewer's Preferences panel (see Figure 6-9 on page 6-14) allows you to specify which header files will be listed at launch.

The Find Panel

Use the Find in Viewer panel, shown in Figure 6-8, to search for any text string in the Header Viewer document window or Finder view results list.

Figure 6-8

This Find panel is similar to the one you use in Edit. Unlike Header Viewer's more powerful Find button, which searches precompiled headers for specific language elements, the Find in Viewer panel is a character-based search tool that only scans the contents of the document window or the Finder view results list. However, this can be very useful when searching for a specific method in a long list of methods displayed in a Finder view results list, or in looking for all occurrences of a string in a header file or documentation chapter.

Header Viewer and the File Viewer

Occasionally you may encounter a header file you would like to investigate while working in the File Viewer. Double-clicking on a .h file usually opens it in Edit. To force Header Viewer to open the .h file, choose Add Header from the Header Viewer submenu of Workspace Manager's Services menu. Header Viewer temporarily precompiles the header, parses its language elements, and displays its contents in the document window.

Header Viewer and Edit

If you are writing code or debugging source, you will want to access Header Viewer from your editor. Select any text string and pass it to Header Viewer. To do so, choose Find from the Header Viewer submenu of the Services menu.

---

Note - Header Viewer can match an entire message expression. This is one of Header Viewer's most powerful facilities. If you are working in Edit, double-click on the first square bracket in an expression to select the entire message expression, then pass it to Header Viewer through the Services menu. Header Viewer strips the expression of its receiver and arguments and matches the message to all corresponding methods. A look at the developer documentation should quickly reveal the correct use of the expression.

---

Setting Preferences

The Preferences command in the Info menu displays the Preferences panel, shown in Figure 6-9. Preferences options are grouped in three views. A pop-up list offers a choice of preference view: Header Files, Documentation Directories, and Other Options.

Figure 6-9

Header Files Preferences

Choose Header Files from the pop-up list in the Preferences panel to specify additional header files that Header Viewer lists when launched. You can add conventional headers (.h files).

Documentation Preferences

Choose Documentation Directories from the pop-up list in the Preferences panel to enable Header Viewer to access additional documentation directories. Documentation must conform to the format used by OpenStep developer documentation, as indicated in the panel shown in Figure 6-10.

Figure 6-10

Other Options Preferences

Choose Other Options from the pop-up list in the Preferences panel to set defaults for Header Viewer on launch and to set default options for the C preprocessor when you add a header file to Header Viewer (see Figure 6-11 on page 6-16).

The Default View group lets you specify what you see when you launch Header Viewer: header files or documentation, the Browser view or the Finder view.

The Default C Preprocessor Options group lets you specify default options (such as the -D, -U, and -I switches) for the C preprocessor to use when precompiling a header file for use in Header Viewer. These options precede any other options you choose when you add a header file to Header Viewer.

Figure 6-11

Header Viewer Command Reference

Header Viewer's main menu offers the standard Info, Edit, Windows, Services, Print, Hide, and Quit commands. All commands unique to Header Viewer are located in the Find (under Edit) and Utilities menus. These menus and the commands they contain are described in "Commands in the Find Menu" and in "Commands in the Utilities Menu" on page 6-18.

Commands in the Find Menu

The Find menu offers the commands listed in Table 6-2 on page 6-17 for finding text in the document window or in the list of results displayed in the Finder view.

Table 6-2

Command	Description
Find Panel	Opens a panel to allow you to enter a text string for a search.
Find Next	Searches forward from the insertion point or current selection in the list of results displayed in the Finder view. It searches for the text you've typed in the Find field of the Find panel. It does the same thing as the Next button in the Find panel.
Find Previous	Same action as the Find Next command, but searches backward.
Enter Selection	A shortcut; same as copying a text selection and pasting it into the Find panel.

Commands in the Utilities Menu

The Utilities menu contains the commands shown in Table 6-3 that let you control the Header Viewer main window.

Table 6-3

Command	Description
Find	Displays the Finder view.
Browse	Displays the Browser view.
Browse Selection	Displays the selection you have made in the Finder view within a Browser view hierarchy.
Update	Determines if any header files have changed since Header Viewer was launched; recompiles and reparses headers that have changed (the precompiled version is stored only in memory). Most useful when you have made changes to your own header files.
Add Header	Allows you to add your own header files to Header Viewer. You can add conventional headers (.h files). If you would like Header Viewer to use these files whenever it is launched, choose the Preferences command from Header Viewer's main menu.
Open in Edit	Opens the current header or documentation files in the Edit application and highlights the declaration of the language element you have specified in the Finder view or selected in the Browser view.