MAN page from Mandrake Other XITE-3.3-3.i386.rpm

XIMAGE

Section: C Library Functions (3)
Updated: 16 Mar 1998
Index

NAME

ximage, ximage_init, ximageInit, ximage_layout, ximageLayout,ximage_histogram, ximage_slice, ximage_info, ximage_colorbar,ximage_mainloop,ximage_exit, ximage_display, ximage_usage_text,ximage_app_usage_text, set_init_color, set_init_ovl_color,LogPosition, LogPositionCallback, Make_label_layout,Make_command_layout, Make_prompt_layout, Make_scroll_layout,Make_menu_layout, Make_entry_layout, Add_entry_layout,Make_list_layout, Make_image_layout, add_callback_to_image,init_image_callbacks, add_to_image_callbacks,add_callback_to_image_layout, add_callback_first,add_callback_last - toolkit for creating X11 applicationsin XITE

SYNTAX

#include <xite/ximage.h>

Widget ximage_init( int* argc, char** argv,
char* classname,
String fallback_resources[], int warn );

Widget ximageInit( int* argc, char** argv,
    char* classname, XtResource* resources,
    int num_resources, XtPointer resources_result,
    XrmOptionDescRec* optionsTable,
    int num_options,
    String fallback_resources[], int warn );

Widget ximage_layout( Widget app_parent,
    IBAND band, char** wids, Widget rwids[],
    int nwids, XtCallbackProc ximage_work_fun,
    char* res_inst_name );

Widget ximageLayout( Widget app_parent,
layout *layouts, int nwids );

char *ximage_app_usage_text( char *app_usage );

char *ximage_usage_text( void );

int ximage_histogram( Widget wid,
image_disp_cb_data *cb_data );

int ximage_slice( Widget wid );

int ximage_info( Widget wid );

int ximage_colorbar( Widget wid,
image_disp_cb_data *cb_data );

void ximage_mainloop( void );

void ximage_exit( Widget wid, XtPointer str,
XtPointer dummy );

Widget ximage_display( Widget parent,
    char* resource_name, char *shell_resource_name,
    IMAGE img, int bandno, WidgetClass widgetClass,
    Visual* visual, int depth,
    menu_button buttons, ArgList args,
    Cardinal num_args, image_callbacks *callbacks );

void set_init_color( int color );

void set_init_ovl_color( int color );

void LogPosition( Widget image_wid, Widget label_wid );

void LogPositionCallback( Widget wid,
XtPointer client_data, XtPointer call_data );

layout_label Make_label_layout( layout_label lay_out,
char *type, char *resource_name,
char *shell_resource_name, Widget wid, int id );

layout_command Make_command_layout(
    layout_command lay_out, char *type,
    char *resource_name, char *shell_resource_name,
    Widget wid, int id, XtCallbackProc callback,
    XtPointer closure );

layout_prompt Make_prompt_layout( layout_prompt lay_out,
    char *type, char *resource_name,
    char *shell_resource_name, Widget wid, int id,
    XtCallbackProc callback, XtPointer closure,
    char *text );

layout_scroll Make_scroll_layout(
    layout_scroll lay_out, char *type,
    char *resource_name, char *shell_resource_name,
    Widget wid, int id, XtCallbackProc jump_callback,
    XtPointer jump_closure,
    XtCallbackProc scroll_callback,
    XtPointer scroll_closure );

layout_menu Make_menu_layout( layout_menu lay_out,
    char *type, char *resource_name,
    char *shell_resource_name, Widget wid, int id,
    int num_entries, layout_menu_entry *menu_entries );

layout_menu_entry Make_entry_layout(
    layout_menu_entry lay_out, char *resource_name,
    char *label, Widget wid, XtCallbackProc callback,
    XtPointer closure );

layout_menu_entry *Add_entry_layout(
    layout_menu lay_out, char *resource_name,
    char *label, Widget wid, XtCallbackProc callback,
    XtPointer closure );

layout_list Make_list_layout( layout_list lay_out,
    char *type, char *resource_name,
    char *shell_resource_name, Widget wid, int id,
    int num_entries, char **list_entries,
    XtCallbackProc callback, XtPointer closure );

layout_image Make_image_layout( layout_image lay_out,
    char *type, char *resource_name,
    char *shell_resource_name, Widget wid, int id,
    IMAGE img, image_callbacks *callbacks );

void add_callback_to_image_layout( layout_image lay_out,
String resource_name, XtCallbackProc callback,
XtPointer closure, Boolean first );

image_callbacks *init_image_callbacks( void );

image_callbacks *add_to_image_callbacks(
    image_callbacks *image_cbs,
    String resource_name_list,
    XtCallbackProc callback, XtPointer closure,
    Boolean first);

XtCallbackList add_callback_first(
XtCallbackList callback_list,
XtCallbackProc new_callback, XtPointer closure );

XtCallbackList add_callback_last(
XtCallbackList callback_list,
XtCallbackProc new_callback, XtPointer closure );

OVERVIEW

ximageis a toolkit for design of X11-applications in XITE,using the Imageand ImageOverlaywidgets as well as someAthena and Free Widget Foundation (FWF) widgets. This givesthe programs a common look and feel.

Prior to XITE version 3.3 the two main ximage functions wereximage_initand ximage_layout.In version 3.3 each of themgot a sibling, ximageInitand ximageLayoutrespectively.The former two provide the simplest and easiest programminginterface. The latter two provide greater flexibility and morecontrol at the cost of a somewhat more complex programminginterface.

The old functions are described before the new ones below.

See the section Compatibilitybelow for information onhow you can increase the functionality of your existingximagetoolkit based applications just by recompiling andrelinking them.

COMPATIBILITY

This section describes what changes must be made to functioncalls ximage_initand ximage_layoutfor old ximagebased applications.

ximage_init

If your application is based on XITE prior to version 3_01,add a warnargument with value zero to the function call.

