The XOBJVIEW procedure is a utility used to quickly and easily view and manipulate IDL Object Graphics on screen. It displays given objects in an IDL widget with toolbar buttons and menus providing functionality for manipulating, printing, and exporting the resulting graphic. The mouse can be used to rotate, scale, or translate the overall model shown in a view, or to select graphic objects in a view.

This routine is written in the IDL language. Its source code can be found in the file xobjview.pro in the lib/utilities subdirectory of the IDL distribution.

Note: The XOBJVIEW_ROTATE and XOBJVIEW_WRITE_IMAGE routines associated with the XOBJVIEW utility do not provide a graphical interface themselves, but act on an existing instance of the XOBJVIEW utility.

Examples

---

See Additional Examples for more information on using XOBJVIEW.

Example 1

This example displays a simple IDLgrSurface object using XOBJVIEW:

oSurf = OBJ_NEW('IDLgrSURFACE', DIST(20))
XOBJVIEW, oSurf

Using XOBJVIEW

XOBJVIEW displays a resizeable top-level base with a menu, toolbar and draw widget, as shown in the following figure:

The XOBJVIEW Toolbar

The XOBJVIEW toolbar contains the following buttons:

Button	Tool Name	Function
	Reset	Resets the display to its original position, orientation, scale, and aspect ratio. Changes to the size of the XOBJVIEW window itself are not reset.
	Rotate	Click the left mouse button on the object and drag to rotate.
	Pan	Click the left mouse button on the object and drag to pan.
	Zoom	Click the left mouse button on the object and drag to zoom in or out.
	Select	Click on the object. The name of the selected object is displayed, if the object has a name, otherwise its class is displayed.

Syntax

---

XOBJVIEW, Obj [, BACKGROUND=[r, g, b]] [, /BLOCK] [, /DOUBLE_VIEW ] [, GROUP=widget_id] [, /JUST_REG] [, /MODAL] [, REFRESH=widget_id] [, RENDERER={0 | 1}] [, SCALE=value] [, STATIONARY=objref(s)] [, /TEST] [, TITLE=string] [, TLB=variable] [, XOFFSET=value] [, XSIZE=pixels] [, YOFFSET=value] [, YSIZE=pixels]

Arguments

---

Obj

A reference to an atomic graphics object, an IDLgrModel, or an array of such references. If Obj is an array, the array can contain a mixture of such references. Also, if Obj is an array, all object references in the array must be unique (i.e., no two references in the array can refer to the same object).

Obj is not destroyed when XOBJVIEW is quit or killed.

Keywords

---

BACKGROUND

Set this keyword to a three-element [r, g, b] color vector specifying the background color of the XOBJVIEW window.

BLOCK

Set this keyword to have XMANAGER block when this application is registered. By default, BLOCK is set equal to zero, providing access to the command line if active command line processing is available. Note that setting the BLOCK keyword causes all widget applications to block, not just this application. For more information, see the documentation for the NO_BLOCK keyword to XMANAGER.

Note: Only the outermost call to XMANAGER can block. Therefore, to have XOBJVIEW block, any earlier calls to XMANAGER must have been called with the NO_BLOCK keyword. See the documentation for the NO_BLOCK keyword to XMANAGER for an example.

DOUBLE_VIEW

Set this keyword to cause XOBJVIEW to set the DOUBLE property on the IDLgrView that it uses to display graphical data.

GROUP

The widget ID of the widget that calls XOBJVIEW. When this ID is specified, the death of the caller results in the death of XOBJVIEW.

JUST_REG

Set this keyword to indicate that the XOBJVIEW utility should just be registered and return immediately. This is useful to register XOBJVIEW before beginning event processing and one or more widgets requests that XMANAGER block event processing. See JUST_REG vs. NO_BLOCK for additional details.

MODAL

Set this keyword to block processing of events from other widgets until the user quits XOBJVIEW. The MODAL keyword does not require a group leader to be specified. If no group leader is specified, and the MODAL keyword is set, XOBJVIEW fabricates an invisible group leader for you.

Note: To be modal, XOBJVIEW does not require that its caller specify a group leader. This is unlike other IDL widget procedures such as XLOADCT, which, to be modal, do require that their caller specify a group leader. These other procedures were implemented this way to encourage the caller to create a modal widget that will be well-behaved with respect to layering and iconizing. (See Iconizing, Layering, and Destroying Groups of Top-Level Bases for more information.)

