CEventHandler Class Reference

Search Toolkit Book for CEventHandler

#include <event_handler.hpp>

Inheritance diagram for CEventHandler:

Inheritance graph
[legend]
Collaboration diagram for CEventHandler:

Collaboration graph
[legend]
List of all members.

Detailed Description

CEventHandler.

CEventHandler provides basic support for event handling. Event handling includes processing events and dispatching events. Processing involves recognizing an event of the particular type and invoking a corresponding callback. CEventHandler provide support for mapping events to callback by means of Event Maps (see macros in this file). A class can define its own Event Map that can be inherited from the Event map of the base class. Dispatching is a process of forwarding an event to other CEventHandler-s subscribed as listeners to the current handler. Dispatching algorithm can be controlled by specifying a strategy (EDispatch enumeration). All events are dispatched within pools. Pools are isolated networks of listeners subscribed to each other. An event sent to a pool will reach only listeners added to this particular pool, all other listeners will be ignored. CEventHandler has several entry points: OnEvent() – processes an event, locates a callback corresponding to it and executes the callback. Dispatch() – dispatches an event to listeners. Send() – synchronously handles events by calling OnEvent() and Dispatch(). Post() – posts an event to the event queue. Events are retrieved from the queue by HandlePostRequest() and then sent to the handler.

Definition at line 194 of file event_handler.hpp.

Public Types

typedef vector< CEventHandler * > TListeners
typedef map< int, TListeners > TPools
typedef list< SPostRequest * > TPostRequests
typedef hash_map< CEventHandler *,
int > 		THandlerToCount
typedef void(* FOnPostCallback )()
enum  EDispatch { eDispatch_SelfOnly, eDispatch_AllHandlers, eDispatch_FirstHandler, eDispatch_Default = eDispatch_AllHandlers }
 enum controlling dispatching strategies More...
enum  EPoolName {
  ePool_Default = 0, ePool_Parent, ePool_Child, ePool_Sibling,
  ePool_NextAvailable
}
 Identifiers for standard pools. More...

Public Member Functions

 CEventHandler ()
 CEventHandler.
virtual ~CEventHandler ()
virtual void FireEvent (CEvent *evt, EDispatch disp_how=eDispatch_Default, int pool_name=ePool_Default)
 FireEvent - depricated, TODO - remove.
Event Dispatching Interface
virtual void AddListener (CEventHandler *listener, int pool_name=ePool_Default)
 Add a listener.
virtual void RemoveListener (CEventHandler *listener)
 Remove a listener.
virtual void RemoveAllListeners (void)
virtual bool HasListener (CEventHandler *listener, int pool_name=ePool_Default) const
 returns "true" if the given listener belongs to the specified pool
virtual const TListeners * GetListeners (int pool_name=ePool_Default) const
 returns a set of listeners fro the specified pool
virtual bool OnEvent (CEvent *evt)
 Processes en event. Returns "true" if event has been processed.
virtual bool Dispatch (CEvent *evt, EDispatch disp_how=eDispatch_Default, int pool_name=ePool_Default)
 Dispatches an event to the listeners (but does not handle it).
virtual bool Send (CEvent *evt, EDispatch disp_how=eDispatch_Default, int pool_name=ePool_Default)
 Sends an event synchronously.
virtual bool Send (CEvent *evt, int pool_name)
virtual void Post (CRef< CEvent > evt, EDispatch disp_how=eDispatch_Default, int pool_name=ePool_Default)
 Handles an event asynchronously (process and/or dispatch).

Static Public Member Functions

Static API
extracts the next request from the Post Queue and sends it to the target returns true if the Queue is empty

static void SetPostCallback (FOnPostCallback callback)
static bool HandlePostRequest ()
static void ClearPostQueue ()
 erases all events from the queue
static void DestroyPostQueue ()

Protected Member Functions

virtual const SEvtMap * GetEventMap () const
virtual void x_DeclareDead ()
 Removes itself unavailable for async event delivery.