Refer to the description of ximage_initbelow for moreinformation.

ximage_layout

If your application is based on XITE prior to version 3.0, addthe callback function ximage_work_fun(or whatever youcalled the function which responds to events in yourapplication) to the list of arguments in the call toximage_layout.

If your application is based on XITE prior to version 3.2,also add a NULL res_inst_nameargument at the end of theargument list in the call to ximage_layout.If you havemultiple calls to ximage_layoutin your application, thenuse a non-NULL res_inst_nameargument in every call whereyou have NULL for the parentargument, and replace the NULLparentargument by the return value from ximage_init.A non-NULL res_inst_nameargument will lead to the creationof a new window with shell resource instance name equal tores_inst_name.

Refer to the description of ximage_layoutbelow for moreinformation.

When you run your recompiled application it should look thesame as before. However, there may be some more menus or menuentries available when you press one of the mouse buttonsalong with the Shift key while the mouse pointer is inside theimage. Some of these may be familiar from the xshowXITEapplication. One of the useful entries available from theOptions menu is to log the mouse pointer position.

Try the option -layout(see below) with your recompiledapplication. This should give you a separate window for eachimage. The images can now be resized with the mouse, just likewhat has been possible in xshow.

You may also want to try the options -panelcontainerand-adjustwidthalong with -layoutto get the desired result.The -widgetsetoption can be used to choose between Athena(Xaw) and Free Widget Foundation (Xfwf) widgets if they arecreated with ximage_layoutor ximageLayout.

If you get dangling windows containing only a label or singlebuttons and you want to collect them into a larger controlpanel window, refer to the description of ximage_layoutbelow for more information.

XIMAGE_INIT

ximage_initinitializes the ximagetoolkit (the X11 toolkitis also initialized) and assigns classnameas the name ofthe application class. The X11 resource file ("app-defaults"file) has the same name as the application class.

fallback_resources

ximage_initcan handle fallback-resources. All XITEapplications should however use NULL as the value for thefallback_resourcesargument. They generally don't expect tofind "app-default" files in a standard directory, such as in/usr/lib/X11/app-defaults, and we don't want the fallbackresources to be used in this event. Resources will bespecified in files which are stored locally under the XITEhome-directory, and the XITE applications are able to findthese files. The fallback_resourcesargument is provided forthose who write their own applications which are not includedin the XITE distribution.

Resource and software version correspondence

Set warnequal to zero unless the application is included inthe XITE distribution. If warnis non-zero, ximage_initchecks that the X resource xiteResourceVersion (classXiteResourceVersion) is set equal to the XITE version. If notequal, a warning is printed. The xiteResourceVersion resourceis set in all the supplied XITE application resource files.This is to ensure correspondence between software versionand resource file version.

Window deletion

ximage_initprepares for acceptance of window deletion bythe window manager. See comment below under ximage_layout.

Visuals

ximage_inittakes care of initializing the necessaryinformation concerning the preferred/requested visual type,any other available visual types which the display and XITEcan support and corresponding XITE-initial colormaps. See alsothe description of the "-iv" option and the "imageVisualClass"application resource. For more information, refer toVisual(3).

"reduced-color" mode is chosen as default for display ofimages. This can be overridden with the Image and ImageOverlaywidget resources XtNdisplayMethod which can be set with theoption -full.See the Optionssection below.

Some options

ximage_initcan initialize popup (and menubar pulldown) menusfor the Image and ImageOverlay widgets, depending on someapplication resources and options. The default behaviour is toinitialize the Colors, OverlayColors, Tools, Options andVisuals menu (but the Visuals menu will not be able todo any work unless the -multivisualoption is used). TheOverlayColors menu will only be available, however, fromImageOverlay widgets. Refer to the Options and Resourcessections below for more information on how to control thepresence of these menus.

Action functions

ximage_initregisters three action functions with theapplication: "PopupMenu", "PopupExit" and "CloseShell". Referto the Actionssection below for a description of thesefunctions.

A few other action functions are also registered, but they arestatic (not globally available), and you don't really need toknow about them. Their tasks are to prepare the popup menusevery time they are popped up.

XIMAGEINIT

ximageInitis a new version of ximage_init(since XITEversion 3.3) with more flexibility. ximageInitis actuallycalled by ximage_init.

resources and options

Application resources can be supplied in resources,andapplication command-line options can be supplied inoptionsTable.If NULL is supplied for these arguments, thenthe ximagetoolkit will supply the application with adefault set of application resources and command-line optionsrespectively. Refer to the sections Optionsand Resourcesbelow.

If you pass along your own set of resources,resources_resultmust supply a reference to a structure forstorage of the resulting resource values. You will need tounpack and interpret this information yourself.

XIMAGE_USAGE_TEXT

ximage_usage_textreturns the standard usage text for theximagetoolkit.

XIMAGE_APP_USAGE_TEXT

ximage_app_usage_textreturns the concatenation ofapp_usage,the standard usage text for the ximagetoolkit(refer to ximage_usage_text)and the standard usage text forXITE (refer to xite_standard_options_usage_text(3)).

Use this function in a call to InitMessage(3)early in themainfunction of an application which is based on ximage.

XIMAGE_LAYOUT

ximage_layoutcreates nwidswidgets and returns a pointerto each through the rwidsarray. For a more flexiblemethod, also refer to the description of ximageLayoutbelow.

app_parent

This argument must not be NULL. It is typically the returnvalue from ximageInit.

ximage_work_fun

This is the callback function which handles howthe widgets will react to events. It is added to callbacklists for some of the widget types specified below. Refer totheir individual description for details. The function must besupplied by the application which uses the ximagetoolkit.Its prototype must be
void ximage_work_fun(Widget wid,
XtPointer client_data,
XtPointer call_data);

