Writing Xamine Restart Handlers.

SpecTcl Home  General Information User Guide Programmer's Guide Obtaining and Installing

This document describes how to detect when Xamine restarts and to execute application speficic code when that happens.

• First we provide a motivation for this capability
• Next we describe how the facility works at a high level
• Finally we describe a sample use of this facility.

Now that SpecTcl implements interfaces to the Xamine client button boxes (see Xamine client button programming), SpecTcl applications may perform application specific actions at initialization time for Xamine. If Xamine exits (either through user action or as the result of a defect), SpecTcl detects the exit and restarts a new instance of Xamine.

Without a mechanism to allow the user to detect Xamine restarts, SpecTcl applications would not be able to recreate the client button box when Xamine restarts. This would have the effect or stripping the application of some of its functionality at an unpredictable time. This is clearly undesirable.

In order to deal with this issue, SpecTcl 3.2 and later include a facility for registering one or more event handlers that will execute when SpecTcl restarts Xamine. This would allow an application to re-create any Xamine client buttons displayed when the previous instance of Xamine exited.

This section shows how to modify the sample button code in SpecTcl's interface to Xamine Client Buttons so that the button box and its button gets rebuilt whenever Xamine is restarted. Take a little time to familiarize yourself with that example.

No modifications will be needed to the CFitButton class. We will instead:

• Create an Xamine restart handler class and an object that is an instance of it.
• Have that object create the button box and the CFitButton as needed
• Ask it to create the button box and fit button object initially
• Add the object the set of handlers SpecTcl calls on Xamine restart

The definition and implementation of our restart handler is:

class CButtonBoxSetup : public CXamineEventHandler::CRestartHandler
{
private:
  CFitButton* m_pButtons;
public:
  CButtonBoxSetup() : m_pButtons(0) {}
  virtual void operator()() {
    delete m_pButtons;
    Xamine_DefineButtonBox(4,4);
    m_pButtons = new CFitButton(myApp.getXamineEvents());
  }
};

The class takes advantage of the fact that the delete statement can be given a null pointer, and that doing so is a no-op. Therefore the constructor initializes the m_pButtons member to 0 (null), so that operator() does not need to worry about whether or not the button has already been created.

The only other thing we need to do is modify CMySpecTclApp::SelectDisplayer

void 
CMySpecTclApp::SelectDisplayer(UInt_t nDisplaySize, CHistogrammer& rHistogrammer)  
{ 
  CTclGrammerApp::SelectDisplayer(nDisplaySize, rHistogrammer);


  // Hook in the button box and ensure that it gets re-hooked on exit.

  CXamineEventHandler* pEventHandler = getXamineEvents();
  CButtonBoxSetup*     pSetup        = new CButtonBoxSetup;
  pEventHandler->addRestartHandler(*pSetup);
  
  (*pSetup)();			// Get it set up the first time.

}