Scrolling Draw Widgets

Another difference between a draw widget and either a graphics window created with the WINDOW procedure or an IDLgrWindow object is that draw widgets can include scroll bars. Setting the APP_SCROLL keyword or the SCROLL keyword to the WIDGET_DRAW function causes scrollbars to be attached to the drawing widget, which allows the user to view images or graphics larger than the visible area.

Differences Between SCROLL and APP_SCROLL

The amount of memory used by a draw widget is directly related to the size of the drawable area of the widget. If a draw widget does not have scroll bars, the entire drawable area is viewable. In this case, the size of the drawable area is controlled by the XSIZE and YSIZE keywords to WIDGET_DRAW.

With the addition of scroll bars, it is possible to display an image that is larger than the viewable area (the viewport) of the draw widget. IDL provides two options for dealing with images larger than the viewport:

Create the draw widget using the SCROLL keyword. This method creates a draw widget whose drawable area is specified by the XSIZE and YSIZE keywords, and whose viewable area is specified by the X_SCROLL_SIZE and Y_SCROLL_SIZE keywords. Since the entire image is kept in memory, IDL can display the appropriate portions automatically when the scroll bars are adjusted.

Create the draw widget using the APP_SCROLL keyword. This method creates a draw widget whose drawable area is the same size as its viewable area (specified by the X_SCROLL_SIZE and Y_SCROLL_SIZE keywords), but which can be different from the virtual drawable area (specified by the XSIZE and YSIZE keywords) that is equal to the full size of the image. In this case, only the portion of the image that is currently visible in the viewport is kept in memory; the IDL programmer must use viewport events to determine when the scroll bars have been adjusted and display the appropriate portion of the full image.

The concept of a virtual drawable area allows you to display portions of very large images in a draw widget without the need for enough memory to display the entire image. The price for this facility is the need to manually handle display of the correct portion of the image in an event-handling routine.

Example Using SCROLL

The following code creates a simple scrollable draw widget and displays an image.

; Event-handler routine. Does nothing in this example.  
PRO draw_scroll_event, ev  
  
END  
  
; Widget creation routine.  
PRO draw_scroll  
  
  ; Read an image for use in the example.  
  READ_JPEG, FILEPATH('muscle.jpg', $  
    SUBDIR=['examples', 'data']), image  
  
  ; Create the base widget.  
  base = WIDGET_BASE()  
  
  ; Create the draw widget. The size of the viewport is set to  
  ; 200x200 pixels, but the size of the drawable area is  
  ; set equal to the dimensions of the image array using the  
  ; XSIZE and YSIZE keywords.  
  draw = WIDGET_DRAW(base, X_SCROLL_SIZE=200, Y_SCROLL_SIZE=200, $  
    XSIZE=(SIZE(image))[1], YSIZE=(SIZE(image))[2], /SCROLL)  
  
  ; Realize the widgets.  
  WIDGET_CONTROL, base, /REALIZE  
  
  ; Retrieve the window ID from the draw widget.  
  WIDGET_CONTROL, draw, GET_VALUE=drawID  
  
  ; Set the draw widget as the current drawable area.  
  WSET, drawID  
  
  ; Load the image.  
  TVSCL, image  
  
  ; Call XMANAGER to manage the widgets.  
  XMANAGER, 'draw_scroll', base, /NO_BLOCK  
  
END

In this example, the drawable area created for the draw widget is the full size of the displayed image. Since IDL handles the display of the image as the scroll bars are adjusted, no event-handling is necessary to update the display.

Example Using APP_SCROLL

We can easily rework the previous example to use the APP_SCROLL keyword rather than the SCROLL keyword. Using APP_SCROLL has the following consequences:

IDL no longer automatically displays the appropriate portion of the image when the scroll bars are adjusted. As a result, we must add code to our event-handling procedure to check for the viewport event and display the appropriate part of the image. Here is the new event-handler routine:

; Event-handler routine.  
PRO draw_app_scroll_event, ev  
  
  COMMON app_scr_ex, image  
  
  IF (ev.TYPE EQ 3) THEN TVSCL, image, 0-ev.X, 0-ev.Y  
  
END

First, notice that since we need access to the image array in both the widget creation routine and the event handler, we place the array in a COMMON block. This is appropriate since the image data itself is not altered by the widget application.

Second, we check the TYPE field of the event structure to see if it is equal to 3, which is the code for a viewport event. If it is, we use the values of the X and Y fields of the event structure as the Position arguments to the TVSCL routine to display the appropriate portion of the image array.

We must add the COMMON block to the widget creation routine.

We change the call to WIDGET_DRAW to include the APP_SCROLL keyword rather than the SCROLL keyword. In this context, the values of the XSIZE and YSIZE keywords are interpreted as the size of the virtual drawable area, rather than the actual drawable area.

Example Code
The modified example is included in the file draw_app_scroll.pro in the examples/doc/widgets subdirectory of the IDL distribution.

On the surface the two examples appear identical. The difference is that the example using APP_SCROLL uses only the memory necessary to create the smaller drawable area described by the size of the viewport, whereas the example using SCROLL uses the memory necessary to create the full drawable area described by the XSIZE and YSIZE keywords. While the example image is not so large that this makes much difference, if the image contained several hundred million pixels rather than a few hundred thousand, the memory saving could be significant.