Unless otherwise stated, the client_dataargument to thecallback function will be a pointer to an integer whichcontains the widget number (the index into the widsarrayfor each particular widget, between 0 and nwids-1inclusive). The callback function can test this number todetermine which widget the event occured in.See the section See alsobelow for references toprogram examples on how to handle this.

The call_dataargument of the callback function is areference to a chunk with various information from the widgetreferenced by widand client_data.This information iscollected in a struct of type ImageCallbackRec,defined bythe Imagewidget. The definition is as follows
typedef struct
{
   int reason;
   XEvent *event;
   struct imagestruct *img;
   struct bandstruct *band;
   int x, y;
   ImageData data;
   pixel *pixtype;
   float zoom, magnification;
   int xpan, ypan;
} ImageCallbackRec, *ImageCallback;

reasonis one of two predefined integral constants:ACTIVATE or RESIZE.

xand yare the image coordinates where the event tookplace, if the event was one of ButtonPress, ButtonRelease,MotionNotify or Expose. In case of a different event type,xand yrefer to present cursor position.

datais a reference to the image pixel at position(x,y).

wids

widsis an array of pointers to strings. Each string is aspecification for a widget. Each widget specification isdivided into one or more fields, separated by ":". The firstfield always determines the widget class, the second fielddetermines the widget instance resource name (for use in X11resource specifications). The simplest widget specificationis

<widget_class>:<r_nam>

The widgets will be created in the order they are specifiedin the widsarray.

If a third field is present in a widget specification, itdetermines whether a widget should be displayed inside thesame window as the previous widget or be the first one in anew window. A new window will by default be launched if thethird field is non-empty, like this

<widget_class>:<r_nam>:<sh_r_nam>

sh_r_namwill be the resource instance name of the newshell widget. Whether or not a new window will be created canalso be controlled via the option -layoutand the applicationresource layout.

The widget_classfield can be chosen among

Ascii_pageClass Text. From the Athena widget set. The widget size willbe set to hold 80 by 24 characters.

AsciiClass Text. From the Athena widget set. Like "Ascii_page", butwithout the fixed size. "Ascii" should be used forsmall Text widgets, such as for small input fields. See the"Prompt" entry below for a better alternative.

CommandClass Command (from the Athena widget set) or XfwfButton (fromthe Xfwf widget set). The widget label will be set equal tor_nam.

ximage_work_funwill be installed as the XtNcallback (orXtNactivate for XfwfButton) callback function, with the widgetnumber (the index into the widsarray for this widget)supplied through the client_dataargument.

Choose between Athena and Xfwf widgets with the option-widgetsetor corresponding application resource.

ImageClass Image. Defined in XITE. In the absence ofsh_r_nama new window will as usual not be created foran Image widget, i.e. the Image widget will become a child ofa Box child of app_parent.In this case the Image may beinside the same window as buttons and other widgets. It cannot be resized with the mouse, and no menubar will be availableabove the image. With sh_r_nampresent in the widgetspecification, a separate window will be made for the image.This is the recommended usage.

As usual a separate window can be created for the image inthe absence of the sh_r_namspecification if the option-layout(or the application resource layout)is used.In this case, the shell resource name will by default beset equal to "imageShell".

The resource instance name for an Image widget is set to"image", regardless of the r_namstring.

bandmust supply the image data. By default, the display ofthe image will be in "reduced-color" mode. This can beoverridden with the option -full.

ximage_work_funis installed as the XtNcallback callbackfunction for the widget with the widget number (the index intothe widsarray for this widget) supplied through theclient_dataargument. LogPositionCallbackis also addedto the XtNcallback callback list, in front ofximage_work_fun.See the description of LogPositionCallbackbelow.

Additional callback functions may be installed after the callto ximage_layoutby calling XtAddCallback or one of thefunctions add_to_image_callbacks,add_callback_firstoradd_callback_last.They are described below.

An Image widget is actually created by the functionximage_display,which is described below.

LabelClass Label. From the Athena widget set. The widget labelwill equal r_nam.

ListClass List. From the Athena widget set. The widgetspecification should be on the following form

List:r_nam:sh_r_nam:lab1:lab2

where r_namis the resource instance name of the widgetas usual and sh_r_namis only required if the listwidget is the first one in a new window. lab1will be thelabel of the first list element, lab2the label of thesecond element etc.

If a label must contain the character ":", escape it witha backslash, like this

List:r_nam:sh_r_nam:lab1:lab\:2

If a label must contain a backslash, use the followingkind of specification

List:r_nam:sh_r_nam:lab1:l\ab2

ximage_work_funwill be installed as the XtNcallbackcallback function for the widget with the widget number (theindex into the widsarray for this widget) supplied throughthe client_dataargument.

MenuClass menuButtonWidget. From the Athena widget set. Thecorresponding string in widsshould be on the followingform

Menu:r_nam:sh_r_nam:nm1:lb1:int1:nm2:lb2:int2

where r_namis the resource instance name of the widgetas usual, sh_r_namis only required if the menubuttonwidget is the first one in a new window, nm1is theresource instance name of the first menuentry button, lb1is the visible text in the first menuentry button, and int1is the client_data returned to the menuentry button callbackfunction when this entry is selected (actually a pointer tothe integer, cast to XtPointer, is returned). int1,int2,

If a label must contain the character ":", escape it witha backslash, like this

Menu:r_nam:sh_r_nam:nm1:l\:b1:int1

If a label must contain a backslash, use the followingkind of specification

Menu:r_nam:sh_r_nam:nm1:l\b1:int1

ximage_work_funwill be installed as the XtNcallbackcallback function for the menuentry buttons. It is importantthat int1,int2etc. are not in the range zero tonwids-1, because ximage_work_funwill typically test itsclient_data arument to determine from which widget it wascalled. Integers in the range zero to nwids-1 are probablyalready used as client_data by some of the widgets specifiedin wids.

OverlayClass ImageOverlay. Defined in XITE. See the description of"Image" above.

