Skip to content

Hotspots

Chapter 7-9
Hotspots

This chapter describes the composition of hotspots, such as popups and buttons, in a rich text field. You can also use the HCL C API for Domino and Notes to create hotspot file attachments, regions, sections, subforms, and links. For details, refer to the HOTSPOTREC_TYPE_xxx symbolic value and the various CD data types in the Reference.


Definitions

Hotspot: An area in a document or form that causes an action to be taken when clicked.

Popup: A hotspot in a document or form to which a block of text is attached. Clicking the hotspot displays the associated text. You can use popups to annotate a document or provide help for a form. You can only use popups in rich text fields.

Button: A control that performs an action when activated. You can add buttons to a form or a rich text field in a document. If you add a button to a form, every document created using that form contains the button. If you add a button to a document, only that document contains the button.

File: A hotspot in a document or form to which a file is attached. Clicking on the hotspot causes the Properties dialog for the file attachment to appear. The user can then choose to view, detach, or launch the document.

Collapsible Section: A control that toggles the appearance of text in a section. When it is closed, the text is not visible. When it is open, you can see the text.

The Structure of Hotspots

Hotspots consist of a series of Composite Data records, beginning with CDHOTSPOTBEGIN and ending with CDHOTSPOTEND.


CDHOTSPOTBEGIN

The CDHOTSPOTBEGIN structure contains the data needed to define a hotspot. This data consists of:

  • Header information specifying that this is a CDHOTSPOTBEGIN data record. This value can be either SIG_CD_HOTSPOTBEGIN or SIG_CD_V4HOTSPOTBEGIN (used for hotspot types that are new to Release 4, such as collapsible sections and scripts) or SIG_CD_V5HOTSPOTBEGIN (used for hotspot types that are new to Release 5).
  • The type of hotspot being defined (Popup, Button, or File). This value is selected from the defines that begin with "HOTSPOTREC_TYPE_".
  • Flags that describe the appearance of the hotspot and specify (for popups) whether the text associated with the popup is static text or generated by a formula.
  • The length of the variable-length data associated with the CDHOTSPOTBEGIN structure, or zero if there is no associated data (for example, in collapsible sections).

    If the data length is non-zero, more data follows this record. For example, if you are defining a popup and associating it with static text, the data that follows is just a packed string containing the text. If you are defining a button or a popup whose associated text is generated by a formula, the data is the compiled formula defined by the button or popup. If you are defining a file, the data consists of two null-terminated strings. The first string is the internal unique file name assigned to the attached file by Notes. The second string is the original name of the file.

    The data that follows is a formula if the flag field HOTSPOTREC_RUNFLAG_FORMULA or HOTSPOTREC_TYPE_BUTTON bit is set and neither the HOTSPOT_RUNFLAG_ACTION bit nor the HOTSPOT_RUNFLAG_SCRIPT bit is set.

    If the HOTSPOT_RUNFLAG_ACTION bit is set, the data field contains a word containing the record type code (TYPE_ACTION), and the CDHOTSPOTBEGIN record is immediately followed by CDACTIONxxx records which identify the action to perform.

    If the HOTSPOTREC_RUNFLAG_SCRIPT bit is set in the flags field, the CDHOTSPOTBEGIN record is immediately followed by the LotusScript information. The DataLength field of the record is set to the number of bytes of source code included. If the length is zero, there is no source for the script.


For more details, see the Reference entry for CDHOTSPOTBEGIN.


CDHOTSPOTEND

The CDHOTSPOTEND structure delimits the end of the definition of a hotspot. It contains only header information specifying that this is a CDHOTSPOTEND record. It can have either a SIG_CD_HOTSPOTEND or a SIG_CD_V4HOTSPOTEND signature or a SIG_CD_V5HOTSPOTEND signature, depending on the type of hotspot you created.

Other CDRECORDs associated with hotspots can come between the CDHOTSPOTBEGIN record and the CDHOTSPOTEND record.

CDBUTTON

The CDBUTTON structure defines the appearance of a button -- the text on the face of the button, its width, and so on. For details, see the Reference entry for CDBUTTON.

CDBAR

The CDBAR structure defines the appearance of a bar -- the text associated with it, the font of that text, and the color of the bar. For details, see the Reference entry for CDBAR.