Name

XmHTMLImageDefaultProc - XmHTML default image loading function

Synopsis

XmImageInfo *XmHTMLImageDefaultProc(Widget w, String file, unsigned char *buf, int size)

Description

XmHTMLImageDefaultProc is the default image loading function of a XmHTML widget. By default, this function is capable of decoding X11 bitmaps (xbm), X11 pixmaps (xpm) and GIF87a and GIF89a images and animations.

Support for JPEG, PNG and GZF images is a compile time option and as such may or may not be present in your version of the XmHTML library.

The value returned by this function is a structure containing all the information a XmHTML widget requires to create the image and can be used as the return value for the callback resource installed on the XmNimageProc resource.

w
Specifies the parent Widget ID. This must be a widget of class xmHTMLWidgetClass;
file
if size is 0, the full path of the image to be decoded. If buf and size are non-zero, the original url of the image that is to be loaded. This argument may never be NULL.
buf
preloaded image data. The size of this data is given by the size argument and is ignored if the size argument is zero.
size
size of the preloaded image data. This argument is ignored if buf is NULL.

If size and/or buf is NULL, file must represent the full location of the image that is to be decoded. If this file can not be found or accessed

To fully appreciate this function, one is advised to read the XmImageInfo(3X) manual page.

Return Value

A newly allocated XmImageInfo structure or NULL upon failure.

Common causes for failure are:

Examples

The simplest example of a function installed for the XmNimageProc resource is the following:
	XmImageInfo*
	loadImage(Widget w, String url, Dimension width, Dimension height,
		XtPointer client_data)
	{
		return(XmHTMLImageDefaultProc(w, url, NULL, 0));
	}
	
A more advanced example is:
	XmImageInfo*
	loadImage(Widget w, String url, Dimension width, Dimension height,
		XtPointer client_data)
	{
		XmImageInfo *image_info;
		unsigned char image_type = IMAGE_UNKNOWN;

		/* check if this is a local url */
		if((XmHTMLGetURLType(url)) != ANCHOR_FILE_LOCAL)
			return(NULL);

		/* it is a local file. Check if it is of a supported type */
		image_type = XmHTMLImageGetType(url, NULL, 0);

		if(image_type == IMAGE_ERROR || image_type == IMAGE_UNKNOWN)
		{
			/* an error occured or the type of this image is unsupported */
			return(NULL);
		}

		/* Load it using the default function */
		if((image_info = XmHTMLImageDefaultProc(w, url, NULL, 0)) != NULL)
		{
			/*
			 * Prevent a XmHTML widget from freeing this image immediatly.
			 * Also prevent scaling of the image (scaling images is
			 * actually a violation of the HTML standard!).
			 */
			image_info->options &= ~XmIMAGE_DEFERRED_FREE & ~XmIMAGE_ALLOW_SCALE;
			return(image_info);
		}
		return(NULL);
	}
	
A more advanced version of this function could fetch remote images, check if support for JPEG and PNG images is available before calling XmHTMLImageDefaultProc, use delayed image loading, implement a caching scheme for the returned XmImageInfo structure or add a decoder for image types unsupported by XmHTMLImageDefaultProc (this can include other types of animations as well!).

See Also

XmHTML(3X), XmImageInfo(3X), XmImageCreate(3X), XmImageCreateFromInfo(3X), XmImageDestroy(3X), XmImage(3X)

XmHTML, June 4, 1998