Using a hash as a widget state variable

The design pattern of a state variable in (procedural) IDL widget programming is used to communicate information from a widget creation routine to event handlers and other helpers. A state variable is typically implemented as a structure or as a pointer to a structure. Though both of these techniques work well, I’d like to show that a hash provides another option, one that I think is easier to use and, in my opinion, results in more elegant code. To demonstrate this technique, I’ve included below two code blocks from the program EARTH3, which I’ve used in recent Application Development with IDL I classes. EARTH3 is a simple widget program, with only a top-level base and a draw widget. It makes an interactive view of the Earth that's based on the Raven Maps One World poster. You can download the full program and its dependents from here. For now, I’d like to solely focus on its use of a hash as a state variable. Here’s the block in EARTH3 where the state variable is defined (line numbers refer to the source code downloaded from the link above):

170   state = hash()
171   state['owindow'] = owindow
172   state['oearthview'] = oearthview
173   state['oearth'] = oearth
174   state['otrack'] = trackball([xsize,ysize]/2.0, xsize/2.0)
175   state['pad'] = pad
176   state['scale'] = scale
177   widget_control, wtop, set_uvalue=state

I chose to start with an empty hash and then append items in subsequent statements. Though this is a little more verbose, I also think it’s cleaner and easier to read. The variables owindow, oearthview, etc. were defined earlier in the program. The hash keys use the variable names as a mnemonic. In line 177, the state variable is copied into the user value of the top-level base widget. Since a hash is an object, copying this reference consumes a negligible amount of memory. Now let’s look at an event handler to see how the state variable is used. Here’s the event handler for the top-level base in EARTH3:

25 pro earth3_resize_event, event
26    compile_opt idl2
27
28    ; Get the state variable from the top-level base.
29    widget_control, event.top, get_uvalue=state
30
31    ; Set new sizes for the draw widget & apply them.
32    newx = (event.x - 2*state['pad']) > 100
33    newy = (event.y - 2*state['pad']) > 100
34    wdraw = widget_info(event.top, find_by_uname='wdraw')
35    widget_control, wdraw, xsize=newx, ysize=newy
36
37    ; Reset the trackball using the current size of the draw widget.
38    state['otrack'].reset, [newx,newy]/2.0, (newx > newy)/2.0
39
40    ; Reset the aspect ratio of the view.
41    state['oearthview'].setviewvolume, state['owindow'], scale=state['scale']
42
43    ; Repaint the window.
44    state['owindow'].draw, state['oearthview']
45 end 

Event handlers are called from XMANAGER. While the only parameter that enters an event handler is the event structure, it contains the top-level base widget identifier, from which we can retrieve the reference to the state variable. This is done in line 29. The state variable is then used several times in the body of this event handler. The feature that appeals to me about using a hash as a state variable is the syntax used for accessing its contents: it’s the same syntax I used above in lines 171-176 in setting up the state variable. There’s also no confusing dereferencing operation needed when using a pointer as the state variable. Though I don’t show it here, a hash is particularly useful when an item in the state variable changes size, like, e.g., an image; there’s no double pointer deference like this: *(*pstate).image = new_image. You can also easily add and remove items from a hash. Though possible, this isn't easy to do with a structure. Using a hash as a state variable isn’t necessarily better than using a structure or a pointer to a structure. It’s merely another option, one that I find appealing. I’ll close with a gratuitous screenshot of the EARTH3 interface from the Windows side of my laptop: