XmHTML Programmers Manual: XmHTML Widget Class
Author: Koen D'Hondt

### Name

> XmHTML - The XmHTML Widget Class

### Synopsis

> #include <XmHTML/XmHTML.h>

### Description

> XmHTML provides a widget capable of displaying HTML 3.2 confirming text. XmHTML widgets can be used for navigating in and between such documents and can also display non HTML 3.2 documents and standalone images. It contains full image support and a keyboard navigation interface which can be customized through XmHTML's translations.

### Class Information

> Class Hierarchy: Core->Composite->Constraint->XmManager->XmHTML

> Class pointer: xmHTMLWidgetClass.

> Class name: XmHTMLWidget

> Functions/Macros: XmCreateHTML, XmHTML... routines, XmIsHTML.

### New Resources

> XmHTML defines the following resources.

> Name | Class | Type | Default | Access
> XmNalignment | XmCAlignment | unsigned char | XmALIGNMENT_BEGINNING | CSG
> XmNanchorActivatedBackground | XmCBackground | Pixel | white | CSG
> XmNanchorActivatedForeground | XmCForeground | Pixel | red | CSG
> XmNanchorButtons | XmCBoolean | Boolean | True | CSG
> XmNanchorCursor | XmCCursor | Cursor | built-in | CSG
> XmNanchorDisplayCursor | XmCBoolean | Boolean | True | CSG
> XmNanchorForeground | XmCForeground | Pixel | blue1 | CSG
> XmNanchorTargetForeground | XmCForeground | Pixel | blue1 | CSG
> XmNanchorTargetUnderlineType | XmCAnchorUnderlineType | unsigned char | XmSINGLE_DASHED_LINE | CSG
> XmNanchorUnderlineType | XmCAnchorUnderlineType | unsigned char | XmSINGLE_LINE | CSG
> XmNanchorVisitedForeground | XmCForeground | Pixel | blue1 | CSG
> XmNanchorVisitedProc | XmCAnchorVisitedProc | (*)() | NULL | CSG
> XmNanchorVisitedUnderlineType | XmCAnchorUnderlineType | unsigned char | XmSINGLE_LINE | CSG
> XmNbodyImage | XmCString | String | NULL | CSG
> XmNcharset | XmCString | String | iso8859-1 | CSG
> XmNclientData | XmCClientData | XtPointer | NULL | CSG
> XmNdecodeGIFProc | XmCDecodeGIFProc | XmImageGifProc | NULL | CSG
> XmNenableBadHTMLWarnings | XmCWarningMode | Byte | XmHTML_ALL | CSG
> XmNenableBodyColors | XmCBoolean | Boolean | True | CSG
> XmNenableBodyImages | XmCBoolean | Boolean | True | CSG
> XmNenableDocumentColors | XmCBoolean | Boolean | True | CSG
> XmNenableDocumentFonts | XmCBoolean | Boolean | True | CSG
> XmNenableFormColors | XmCBoolean | Boolean | True | CSG
> XmNenableIconEntities | XmCBoolean | Boolean | False | CSG
> XmNenableOutlining | XmCBoolean | Boolean | False | CSG
> XmNeventProc | XmCEventProc | XmHTMLEventProc | NULL | CSG
> XmNfontFamily | XmCString | String | adobe-times-normal-* | CSG
> XmNfontFamilyFixed | XmCString | String | adobe-courier-normal-* | CSG
> XmNfontSizeList | XmCString | String | 14,8,24,18,14,12,10,8 | CSG
> XmNfontSizeFixedList | XmCString | String | 12,8 | CSG
> XmNfreezeAnimations | XmCBoolean | Boolean | False | CSG
> XmNhighlightOnEnter | XmCHighlightOnEnter | Boolean | True | CSG
> XmNhorizontalScrollBar | XmCHorizontalScrollBar | Widget | NULL | CG
> XmNiconAlignment | XmCVerticalAlignment | unsigned char | XmALIGNMENT_CENTER | CSG
> XmNimageEnable | XmCBoolean | Boolean | True | CSG
> XmNimagemapDrawBoundingBoxes | XmCBoolean | Boolean | False | CSG
> XmNimagemapBoundingBoxForeground | XmCForeground | Pixel | White | CSG
> XmNimageMapToPalette | XmCConversionMode | unsigned char | XmDISABLED | CSG
> XmNimagePalette | XmCString | String | NULL | CG
> XmNimageProc | XmCImageProc | XmImageProc | dynamic | CSG
> XmNimageRGBConversion | XmCConversionMode | unsigned char | XmBEST | CSG
> XmNmarginHeight | XmCMarginHeight | Dimension | 20 | CSG
> XmNmarginWidth | XmCMarginWidth | Dimension | 20 | CSG
> XmNmaxImageColors | XmCMaxImageColors | int | 0 | CSG
> XmNmimeType | XmCString | String | text/html | CSG
> XmNrepeatDelay | XmCRepeatDelay | int | 25 | CSG
> XmNresizeHeight | XmCResizeHeight | Boolean | False | CSG
> XmNresizeWidth | XmCResizeWidth | Boolean | False | CSG
> XmNscreenGamma | XmCScreenGamma | float | 2.2 | CSG
> XmNscrollBarDisplayPolicy | XmCScrollBarDisplayPolicy | unsigned char | XmAS_NEEDED | CSG
> XmNscrollBarPlacement | XmCScrollBarPlacement | unsigned char | XmBOTTOM_RIGHT | CSG
> XmNsmoothScrolling | XmCBoolean | Boolean | True | CSG
> XmNstrictHTMLChecking | XmCBoolean | Boolean | False | CSG
> XmNStringDirection | XmCStringDirection | unsigned char | XmSTRING_DIRECTION_L_TO_R | CSG
> XmNtabWidth | XmCTabWidth | int | 8 | CSG
> XmNtopLine | XmCTopLine | Cardinal | 0 | CSG
> XmNuncompressCommand | XmCString | String | uncompress | CSG
> XmNvalue | XmCValue | String | NULL | CSG
> XmNverticalScrollBar | XmCVerticalScrollBar | Widget | NULL | CG
> XmNworkWindow | XmCWorkWindow | Widget | NULL | CG