PromptClass XfwfPrompt. From the Free Widget Foundation. It issuitable to use as an input field. It is recommended to usethis widget only for the input field itself. Any leading text(telling the user what kind of input is expected) should besupplied in a Label widget to the left of the Prompt widget.

The widget specification should be on the following form

Prompt:r_nam:sh_r_nam:text

where r_namand sh_r_namhave the usual meaningand textwill be shown initially in the Prompt widget.

ximage_work_funwill be installed as the XtNactivatecallback function for the widget with the widget number (theindex into the widsarray for this widget) supplied throughthe client_dataargument.

ScrollClass Scrollbar. From the Athena widget set.

ximage_work_funwill be installed as the XtNjumpProccallback function for the widget with the widget number (theindex into the widsarray for this widget) supplied throughthe client_dataargument. No callback function is suppliedfor the XtNscrollProc callback list.

ToggleClass Toggle (from the Athena widget set) or XfwfToggle (formthe Xfwf widget set). The widget label will equal r_nam.

ximage_work_funwill be installed as the XtNcallback (orXtNonCallback and XtNoffcallback for XfwfToggle) callbackfunction for the widget with the widget number (the index intothe widsarray for this widget) supplied through theclient_dataargument.

Choose between Athena and Xfwf widgets with the option-widgetsetor corresponding application resource.

Examples of widget specifications

A single window
String rwids[] = {
   "Label:label1",
   "Command:command1",
   "Image:image",
   "Label:label2",
   "Command:command2",
   };

Several windowsOne window for the first two widgets, one for the image andone for the remaining two widgets:
String rwids[] = {
   "Label:label1",
   "Command:command1",
   "Image:image:imageShell",
   "Label:label2:Control panel",
   "Command:command2",
   };

If several widgets are to appear inside the same window, theywill be children of a container widget which itself is thechild of a shell widget. The default widget class for thecontainer widget is Box (Athena widget). Alternatively, theclass may be forced to be Form (Athena widget), if no imagewidgets are to appear in the container, by using the option-panelcontainer(or the application resourcepanelContainer).

In the event that the container widget class is Form, thelabels, command buttons, toggle buttons etc. inside thecontainer, need resources specified for their relativeplacement (resources fromVert and fromHoriz). With a containerwidget of class Box they will be placed after each otheraccording to their order in the widsarray.

res_inst_name

If res_inst_nameis not NULL, a new popup shell will be theparent of the given widgets. This popup shell will appear as anew window. (If the number of specified widgets are zero, thewindow will not be visible on the screen).

ximage_layoutsets the windowmanager protocol for windowdeletion. Refer to the Actionssection below for informationon how to close a window upon requeste from the windowmanager.

XIMAGELAYOUT

ximageLayoutis a new version of ximage_layout(since XITEversion 3.3) with more flexibility.

The differences between ximage_layoutand ximageLayoutare:

Separate image windows

Image widgets will by default be created in separate windows.This can be overridden with the option -layout(andapplication resource layout).

Container widget class

By default the container widget is of class Form (Athenawidget). Alternatively, the class may be forced to be class Box(Athena widget) by using the option -panelcontainer(or theapplication resource panelContainer).

Multiple images

Several images can be supplied for each call to ximageLayout.

Multiple callback functions

There is no need to use one common callback functionximage_work_funfor all the widgets. Separate functionscan be installed for each widget.

Widget specifications

The widget specifications are different. This is explainedbelow.

The widget specifications are supplied in the layoutsargument. The number of widget specifications are given bynwids.

layouts

layoutsis an array of pointers to layoutreferences.Each layoutreference in the array refers to one of a setof predefined structures. There is a structure type for eachof the widget types described for the ximage_layoutfunctionabove. The details of the structures are given in thefile $XITE_HOME/include/layout.h. A number of functions havebeen defined to handle the widget-type specific structures andhide the internal definition from the programmer. Thesefunctions will be described in the following.

Make_label_layoutThis function returns a reference of type layout_labeltoa structure of type layout_label_rec.This can be used forwidgets of type "Label", "Ascii_page" and "Ascii", as definedabove in the description of function ximage_layout.The function prototype for Make_label_layoutis shown in theSyntaxsection above.

If the function argument lay_outis NULL, a new object whichcan contain "Label" layout data is created. Otherwise, the onereferenced by lay_outis used. type,resource_nameandshell_resource_nameshould be used in the same way as thefields widget_class,r_namand sh_r_namdescribed forthe ximage_layoutfunction above. widis not used. idsupplies an identification for the widget. It is not used fora "Label" widget.

Make_command_layoutThe differences from Make_label_layoutare that callbackwill be installed as a callback function, and closurewillbe the client_dataargument for the callback function.If closureis NULL, id(actually a reference to an integervariable containing the idvalue) will be passed along as theclient_dataargument.

Make_prompt_layoutThe difference from Make_command_layoutis that textis shown initially in the widget.

Make_scroll_layoutThe differences from Make_command_layoutare that twocallback functions may be specified, one for the XtNjumpProccallback list, and one for the XtNscrollProc callback list.idwill be used instead of a NULL closureargument.

Make_image_layoutThe differences from Make_label_layoutare that imgisa reference to a BIFF image and that callbacksrefers toa structure containing callback function data for an Imageor ImageOverlay widget.

To construct the callbacksargument, use the functionsadd_to_image_callbacksand/or init_image_callbacks.Prototypes for these functions are shown in the Syntaxsection above.

init_image_callbackssimply initializes an object of typeimage_callbacksand returns a reference to this object.

add_to_image_callbacksadds the function callbackwithclient_data given by closureto the callback list given byresource_name.With firstnonzero, callbackis added atthe front of the callback list, otherwise it is added at theend of the list.

Three other convenience functions are also available forhandling callback lists: add_callback_to_image_layout,add_callback_firstand add_callback_last.The latter twoare independent of the layoutdefinitions, they operatecompletely within the X Toolkit terminology.

