The JHSecondaryViewer Component

The JavaHelp 1.0 release provides popup and secondary window support through the JHSecondaryViewer lightweight component. Popups and secondary windows are added to help topics by means of the <OBJECT> tag. This topic describes how to use the <OBJECT> tag for this purpose.

To see how popups and secondary windows work, you can experiment with the object demo located in:

   demos\bin

You can also launch the object demo program using shortcuts (program groups, desktop icons, links) that you may have created during the installation of the JavaHelp system.

The topic files used in that demo provide examples of the <OBJECT> tag in use. These files are located in:

   demos\hs\object

The following example creates a popup that is activated by clicking on the text object "Click here":


   <OBJECT classid="java:com.sun.java.help.impl.JHSecondaryViewer">
     <param name="content" value="../topicB/glossary_def.html">
     <param name="viewerActivator" value="javax.help.LinkLabel">
     <param name="viewerStyle" value="javax.help.Popup">
     <param name="viewerSize" value="300,400">
     <param name="text" value="Click here">
     <param name="textFontFamily" value="SansSerif">
     <param name="textFontSize" value="x-large">
     <param name="textFontWeight" value="plain">
     <param name="textFontStyle" value="italic">
     <param name="textColor" value="red">
   </OBJECT>

The <param> element specifies parameters to the JHSecondaryViewer component. The <param> element takes two attributes: "name", and "value". Parameters may be specified in any order--if parameters conflict, the one specified last is used. Valid parameter names are:

viewerStyle
content
id
viewerActivator
viewerSize
viewerLocation
viewerName
iconByName
iconByID
text
textFontFamily
textFontSize
textFontWeight
textFontStyle
textColor

Parameter Definitions

viewerStyle

Specifies whether the window is a popup or secondary window (see Using Popup and Secondary Windows for a list of differences). The valid values for this parameter are "javax.help.Popup" and "javax.help.SecondaryWindow". If the viewerStyle parameter is omitted the window is created as a secondary window. Example:


   <param name="viewerStyle" value="javax.help.Popup">
   <param name="viewerStyle" value="javax.help.SecondaryWindow">

content

The URL of the topic displayed in the popup or secondary window. The URL must be specified relative to the base address of the containing topic. Example:


   <param name="content" value="../topicB/glossary_def.html">

The ID of the topic displayed in the popup or secondary window. The ID must be defined in the map file for that HelpSet. Example:


   <param name="id" value="gloss_def">

viewerActivator

Specifies how the user activates the window (see Using Popup and Secondary Windows for details about activation). Valid values are:

javax.help.LinkButton User activates the window by clicking on the standard button provided as part of the popup/secondary window lightweight component. You can use the text parameter to add text to the button or you can use the iconByName or iconByID parameters to add images to the button.

javax.help.LinkLabel User activates the window by clicking on a text object or GIF/JPEG image. The text object is specified by means of the text parameter and the image is specified by means of the iconByName and iconByID parameters.

Examples:


   <param name="viewerActivator" value="javax.help.LinkButton">

   <param name="viewerActivator" value="javax.help.LinkLabel">

viewerSize

The width and height (in pixels) of the window. Example:


     <param name="viewerSize" value="300,400">

viewerLocation (secondary windows only)

The x,y position (in pixels) of the upper left corner of the secondary window on the screen--0,0 being the upper left corner of the screen. Popups ignore this parameter. Example:


     <param name="viewerLocation" value="300,400">

viewerName (secondary windows only)

Names a window. This makes it possible to reuse an active window. Popups ignore this parameter. Example:


     <param name="viewerName" value="glossary_window">

iconByName

The URL of a GIF/JPEG image. Images can be used in two ways:

The user clicks on an image to activate a window. In this case iconByName is used in conjunction with the following parameter:
```
   <param name="viewerActivator" value="javax.help.LinkLabel">
```
The images added to the standard button the user clicks on to activate a window. In this case iconByName is used in conjunction with the following parameter:
```
   <param name="viewerActivator" value="javax.help.LinkLabel">
```

Example:


   <param name="iconByName" value="../topicB/glossary_icon.gif">

iconByID

The ID of a GIF/JPEG image. The ID must be defined in the map file for that HelpSet. Images can be used in two ways:

The user clicks on an image to activate a window. In this case iconByID is used in conjunction with the following parameter:
```
   <param name="viewerActivator" value="javax.help.LinkLabel">
```
The images added to the standard button the user clicks on to activate a window. In this case iconByID is used in conjunction with the following parameter:
```
   <param name="viewerActivator" value="javax.help.LinkLabel">
```

Example:


   <param name="iconByID" value="gloss_icon">

text

The string of text that the user clicks on to activate the window. The font characteristics of this text can be controlled using these parameters:

Example:


   <param name="text" value="Click here">

textFontFamily

The font family of the text object. Valid values are:

Serif
SansSerif
Monospaced
Dialog
DialogInput
Symbol

Additional fonts will be supported in future versions of Java^TM 2 SDK.

Example:


   <param name="textFontFamily" value="SansSerif">

textFontSize

The size of the font in the text object. Valid values are:

xx-small
x-small
small
medium
large
x-large
xx-large
bigger (Increases the current base font size by 1)
smaller (Decreases the current base font size by 1)
nnpt (Sets the font size to a specific pt value of nn)
+n (Increases the current base font size by a value of n)
-n (Decreases the current base font size by a value of n)
n (Sets the font size to the point size associated with the index n)

Example:


   <param name="textFontSize" value="x-large">

textFontWeight

The weight of the font in the text object. Valid values are:

plain
bold

Example:


   <param name="textFontWeight" value="plain">

textFontStyle

The style of the font in the text object. Valid values are:

plain
italic

Example:


   <param name="textFontStyle" value="italic">

textColor

The color of the font in the text object. Valid values are:

black
blue
cyan
darkGray
gray
green
lightGray
magenta
orange
pink
red
white
yellow

Example:


     <param name="textColor" value="red">

See also:

Using Popup and Secondary Windows

Creating Lightweight Java Components

`javax.help.LinkButton`	User activates the window by clicking on the standard button provided as part of the popup/secondary window lightweight component. You can use the `text` parameter to add text to the button or you can use the `iconByName` or `iconByID` parameters to add images to the button.
`javax.help.LinkLabel`	User activates the window by clicking on a text object or GIF/JPEG image. The text object is specified by means of the `text` parameter and the image is specified by means of the `iconByName` and `iconByID` parameters.