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),