NAME

     ilViewer -	interactively displays multiple	images in an X window

INHERITS FROM

     ilDisplay

HEADER FILE

     #include <il/ilViewer.h>

CLASS DESCRIPTION

     ilViewer displays multiple	images in an X window and interprets X events
     to	manipulate views of those images. An image view	can be moved within
     the window, the image can be moved	within the view	and the	size of	the
     view can be resized by wiping an edge or corner with the mouse.

     Using the mouse

     The left mouse button is normally used to select and drag views.  If the
     shift button is held down when the	left button is pressed then additional
     views can be selected.  When the pointer is near the edge of a view its
     shape will	be changed to indicate that the	left button will adjust	the
     size of that view rather than dragging it.	 Images	that are larger	than
     their view	can be roamed by dragging the image with the middle mouse
     button.  If the Alt key is	held down when then left button	is pressed
     then the view will	be dragged across a stationary image.  If the Control
     key is held down when the left button is pressed then the view is
     automatically dragged relative to the mouse position when the left	button
     was pressed.  If the Control key is held down when	the middle button is
     pressed then the image is automatically roamed relative to	the mouse
     position when the middle button was pressed.  To summarize, the mouse
     controlled	function are:

     drag image	only
	  Position the pointer on top of the view and drag the mouse with the
	  middle mouse button pressed.

     drag view and image
	  Position the pointer on top of the view but away from	the view edge
	  and drag the mouse with the left mouse button	pressed.

     drag view only
	  Position the pointer on top of the view but away from	the view edge
	  and drag the mouse with the Alt key and the left mouse button
	  pressed.

     wipe view edge
	  Position the pointer on top of the view and near a view edge or
	  corner and drag the mouse with the left mouse	button pressed.

     wipe view size
	  Press	the control key	and position the pointer on top	of the view
	  and near a view edge or corner and drag the mouse with the left
	  mouse	button pressed.	 Performs a wipeSize operation (see ilDisplay
	  man page).

     wipe view split
	  Press	the Alt	key and	position the pointer on	top of the view	and
	  near a view edge or corner and drag the mouse	with the left mouse
	  button pressed.  Performs a wipeSplit	operation (see ilDisplay man
	  page).

     select single view
	  Position the pointer on top of the view and click the	left button.

     select additional views
	  Position the pointer on top of the view, hold	down the shift key and
	  click	the left button. If the	view is	already	selected it will be
	  deselected.

     auto-drag view
	  Press	control	key and	press the left mouse button away from any view
	  edge.	The view will be dragged automatically relative	the starting
	  position.

     auto-roam image
	  Press	control	key and	press the middle mouse button. The image will
	  be roamed automatically relative the starting	position.

     When multiple views are selected the wipe and drag	operations will	apply
     to	all selected views when	any one	of them	is operated on.

     Other view	manipulations

     The selected views	can be operated	on with	the following functions:

     raise()	Pops the selected views	to the top of the view stack.

     lower()	Pushes the selected views to the bottom	of the view stack.

     center()	Centers	the selected views and their corresponding images in
		the window.  The views are resized to fill the window.

     split()	Rearranges the selected	views side by side with	the same
		portion	of each	image visible in each view.

     abut()	Rearranges the selected	views side by side with	all of the
		images aligned to same window origin.

     save()	Saves the selected view	in an image file.


     remove()	Deletes	the selected views from	the window.

     Controlling the view operators

     The display operations can	be controlled with the following functions:

     setDrag()	  Enables or disables the combined image and view drag
		  operation.

     setRoam()	  Enables or disables the image	drag or	`roam' operation.

     setWipe()	  Enables or disables the view edge wipe operation.

     setInset()	  Enables or disables the view only drag operation.

     setStop()	  Controls whether or not wipe operations stop at the edge of
		  the image.

     setAutoRecenter()
		  Enables the automatic	view recentering capability.

     inhibitAutoRecenter()
		  Disables automatic view recentering for the next redraw.

CLASS MEMBER FUNCTION SUMMARY

     Constructor

	  ilViewer(Display* xd,	Window xw, int mode = ilDefault)
	  ilViewer(Display* display, int width,	int height,
		   int attr=ilVisDoubleBuffer,
		   int minComponentSize=8, int maxComponentSize=0,
		   int mode = ilDefault,
		   long	eventMask = ExposureMask|KeyPressMask|
				    PointerMotionMask|
				    PointerMotionHintMask|ButtonPressMask|
				    ButtonReleaseMask|StructureNotifyMask)

     Event dispatch

	  void event(XEvent* event)
	  int eventLoop()
	  void addEventCallback(ilCallback* cb,	int autoDelete=FALSE)

     Event Window

	  void setEventWindow(Window eventWindow)
	  Window getEventWindow()

     Display operators



	  void raise()
	  void lower()
	  void center()
	  void abut()

     View management

	  ilStatus save(const char* name, ilAreaOption opt, iflFormat* format=NULL,
			iflFileConfig* fcfg=NULL, int append=FALSE)
	  ilStatus save(iflFileDesc& desc, ilAreaOption	opt, iflFileConfig* fcfg=NULL,
			int append=FALSE)
	  void remove()

     View selection

	  void setSelected(int flag, ilView* view=NULL)
	  int getNumSelected()
	  ilView* getSelected(int index=0)

     Cursor Management

	  ilView* getCursor(int& X, int& Y)
	  void setCursor(Cursor	cur)

     Mode control

	  void setDrag(int allow)
	  void setRoam(int allow)
	  void setWipe(int allow)
	  void setInset(int allow)
	  void setStop(int flag)
	  void setAutoRecenter(int enable)
	  void inhibitAutoRecenter()

     Selection callback	support

	  void addSelectionCallback(ilCallback*	cb, int	autoDelete=FALSE)
	  ilStatus removeSelectionCallback(ilCallback* cb)

FUNCTION DESCRIPTIONS

     ilViewer()

	  ilViewer(Display* display, int width,	int height,
		   int attr=ilVisDoubleBuffer,
		   int minComponentSize=8, int maxComponentSize=0,
		   int mode = ilDefault,
		   long	eventMask = ExposureMask|KeyPressMask|
				    PointerMotionMask|
				    PointerMotionHintMask|ButtonPressMask|
				    ButtonReleaseMask|StructureNotifyMask)

	  ilViewer(Display* xd,	Window xw, int mode = ilDefault)


	  Creates an image viewer in the X window specified by display and
	  window. If OpenGL rendering is supported by the visual associated
	  with the window, then	OpenGL is used,	otherwise X is used. The last
	  parameter, mode can be used to specify various display modes such as
	  ilDefer.

	  The second version of	the constructor	creates	an X window width
	  pixels wide, height pixels high with the attributes specified	by
	  attr,	minComponentSize and maxComponentSize for the visual class.
	  See ilXWindowImg for more information. In addition, it will select
	  the X	events passed in eventMask for input.

     abut()

	  void abut()


	  Rearranges the selected views	side by	side with all of the images
	  aligned to same window origin.

     addEventCallback()

	  void addEventCallback(ilCallback* cb,	int autoDelete=FALSE)


	  This method adds a callback that will	be triggered whenever an event
	  arrives to the viewer. Either	ilViewerEventMethodCB or
	  ilViewerEventFunctionCB can be used with addEventCallback().	The
	  callback method or function has the following	prototype:

	      func(UserArgType userArg,	XEvent*	callerArg)


	  To define and	use an event callback to a member function you might
	  do something like:

	      ...
	      ilStatus Bar::event(Foo*,	XEvent*) { ... }
	      ...
	      typedef ilViewerEventMethodCB<Bar,Foo*> EventCallback;

	      Bar bar;
	      Foo foo;
	      EventCallback eventCb(&bar, Bar::event, &foo);

	      viewer->addEventCallback(&eventCb);



     addSelectionCallback()

	  void addSelectionCallback(ilCallback*	cb, int	autoDelete=FALSE)


	  This method adds a callback that will	be triggered whenever the set
	  of selected view changes.  Either ilViewerSelectMethodCB or
	  ilViewerSelectFunctionCB can be used with addSelectionCallback().
	  The callback method or function has the following prototype:

	      func(UserArgType userArg,	ilViewer* callerArg)


	  To define and	use a selection	callback to a member function you
	  might	do something like:

	      ...
	      ilStatus Bar::select(Foo*, ilViewer*) { ... }
	      ...
	      typedef ilViewerSelectMethodCB<Bar,Foo*> SelectionCallback;

	      Bar bar;
	      Foo foo;
	      SelectionCallback	selectCb(&bar, Bar::select, &foo);

	      viewer->addSelectionCallback(&selectCb);


     center()

	  void center()


	  Centers the selected views and their corresponding images in the
	  window.  The views are resized to fill the window.

     event()

	  void event(XEvent* event)


	  Use this function to pass an X-event to the viewer.  The viewer will
	  process this event and perform any required operations based on the
	  mouse	events.	 A simple event	loop might look	like.

	      XSelectInput(dpy,	win, ExposureMask|KeyPressMask|
				     PointerMotionMask|PointerMotionHintMask|
				     ButtonPressMask|ButtonReleaseMask);
	      ilViewer viewer(dpy, win);
	      XEvent event;
	      int active = 1;

	      while (active) {
		  XNextEvent(dpy, &event);
		  switch (event.type) {
		      case DestroyNotify:
			  active = 0;
			  break;
		      default:
			  viewer.event(&event);
			  break;
		  }
	      }


     eventLoop()

	  int eventLoop()


	  This member function provides	an X event loop	for processing X
	  events. It implements	some action based on some KeyPress events and
	  calls	event()	to handle other	events.	Note that events are ignored
	  if they do not occur in the display window or	the event window. See
	  setEventWindow(). It returns True if DestroyNotify was received,
	  otherwise it returns False.

	  The Home key causes all selected views to be re-centered and resized
	  to the display window. The Up	and Down arrow keys cause the selected
	  views	to be poped to the top or pushed to the	bottom respectively.
	  The Escape key causes	the event loop to be exited.

     getCursor()

	  ilView* getCursor(int& X, int& Y)


	  Returns the current window relative mouse position, based on the
	  events passed	to event() so far.

     getEventWindow()

	  Window getEventWindow()


	  Returns the current event window. The	event window is	checked	during
	  event	handling and events received from different windows are
	  ignored. See setEventWindow().

     getNumSelected()

	  int getNumSelected()


	  Returns the number of	views currently	selected.

     getSelected()

	  ilView* getSelected(int index=0)


	  Returns the view selected view indicated by index. This value	must
	  be between 0 and getNumSelected()-1.

     inhibitAutoRecenter()

	  void inhibitAutoRecenter()


	  Temporarily inhibits the automatic recentering facility for the next
	  redraw. Following the	next redraw, this facility will	be re-enabled
	  if it	was enabled prior to this call.	A call to setAutoRecenter will
	  reset	this inhibit.

     lower()

	  void lower()


	  Pushes the selected views to the bottom of the view stack.

     raise()

	  void raise()


	  Pops the selected views to the top of	the view stack.

     remove()

	  void remove()


	  Deletes the selected views from the window.

     removeEventCallback()

	  ilStatus removeEventCallback(ilCallback* cb)


	  This method removes a	Event callback previously added	with
	  addEventCallback().

     removeSelectionCallback()


	  ilStatus removeSelectionCallback(ilCallback* cb)


	  This method removes a	selection callback previously added with
	  addSelectionCallback().

     save()

	  ilStatus save(const char* name, ilAreaOption opt,
			iflFormat* format=NULL,	iflFileConfig* fcfg=NULL,
			int append=FALSE)
	  ilStatus save(iflFileDesc& desc, ilAreaOption	opt,
			iflFileConfig* fcfg=NULL, int append=FALSE)


	  Saves	the selected view in the image file specified by name.	The
	  file format of the created file is selected by format.  The
	  attributes of	the saved file can be controlled with fcfg.  See
	  iflFileConfig(3) for more details.  If append	is TRUE, the viewed
	  image	will be	appends	to the specified image file; otherwise it will
	  overwrite it,	if it already exists.

	  The alternate	form taking a desc argument, encapsulates the name and
	  format arguments in this single argument.  See iflFileDesc(3)	for
	  more details.

     setAutoRecenter()

	  void setAutoRecenter(int enable)


	  Sets the automatic recentering facility for this viewer to enable.
	  By default, this capability is enabled.  setCursor()

	  void setCursor(Cursor	cur)


	  Sets the cursor to be	displayed over this viewer to cur. If cur is
	  None,	then the original cursor configuration will be restored.

     setDrag()

	  void setDrag(int allow)


	  If allow is TRUE the combined	image and view drag operation will be
	  enabled; otherwise it	is disabled.

     setEventWindow()



	  void setEventWindow(Window eventWindow)


	  Sets the event window	to eventWindow.	The event window is checked
	  during event handling	and events received from different windows are
	  ignored. Note	that when using	overlays, events occur in the overlay
	  window rather	than in	the main window. Therefore, it is necessary to
	  set the event	window to the overlay window for proper	event
	  handling.

     setInset()

	  void setInset(int allow)


	  If allow is TRUE the view only drag operation	will be	enabled;
	  otherwise it is disabled.

     setRoam()

	  void setRoam(int allow)


	  If allow is TRUE the image only roam operation will be enabled;
	  otherwise it is disabled.

     setSelected()

	  void setSelected(int flag, ilView* view=NULL)


	  If flag is TRUE the indicated	view will be selected; otherwise the
	  view is deselected.  If view is NULL,	then all views will be
	  affected.

     setStop()

	  void setStop(int flag)


	  If flag is TRUE then wipe operations stop at the edge	of the image;
	  otherwise they are allowed to	continue beyond	the image edge.

     setWipe()

	  void setWipe(int allow)


	  If allow is TRUE the view edge wipe operation	will be	enabled;
	  otherwise it is disabled.

INHERITED MEMBER FUNCTIONS

   Inherited from ilDisplay
     abort(), addStereoView(), addView(), addViewChangeCallback(), alignImg(),
     alignView(), calcWindowSize(), deleteView(), destroyNotify(), display(),
     enableAutoAbort(),	enableCallback(), enableFrontRedraw(),
     enableQueueing(), findEdge(), findView(), flush(),	getBackground(),
     getCallback(), getColorModel(), getColormap(), getDispOp(), getDisplay(),
     getGLXContext(), getILDisplay(), getLoc(),	getMargin(), getMouse(),
     getNumViews(), getPixel(),	getPos(), getRoamLimit(), getRoamRate(),
     getSize(),	getStatus(), getView(),	getViewIndex(),	getVisibleArea(),
     getWindow(), getXWindowImg(), isAutoAbortEnabled(), isCallbackEnabled(),
     isDefer(),	isDoubleBuffer(), isFrontRedrawEnabled(), isNop(),
     isQueueingEnabled(), isRgb(), isSelected(), isStereo(), mapTile(),
     mapXY(), moveImg(), moveView(), paint(), pop(), push(), qPaint(),
     redraw(), removeViewChangeCallback(), save(), select(), setBackground(),
     setBorderColor(), setBorderStyle(), setBorderWidth(), setBorders(),
     setCallback(), setColormap(), setDefer(), setLoc(), setMargin(),
     setMode(),	setMouse(), setNop(), setPixel(), setRoamLimit(), setStatus(),
     setVisibleArea(), setWindow(), split(), swap(), syncPaint(), unselect(),
     update(), updateWindow(), wipe(), wipeSize(), wipeSplit()

SEE ALSO

     ilDisplay,	ilXWindowImg, iflFileDesc