> XmNalignment
>   Identifies the default alignment (left to right) in which text will be displayed. Possible values are: XmALIGNMENT_BEGINNING, XmALIGNMENT_CENTER and XmALIGNMENT_END.

>   This resource is only meaningfull when the XmNenableOutlining resource is False.

> XmNanchorActivatedBackground
>   The background color to use when an anchor is activated. This resource is only honored when the XmNanchorButtons resource is set to False

> XmNanchorActivatedForeground
>   The foreground color to use when an anchor is activated.

> XmNanchorButtons
>   When set to True, all anchors will be rendered as pushbuttons instead of being underlined.

> XmNanchorCursor
>   The cursor to display when the pointer is moved over an anchor. The built-in cursor is a hand with a pointing finger. Only in effect when the XmNanchorDisplayCursor resource is set.

> XmNanchorDisplayCursor
>   When set to True, the cursor will change when the pointer is moved over an anchor.

> XmNanchorForeground
>   The color in which anchors will be displayed.

> XmNanchorTargetForeground
>   The color in which anchors that have a TARGET attribute specified will be displayed.

> XmNanchorTargetUnderlineType
>   Underlining style for anchors that have a TARGET attribute specified. See XmNanchorUnderlineType for possible values. This resource is only honored when the XmNanchorButtons resource is set to False

> XmNanchorUnderlineType
>   Underlining style for anchors. Can be any of the following:

>   XmNO_LINE | /* no underlines */
>   XmSINGLE_LINE | /* a single, solid, underline */
>   XmDOUBLE_LINE | /* a double, solid, underline */
>   XmSINGLE_DASHED_LINE | /* a single, dashed, underline */
>   XmDOUBLE_DASHED_LINE | /* a double, dashed, underline */

>   This resource is only honored when the XmNanchorButtons resource is set to False

> XmNanchorVisitedForeground
>   The color in which previously visited anchors will be displayed.

> XmNanchorVisitedProc
>   The procedure that should be called to test if an anchor has been activated before. There are three arguments to this procedure: the widget id, the name of the anchor and a pointer to data that the application attached to the widget using the XmNclientData resource. It should return True when the anchor should be rendered using the XmNanchorVisitedForeground resource.

>   This procedure is used when a document is loaded into the widget. It is called for every anchor encountered.

> XmNanchorVisitedUnderlineType
>   Underlining style for previously visited anchors. See XmNanchorUnderlineType for possible values. This resource is only honored when the XmNanchorButtons resource is set to False

> XmNbodyImage
>   The name of the image to be used as the default body image. This resource is only honored when the XmNenableBodyImages resource is set to True

> XmNcharset
>   A string representing the ISO character set encoding to be used. The default value (iso8859-1) represents the ISO Latin-1 character set.

>   When an attempt is made to set a charset which does not exist on the X server, the XmHTML widget falls back to it's default charset.

> XmNclientData
>   A pointer to data that the application can attach to the functions attached to the XmNanchorVisitedProc and XmNimageProc resources. This resource is unused internally.

> XmNdecodeGIFProc
>   An alternative procedure that should be used for decoding GIF images.

>   To avoid patent issues related to the use of the LZW algorithm (patented by Unisys Coorporation), the default GIF decoder uses a patent-free workaround (involving a system call to the program specified under the XmNuncompressCommand resource). Although this workaround is fairly fast for single-image GIF images, decoding animations can take a considerable amount of time. Therefore, owners of a LZW license or authors of freeware can attach their own LZW decoder to this resource, thereby achieving a small to considerable performance increase.

>   See XmHTMLGIFStream --XmHTML External GIF Decoder Interface Definition-- for more information.

> XmNenableBadHTMLWarnings
>   Specifies the types of warnings a XmHTML Widget may issues when the HTML parser detects bad HTML constructs in the input document. Unless were noted, multiple warning types can be specified by OR'ing different warning types together.

>   Possible values are:

>   XmHTML_NONE | /* no warnings at all, exclusive value */
>   XmHTML_UNKNOWN_ELEMENT | /* unknown HTML element */
>   XmHTML_BAD | /* very badly placed element */
>   XmHTML_OPEN_BLOCK | /* block still open while new block started */
>   XmHTML_CLOSE_BLOCK | /* block closed but was never opened */
>   XmHTML_OPEN_ELEMENT | /* unbalanced terminator */
>   XmHTML_NESTED | /* improperly nested element */
>   XmHTML_VIOLATION | /* bad content for current block/element */
>   XmHTML_ALL | /* show all warnings, exclusive value */

> XmNenableBodyColors
>   If True (default), the body and text colors specified in a HTML document will be honored.

> XmNenableBodyImages
>   If True (default), the background image specified in a HTML document will be honored.