void x_AddListenerToPool (CEventHandler *listener, int pool_name)

Protected Attributes

TPools m_Pools

Static Protected Attributes

static const SEvtMap sm_EvtMap

Private Attributes

CRef< CPostQueue > m_Queue

Static Private Attributes

static const SEvtMapEntry sm_EvtMapEntries []
static FOnPostCallback sm_PostCallback = NULL
 the queue will not be destroyed until the Last handler is destroyed

Friends

class CPostQueue

Classes

class  CPostQueue
 CPostQueue - singleton queue for asynchronous events all methods are synchronized. More...
struct  SPostRequest

Member Typedef Documentation

typedef void(* CEventHandler::FOnPostCallback)()
 

Definition at line 230 of file event_handler.hpp.

typedef hash_map<CEventHandler*, int> CEventHandler::THandlerToCount
 

Definition at line 229 of file event_handler.hpp.

typedef vector<CEventHandler*> CEventHandler::TListeners
 

Definition at line 217 of file event_handler.hpp.

typedef map<int, TListeners> CEventHandler::TPools
 

Definition at line 227 of file event_handler.hpp.

typedef list<SPostRequest*> CEventHandler::TPostRequests
 

Definition at line 228 of file event_handler.hpp.

Member Enumeration Documentation

enum CEventHandler::EDispatch
 

enum controlling dispatching strategies

Enumerator:
eDispatch_SelfOnly 
eDispatch_AllHandlers  handle and do not dispatch to listeners
eDispatch_FirstHandler  dispatch to all handlers
eDispatch_Default  dispatch until handled at least by one handler

Definition at line 198 of file event_handler.hpp.

enum CEventHandler::EPoolName
 

Identifiers for standard pools.

Set of pools is extandable, programmers can define their own pools but need to make sure that pool identifiers are unique.

Enumerator:
ePool_Default 
ePool_Parent 
ePool_Child 
ePool_Sibling 
ePool_NextAvailable  this needs to be last!

Definition at line 208 of file event_handler.hpp.

Constructor & Destructor Documentation

CEventHandler::CEventHandler (   ) 
 

CEventHandler.

Definition at line 46 of file event_handler.cpp.

CEventHandler::~CEventHandler (   )  [virtual]
 

disconnect our listeners

Definition at line 51 of file event_handler.cpp.

References map_checker< Container >::end(), m_Pools, NON_CONST_ITERATE, and x_DeclareDead().

Member Function Documentation

void CEventHandler::AddListener (  CEventHandler *  listener,
int  pool_name = ePool_Default
)  [virtual]
 

Add a listener.

The listener will always be added to the default pool; the 'name' parameter may be used to indicate an additional pool to which

Definition at line 140 of file event_handler.cpp.

References _TRACE, ePool_Default, and x_AddListenerToPool().