To provide a simple means of invoking XOBJVIEW as a modal widget in applications that contain no other widgets, XOBJVIEW can be invoked as MODAL without specifying a group leader, in which case XOBJVIEW fabricates an invisible group leader for you. For applications that contain multiple widgets, however, it is good programming practice to supply an appropriate group leader when invoking XOBJVIEW, /MODAL. As with other IDL widget procedures with names prefixed with "X", specify the group leader via the GROUP keyword.

REFRESH

Set this keyword to the widget ID of the XOBJVIEW instance to be refreshed. To retrieve the widget ID of an instance of XOBJVIEW, first call XOBJVIEW with the TLB keyword. To refresh that instance of XOBJVIEW, call XOBVIEW again and set REFRESH to the value retrieved by the TLB keyword in the earlier call to XOBJVIEW. For example, in the initial call to XOBJVIEW, use the TLB keyword as follows:

XOBJVIEW, myobj, TLB=tlb

If the properties of myobj are changed in your application or at the IDL command line, refresh the view in XOBJVIEW by calling XOBJVIEW again with the REFRESH keyword:

XOBJVIEW, REFRESH=tlb

For an example application demonstrating the use of the REFRESH keyword, see Example 3.

Note: Currently, the REFRESH keyword can only be used to refresh the object itself. All other keywords and arguments to XOBJVIEW are ignored when REFRESH is specified, therefore, properties such as the background color and scale are not affected.

RENDERER

Set this keyword to an integer value indicating which graphics renderer to use when drawing objects in the XOBJVIEW draw window. Valid values are:

• 0 = Platform native OpenGL
• 1 = IDL’s software implementation

By default, your platform’s native OpenGL implementation is used. If your platform does not have a native OpenGL implementation, IDL’s software implementation is used regardless of the value of this property. Your choice of renderer may also affect the maximum size of the XOBJVIEW draw window.

SCALE

Set this keyword to the zoom factor for the initial view. The default is 1/SQRT(3). This default value provides the largest possible view of the object, while ensuring that no portion of the object will be clipped by the XOBJVIEW window, regardless of the object’s orientation.

STATIONARY

Set this keyword to a reference to an atomic graphics object, an IDLgrModel, or an array of such references. If this keyword is an array, the array can contain a mixture of such references. Also, if this keyword is an array, all object references in the array must be unique (i.e., no two references in the array can refer to the same object). Objects passed to XOBJVIEW via this keyword will not scale, rotate, or translate in response to mouse events. Default stationary objects are two lights. These two lights are replaced if one or more lights are supplied via this keyword. Objects specified via this keyword are not destroyed by XOBJVIEW when XOBJVIEW is quit or killed.

For example, to change the default lights used by XOBJVIEW, you could specify your own lights using the STATIONARY keyword as follows:

mylight1 = OBJ_NEW('IDLgrLight', TYPE=0, $

   COLOR=[255,0,0]) ; Ambient red

mylight2 = OBJ_NEW('IDLgrLight', TYPE=2, $

   COLOR=[255,0,0], LOCATION=[2,2,5]) ; Directional red

mymodel = OBJ_NEW('IDLgrModel')

mymodel->Add, mylight1

mymodel->Add, mylight2

XOBJVIEW, /TEST, STATIONARY=mymodel

TEST

If set, the Obj argument is not required (and is ignored if provided). A blue sinusoidal surface is displayed. This allows you to test code that uses XOBJVIEW without having to create an object to display.

TITLE

Set this keyword to the string that appears in the XOBJVIEW title bar.

TLB

Set this keyword to a named variable that upon return will contain the widget ID of the top level base.

XOFFSET

The horizontal offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent.

Specifying an offset relative to a row-major or column-major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.

XSIZE

Set this keyword to the width of the drawable area in pixels. The default is 400.

YOFFSET

The vertical offset of the widget in units specified by the UNITS keyword (pixels are the default) relative to its parent. This offset is specified relative to the upper left corner of the parent widget.

Specifying an offset relative to a row-major or column-major base widget does not work because those widgets enforce their own layout policies. This keyword is primarily of use relative to a plain base widget. Note that it is best to avoid using this style of widget layout.