Make_menu_layoutThe difference from Make_label_layoutare that num_entriesgives the number of menu entries and that menu_entriesisa reference to an array of pointers (of typelayout_menu_entry)to menu entry objects (of typelayout_menu_entry_rec).

To construct the menu_entriesargument, use the functionsMake_entry_layoutand/or Add_entry_layout.The functionprototypes are shown in the Syntaxsection above.

The resource_nameargument to Make_entry_layoutgives theX11 resource instance name of the menu entry widget. Iflay_outis NULL, an object of type layout_menu_entry_recwill be constructed. The other arguments should beself-explanatory.

Add_entry_layoutadds a menu entry to the menu referencedby lay_out(which must be non-NULL). The new entry isadded after any previous entries.

Make_list_layoutThe differences from Make_command_layoutare thatnum_entriesgives the number of entries in the list and thatlist_entriesis an array of strings, one for each listentry. callbackis the same for all the list entries.

For all the funtions above, the widargument will refer tothe actual widget upon return from ximageLayout.

If you need access to the various members of the layoutstructures, use the following definitions

TypeOfLayout(layout)Return type is "char *".

ResourceNameOfLayout(layout)Return type is "char *".

ShellResourceNameOfLayout(layout)Return type is "char *".

WidgetOfLayout(layout)Return type is "Widget".

IdOfLayout(layout)Return type is "int".

CallbackOfCommandLayout(layout)Return type is "XtCallbackList".

CallbackOfPromptLayout(layout)Return type is "XtCallbackList".

TextOfPromptLayout(layout)Return type is "char *".

ResourceNameOfMenuEntry(layout_menu_entry)Return type is "char *".

LabelOfMenuEntry(layout_menu_entry)Return type is "char *".

WidgetOfMenuEntry(layout_menu_entry)Return type is "Widget".

CallbackOfMenuEntry(layout_menu_entry)Return type is "XtCallbackList".

NumEntriesOfMenuLayout(layout)Return type is "int".

EntriesOfMenuLayout(layout)Return type is "layout_menu_entry *".

JumpCallbackOfScrollLayout(layout)Return type is "XtCallbackList".

ScrollCallbackOfScrollLayout(layout)Return type is "XtCallbackList".

NumEntriesOfListLayout(layout)Return type is "int".

EntriesOfListLayout(layout)Return type is "char **".

CallbackOfListLayout(layout)Return type is "XtCallbackList".

ImgOfImageLayout(layout)Return type is "IMAGE".

CallbacksOfImageLayout(layout)Return type is "image_callbacks *".

DestroyCallbackOfImageLayout(layout)Return type is "XtCallbackList".

CallbackCallbackOfImageLayout(layout)Return type is "XtCallbackList".

ResizeCallbackOfImageLayout(layout)Return type is "XtCallbackList".

DrawCallbackOfImageLayout(layout)Return type is "XtCallbackList".

RoiCallbackOfImageLayout(layout)Return type is "XtCallbackList".

XIMAGE_MAINLOOP

ximage_mainloopstarts the X11 event loop.

XIMAGE_EXIT

ximage_exitexits the application. The three arguments arenot used by the function. It used to be added to theXtNdestroyCallback callback list for every Image orImageOverlay widget created with ximage_layout,but thisis not the case any more.

XIMAGE_INFO

ximage_infoprints image widget information, specificallythe image name (title), size, start coordinates, pixel type,panning and zoom, minimum and maximum, visual class, depthand text (history) field.

The minimum and maximum may not correspond to actual extremavalues in the image. For pixeltype unsigned byte(ImageBytePixel), the minimum is assumed to be 0, the maximumto be 256, regardless of the actual values. The colormapvalues are distributed over the pixel value range given by theminimum and the maximum. An image with pixeltype unsigned bytemay thus not look identical to the same image with pixeltypereal.

XIMAGE_HISTOGRAM

ximage_histogrammakes a histogram window. A copy of thecurrent image colormap is added to the Colors colortable menuand made the current image colormap (in "reduced-color" mode).This colormap can be manipulated from the histogram window.

cb_datais a reference to an object of typeimage_disp_cb_data

typedef struct {
int index;
ximage_display_func display_func;
image_callbacks *callbacks;
} image_disp_cb_data

display_funcis the function used to send histogramtransformed images back from the histogram window. This shouldtypically be the function ximage_displaywhich is describedbelow. The type definition of ximage_display_funcis

typedef Widget (*ximage_display_func)( Widget parent,
    char *resource_name, char *shell_resource_name,
    IMAGE img, int bandno, WidgetClass widgetClass,
    Visual *visual, int depth, menu_button buttons,
    ArgList args, Cardinal num_args,
    image_callbacks *callbacks );

callbacksis a collection of callback lists for theImage and ImageOverlay widget displayed with display_func.callbacksshould be constructed with the functionsinit_image_callbacksand/or add_to_image_callbacksdescribed above.

indexis not used.

ximage_histogramcalls the xhistogramfunction. Refer toxhistogram(3)for more information.

XIMAGE_SLICE

ximage_slicemakes a color palette window. A copy of thecurrent image colormap is added to the Colors colortablemenu and made the current image colormap (in "reduced-color"mode). This colormap can be manipulated from the palette(slice) window by specifying rgb or ihs color values.

ximage_slicecalls the xslicefunction. Refer toxslice(3)for more information.

XIMAGE_COLORBAR

ximage_colorbarmakes a colorbar window for the colortablecurrently active in an image window.

XIMAGE_DISPLAY

ximage_displaycreates an Image or ImageOverlay widget(depending on widgetClass)with image contents given bythe first (or three first) band(s) in img.A new windowmay be created for the widget. See the description of theparentargument.

parentmust be non-NULL. If it refers to a shell widget,a new window will be created for the image.

resource_namegives the widget resource instance name(default "image" if the argument is NULL). We recommend thedefault value, to make it easier to write X resource files.