Referenced by CGraphContainer::AddGraph(), CGBDocument::AttachView(), CAlnMultiView::CAlnMultiView(), CAlnSpanWidget::CAlnSpanWidget(), CAlnTableWidget::CAlnTableWidget(), CAlnVecRow::CAlnVecRow(), CAnnotCompareWidget::CAnnotCompareWidget(), CCrossAlnWidget::CCrossAlnWidget(), CDiagPanel::CDiagPanel(), CGBenchApp::CGBenchApp(), CHistogramDlg::CHistogramDlg(), CObjectListWidget::CObjectListWidget(), CObjectTextWidget::CObjectTextWidget(), COpenViewDlg::COpenViewDlg(), CProjectTree::CProjectTree(), CScoreDlg::CScoreDlg(), CSerialBrowser::CSerialBrowser(), CSnpTableWidget::CSnpTableWidget(), CStudyPreviewTable::CStudyPreviewTable(), CTaskManagerStatusBarGadget::CTaskManagerStatusBarGadget(), CViewAlnTable::CViewAlnTable(), CViewFeatTable::CViewFeatTable(), CViewFlatfile::CViewFlatfile(), CViewMenuDelegate::CViewMenuDelegate(), CViewTaxTree::CViewTaxTree(), CViewValidator::CViewValidator(), CGBenchGUI::Init(), CTestDispatchApp::Run(), CFrameWindow::SetClient(), CSelectionView::SetDisplayMode(), CSeqTextPane::SetWidget(), CSeqGraphicPane::SetWidget(), CHitMatrixPane::SetWidget(), CAlnMultiPane::SetWidget(), CCrossAlnPane::SetWidget(), CErrorDisplay::x_ConfigTable(), CMenuDemoApp::x_Create(), CWorkspaceWindow::x_CreateControls(), CFlatfileDisplay::x_CreateGUI(), CViewComposite::x_CreateView(), CViewComposite_CrossAln::x_CreateViews(), CGroupMapWidget::x_Init(), CGBenchToolMonitor::x_Init(), CDataMiningView::x_Init(), CErrorDisplay::x_Init(), CViewFlatfile::x_InitBar(), CWindowManager::x_InsertClient(), CColorCalcDemo::x_MakeWindow(), and CSystemView::x_RegisterMenuDelegates().

void CEventHandler::ClearPostQueue (   )  [static]
 

erases all events from the queue

Definition at line 400 of file event_handler.cpp.

References CEventHandler::CPostQueue::GetInstance().

Referenced by CGBenchApp::x_RunMessageLoop().

void CEventHandler::DestroyPostQueue (   )  [static]
 

Definition at line 407 of file event_handler.cpp.

References CEventHandler::CPostQueue::DestroyInstance().

Referenced by CGBenchApp::x_RunMessageLoop().

bool CEventHandler::Dispatch (  CEvent *  evt,
EDispatch  disp_how = eDispatch_Default,
int  pool_name = ePool_Default
)  [virtual]
 

Dispatches an event to the listeners (but does not handle it).

Returns "true" if event has been dispatched and handled by a listener.

Definition at line 285 of file event_handler.cpp.

References _ASSERT, eDispatch_AllHandlers, eDispatch_FirstHandler, eDispatch_SelfOnly, map_checker< Container >::end(), map_checker< Container >::find(), handler(), ITERATE, m_Pools, and CEvent::Visit().

Referenced by CView::BroadcastVisibleRange(), CWindowManager::Dispatch(), Dispatcher::FireEvent(), Send(), CTreeBrowser::x_OnFluEvent(), and CSequenceGotoDlg::x_OnGoto().

void CEventHandler::FireEvent (  CEvent *  evt,
EDispatch  disp_how = eDispatch_Default,
int  pool_name = ePool_Default
)  [virtual]
 

FireEvent - depricated, TODO - remove.

Definition at line 384 of file event_handler.cpp.

References LOG_POST, and Send().

Referenced by CFilterBar::x_FireFilterChanged().

const SEvtMap * CEventHandler::GetEventMap (   )  const [protected, virtual]
 

Definition at line 128 of file event_handler.cpp.

References sm_EvtMap.

Referenced by OnEvent().

const CEventHandler::TListeners * CEventHandler::GetListeners (  int  pool_name = ePool_Default  )  const [virtual]
 

returns a set of listeners fro the specified pool

Definition at line 210 of file event_handler.cpp.

References map_checker< Container >::end(), map_checker< Container >::find(), and m_Pools.

Referenced by CGuiDiagHandler::Post().

bool CEventHandler::HandlePostRequest (   )  [static]
 

Definition at line 392 of file event_handler.cpp.

References CEventHandler::CPostQueue::GetInstance().

Referenced by BOOST_AUTO_TEST_CASE(), CWorkspaceApp::Run(), CWinManagerApp::Run(), CAppJobTestApplication::Run(), s_FltkGBenchIdleFunc(), CSnpViewUI::Show(), CSeqGraphicDemoUI::Show(), CMultiDemoUI::Show(), and TestPostVersusSend().

