SpecTcl's interface to Xamine Client Buttons.

What Xamine Client buttons are

This section describes what Xamine Client buttons are, why you might want to use them and how they work at a high level. The intent is to give you the needed background to decide if you should create Xamine client buttons and, if so what it means to do so.

Before discussing Xamine Client buttons it is important to understand what is meant by Xamine. SpecTcl itself has no display component. SpecTcl merely creates histograms and makes them available to a separate program, called Xamine, that creates histogram displays.

Xamine and SpecTcl communicate in several ways:

• SpecTcl creates spectrum definitions and spectra in a shared memory region so that Xamine can quickly produce updates, list spectra and so on.
• When a user accepts a gate, Xamine uses a messages passing interface to to communicate information about the new gate to SpecTcl. SpecTcl processes these events and creates or modifies the gate in accordance with the message Xamine passed.
• When SpecTcl creates a new gate, it is passed to Xamine for display using a message passing interface.

While this division of labor allows Xamine to be a re-usable display program, it does have disadvantages. In particular, SpecTcl has no way of knowing exactly what Xamine is displaying and no direct way to prompt the user to click points into a spectrum and then get those points.

The Xamine Client Button API

The following are a set of additional Xamine client button API functions.

int Xamine_EnableButton(int r, int c);
int Xamine_DisableButton(int r, int c);
int Xamine_DeleteButton(int r, int c);
int Xamine_DeleteButtonBox();
int Xamine_InquireButton(int r, int c,
			 void  *ack);

The functions Xamine_EnableButton and Xamine_DisableButton are shortcuts for modifying the button by setting or clearing the sensitive field of the descriptor. r and c are the row and column coordinates of the button to modify.

Xamine_DeleteButton deletes a button at the button box row and column coordinates r and c.

Xamine_DeleteButtonBox destorys the button box and all buttons it contains. The client buttons will no longer be visible on the display.

Finally, Xamine_InquireButton requests information about the button at button box coordinates r and c. The ack parameters must be a pointer to storage that is at least sizeof(struct msg_InquireButtonAck). The data returned in this buffer will have the form of that structure which is:

struct msg_InquireButtonAck {	/* Button information... */
  ButtonCoordinate  size;	/* Size of the button grid... */
  Logical           valid;	/* Indicates if button queried was valid. */
  ButtonDescription button;	/* Info about the requested button */
};

Where:

Processing Xamine Button Events in SpecTcl

This section describes how to process Xamine events. This discussion will include

• Background information about SpecTcl's Xamine event processing
• A description of the SpecTcl API for hooking into button event processing
• A description of what you need to do to write code that hooks into the SpecTcl button event processing

Background on SpecTcl's Xamine Event processing

SpecTcl works with the Tcl event loop to ensure that the user interface remains lively at all times, that event analysis gets scheduled, and that external inputs get mapped to Tcl events. In this case, Xamine's gate and messages are external inputs that get mapped to a Tcl Event that, in turn is dispatched to a CXamineEventHandler object that is held in the base class of the class you define in MySpecTclApp.cpp.

The CXamineEventHandler class is described in the header XamineEventHandler.h. The key points I want to point out are:

• The member m_buttonHandlers which contains a list of objects derived from CXamineEventHandler::CButtonHandler
• The member function addButtonHandler which adds a handler object to that list.

When a button event is detected, control eventually passes to the OnButton function of the CXamineEventHandler object. During the processing of a button event, the button handlers in the m_buttonHandlers are invoked in the order in which they were registered. Each button handler is given a chance to process the button event. If a button handler returns true OnButton calls no more button handlers.

This scheme is analagous to the event processing pipeline but, instead is intended to allow you to set up button handlers that cooperate to handle all possible button events.

The SpecTcl API for hooking into button events

We have already seen that the CXamineEventHandler object maintains a list of button handlers which are called in response to button events. A button handler is an object of a class that is derived from CXamineEventHandler::CButtonHandler. CXamineEventHandler::CButtonHandler is an abstract base class whose definition is nested inside the definition of CXamineEventHandler as follows:

  class CButtonHandler {
  public:
    virtual Bool_t operator()(CButtonEvent& event) = 0;
  };

The event parameter is a reference to the massaged button event that is being processed. It's header ButtonEvent.h shows that it exports the following key member functions:

class CButtonEvent      
{
  
public:

