XmHTML Programmers Manual: XmHTMLImageDefaultProc
Author: Koen D'Hondt

### 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:

> - the image to be decoded is of an unsupported type;
> - the file argument is NULL;
> - the file argument represents a file that could not be found or accessed.

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