bool CEventHandler::HasListener (  CEventHandler *  listener,
int  pool_name = ePool_Default
)  const [virtual]
 

returns "true" if the given listener belongs to the specified pool

Definition at line 196 of file event_handler.cpp.

References map_checker< Container >::end(), map_checker< Container >::find(), and m_Pools.

Referenced by CWindowManager::Dispatch(), and CViewComposite::Dispatch().

bool CEventHandler::OnEvent (  CEvent *  evt  )  [virtual]
 

Processes en event. Returns "true" if event has been processed.

Definition at line 220 of file event_handler.cpp.

References _ASSERT, CEvent::eEvent_Command, CEvent::eEvent_CommandUpdate, ERR_POST, SEvtMapEntry::evt_class, FindEventMapEntry(), CEvent::GetAttachment(), CEvent::GetEventClass(), GetEventMap(), CEvent::GetID(), CException::GetMsg(), CEvent::GetTypeInfo(), handler(), SEvtMapEntry::handler, SEvtMapEntry::id, kOnEventException, SEvtMapEntry::last_id, and CEvent::Visit().

Referenced by Send().

void CEventHandler::Post (  CRef< CEvent >  evt,
EDispatch  disp_how = eDispatch_Default,
int  pool_name = ePool_Default
)  [virtual]
 

Handles an event asynchronously (process and/or dispatch).

The event will be posted to the event queue and then Post() will return, the event will be processed at indefenite point in time after Post() returns. The event must be created on heap and managed by CRef.

Definition at line 367 of file event_handler.cpp.

References _ASSERT, CEventHandler::CPostQueue::GetInstance(), CEventHandler::SPostRequest::m_DispHow, CEventHandler::SPostRequest::m_Event, CEventHandler::SPostRequest::m_PoolName, m_Queue, and CEventHandler::SPostRequest::m_Target.

Referenced by CDataMiningView::BroadcastVisibleRange(), CWindowManager::OnContainerCommand(), CAppJobEventTranslator::OnJobProgress(), CAppJobEventTranslator::OnJobStateChanged(), CGuiDiagHandler::Post(), CWindowManager::PostDockEvent(), PostEvent(), CGBDocument::PostProjectChanged(), CGBDocument::PostViewEvent(), CPluginTaskManager::TaskStatusChanged(), TestPostVersusSend(), CFlatfileBar::x_OnAccsChange(), CFlatfileBar::x_OnConfigChange(), x_PostWMEvent(), and CEditCommand::x_SendDataChangedEvent().

void CEventHandler::RemoveAllListeners (  void   )  [virtual]
 

Definition at line 190 of file event_handler.cpp.

References map_checker< Container >::clear(), and m_Pools.

Referenced by CGBDocument::Clear(), CColorButtonPanel::~CColorButtonPanel(), CDataMiningView::~CDataMiningView(), CGradientColorPanel::~CGradientColorPanel(), CObjectListWidget::~CObjectListWidget(), and COpenViewDlg::~COpenViewDlg().

void CEventHandler::RemoveListener (  CEventHandler *  listener  )  [virtual]
 

Remove a listener.

This will remove the listener from all pools in which it exists.

Definition at line 166 of file event_handler.cpp.

References map_checker< Container >::begin(), map_checker< Container >::end(), map_checker< Container >::erase(), and m_Pools.