  Int_t getId() const;              // Get button id.
  Int_t getCurrentSpectrum() const; // Get Xamine id of selected spectrum.
  Bool_t getToggleState() const;    // Get state of toggle if toggle button.
  Int_t getPromptedSpectrum() const; // Get Xamine id of spectrum selected by user
  STD(string) getm_sPromptedString() const; // Get String user typed in prompter.
  const PointArray& getPoints() const; // Get points picked by user

  PointIterator begin ();           // Iterator to first user picked point.
  PointIterator end ();             // Iterator for end of user picked points.
  UInt_t size () const;             // # of user picked points.
  const CPoint& operator[] (UInt_t nI)  const; // Index into user picked points.
 
};

Button handlers are registered by invoking:

void CXamineEventHandler::addButtonHandler(CButtonHandler& handler);

Recall that in MySpecTclApp.cpp you define a class that is derived from CTclGrammerApp adding code to member functions as needed to set up your analysis. The displayer is setup in the SelectDisplayer member function. Normally this looks like:

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

For Example:

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


  CXamineEventHandler* pEventHandler = getXamineEvents();

   // do pEventHandler->addButtonHandler calls for each handler object you want
   // to register.
   …
}

How to tie it all together

This section ties this all together by presenting code fragments that implement a button that accepts a pair of points on a 1-d spectrum and then performs a gaussian fit to the data between these points using the SpecTcl fit command.

We will start by creating a class CFitButton defined as follows:

class CFitButton : public CXamineEventHandler::CButtonHandler
{
private:
  int   m_FitButtonId;		// Ids assigned to buttons.

public:
  CFitButton(CXamineEventHandler* pHandler);
  virtual ~CFitButton();
private:
  virtual Bool_t operator()(CButtonEvent& event);

  STD(string) spectrumName(CButtonEvent& event);
  void        invokeScript(STD(string) script);

};

In this example, we are just going to show the implementations of the constructor and the function call operator (operator()). The other two member functions:

• spectrumName - returns the name of the spectrum in the button event. It does this by interacting with the event and the Histogrammer.
• invokeScript - Invokes a Tcl script.

In the constructor, we must add the button to a button box that we assume already exists, and add ourself as an event handler using the pointer to the event handler that was passed in:

CFitButton::CFitButton(CXamineEventHandler* pEventHandler) 
{
  // Generic Gauss fit button.


  m_FitButtonId          = 1;

  ButtonDescription myButton;
  myButton.button_code   = m_FitButtonId;
  strcpy(myButton.label, "Gauss Fit");
  myButton.type          = Push;
  myButton.sensitive     = T;
  myButton.prompter      = Points;
  myButton.whenavailable = In1dSpectrum;
  strcpy(myButton.promptstr, "Fit limits"); 
  myButton.spectype      = Oned;            // I think this is ignored for this prompter
  myButton.minpts        = 2;
  myButton.maxpts        = 2;               // need exactly 2 pts.

  Xamine_DefineButton(0,0, &myButton);

  pEventHandler->addButtonHandler(*this);
  

}

When a button event is triggered, we execute the following code:

Bool_t 
CFitButton::operator()(CButtonEvent& event)
{

  int buttonId = event.getId();


  if (buttonId == m_FitButtonId) {

    PointArray     pts           = event.getPoints();
    string spectrum              = spectrumName(event);

    string fitName;
    fitName       = event.getm_sPromptedString();

    // Now we can create the fit:

    char x1String[100];
    char x2String[100];

    string command = "fit ";
    command += fitName;
    command += ' ';
    command += spectrum;
    command += " ";
    
    sprintf(x1String, "%d", pts[0].X());
    sprintf(x2String, "%d", pts[1].X());

    command += x1String;
    command += ' ';
    command += x2String;
    command += " gaussian";

    invokeScript(command); 
  }
  else {
    return kfFALSE;
  }
  return kfTRUE;
}

The main point of this code is to get the information from the button event and build an appropriate SpecTcl fit command which is then executed to create the fit.

The only thing that remains is to create the button box, and create an CFitButton object in MySpecTclApp.cpp once the event handler has been set up. To do this we make SelectDisplayer look like this:

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

  CXamineEventHandler* pEventHandler = getXamineEvents();
  Xamine_DefineButtonBox(2,2);
  new CFitButton(pEventHandler);

}