YSIZE

Set this keyword to the height of the drawable area in pixels. The default is 400.

Additional Examples

---

Example 2

This example displays an IDLgrModel object consisting of two separate objects:

; Create contour object:
oCont = OBJ_NEW('IDLgrContour', DIST(20), N_LEVELS=10)
; Create surface object:
oSurf = OBJ_NEW('IDLgrSurface', $
   DIST(20),INDGEN(20)+20, INDGEN(20)+20)
; Create model object:
oModel = OBJ_NEW('IDLgrModel')
; Add contour and surface objects to model:
oModel->Add, oCont
oModel->Add, oSurf
; View model:
XOBJVIEW, oModel

This code results in the following view in the XOBJVIEW widget:

Note that when you click the Select button, and then click on an object, the class of that object appears next to the Select button. If the selected object has a non-null NAME property associated with it, that string value will be displayed, otherwise the name of the selected object’s class will be displayed.

To have the class of the model to appear when you click over any object in the model, you can set the SELECT_TARGET property of the model as follows:

oModel->SetProperty, /SELECT_TARGET

Also note that it is not necessary to create a model to view more than one object using XOBJVIEW. We could view the oCont and oSurf objects created in the above example by placing them in an array as follows:

XOBJVIEW, [oCont, oSurf]

Example 3

This example demonstrates how the REFRESH keyword can be used to refresh the object displayed in an instance of XOBJVIEW.

The following lines of code would be saved in a single file, named xobjview_refresh.pro. Compile the file and enter xobjview_refresh at the IDL command line to run the code. (If you are viewing this topic in the IDL Workbench help, you can click on the two code blocks below to compile them, then enter xobjview_refresh at the IDL command line.)

PRO xobjview_refresh_event, event
   WIDGET_CONTROL, event.id, GET_UVALUE=uval
   WIDGET_CONTROL, event.top, GET_UVALUE=state
   CASE uval OF
      'red': BEGIN
          WIDGET_CONTROL, event.id, GET_VALUE=val
          state.myobj->GetProperty, COLOR=c
          state.myobj->SetProperty, COLOR=[val,c[1],c[2]]
          XOBJVIEW, REFRESH=state.tlb
          END
      'green':  BEGIN
          WIDGET_CONTROL, event.id, GET_VALUE=val
          state.myobj->GetProperty, COLOR=c
          state.myobj->SetProperty, COLOR=[c[0],val,c[2]]
          XOBJVIEW, REFRESH=state.tlb
          END
      'blue': BEGIN
          WIDGET_CONTROL, event.id, GET_VALUE=val
          state.myobj->GetProperty, COLOR=c
          state.myobj->SetProperty, COLOR=[c[0],c[1],val]
          XOBJVIEW, REFRESH=state.tlb
          END
   ENDCASE
END
PRO xobjview_refresh_cleanup, wID
   WIDGET_CONTROL, wID, GET_UVALUE=state
   OBJ_DESTROY, state.myobj
END

PRO xobjview_refresh
   base = WIDGET_BASE(/COLUMN, TITLE='Adjust Object Color', $
      XOFFSET=420, XSIZE=200, GROUP=tlb)
   myobj = OBJ_NEW('IDLgrSurface', $
      BESELJ(SHIFT(DIST(40), 20, 20) / 2,0) * 20, $
      COLOR=[255, 60, 60], STYLE=2, SHADING=1)
   XOBJVIEW, myobj, TLB=tlb, GROUP=base, BACKGROUND=[0,0,0]
   red = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, TITLE='Red', $
      UVALUE='red', VALUE=255)
   green = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, $
      TITLE='Green', UVALUE='green', VALUE=60)
   blue = WIDGET_SLIDER(base, /DRAG, MIN=0, MAX=255, $
      TITLE='Blue', UVALUE='blue', VALUE=60)
   WIDGET_CONTROL, base, /REALIZE
   state = {myobj:myobj, tlb:tlb}
   WIDGET_CONTROL, base, SET_UVALUE=state
   XMANAGER, 'xobjview_refresh', base, /NO_BLOCK, $
      CLEANUP='xobjview_refresh_cleanup'
END

Version History

---

5.3	Introduced

See Also

---

XOBJVIEW_ROTATE, XOBJVIEW_WRITE_IMAGE