> XmNenableDocumentColors
>   If True (default), the color attribute will be honored for the HTML tags listed in the XmHTML HTML Extensions as well as for the <FONT> element. If set to False no color switching will be performed.

> XmNenableDocumentFonts
>   If True (default), the size and face attribute of the <FONT> will be honored. If set to False, no font switching will be performed. Note that setting both XmNenableDocmentColors and XmNenableDocumentFonts to False effectively disables the <FONT> element.

> XmNenableFormColors
>   If True (default), any widgets created by a XmHTML Widget as part of a HTML <FORM> tag use the document background and foreground colors. When False, Motif's default values will be used. Please note that in the latter case this will break the natural look of the document.

> XmNenableIconEntities
>   If True, support for builtin icon entities will be enabled. This allows the recognition of character escapes that are to be rendered as icons. For example, `&folder.open;` represents an icon of an open file folder. XmHTML supports all 61 icons listed in the W3C Working Draft WD-wwwicon-960729.

>   The default value of this resource is False.

> XmNenableOutlining
>   If True (default), all text of which the alignment is not explicitly set will be outlined (justified): every line in a paragraph (or sentence spanning more than a single line) will have the same left and right margin.

> XmNeventProc
>   This resource identifies a procedure to be called whenever a HTML4.0 event is encountered while the document is being loaded.

>   The call to this procedure contains three arguments: the widget ID of the XmHTML widget, the value of the event (some action that should be performed when a HTML4.0 event occurs) and a pointer to data that the application attached to the widget using the XmNclientData resource.

>   The return value of this procedure is a pointer to application data which is used as the data field of the XmNeventCallback whenever a HTML4.0 event occurs. This value is unused internally.

>   Note: the XmHTMLGetHeadAttributes convenience function can be used to retrieve the <SCRIPT> source to which these actions most likely refer.

> XmNfontFamily
>   A sequence of four, dash-separated strings that make up the family of fonts to be used for displaying text. A fontFamily is composed of the following fields:

>   1. foundry: the type foundry that digitized and supplied the font, i.e. Adobe;
>   2. family: the font family name, i.e. roman;
>   3. set width: a value describing a font's proportionate width according to the selected foundry, i.e. normal;
>   4. spacing: type of character spacing for a font. m (for monospace, i.e. fixed width) or p (proportional, i.e., variable-width) are two well known font spacings.

>   Wildcards are allowed for all four fields, but can produce unwanted results if your X (or font) server is not configured correctly or if you have a lot of fonts installed. A nominal specification should at least include the family field.

> XmNfontFamilyFixed
>   A string describing the family of fonts to be used for displaying text at a fixed width.

>   See XmNfontFamily on how to compose this string.

> XmNfontSizeList
>   A comma separated list of eight strings describing the various default font sizes to be used, specified in points. The list below describes the various fields in this resource.

>   1. default font size.
>   2. sub and superscript font size
>   3. font size for the <H1> element
>   4. font size for the <H2> element
>   5. font size for the <H3> element
>   6. font size for the <H4> element
>   7. font size for the <H5> element
>   8. font size for the <H6> element

>   When an element in this list has the value 0 (zero), the appropriate default font size is used.

> XmNfontSizeFixedList
>   A comma separated list of two strings describing the fixed font sizes to be used, specified in points. The list below describes the various fields in this resource.

>   1. default fixed font size.
>   2. sub and superscript fixed font size

>   When an element in this list has the value 0 (zero), the appropriate default font size is used.

> XmNfreezeAnimations
>   When set to True, XmHTML will freeze all animations in a document at the currently displayed frame. Animation will continue when the value of this resource is set to False.

> XmNhighlightOnEnter
>   When True (default), an anchor will appear highlighted when the cursor is moved over it. When set to False, anchor highlighting is not performed. The color used for performing anchor highlighting is computed dynamically and depends on the current document foreground color and background setting.

> XmNhorizontalScrollBar
>   The widget ID of the horizontal scrollbar.

> XmNiconAlignment
>   This resource specifies the default vertical alignment that must be used for icon entities. Only meaningfull when the XmNenableIconEntities resource has been set to True.

>   Possible values for this resource are:

>   XmALIGNMENT_BASELINE_TOP | /* text will be aligned at the top of the icon */
>   XmALIGNMENT_CENTER | /* text will be aligned at the center of the icon */
>   XmALIGNMENT_BASELINE_BOTTOM | /* text will be aligned at the bottom of the icon */

> XmNimageEnable
>   When True (default) images are displayed.

> XmNimagemapDrawBoundingBoxes
>   When True, XmHTML will draw a bounding box around each area in an imagemap. The color used for drawing these bounding boxes can be changed using the XmNimagemapBoundingBoxForeground resource.

>   This resource is especially usefull for debugging imagemaps in a document, and it can be an aid to persons with limited visual capability.

> XmNimagemapBoundingBoxForeground
>   The color used for drawing imagemap bounding boxes.

> XmNimageMapToPalette
>   This resource determines if a XmHTML widget should perform dithering to a fixed palette and if so how that should be done.

>   Possible values are:

>   XmQUICK | A closest distance algorithm is used to map image colors to the palette. No error correction is performed. Fast, but the resulting image quality depends on the distribution of the colors in the image.
>   XmBEST | Ordered dither using predefined error matrices. Offers the best balance between speed and quality but uses a lot of memory (512kb).
>   XmFAST | Simple ordered dither without error correction. This is the fastest method but uses a lot of memory (512kb).
>   XmSLOW | A closest distance algorithm followed by Floyd-Steinberg error diffusion. Slowest method but highest quality.
>   XmDISABLED | disables palette mapping. This is the default setting.

