### Name

> XmHTML - The XmHTML Widget Class

### Synopsis

> #include <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
> XmNdecodeGIFProc | XmCDecodeGIFProc | XmImageGifProc | NULL | CSG
> XmNenableBadHTMLWarnings | XmCBoolean | Boolean | True | CSG
> XmNenableBodyColors | XmCBoolean | Boolean | True | CSG
> XmNenableBodyImages | XmCBoolean | Boolean | True | CSG
> XmNenableDocumentColors | XmCBoolean | Boolean | True | CSG
> XmNenableDocumentFonts | XmCBoolean | Boolean | True | CSG
> XmNenableOutlining | XmCBoolean | Boolean | False | 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
> 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
> XmNstrictHTMLChecking | XmCBoolean | Boolean | False | CSG
> XmNStringDirection | XmCStringDirection | unsigned char | XmSTRING_DIRECTION_L_TO_R | CSG
> XmNtopLine | XmCTopLine | int | 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 two arguments to this procedure: the widget id and the name of the anchor. 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.

> 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
>   When True (default), a XmHTML Widget will generate warnings for every HTML3.2 violation it encounters in a newly loaded document.

> 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.

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

> 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.

> 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 two arguments: the widget ID of the XmHTML widget and the URL where the image can be obtained. 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 */

> 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.

> 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
> 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.

> 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                */
>     }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 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.

> #### 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;
>     }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;

> #### 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, October 7, 1997