shell_resource_namegives the resource instance name of theancestor shell (default "imageShell" if the argument is NULL).shell_resource_nameis only used if a new window is createdfor the image.

argsmay be a list of num_argswidget resource settings.

buttonsdetermines which menus should be available from theimage widget. The menus can be reached from a menubar abovethe image (unless the menubar has been made invisible, e.g.with the use of option -mb)and as popup menus inside theimage widget. buttonsis a bitwise OR between COLORS_BUTTON,OVERLAYS_BUTTON, TOOLS_BUTTON, OPTIONS_BUTTON andVISUALS_BUTTON. The value of buttonscan be controlled viasome options, such as -colorsmenu.The necessarytranslations for popup menus are added automatically. Refer tothe Optionsand Actionssections below. A request for anOverlay menu is only honored if widgetClassrefers toimageOverlayWidgetClass.

imgspecifies the image data to be displayed. bandnospecifies the band number from imgwhich will be displayedin the Image widget.

If imghas exactly three bands, bandnois equal to one andthe -rgboptions is used (or the rgbImagesresource isset), then imgis displayed as an rgb color image where band1 represents red, band 2 represents green and band 3represents the blue component. For this to work as expected,the visual class must be selected appropriately. See thedescriptions of options -rgband -ivbelow.

bandnoequal to zero will give the default value of one.

An image will be displayed with a default monotonously risingcolormap. When only one band of an image is used in thedisplay, the default colormap is a gray-scale colormap (in"reduced-color" mode). For a three-band image the defaultcolormap is the same for all the three bands, and the imagewill appear with its expected colors (subject to theconditions of an appropriate visual class as described above).The choice of colormap can be changed with the functionset_init_color,the option -colortableor the applicationresource colorTabledescribed below. The initial colortablefor an image overlay is by default a predefined 32-elementtable. It can be overridden with the functionset_init_ovl_color,the option -overlaytableor theapplication resource overlayTabledescribed below.

If the display hardware does not have a changeable colormap,the default colormap for the display will be used to displaythe image.

callbacksis a collection of callback lists for the Imageor ImageOverlay widget. It should be constructed with thefunctions add_to_image_callbacksand/orinit_image_callbacksdescribed above.

Default value for visualis the requested/preferred visualtype, and default for depthis the depth of visual.To get the default values, use NULL and 0 respectively.The option -ivcan be used to change the requested/preferredvisual type.

argsare overridden by img(and its bands), visualanddepth.

ximage_displayis used for the Image and ImageOverlaywidgets created by ximage_layoutand ximageLayout.

The return value from ximage_displayis a reference to thecreated image widget (not its ancestor). This widget isrealized, but not popped up. It needs a call to XtPopup tobecome visible.

SET_INIT_COLOR

set_init_colorsets the colortable which will be usedwhen new images are created. By default this is a predefinedgray-scale colortable (in "reduced-color" mode). It canalso be overridden with option -colortable(or theapplication resource colorTable).

coloris an index into the list of colortables availablevia the Colors menu in the image widget.

SET_INIT_OVL_COLOR

set_init_ovl_colorsets the colortable for new imageoverlays. Default is the built-in standard 32-element table.It can also be overridden with option -overlaytable(or theapplication resource overlayTable).

coloris an index into the list of colortables availablevia the OverlayColors menu in the image widget.

LOGPOSITIONCALLBACK

This function is added at the front of the XtNcallbackcallback list of all images created with ximage_layoutorximageLayout.LogPositionCallbackmay also be added tothe callback lists of images created without the use ofximage_layoutor ximageLayout.

LogPositionCallbackwill enable the coordinates of thecursor position in an image window to be displayed. Theclient_datainput argument to the callback function mustrefer to the label widget into which the cursor position willbe written.

If the label widget referred to by the client_dataargumentof the callback function is the "label" part of an Xaw dialogwidget, then this dialog widget is assumed to be the child ofa popup shell which will be popped up/down when needed.Otherwise, it is assumed that the label widget is permanentlyvisible, and no popping up or down is handled.

call_datamust supply an ImageCallbackreference whichcontains cursor coordinates etc.

The functions on the XtNcallback list are called by the"notify" Image widget action function. The action functionsupplies the proper call_dataargument.

LOGPOSITION

Add LogPositionCallbackto the XtNcallback callback list ofwidget image_widwith client data label_wid.

OPTIONS

ximagebased programs accept all standard X Toolkit commandline options in addition to the following. They don't allapply to all the widget types supplied to ximage_layoutorximageLayout.

All the options have their X resource equivalents. This isthe reason why many of the options have two legal forms,one to give a certain effect, the other to cancel the effect.This is necessary in order to be able to override X resourcesettings. See also the section Resourcesbelow.

Unique abbreviations for the options will be accepted.

-adjustwidth

Try to automatically adjust the width of "Label", "Scroll"and "Ascii_page" widgets to match the widest widget incontainer-widgets of class Box. +adjustwidthhas the reverseeffect.

-aspect

Don't preserve image aspect ratio when resizing windows.Normally an image window will have the same width/height ratioas the image data. When a window is resized, it will be forcedto keep this ratio unchanged. If -aspectis specified, it ispossible to resize the window independently in the width andheight directions. This can also be switched on/offindividually for each image (in the Options menu).

-cl filename, -colorlist filename

The file given by filenamecontains a list of colortablefilenames which will be used instead of the default list ofcolortables. Leading "~" and environment variables infilenamewill be expanded. If not found, try to findfilenamein one of the directories listed in the environmentvariable XSHOWPATH. The colortables will be available from theColors menu of the image windows. See also option-colortable.

The default value for filenameis "xshow_colortabs".

-colmenu, -colorsmenu

Supply the Image and ImageOverlay widgets with a color menu.Default: Supply menu. The form +colmenuhas the reverseeffect.

-ct filename, -colortable filename