> XmNimagePalette
>   Specifies a fixed palette a XmHTML widget should use. Document colors are mapped onto this palette and document images are dithered against it.

>   A palette is defined as a string consisting of RGB triplets. Each color component in a triplet must be given as a hexadecimal string and its value must be in the range 0-255 inclusive. Each color component is separated from the next by a single space. Triplets are separated by (any amount of) whitespace.

>   If the XmNmaxColors resource isn't set or differs from the number of colors in the specified palette, it will be set to the size of this palette (with a maximum of 256 colors).

>   If the imageMapToPalette resource has been set but no value has been specified for this resource, the XmHTML Widget will create a palette. The size of this palette is given by the value of the maxImageColors resource.

>   This resource can only be set at creation time.

> XmNimageProc
>   The procedure that should perform image loading. The call to this procedure contains five arguments: the widget ID of the XmHTML widget, the URL where the image can be obtained, the width and height of the image as specified by the `width` and `height` attributes on the `<IMG>` tag (they are 0 (zero) if these attributes have not been specified) and a pointer to data that the application attached to the widget using the XmNclientData resource.

>   The return value of this procedure must be a pointer to a XmImageInfo structure. The URL argument to this procedure must be copied into this structure, it has a very limited lifetime within XmHTML itself.

>   For common use, this resource should point to a procedure which retrieves the requested image, calls the XmHTMLImageDefaultProc convenience function and returns the obtained XmImageInfo structure.

>   When no value is provided for this resource, XmHTML installs an internal procedure that is capable of loading local images only. This resource has no effect if XmNimageEnable is False.

> XmNimageRGBConversion
>   This resource determines the conversion XmHTML should use when it's converting 24bit PNG images to 8bit ones.

>   Possible values are:

>   XmQUICK | A fast check is made to see if an image contains less than XmNmaxImageColors colors. If not, 24 to 8 bit conversion is done using (ordered) dither against a fixed palette.
>   XmBEST | A fast check is made to see if an image contains less than XmNmaxImageColors colors. If not, 24 to 8 bit conversion is done using a histogram of the 24bit image. This offers the best tradeoff between speed and image quality for 24 to 8 bit conversion as 24bit RGB images on web pages often have less than 256 colors. This is the default setting.
>   XmFAST | dithers to a fixed palette right away. This is the fastest way to do 24 to 8 bit conversion.
>   XmSLOW | skips the fast check and does 24 to 8 bit conversion using a histogram immediatly. This setting produces the best results.

> XmNmarginHeight
>   The spacing at the top and bottom of the display area.

> XmNmarginWidth
>   The spacing at the right and left sides of the display area.

> XmNmaxImageColors
>   Specifies how many colors each image may take. A value of 0 (default) informs a XmHTML widget that it may allocate as many colors as it can (with a maximum of 256 colors). When set to a non-zero value, images with more colors than allowed will be quantized to reduce the number of colors in the image.

>   When the XmNimageMapToPalette resource has a value other than XmDISABLED without providing a palette with the XmNimagePalette resource, a XmHTML widget will create a palette with at most this many colors.

> XmNmimeType
>   This resource informs how XmHTML should treat any content specified by the XmNvalue resource. XmHTML knows how to handle the following mime types: text/html, text/plain and every image mime type specification that starts with image/.

>   This resource only takes effect when used in combination with the XmNvalue resource.

> XmNrepeatDelay
>   The number of milliseconds a button must remain pressed before continuing further scrolling. This resource is used for both the keyboard navigation keys and scrollbars. Depending on the capabilities of your graphics hardware, setting this resource to a small value can cause screen updates to be slow or incomplete.

> XmNresizeHeight
>   If False(default), the HTML widget will not expand vertically to fit all of the text. If True, the HTML widget always begins its display with the text at the beginning of the source and expand as much as possible, but it will never exceed 80% of the available screen height.

> XmNresizeWidth
>   If False(default), the HTML widget will not expand horizontally to fit its text. If True, the widget tries to change its width, but it will never exceed 80% of the available screen width.

> XmNscreenGamma
>   Display gamma correction. The default value of 2.2 will be sufficient for most displays. When using a Silicon Graphics display, this value should be set to 1.8, and when using a Macintosh display (MkLinux) it should be 1.4. This resource is only used for rendering JPEG and PNG images.

> XmNscrollBarDisplayPolicy
>   Controls the presence of the Vertical and Horizontal ScrollBars. Possible values:

>   XmSTATIC | /* scrollbars are always displayed */
>   XmAS_NEEDED | /* scrollbars are only displayed when view is clipped */

> XmNscrollBarPlacement
>   The positions of the ScrollBars relative to the work window. Possible values:

>   XmTOP_LEFT | /* vertical ScrollBar on left; horizontal on top */
>   XmBOTTOM_LEFT | /* vertical ScrollBar on left; horizontal on bottom */
>   XmTOP_RIGHT | /* vertical ScrollBar on right; horizontal on top */
>   XmBOTTOM_RIGHT | /* vertical ScrollBar on right; horizontal on bottom */

> XmNsmoothScrolling
>   If True (default), XmHTML will perform smooth scrolling: any slider movement of the scrollbars will result in an immediate update of the screen.

