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