The file filenamecontains a colortable. Leading "~" andenvironment variables in filenamewill be expanded. If notfound, try to find filenamein one of the directories listedint the environment variable XSHOWPATH. The colortable will beavailable from the Colors menu of the image windows.

Image command-line arguments will initially be displayed withthis colortable. Default is a monotonously rising colormap,grayscale for single band image displays.

-full

Do not use "Reduced color" display of images to reduce"technicolor" problems. The default is that only 128 colorswill be used to display images with PseudoColor visuals andonly about 2 million colors will be used to display imageswith DirectColor visuals. This can be toggled individually foreach image, from the Options menu. This option directly setsthe XtNdisplayMethod Image and ImageOverlay widget resourceto one.

-ih height, -imageheight height

Height of Image and ImageOverlay widgets. -aspectcanbe useful with -ih,along with toggling the fixed aspectratio entry of the Image Options menu.

-iv VisualClassName

Use VisualClassNamefor all image windows (and certain partsof the histogram and slice application windows). Default:PseudoColor. If this is not available, try DirectColor. Ifthis also fails, try TrueColor.

Legal choices: PseudoColor, DirectColor and TrueColor. Thedepth of the visual can not be chosen. For PseudoColor, adepth of 8 is used, for DirectColor and TrueColor, a depth of24 is used. See also the menu entry in the Visualsmenu ofthe image widget, the -visualsmenu,the -multivisualandthe -rgboptions.

-iw width, -imagewidth width

Width of Image and ImageOverlay widgets. -aspectcanbe useful with -iw,along with toggling the fixed aspectratio entry of the Image Options menu.

-layout type

Determines whether images get separate windows or are includedin container widgets along with buttons etc. Default forximage_layoutis to obey the widget specifications in thewidsargument. Default for ximageLayoutis to separateimages from other widgets. typecan be one of "separate","together" or "check", where the latter means to obey thewidsargument.

-logpos

Turn log position mode on. When the cursor is moved inside animage and the Log positionoption is on, the cursorposition and pixel value are printed. Default: Off.

-mb, -menubar

Start without menubar above image windows. The menubar willbe a widget of class XfwfMenuBar.

-multivisual

Enable display of images for all available visual classes, viathe Image visuals menu. Implies -visualsmenu.

-optionsmenu

Supply the Image and ImageOverlay widgets with an optionsmenu. Default: Supply menu. The form +optionsmenuhas thereverse effect.

-ovlmenu, -overlaysmenu

Supply the ImageOverlay widgets with a color menu for imageoverlays. Default: Supply menu. The form +ovlmenuhas thereverse effect.

-ovt filename, -overlaytable filename

Similar to option -colortable,but filenamenow contains acolortable for an image overlay. It will be available from theimage widget OverlayColors menu for widgets of classImageOverlay.

Image overlay command-line arguments will initially bedisplayed with this colortable. Default is a built-in32-element table.

-panelcontainer type

Determines the widget class of container widgets which willhold buttons etc. Default for ximage_layoutis Box, forximageLayoutit is Form. typecan be "Box" or "Form"(case is not considered).

-protect

Set protectmode on. It will then not be possible to overdrawnonzero pixels in the overlay plane.

-rgb

Assume that all three-band images represent 24-bit colorimages, where the first, second and third bands represent thered, green and blue colors respectively. If a three-band imageis displayed on a 24 bitplane RGB Color screen and the -rgbswitch is specified, the program will combine the three bandsto a color image. If the image is displayed on a differentkind of screen, the three bands will be shown separately. Forthis to work, you may need to consider option -ivor theresource imageVisualClass.Default: No.

-share

Let non-image windows use the same initial colormap as imagewindows. This can reduce colormap flashing on displays witha single hardware colormap. It is especially useful in thiscase for applications which involve manipulation of a non-imagewidget with real-time image changes, such as using the sliderin the XITE applications xaddand xfilter.

Non-image windows will use a copy of the "Work-map" imagecolormap or the image colormap given by the ximage option-ct.The non-image windows colormap will not change when theimage colormap is changed via the Colors image menu.

Every ximagebased application will issue a recommendationto use this option if it determines that the option may reducecolormap flashing.

The drawback of using this option is that the colors of thenon-image windows may not be set equal to the colors requestedin the X resource file (or with X toolkit options -bg and -fg).Warnings will be issued to this effect, from the X toolkit.

This option only works when the preferred image visual classequals the default display visual class.

-toolsmenu

Supply the Image and ImageOverlay widgets with a tools menu.Default: Supply menu. The form +toolsmenuhas the reverseeffect.

-version

Print XITE version number and exit. Default: Don't.

-visualsmenu

Supply the Image and ImageOverlay widgets with a visuals menu.Default: Supply menu. The form +visualsmenuhas thereverse effect.

-widgetset name

namecan be Xaw or Xfwf. Choose between the Athena widgetsCommand and Toggle and the Xfwf widgets XfwfButton andXfwfToggle. This only affects widgets created withximage_layoutor ximageLayout.

-zoomall

Turn zoom allmode on. With this mode set, all imageswill be zoomed/panned with the same parameters.

The two following options are obsolete since XITE version3.3.

-iow width, -imageoverlaywidth width

This used to set the width of ImageOverlay widgets only.This is now handled by -iwas long as the widget resourceinstance name of the ImageOverlay widget equals "image"(the default).

-ioh height, -imageoverlayheight height

This used to set the height of ImageOverlay widgets only.This is now handled by -ihas long as the widget resourceinstance name of the ImageOverlay widget equals "image"(the default).

ACTIONS

Refer to Image(3)and ImageOverlay(3)for descriptionsof available Image and ImageOverlay widget action functions.

Applications initialized with ximage_initor ximageInithave a few additional action functions available. These are

PopupMenu

Refer to PopupMenu(3).This is added to the defaulttranslations described below.

PopupExit