>   In some cases, smooth scrolling may lead to portions of the document not being updated properly (for example, very fast dragging of a scrollbar or a small value for the XmNrepeatDelay resource). If you experience this (unwanted) behavior, try setting this resource to False. XmHTML will then discard any motion events that are still unprocessed if a new motion event arrives. This may lead to jumpy scrolling but ensures that the screen is updated properly.

> XmNstrictHTMLChecking
>   This resource enables strict checking of HTML files according to the HTML 3.2 standard. Beware that many HTML files are in violation of this standard and that the result might be not exactly what is intended.

>   One important check that is performed when this resource is True concerns the values for all color specifications. When a color is specified by a name, only the 16 standard colors are allowed.

> XmNStringDirection
>   The direction in which to render the document contents. Possible values are XmSTRING_DIRECTION_L_TO_R and XmSTRING_DIRECTION_R_TO_L.

> XmNtabWidth
>   Specifies the width of a horizontal tab in preformatted text. This resource is specified as a positive, non-zero integer value.

> XmNtopLine
>   The number of the line to display at the top of the window. Values for this resource are relative to the beginning of the text, where the first line is defined as 0.

> XmNuncompressCommand
>   Specifies the command the internal GIF decoder should use to uncompress `compress(1)` data. If the target system lacks the presence of `compress(1)`, `gzip -d` provides a good alternative.

> XmNvalue
>   The string value to display in the HTML Widget. Use XtSetValues to copy string values to the internal buffer. XtGetValues will return a pointer to the internal buffer which may not be freed nor modified.

> XmNverticalScrollBar
>   The widget ID of the vertical scrollbar.

> XmNworkWindow
>   The widget ID of the display area.

### Inherited Resources

> XmHTML inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them

> Resource | Inherited From | Resource | Inherited From
> XmNaccelerators | Core | XmNancestorSensitive | Core
> XmNbackground | Core | XmNbackgroundPixmap | Core
> XmNborderColor | Core | XmNborderPixmap | Core
> XmNborderWidth | Core | XmNbottomShadowColor | Core
> XmNbottomShadowPixmap | Core | XmNchildren | Composite
> XmNcolormap | Core | XmNdepth | Core
> XmNdestroyCallback | Core | XmNforeground | Manager
> XmNhelpCallback | Manager | XmNheight | Core
> XmNhighlightColor | Manager | XmNhightlightPixmap | Manager
> XmNinitialResourcesPersistent | Core | XmNinsertPosition | Composite
> XmNmappedWhenManaged | Core | XmNnavigationType | Manager
> XmNnumChildren | Composite | XmNscreen | Core
> XmNsensitive | Core | XmNshadowThickness | Manager
> XmNstringDirection | Manager | XmNtopShadowColor | Manager
> XmNtopShadowPixmap | Manager | XmNtranslations | Core
> XmNtraversalOn | Manager | XmNunitType | Manager
> XmNuserData | Manager | XmNwidth | Core
> XmNx | Core | XmNy | Core

### Callback Resources

> XmHTMLWidget defines the following callback resources:

> Callback | Reason Constant | Event Type
> XmNactivateCallback | XmCR_ACTIVATE | XButtonReleasedEvent
> XmNanchorTrackCallback | XmCR_HTML_ANCHORTRACK | XMotionEvent, XLeaveWindowEvent, XFocusOutEvent
> XmNarmCallback | XmCR_ARM | XButtonPressedEvent
> XmNdocumentCallback | XmCR_HTML_DOCUMENT | NULL
> XmNeventCallback | XmCR_HTML_EVENT, XmCR_HTML_EVENTDESTROY | dynamic
> XmNfocusCallback | XmCR_FOCUS | XFocusInEvent
> XmNformCallback | XmCR_HTML_FORM | XButtonPressedEvent
> XmNframeCallback | XmCR_HTML_FRAME, XmCR_HTML_FRAMECREATE, XmCR_HTML_FRAMEDESTROY | NULL
> XmNimagemapCallback | XmCR_HTML_IMAGEMAP, XmCR_HTML_IMAGEMAPACTIVATE | undefined
> XmNinputCallback | XmCR_INPUT | XKeyEvent
> XmNlinkCallback | XmCR_HTML_LINK | NULL
> XmNlosingFocusCallback | XmCR_LOSING_FOCUS | XFocusOutEvent
> XmNmotionTrackCallback | XmCR_HTML_MOTIONTRACK | XMotionEvent

> XmNactivateCallback is activated when a BSelect press occurs over an anchor or imagemap.

> XmNanchorTrackCallback is activated when the pointer is moved over an achor or imagemap.

> XmNarmCallback is activated when a BSelect Press occurs when not over an anchor or imagemap.

> XmNdocumentCallback is activated when a XmHTML Widget has parsed a document but before it is displayed.

> XmNeventCallback is activated when a HTML4.0 event is encountered.

> XmNfocusCallback is activated when a XmHTML Widget gains the focus.

> XmNformCallback is activated when a document containing a HTML <FORM> is to be submitted.

> XmNframeCallback is activated when a XmHTML Widget encounters a document containing one or more <FRAMESET> specifications. A XmHTML Widget will only be able to handle framesets if a function has been registed for this callback resource.

> XmNimagemapCallback is actived in any of the following cases:

> 1. a BSelect press occurs over an image with the ISMAP attribute set but the USEMAP attribute has not been set or refers to a server-side imagemap;
> 2. a remote client-side imagemap should be fetched.

> XmNinputCallback is activated whenever keyboard events that are not served by any of the other callback resources or action routines are received.

> XmNlinkCallback is activated when a document containing <LINK> elements is loaded into the a XmHTML widget. It is activated only once for a document.

> XmNlosingFocusCallback is activated when a XmHTML Widget loses the focus. XmNmotionTrackCallback complements the XmNanchorTrackCallback resource. It is activated when pointer movement does not take place over an anchor or imagemap.

### Callback Structures

> Each callback function is passed the following structure:

>     typedef struct{
>         int reason;     /* the reason the callback was called */
>         XEvent *event;  /* points to event structure that triggered callback */
>     }XmAnyCallbackStruct;

> None of the fields in this structure (and any other callback structure for that matter) may be freed, unless explicitly noted otherwise.

> In addition, several callback resources reference additional structures.

> #### XmNactivateCallback, XmNanchorTrackCallback

> XmNactivateCallback and XmNanchorTrackCallback reference the following structure:

>     typedef struct{
>         int reason;             /* the reason the callback was called       */
>         XEvent *event;          /* event structure that triggered callback  */
>         URLType url_type;       /* type of url referenced                   */
>         Cardinal line;          /* line number of the selected anchor       */
>         String href;            /* pointer to the anchor value              */
>         String target;          /* pointer to target value                  */
>         String rel;             /* pointer to rel value                     */
>         String rev;             /* pointer to rev value                     */
>         String title;           /* pointer to title value                   */
>         Boolean is_frame;       /* true when inside a frame                 */
>         Boolean doit;           /* local anchor vetoing flag                */
>         Boolean visited;        /* local anchor visited flag                */
>         Boolean doc_modified;   /* document modification flag               */
>     }XmHTMLAnchorCallbackStruct;

> The doit member is only meaningfull when the callback reason is XmCR_ACTIVATE and the referenced anchor is a local (named) anchor. When set to True, the widget will scroll to the referenced anchor. When this member is False (default), the widget will not scroll to the named anchor.

> The visited member is only meaningfull when the callback reason is XmCR_ACTIVATE and the referenced anchor is a local (named) anchor. When set to True, the referenced anchor will be rendered using the XmNanchorVisitedForeground and XmNanchorVisitedUnderlineType resources. The default value for this member is False.

> The doc_modified member should be set to True when an action taken during processing of this callback results in a modification of the currently displayed document. The default value for this member is False.

> The XmNanchorTrackCallback callback is called twice for an anchor: once when the pointer is moved into an anchor and once when it is moved away from an anchor. In the latter case, all fields except reason and event will be NULL.

> See XmHTMLGetURLType(3X) for possible values and meaning of the url_type field.

> #### XmNdocumentCallback

> XmNdocumentCallback references the following structure:

>     typedef struct{
>         int reason;             /* the reason the callback was called       */
>         XEvent *event;          /* always NULL for XmNdocumentCallback      */
>         Boolean html32;         /* True if document was HTML 3.2 conforming */
>         Boolean verified;       /* True if document has been verified       */
>         Boolean balanced;       /* True if parser tree is balanced          */
>         Boolean terminated;     /* True if parser terminated prematurely    */
>         int pass_level;         /* current parser level count. Starts at 1  */
>         Boolean redo;           /* perform another pass?                    */
>     }XmHTMLDocumentCallbackStruct, *XmHTMLDocumentPtr;

> The verified field is set to True when the internal parses has successfully verified the HTML semantics of the loaded document, while the balanced field will be True when the parser has generated a balanced tree. A balanced tree is one in which all terminated HTML elements have their opening and closing members at the same level in the tree. The pass_level field contains the number of passes performed so far by the parser.

> Setting the redo field to True will instruct the parser to make another pass on the current document. It is only effective when the parser failed to generate a balanced tree since using an unbalanced tree can lead to weird markup. When the balanced field is false, the default value for this field is True.

> When no XmNdocumentCallback callback resource is installed, the internal HTML parses will make at most two passes on the current document.

> #### XmNeventCallback

> XmNeventCallback references the following structure:

>     typedef struct{
>         int reason;             /* the reason the callback was called       */
>         XEvent *event;          /* event structure that triggered callback  */
>         int type;               /* HTML4.0 event type, see below            */
>         XtPointer data;         /* HTML4.0 event callback data              */
>         Boolean doc_modified;   /* document modification flag               */
>     }XmHTMLEventCallbackStruct;

> Where type identifies a HTML4.0 event and data any data returned by the function installed on the XmNeventProc resource.

> The doc_modified member should be set to True when an action taken during processing of an event results in a modification of the currently displayed document. Failing to update this member properly while the document is changed during event processing will lead to serious problems since XmHTML's internal data structures will then no longer refer to the currently displayed document.

> The table shown below lists all events for which a modification of the document is supported during event processing. The default value for this member is False.

> type can have any of the following values:

> type value | HTML4.0 event | doc_modified allowed?
> --- | --- | ---
> XmCR_HTML_LOAD | onLoad | No
> XmCR_HTML_UNLOAD | onUnLoad | No
> XmCR_HTML_SUBMIT | onSubmit | Yes
> XmCR_HTML_RESET | onReset | Yes
> XmCR_HTML_FOCUS | onFocus | Yes
> XmCR_HTML_BLUR | onBlur | Yes
> XmCR_HTML_SELECT | onSelect | Yes
> XmCR_HTML_CHANGE | onChange | Yes
> XmCR_HTML_CLICK | onClick | Yes
> XmCR_HTML_DOUBLE_CLICK | onDblClick | Yes
> XmCR_HTML_MOUSEDOWN | onMouseDown | Yes
> XmCR_HTML_MOUSEUP | onMouseUp | Yes
> XmCR_HTML_MOUSEOVER | onMouseOver | Yes
> XmCR_HTML_MOUSEMOVE | onMouseMove | Yes
> XmCR_HTML_MOUSEOUT | onMouseOut | Yes
> XmCR_HTML_KEYPRESS | onKeyPress | Yes
> XmCR_HTML_KEYDOWN | onKeyDown | Yes
> XmCR_HTML_KEYUP | onKeyUp | Yes

