Fanning Software Consulting

Understanding XMANAGER Keywords

QUESTION: Ken Bowman posed this question recently on the IDL newsgroup.

I wrote a widget program that I can run simultaneously with the same program using different data, but I'm still not sure I understand the GROUP_LEADER, JUST_REG, and EVENT_PRO keywords. Can you explain them to me? For example, is GROUP_LEADER only used to handle killing a widget hierarchy containing multiple top level bases?

ANSWER: The GROUP_LEADER keyword is used to assign a "group leader" to a widget hierarchy. When the group leader "dies", then every member of the group dies (is "killed" or "destroyed") as well. Every widget program you write will probably want to be defined with a GROUP_LEADER keyword:

  PRO JUNK, GROUP_LEADER=group_leader

You don't need to check this keyword, just pass the "group_leader" variable along to the XMANAGER command, where you will use the XMANAGER GROUP_LEADER keyword to assign this variable as the group leader of the program's top-level base. If the "group_leader" variable is undefined, no matter. This is one of the rare times you don't have to check a keyword before you use it.

   XMANAGER, 'junk', tlb, GROUP_LEADER=group_leader

Now your widget program is set up to be called from within some other widget program. For example, from an event handler like this:

   PRO OTHER_PROGRAM_CALL_JUNK_EVENT, event
      Junk, Group_Leader=event.top
   END

Now, when this other program is killed, your JUNK program will be killed as well.

Ken goes on to write this:

Should I use EVENT_PRO when I create the top-level bases, or should I call XMANAGER with /JUST_REG? For consistency, why not always use EVENT_PRO when creating a TLB and then call XMANAGER without any arguments?

EVENT_PRO (or EVENT_FUNC) can be used to assign an event handler to any widget EXCEPT a widget that is being directly managed by XMANAGER. An event handler is assigned to the widget that is being directly managed by XMANAGER (for example, the widget "tlb" in the example above) by using the EVENT_HANDLER keyword to the XMANAGER command:

   XMANAGER, 'junk', tlb, EVENT_HANDLER='JUNK_EVENT', $
      GROUP_LEADER=group_leader

If this EVENT_HANDER keyword is not used, then a default event handler is assigned to the "tlb" widget by using the name the program is registered with ("junk" in this case) and appending an "_event" to the name. In other words, had I not used the EVENT_HANDLER keyword in the command above, an event handler of the same name would have still been assigned to the "tlb" widget.

If you do use EVENT_PRO to assign an event handler for a top-level base being directly managed by XMANAGER, you will find exceedingly strange things going on in your widget program, if it works at all. Believe me, you don't want to do this.

I can't think of any particular reason to use JUST_REG in a widget program. In the old days, when you couldn't get to the IDL command line when a widget program was running, and you wanted to start, say, three widget programs all at once, you might "just register" two of the programs before you actually started the third one. This way they would all be on the display and they would all be running when the last program started actively managing all of the programs that were "registered" with XMANAGER.

These days (i.e, with the introduction of IDL 5.0) I either call other widget programs (e.g. XLOADCT) from within a widget program (always making sure I set their GROUP_LEADER keyword to be my top-level base), or I make my widget programs non-blocking and just run as many as I like from the IDL command line.

(Incidentally, don't use KILL_NOTIFY with the top-level base being managed directly by XMANAGER either. Use the CLEANUP keyword with XMANAGER to assign a cleanup routine that is called when this widget dies. KILL_NOTIFY can be used if you like to assign a cleanup routine to any widget NOT being directly managed by XMANAGER.)

Google
 
Web Coyote's Guide to IDL Programming