Referenced by CGBenchGUI::Destroy(), CGBDocument::DetachView(), CGBDocument::DetachViewer(), CFrameWindow::RemoveClient(), CGraphContainer::RemoveGraph(), CSelectionView::SetDisplayMode(), CSeqTextPane::SetWidget(), CSeqGraphicPane::SetWidget(), CHitMatrixPane::SetWidget(), CAlnMultiPane::SetWidget(), CCrossAlnPane::SetWidget(), CGBDocument::x_DetachAllViews(), CWindowManager::x_RemoveClient(), CWizardDlg::x_SetClient(), CSystemView::x_UnRegisterMenuDelegates(), CAlnMultiWidget::~CAlnMultiWidget(), CDiagPanel::~CDiagPanel(), CGBenchApp::~CGBenchApp(), CGBenchGUI::~CGBenchGUI(), CGroupMapWidget::~CGroupMapWidget(), CHistogramDlg::~CHistogramDlg(), CHomePageView::~CHomePageView(), CObjectTextWidget::~CObjectTextWidget(), CProjectTree::~CProjectTree(), CScoreDlg::~CScoreDlg(), CSeqGraphicWidget::~CSeqGraphicWidget(), CSerialBrowser::~CSerialBrowser(), CTaskManagerStatusBarGadget::~CTaskManagerStatusBarGadget(), CView::~CView(), CViewMenuDelegate::~CViewMenuDelegate(), and CWorkspaceWindow::~CWorkspaceWindow().

bool CEventHandler::Send (  CEvent *  evt,
int  pool_name
)  [virtual]
 

Definition at line 361 of file event_handler.cpp.

References eDispatch_Default, and Send().

bool CEventHandler::Send (  CEvent *  evt,
EDispatch  disp_how = eDispatch_Default,
int  pool_name = ePool_Default
)  [virtual]
 

Sends an event synchronously.

Returns "true" if event has been handled. An event that is provided as the argument can be created on heap or stack.

Definition at line 337 of file event_handler.cpp.

References _ASSERT, Dispatch(), eDispatch_AllHandlers, eDispatch_FirstHandler, eDispatch_SelfOnly, and OnEvent().

Referenced by CWindowManager::Dispatch(), FireEvent(), CViewLink::FireEvent(), CGBDocument::FireProjectChanged(), CGBDocument::FireViewEvent(), CTreeBrowser::handle(), CHitMatrixPane::HMGH_OnChanged(), CAlnMultiPane::NotifyParent(), CGlPaneWidget::NotifyVisibleRangeChanged(), CCrossAlnPane::NotifyVisibleRangeChanged(), CCommandTarget::OnCommand(), CSeqTextWidget::OnDeleteFeature(), CSeqTextWidget::OnEditFeature(), CSeqGraphicWidget::OnFlipStrands(), CCrossAlnWidget::OnScroll(), CTaxTreeBrowser::OnSelChangedEvent(), CSeqTextWidget::OnShowPopup(), CPhyloTreeWidget::OnShowPopup(), CHitMatrixWidget::OnShowPopup(), CAlnMultiWidget::OnShowPopup(), CCrossAlnWidget::OnShowPopup(), CCommandTarget::OnUpdateCommand(), CViewGraphic::OnViewSnpTable(), CErrorDisplay::PerformAction(), CGuiDiagHandler::Post(), PostEvent(), CFeatTableWidget::SelectionChanged(), CAlnSpanWidget::SelectionChanged(), CAlnTableWidget::SelectionChanged(), CFlatfileDisplay::SelectionChanged(), CAnnotCompareWidget::SelectionChanged(), Send(), IWizardClient::SendButtonEvent(), CPhyloTreeWidget::SendEditEvent(), CPhyloTreeWidget::SendSelChangedEvent(), CHitMatrixPane::SHH_OnChanged(), CCrossAlnPane::SHH_OnChanged(), CSeqTextPane::STG_OnChanged(), CPluginTaskManager::TaskStatusChanged(), TestPostVersusSend(), CSeqGraphicPane::UpdateConfig(), CColorButton::x_ClickCB(), CWindowManager::x_CloseClient(), CMapControl::x_CreatePopupMenu(), CSeqGraphicDataSource::x_ForegroundJob(), CSeqGraphicDataSource::x_ForegroundUtilJob(), CTablePanelBase::x_HandleCellClick(), CTablePanelBase::x_HandleCellPopup(), CTablePanelBase::x_HandleColHeaderClick(), CTablePanelBase::x_HandleColHeaderPopup(), CTablePanelBase::x_HandleRowHeaderClick(), CTablePanelBase::x_HandleRowHeaderPopup(), CTablePanelBase::x_HandleTablePopup(), CSeqGraphicPane::x_NotifyWidgetRangeChanged(), CSeqGraphicPane::x_NotifyWidgetSelChanged(), CAnnotCompareDS::x_OnAppJobNotification(), CTablePanelBase::x_OnCellSelect(), CFrameWindow::x_OnCloseWindow(), CObjectListTableControl::x_OnContextAction(), CFeatTableWidget::x_OnContextAction(), CTableControl::x_OnContextMenu(), CAnnotCompareWidget::x_OnDoubleClick(), CFlatfileDisplay::x_OnEditAction(), CTaxTreeBrowser::x_OnFluEventUnselected(), CCrossAlnPane::x_OnMousePush(), CSeqGraphicPane::x_OnMouseRelease(), CHitMatrixWidget::x_OnScrollX(), CSeqTextWidget::x_OnScrollY(), CHitMatrixWidget::x_OnScrollY(), CGroupMapWidget::x_OnSelectItem(), CTextEditor::x_OnShowPopupMenu(), CGBenchApp::x_RunMessageLoop(), CPluginTaskManager::x_SendTaskChangedEvent(), CWindowManager::x_UpdateListener(), and CAlnMultiWidget::x_UpdateOnSwitchMaster().