> The expected behavior depends on the value of the reason field:

> XmCR_EVENT
>   A HTML4.0 event occured on an element in the currently displayed document. The application should undertake any actions that correspond to the HTML4.0 event type. data identifies the data associated with this particular event (which can be different depending on the HTML tag that triggered this event).

> XmCR_EVENTDESTROY
>   This reason occurs as part of the document unloading process, e.i., prior before a new document is loaded. Any application data stored to serve the HTML4.0 event type can be freed safely.

> #### XmNformCallback

> XmNformCallback references the following structure:

>     typedef struct{
>         int reason;             /* the reason the callback was called       */
>         XEvent *event;          /* event structure that triggered callback  */
>         String action;          /* URL or cgi-bin destination               */
>         String enctype;         /* form encoding                            */
>         int method;             /* Form Method, GET (0) or POST (1)         */
>         int ncomponents;        /* no of components in this form            */
>         XmHTMLFormDataPtr components;
>         Boolean doc_modified;   /* document modification flag               */
>     }XmHTMLFormCallbackStruct, *XmHTMLFormPtr;

> Where the XmHTMLFormDataPtr field points to an array of structures of the following type:

>     typedef struct{
>         componentType type;     /* Form component type  */
>         String name;            /* component name       */
>         String value;           /* component value      */
>     }XmHTMLFormDataRec, *XmHTMLFormDataPtr;

> The componentType type identifies the type of the form member that is to be submitted. Possible values are:

>     typedef enum{
>         FORM_TEXT = 1,          /* textfield            */
>         FORM_PASSWD,            /* password textfield   */
>         FORM_CHECK,             /* checkbox             */
>         FORM_RADIO,             /* radiobox             */
>         FORM_RESET,             /* reset button         */
>         FORM_FILE,              /* filelisting          */
>         FORM_SELECT,            /* select parent        */
>         FORM_OPTION,            /* select child         */
>         FORM_TEXTAREA,          /* multiline edit field */
>         FORM_IMAGE,             /* drawbutton           */
>         FORM_HIDDEN,            /* hidden input         */
>         FORM_SUBMIT             /* submit button        */
>     }componentType;

> The doc_modified member should be set to True when an action taken during processing of this callback results in a modification of the currently displayed document. The default value for this member is False.

> #### XmNframeCallback

> XmNframeCallback references the following structure:

>     typedef struct{
>         int reason;         /* the reason the callback was called       */
>         XEvent *event;      /* event structure that triggered callback  */
>         String src;         /* requested document                       */
>         String name;        /* frame name                               */
>         Widget html;        /* XmHTML widget id                         */
>         Boolean doit;       /* destroy/create vetoing flag              */
>     }XmHTMLFrameCallbackStruct, *XmHTMLFramePtr;

> The expected behavior depends on the value of the reason field:

> XmCR_HTML_FRAMECREATE
>   A XmHTML Widget is about to create a xmHTMLWidgetClass widget (referred to as a frame) to be used as part of a HTML frameset.

>   The src field contains the URL where a source document destined for this frame can be obtained. The name field contains the name given to this frame by the author of the document. If no name has been provided in the frameset definition, XmHTML will use `_frame` appended with a rank number as a default name.

>   The doit field is set to True by default. When this field is set to False and the html field (which is initially NULL) is set to contain the id of a xmHTMLWidgetClass widget, XmHTML will use this widget as a frame and will not create a new one when this callback function returns. When the doit field is unchanged, or when the provided widget ID does not identify a Widget of class xmHTMLWidgetClass, XmHTML will create a frame.

>   Each frame created by XmHTML in response to a HTML frameset will be a child of the XmHTML widget in which the original document was loaded.

> XmCR_HTML_FRAME
>   A XmHTML Widget XmHTML has created a frame (or prepared the widget provided by the previous callback reason). The src and name field are unchanged, while the html field contains a valid widget id.

>   This callback reason allows one to (amongst others) add callbacks (most noticeably a XmNactivateCallback) and resources (such as a XmNimageProc handler) to this newly created or reused widget.

> XmCR_HTML_FRAMEDESTROY
>   A XmHTML Widget is about to destroy a frame. The src, name and html fields identify the frame that is to be destroyed. Modifying the value of the doit field from True (default) to False will veto the destruction of this frame, and subsequently this frame can be reused at a later stage.

> The name field is rather important for navigating between different frames in a frameset: anchors can reference to another frame by using the target attribute on the <A> tag. Knowing this, the reasons for this type of approach becomes apparent: to allow navigation between different frames in a frameset, one should not only know the name of the referenced frame but also the widget id of the corresponding frame. And this is exactly what this approach provides.

> #### XmNimagemapCallback

> XmNimagemapCallback references the following structure:

