:h1. through :h6. (Headings)

Define window characteristics.

Syntax

┌───────────────┬───────────────┬───────────────┬───────────────┐
│Tag            │Element        │Attributes     │End            │
├───────────────┼───────────────┼───────────────┼───────────────┤
│:h1.-:h6.      │Define cross   │res=           │               │
│               │references to  │id=            │               │
│               │internal and   │name=          │               │
│               │external       │global         │               │
│               │sources.       │tutorial=' '   │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Define origin  │x=             │               │
│               │and size of    │y=             │               │
│               │windows with   │width=         │               │
│               │relation the   │height=        │               │
│               │primary window.│               │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Manage the     │group=         │               │
│               │display of     │viewport       │               │
│               │information in │clear          │               │
│               │multiple       │               │               │
│               │windows.       │               │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Define the     │titlebar=      │               │
│               │user's control │scroll=        │               │
│               │over the       │rules=         │               │
│               │window.        │               │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Restrict user  │nosearch       │               │
│               │retrieval of   │noprint        │               │
│               │information.   │hide           │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Change heading │toc=           │               │
│               │levels that    │               │               │
│               │appear in the  │               │               │
│               │Contents       │               │               │
│               │window.        │               │               │
├───────────────┼───────────────┼───────────────┼───────────────┤
│               │Define the     │ctrlarea=      │               │
│               │control area of│ctrlrefid=     │               │
│               │a window for   │               │               │
│               │displaying push│               │               │
│               │buttons.       │               │               │
└───────────────┴───────────────┴───────────────┴───────────────┘

Attributes

res=
id=
name=


Specify window identifiers.

If you are creating an .HLP file, res= is required and can be any integer from 1 through 64 000. However, if you are creating an .INF file (compiled by specifying the /INF parameter with the IPFC command), you can use res=, name= or id=. With name= and id=, you can include alphabetic characters. You cannot use these attributes if you plan to concatenate .INF files. Instead, you must use res=. For more information see Concatenating .INF Files.

global
Indicates to IPF that the window can be a reference in an external database (another IPF .HLP or .INF file). A reference from one IPF database to another is made by specifying reftype=hd and database='filename' with the link tag.
tutorial=' '
Specifies the file name of the tutorial and causes the tutorial choice to be added to the help pull-down when the window is displayed. When the user selects Tutorial, the HM_TUTORIAL message specifying the file name of the tutorial is sent to the application. An example of the tagging follows:

:h1 tutorial='example.exe'.Test Window

x=
y=
width=
height=

Define the size and position of a window. The x= and y= attributes are values along the x and y axes; they define the origin of the window. The x axis runs horizontally from left to right, and the y axis runs vertically from bottom to top. The position where the values specified for x= and y= intersect is the the origin of the window. (The 0,0 intersection is the bottom left corner of the parent window.) From this location, width and height are measured. For more information about window coordinates, see Defining Window Origin and Size.

Size and position attributes can be given in absolute, dynamic, or relative values:

Absolute value:

A number followed by a letter, which indicates the unit of measure:

c

(Characters): Average character width of the default system font.
x
(Pixels): Dependent on the display adapter in use.
p
( Points): Typesetting measure; equal to approximately 1/72 inch.
Relative value:
A number followed by the percent sign (%), indicating a percentage of the parent-window width or height.
Dynamic value:
A term indicating a window coordinate location that is dependent on the current size and position of the primary window:

center | left | right

For x= values: In the center of, flush left in, or flush right in the parent window.
center | top | bottom
For y= values: In the center of, at the top of, or at the bottom of the parent window.
Restrictions:
When defining window position and size, you cannot mix absolute values with dynamic or relative values for either of the following combinations of attributes:

• The x coordinate and the width 
  The y coordinate and the height.
  If no values for x= and y= are specified, the origin of the window is 0,0. If you specify values other than 0,0, you also must specify width and height values. Negative values for these attributes are not allowed.
group=
viewport
clear

The group= attribute enables you to assign the window a number from 1 through 64 000. This associates the window with a heading definition and the IPFC information that follows it. If you do not provide a number with group=, IPF assigns the number 0.

A group number can be assigned to a viewport by a heading or link definition. For example, suppose you have a group number specified in a link definition, and another in the heading that the link refers to. If a user action causes the link definition to be selected, the link group number overrides the heading group number. However, if the user selects the heading from either the Contents window or the Index window, the heading group number takes effect.

IPF searches among the open windows to find one with a number matching the one specified with group=. If no match is found, IPF opens a new window. If a match is found, the information associated with the group number is swapped with the information in the matched window.

The viewport attribute always opens a window. If you specify both viewport and group=, and a window with the specified group number is already open, IPF opens another window with the same group number. Thus, it is better that you do not specify the viewport attribute in a heading that will appear in the Contents window, unless you want your contents entries to always open separate windows.

The clear attribute causes IPF to close any open windows before opening a window to display the current window.

titlebar=yes | sysmenu | minmax | both | none
rules=border | sizeborder | none
scroll=horizontal | vertical | both | none

These attributes define Presentation Manager window controls and are used primarily when defining secondary windows. If none of these attributes are specified, the default is to open a window that has a title bar with title bar icon, hide button, maximize button; a sizing border; and vertical and horizontal scroll bars.
nosearch
noprint
hide

These attributes restrict information retrieval and are most often used in heading definitions for secondary windows.

The nosearch attribute in a secondary heading definition prevents the heading from being returned as an entry in the search-results window. This does not mean the secondary window is not searched. It is, however, only the primary heading definition that is returned. When the user selects the primary heading definition, the contents of the second window are displayed as part of the primary-window composition.

The noprint attribute in a secondary heading definition prevents the contents of a secondary window from being printed as a separate entity. Instead, secondary windows are printed as part of their primary window. The contents of secondary windows are printed in the order in which the link definitions are listed in the primary window.

When used in secondary heading definitions, nosearch and noprint merely prevent duplication of output (search results or printed copy). When used in regular heading definitions, they prevent retrieval of the information by the user. The only exception to this condition is if the user selects This section for either printing or searching.

The hide attribute prevents a heading level from appearing in the Contents window; however, there must be at least one heading level that is not hidden.

toc=
Specifies heading levels that are to be entries in the Contents window. When this attribute is encountered in a heading tag, the specified heading levels override any levels specified by toc= of the document-profile tag (:docprof.) until either the end-of-file is reached or another toc= attribute is encountered in a heading tag. If no document-profile tag exists, the heading levels that appear in the Contents window are levels 1, 2, and 3. The toc= attribute must be greater than zero.
ctrlarea=
Specifies which control area in a window you want to display push buttons. When this attribute is encountered in a heading tag, it overrides the ctrlarea attribute specified by :docprof.. Possible values are:

page

Identifies the control area as the IPF text window.
none
Specifies that you do not want a control area.
For example, if your document consisted of 100 windows, and you wanted only one window to display push buttons in the IPF text window, you would tag your source file as follows:

:docprof ctrlarea=none..
.
.
:h1 ctrlarea=page.One Window

ctrlrefid=
Refers to the identification value (id=) specified by the control area tag (:ctrl.). This attribute specifies which control area you want to display for this heading. This attribute is used to override the default control area (the coverpage window).

Note: Be careful when using heading tags to define a control area for split windows. A control area cannot be defined in the secondary window heading tag of a split window. You must define the control area (the coverpage window) in the primary window heading tag.

---

[Back: :fn. (Footnote)]
[Next: :hdref. (Heading Reference)]