void CEventHandler::SetPostCallback (  FOnPostCallback  callback  )  [static]
 

Definition at line 416 of file event_handler.cpp.

References sm_PostCallback.

Referenced by CGBenchApp::Run().

void CEventHandler::x_AddListenerToPool (  CEventHandler *  listener,
int  pool_name
)  [protected]
 

Definition at line 154 of file event_handler.cpp.

References _ASSERT, and m_Pools.

Referenced by AddListener().

void CEventHandler::x_DeclareDead (   )  [protected, virtual]
 

Removes itself unavailable for async event delivery.

This function is called from the destructor, but derived classes may need to do it before destructor is called.

Definition at line 72 of file event_handler.cpp.

References m_Queue.

Referenced by ~CEventHandler().

Friends And Related Function Documentation

friend class CPostQueue [friend]
 

Definition at line 345 of file event_handler.hpp.

Referenced by CEventHandler::CPostQueue::GetInstance().

Member Data Documentation

TPools CEventHandler::m_Pools [protected]
 

Definition at line 313 of file event_handler.hpp.

Referenced by Dispatch(), GetListeners(), HasListener(), RemoveAllListeners(), RemoveListener(), x_AddListenerToPool(), and ~CEventHandler().

CRef<CPostQueue> CEventHandler::m_Queue [private]
 

Definition at line 348 of file event_handler.hpp.

Referenced by Post(), and x_DeclareDead().

const SEvtMap CEventHandler::sm_EvtMap [static, protected]
 

Initial value:

{
    NULL, 
    &CEventHandler::sm_EvtMapEntries[0]
}

Definition at line 303 of file event_handler.hpp.

Referenced by GetEventMap().

const SEvtMapEntry CEventHandler::sm_EvtMapEntries [static, private]
 

Initial value:

{
    {   CEvent::eEvent_Unknown, typeid(void).name(),
        CEvent::eEvent_InvalidID, CEvent::eEvent_InvalidID, 0 } 
}

Definition at line 303 of file event_handler.hpp.

CEventHandler::FOnPostCallback CEventHandler::sm_PostCallback = NULL [static, private]
 

the queue will not be destroyed until the Last handler is destroyed

Definition at line 350 of file event_handler.hpp.

Referenced by CEventHandler::CPostQueue::Post(), and SetPostCallback().

The documentation for this class was generated from the following files:
Generated on Mon Nov 23 14:00:16 2009 for NCBI C++ ToolKit by  doxygen 1.4.6
Modified on Mon Nov 23 19:55:36 2009 by modify_doxy.py rev. 173732