Refer to PopupExit(3).This is added to the defaulttranslations described below.

CloseShell

Destroy the shell widget ancestor of a widget. This is notadded to the default translations. To close a window whenrequested by a window manager operation, add the followingtranslation to an application resource file

*TopLevelShell.baseTranslations: #override \n\
<ClientMessage>WM_PROTOCOLS: CloseShell()

DEFAULT TRANSLATIONS

Apart from the mouse button and key bindings defined by theImage(3)and ImageOverlay(3)widgets, the following areadded by the initialization functions ximage_initandximageInit.

Menues

Whether these bindings are in effect depend on the options-colmenu,-ovlmenu,-toolsmenu,-optionsmenuand-visualsmenuand the corresponding application resources.
Shift <Btn1Down>: ColorsHook()
                   PopupMenu(colorsmenu)
Shift <Btn2Down>: PopupMenu(toolsmenu)
Shift <Btn3DOwn>: OptionsHook()
                   PopupMenu(optionsmenu)
Shift Mod1 <Btn1Down>: OverlaysHook()
                        PopupMenu(overlaysmenu)
     (Overlay colortables, only for
      ImageOverlay widgets)
Shift Mod1 <Btn3Down>: VisualsHook()
                        PopupMenu(visualsmenu)

The Hook functions in the above translations take care ofadding marks to active menu entries and desensitizingillegal/irrelevant entries.

RESOURCES

ximage-based programs accept all standard X Toolkitresources. Some other common resources are mentioned below.See also the description of ximage_layoutand ximageLayoutabove.

Options take precedence over resources.

Application resources. (Application name and class is givenby the actual application which calls ximage_initorximageInit.The application name can also be changedwith the X Toolkit option -name.):

adjustWidth (Class AdjustWidth)

See option -adjustwidth.

colorList (Class ColorList)

See option -cl.

colorsMenu (Class ImageMenu)

See option -colmenu.

colorTable (Class ColorTable)

See option -ct.

imageVisualClass (Class VisualClass)

See option -iv.

layout (Class Layout)

See option -layout.

logpos (Class LogPos)

See option -logpos.

optionsMenu (Class ImageMenu)

See option -optionsmenu.

overlaysMenu (Class ImageMenu)

See option -ovlmenu.

overlayTable (Class ColorTable)

See option -overlaytable.

panelContainer (Class PanelContainer)

See option -panelcontainer.

rgbImages (Class RgbImages)

See option -rgb.

toolsMenu (Class ImageMenu)

See option -toolsmenu.

version (Class Version)

See option -version.

visualsMenu (Class ImageMenu)

See option -visualsmenu.

widgetSet (Class WidgetSet)

See option -widgetset.

xiteHelper (Class XiteHelper)

Determines which program is started when the helpbuttonis pushed. Colon-separated list of strings, started in theorder listed until one is successful.

xiteHelperOption (Class XiteHelperOption)

Options for the resource xiteHelper.

xiteResourceVersion

This resource should typically be the same as the XITE version(given in response to option -version).If the warnargument to ximage_initor ximageInitis True, the ximageapplication will check whether xiteResourceVersionis tooold for the running XITE version.

zoomAll (Class ZoomAll)

See option -zoomall.

Some of the Image widget resources:

displayMethod (Class DisplayMethod)

See option -full.

imageHeight (class ImageHeight)

See option -ih.

imageWidth (class ImageWidth)

See option -iw.

menubar (Class Menubar)

See option -mb.

protectOverlay (Class ProtectOverlay)

See option -protect.

variableAspect (Class VariableAspect)

See option -aspect.

See the section Widget hierarchyon how to specify resources.

WIDGET HIERARCHY

ximage_layout

The top of the hierarchy is always
<application name> (Class <application class>)

The second level depends on how the widgets have been created.If the application consists of a single window which containsan image as well as buttons etc., the second level will mostlikely be
topContainer (Class Box or Form) (if nwids > 1)

The class of topContainer is Box by default, but can be setto Form with option -panelcontaineror the resourcepanelContainer.

With multiple windows or if sh_r_namwas given in thewidget specification in wids,the second level will be
<sh_r_nam> (Class TopLevelShell)

The level below sh_r_namwill be
topContainer (Class Box or Form)

if at least one of the widgets "belonging" to sh_r_namis not an image. If there is only one widget which is an image,then the level will be
imageForm (Class ImageForm)

followed by
image (Class Image or ImageOverlay)

Below a "topContainer" level follows any number of widgetsaccording to the widget specifications in the widsargumentto ximage_layout(described above). The widgetspecifications give both resource instance name and class.

See the documentation for each specific application to findout which widget classes are used and the specific widgetinstance names.

ximageLayout

The hierarchy will be the same as for ximage_layout,but the widget specifications are of course not given bywids,but when creating the layoutstructures by calld toMake_label_layout,Make_image_layoutetc.

AUTHOR

Otto Milvang and Svein Bře

DOC

Svein Bře

ID

$Id: ximage.c,v 1.146 1997/08/01 09:42:56 svein Exp $

Index

NAME
SYNTAX
OVERVIEW
COMPATIBILITY
XIMAGE_INIT
XIMAGEINIT
XIMAGE_USAGE_TEXT
XIMAGE_APP_USAGE_TEXT
XIMAGE_LAYOUT
XIMAGELAYOUT
XIMAGE_MAINLOOP
XIMAGE_EXIT
XIMAGE_INFO
XIMAGE_HISTOGRAM
XIMAGE_SLICE
XIMAGE_COLORBAR
XIMAGE_DISPLAY
SET_INIT_COLOR
SET_INIT_OVL_COLOR
LOGPOSITIONCALLBACK
LOGPOSITION
OPTIONS
ACTIONS
DEFAULT TRANSLATIONS
RESOURCES
WIDGET HIERARCHY
SEE ALSO
AUTHOR
DOC
ID

This document was created byman2html,using the manual pages.