>     typedef struct{
>         int reason;           /* the reason the callback was called */
>         XEvent *event;        /* points to event structure that triggered callback */
>         int x,y;              /* pointer position relative to the upper-left
>                                * corner of the image.
>                                */
>         String image_name;    /* name of referenced image  */
>         String map_name;      /* name of imagemap to fetch */
>         String map_contents;  /* contents of fetched imagemap */
>     }XmHTMLImagemapCallbackStruct, *XmHTMLImagemapCallbackStructPtr;

> The expected behavior depends on the value of the reason field:

> XmCR_HTML_IMAGEMAPACTIVATE

>   THIS REASON IS UNIMPLEMENTED

>   user clicked on an image. All fields except map_name are valid. x and y are relative to the upper-left corner of the image. Only invoked when an image has it's ismap attribute set and no client-side usemap is present for this image.

> XmCR_HTML_IMAGEMAP
>   an image requires an external imagemap. Valid fields are image_name and map_name. The latter contains the location of the imagemap to fetch. If the contents of this imagemap are set in the map_contents field, it will be copied by the widget. Alternatively, one could also use the XmHTMLAddImagemap convenience function to set an imagemap into the widget.

> #### XmNlinkCallback

> XmNlinkCallback references the following structure:

>     typedef struct{
>         int reason;                 /* the reason the callback was called       */
>         XEvent *event;              /* event structure that triggered callback  */
>         int num_link;               /* number of LINK info to process           */
>         XmHTMLLinkDataPtr link;     /* array of LINK info to process            */
>     }XmHTMLLinkCallbackStruct, *XmHTMLLinkPtr;

> Where the XmHTMLLinkDataPtr field points to an array of structures of the following type:

>     typedef struct{
>         String url;             /* value of URL tag     */
>         String rel;             /* value of REL tag     */
>         String rev;             /* value of REV tag     */
>         String title;           /* value of TITLE tag   */
>     }XmHTMLLinkDataRec, *XmHTMLLinkDataPtr;

### Translations

> The translations for XmHTML include those from Manager, as well as the following.

> Virtual Event | Actual Event | Action
> --- | --- | ---
> BSelect Press | None<Btn1>Press | extend-start()
> BDrag Press | None<Btn2>Press | extend-start()
> BSelect Motion | None<Btn1>Motion | extend-adjust()
> BDrag Motion | None<Btn2>Motion | extend-adjust()
> BSelect Release | None<Btn1>Release | extend-end()
> BDrag Release | None<Btn1>Release | extend-end()
> Motion | Motion | track-motion()
> KHelp | None<Key>osfHelp | ManagerGadgetHelp()
> KPageUp | None<Key>osfPageUp | page-up-or-left(0)
> KPageDown | None<Key>osfPageDown | page-down-or-right(0)
> KPageLeft | !Ctrl<Key>osfPageUp | page-up-or-left(1)
> KPageRight | !Ctrl<Key>osfPageDown | page-down-or-right(1)
> KUp | None<Key>osfUp | increment-up-or-left(0)
> KDown | None<Key>osfDown | increment-down-or-right(0)
> KLeft | None<Key>osfLeft | increment-up-or-left(1)
> KRight | None<Key>osfRight | increment-down-or-right(1)
> KBeginData | !Ctrl<Key>osfBeginLine | top-or-bottom(0)
> KEndData | !Ctrl<Key>osfEndLine | top-or-bottom(1)
> Press | <Key>Press | process-html-input()
> Release | <Key>Release | process-html-input()

> These translations mask off any key and button modifiers (except where noted otherwise), and as such application programmers can use any modifiers on the events shown above for their own purposes.

### Action Routines

> XmHTML defines the following action routines:
> extend-adjust()
>   Selects text that is between the pointer anchor and the current pointer location, while deselecting text that is outside this area. As a result of this action, when the pointer moves past lines of text, these lines are selected and the current line is selected up to the position of the pointer.

> extend-end()
>   Ends the selection performed by extend-adjust. When the current selection is an exclusive HTML anchor, this action routine also invokes the list of callbacks specified by XmNactivateCallback.

> extend-start()
>   Invalidates any previous selection, sets the pointer anchor and prepares for selecting text via the extend-adjust action. This action routine invokes the list of callbacks specified by XmNarmCallback.

> increment-up-or-left(flag)
>   Moves the visible area by one increment - upward if flag is 0; to the left if flag is 1.

> increment-down-or-right(flag)
>   Moves the visible area by one increment - downward if flag is 0; to the right if flag is 1.

> page-up-or-left(flag)
>   Moves the visible area by one page - upward if flag is 0; to the left if flag is 1.

> page-down-or-right(flag)
>   Moves the visible area by one page - downward if flag is 0; to the right if flag is 1.

> process-html-input()
>   This action routine processes all remaining keyboard events and invokes the list of callbacks specified by XmNinputCallback.

> top-or-bottom(flag)
>   Moves the visible area - to the top of the text if flag is 0; to the bottom of the text if flag is 1.

> track-motion
>   This action routine processes any pointer movement events. When pointer movement takes place over a HTML anchor, the list of callbacks specified by XmNanchorTrackCallback is invoked, otherwise it invokes the list of callbacks specified by XmNmotionTrackCallback.

### Additional Behavior

> XmHTML has additional behavior associated with <Leave> and <FocusOut> which invokes the list of callbacks specified by XmNanchorTrackCallback. Also, XmHTML attaches Manager's ManagerGadgetHelp() action routine to the workWindow.

### See Also

> Core(3X), Composite(3X), Constraint(3X), Manager(3X),

XmHTML, September 1, 1998