DESCRIPTION

The display widget uses different resources to control the appearance and behavior of the widget.  It has access to the resources listed in the following table.  You cannot redefine these resources. The codes in the Access column indicate if the resource can be set at creation time (C) , set by using XtSetValues (S) , or retrieved by using XtGetValues (G). 

The display widget is a subclass of the XmScrolledWindow resource, which means that, in addition to the preceding resources, most of the resources for scrolled windows are applicable.  Upon creation, the display widget also creates two scrollbars and a drawing area, which are accessible by using the XmNverticalScrollBar, XmNhorizontalScrollBar and XmNworkWindow resources.  For information on using these resources, see the OSF/Motif Programmer’s Reference Guide. 

The following four resources control the clip rectangle.  The clip rectangle is in image coordinates which correspond to an unscaled, unrotated image.  These values may change when IvwSetZoomRegion() is called, IvwNpixelToPixel() is changed, or the widget is resized with IvwNresizeMode = IvwDO_NOT_RESCALE. 

IvwNclipRectX
is the X cordinate of the upper left corner of the clip rectangle.

IvwNclipRectY
is the Y cordinate of the upper left corner of the clip rectangle.

IvwNclipRectH
is the height in pixels of the clip rectangle

IvwNclipRectW
is the width in pixels of the clip rectangle

The following resources should only be used when the display area (a Drawing Area widget) is using a different visual from the rest of the application.  An example of this is displaying a 24-bit image.  It is useful for the application to use the default (8 bit) visual, and have only the display area use the 24 bit visual. 

IvwNdispColormap
is the colormap used by the display area.

IvwNdispDepth
is the depth (in bits) of the display area.

IvwNdispVisual
is the visual used by the display area.

The following resources control the scale of the image. 

IvwNscaleFactor
is the current overall scale factor for the image. Changing the value of this resource will cause a redispay, assuming a positive scale factor was specified.  This resource may be changed by resizing the widget, if IvwNresizeMode = IvwFIT_TO_WINDOW.  It may also change when a new image is specified.  The default value will be as close to 1.0 as possible and still fit the entire image in the area allowed by IvwNmaxHeight and IvwNmaxWidth. 

To set this resource you must cast the variable containing the desired scale factor as follows:

XtSetArg(args[n], IvwNscaleFactor *(int*)&scale);

This code is necessary to copy the exact floating point bit string into the integer args[n].value. 

IvwNscaleYRatio
is the ratio between the X scale factor and the Y scale factor.

This allows an image to have rectangular pixels.  A value of greater than 1.0 means the pixels are higher than wide.  A value between 0.0 and 1.0 means the pixels are wider than high. 

This resource does not change when the widget is resized.  It may change when a new image is specified, since it looks at the X and Y resolutions in the image header.  If an internal image is specified, IvwNscaleYRatio will default to 1.0. 

To set this resource you must cast the variable containing the desired ratio as follows:

XtSetArg(args[n], IvwNscaleYRatio *(int*)&ratio);

This code is necessary to copy the exact floating point bit string into the integer args[n].value. 

IvwNpixelToPixel
causes each pixel in the image to be displayed as exactly one pixel in the display area.  Changing the value of this resource causes a redisplay.  Setting this resource to TRUE causes IvwNscaleFactor to be set to 1.0 and IvwNscaleYRatio to be ignored.  Setting it to FALSE will leave IvwNscaleFactor unchanged, but cause IvwNscaleYRatio to be taken into account again. 

This resource may change value when a new page or image is specified.  Unless otherwise ordered, the display widget initially tries to display the image so that each image pixel is mapped to one pixel on the screen.  If the image is too big to fit on the screen, or the X and Y resolutions are not equal, or scale factors are specifically set, then IvwNpixelToPixel becomes FALSE. 

IvwNresizeMode
defines what action to take when the display area is resized as follows:

IvwFIT_TO_WINDOW keeps the clip region (the visible portion of the image) unchanged, but modifies the scale factor ( IvwNscaleFactor ) so that the same portion of the image fills the display area. 

IvwDO_NOT_RESCALE
keeps the scale factors unchanged but modifies the clip region, so that a larger or smaller portion of the image is visible.

The following resources determine whether or not the widget is automatically scaled down to fit into a particular space.  If the image is smaller than the width and height supplied, it is displayed at a scale factor of 1.0.  Changing these values may cause a redisplay if they are set smaller than the current size of the display area. 

IvwNdispMaxHeight
is the maximum height for the display area.

IvwNdispMaxWidth
is the maximum width for the display area.

The following resources control the source of the image.  Only one of these resources are in effect at a time, as determined by IvwNimageSource.  Changing this resource will cause a redisplay, and may change IvwNscaleFactor, IvwNscaleYRatio, IvwNpixelToPixel and IvwNdisplayPage. 

IvwNimageSource
defines whether the image is from a disk file or an internal image in memory.  The choices are IvwFILENAME and IvwINTERNAL_IMAGE. 

IvwNimageFile
is the file name of the image to be displayed.

IvwNimagePtr is a pointer to an internal image, an image only in memory. 

The following resources control the zoom region. 

IvwNregionDef
is TRUE if a box defining a region is currently visible; it is FALSE if it is not visible.

IvwNregionEnabled
determines if a region can be selected by using the mouse.  If TRUE (on), clicking the left most mouse button while the cursor is in the display area causes a rubber-banded region to be defined.

IvwNregionH is the height in pixels of the selected region. 

IvwNregionW is the width in pixels of the selected region. 

IvwNregionX is the X coordinate of the upper left corner of the selected region. 

IvwNregionY is the Y coordinate of the upper left corner of the selected region. 

IvwGetRegion is a convenience function that obtains all five of these resources at once.  Any time a redisplay of the image is performed, the region is erased and the resource IvwNregionDef is set to FALSE. 

The following resources control the pages in the file. 

IvwNnumPages is the number of pages in the currently displayed file.  This value can only be changed by loading in a new file (or internal image) to be displayed. 

IvwNdisplayPage
is the page currently displayed.  Changing the value of this resource will cause a redisplay, assuming that the page number is valid and not equal to the current value.  This resource is set to 1 whenever a new image is specified via IvwNimageFile or IvwNimagePtr. 

The following resources provide various useful capabalities. 

IvwNscrollbarVis
is set to TRUE if you want the scroll bars to be visible for the life of the widget.  This resource can only be set at widget creation.  Thereafter, any changes are ignored.

IvwNwholeImage
shows whether or not the entire image is visible in the displayed area.  Basically, this resource is TRUE if the crop area is the same size as the image.  It does not reflect whether or not the display area is hidden by some other window.

IvwNerrorCallback
specifies the list of callbacks to call when an error condition occurs within the display widget.  Error conditions can happen on creation, when values of resources are changed via XtSetValues, or as the result of a window expose or resize event.  The error condition, severity (whether it is fatal or not) and any internal Image Library information are passed to the callback list via the error IvwErrorCallbackStruct data structure. 

If the application needs to access the display area directly, the widget ID can be obtained by using the XmNworkWIndow resource, then the associated display or window can be accessed by using XtDisplay(widget_id) or XtWindow(widget_id).  The associated graphics context can be obtained by using the XtGetGC() call. 

AUTHOR

IvwResources was developed by HP. 

SEE ALSO

IvwGetRegion(3X), IvwSetZoomRegion(3X), IvwCreateDisplay(3X), IvwErrorCallback(5). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995