BHandler Class Reference

#include <Handler.h>

Inheritance diagram for BHandler:

List of all members.

---

Detailed Description

A BHandler object responds to messages that are handed to it by a BLooper. The BLooper tells the BHandler about a message by invoking the BHandler's MessageReceived() function.

See also:

Using BHandler

---

Hook Functions

• MessageReceived()

---

Public Member Functions
	BHandler (const char *name=NULL)
virtual	~BHandler ()
	BHandler (BMessage *data)
virtual status_t	Archive (BMessage *data, bool deep=true) const
virtual void	MessageReceived (BMessage *message)
BLooper *	Looper () const
void	SetName (const char *name)
const char *	Name () const
virtual void	SetNextHandler (BHandler *handler)
BHandler *	NextHandler () const
virtual void	AddFilter (BMessageFilter *filter)
virtual bool	RemoveFilter (BMessageFilter *filter)
virtual void	SetFilterList (BList *filters)
BList *	FilterList ()
bool	LockLooper ()
status_t	LockLooperWithTimeout (bigtime_t timeout)
void	UnlockLooper ()
virtual BHandler *	ResolveSpecifier (BMessage *msg, int32 index, BMessage *specifier, int32 form, const char *property)
virtual status_t	GetSupportedSuites (BMessage *data)
status_t	StartWatching (BMessenger, uint32 what)
status_t	StartWatchingAll (BMessenger)
status_t	StopWatching (BMessenger, uint32 what)
status_t	StopWatchingAll (BMessenger)
status_t	StartWatching (BHandler *, uint32 what)
status_t	StartWatchingAll (BHandler *)
status_t	StopWatching (BHandler *, uint32 what)
status_t	StopWatchingAll (BHandler *)
virtual status_t	Perform (perform_code d, void *arg)
virtual void	SendNotices (uint32 what, const BMessage *=0)
bool	IsWatched () const
Static Public Member Functions
static BArchivable *	Instantiate (BMessage *data)
Friends
class	BLooper
class	BMessageFilter
int32	_get_object_token_ (const BHandler *)

---

Constructor & Destructor Documentation

BHandler (  const char *  name = NULL  )

Initializes the BHandler by assigning it a name and registering it with the messaging system. Parameters: name  (default = NULL)

~BHandler (   )  [virtual]

Deletes any BMessageFilters assigned to the BHandler.

BHandler (  BMessage *  data  )

BHandlers can also be reconstructed from a BMessage archive. Parameters: data

---

Member Function Documentation

void AddFilter (  BMessageFilter *  filter  )  [virtual]

Managing a list of BMessageFilter objects associated with the BHandler. AddFilter() adds a filter to the end of the BHandler's list of filters. It creates the BList object if it doesn't already exist. By default, BHandlers don't maintain a BList of filters until one is assigned or the first BMessageFilter is added. Parameters: filter  For SetFilterList(), AddFilter(), and RemoveFilter() to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.

status_t Archive (  BMessage *  data, bool  deep = true )  const [virtual]

BHandlers can also be reconstructed from a BMessage archive. Parameters: data  Reimplemented from BArchivable. Reimplemented in BMailProtocolConfigView, BApplication, BLooper, LayoutHVGroup, LayoutManager, BSpinField, BStringView, BTextField, BDirectWindow, BAlert, BBox, BButton, BChannelControl, BChannelSlider, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BSeparator, BShelf, BSlider, BSlideRule, BSpeedButton, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, and BPrintConfigView.

BList * FilterList (   )

Managing a list of BMessageFilter objects associated with the BHandler. FilterList() returns the current list of filters. For SetFilterList(), AddFilter(), and RemoveFilter() to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.

virtual status_t GetSupportedSuites (  BMessage *  data  )  [virtual]

Reimplemented in BApplication, BLooper, BDirectWindow, BAlert, BBox, BButton, BChannelControl, BChannelSlider, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BShelf, BSlider, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, BMediaRoster, BDirectGLWindow, and BPrintConfigView.

BArchivable * Instantiate (  BMessage *  data  )  [static]

Reimplemented from BArchivable. Reimplemented in BApplication, BLooper, LayoutHVGroup, LayoutManager, BSpinField, BStringView, BTextField, BDirectWindow, BAlert, BBox, BButton, BChannelSlider, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BSeparator, BShelf, BSlider, BSlideRule, BSpeedButton, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, and BPrintConfigView.

bool IsWatched (   )  const

bool LockLooper (   )

This are a "smart" version of BLooper's locking functions (BLooper::Lock() et. al.). The difference between the versions is that these functions retrieve the handler's looper and lock it (or unlock it) in a pseudo-atomic operation, thus avoiding a race condition. Returns: LockLooper() returns true if it was able to lock the looper, or if it's already locked by the calling thread, and false otherwise. If the handler changes loopers during the call, false is returned.

status_t LockLooperWithTimeout (  bigtime_t  timeout  )

Except for an additional return value in LockLooperWithTimeout(), these functions are identical to their BLooper analogues. See to BLooper::Lock() for details. Returns: B_OK. The looper was successfully locked. B_TIMED_OUT. The call timed out without locking the looper. B_BAD_VALUE. This handler's looper is invalid. B_MISMATCHED_VALUES. The handler switched loopers during the call.

BLooper * Looper (   )  const

Returns: Returns the BLooper object that the BHandler has been added to. The function returns NULL if the object hasn't been added to a BLooper. A BHandler can be associated with only one BLooper at a time. Note that a BLooper object automatically adds itself (as a handler) to itself (as a looper), and a BWindow automatically adds its child views. To explicitly add a handler to a looper, you call BLooper::AddHandler().

void MessageReceived (  BMessage *  msg  )  [virtual]

Implemented by derived classes to respond to messages that are received by the BHandler. The default (BHandler) implementation of this function responds only to scripting requests. It passes all other messages to the next handler by calling that object's version of MessageReceived(). Reimplemented in BMailChainRunner, BMailProtocolConfigView, BApplication, BLooper, BCalendarControl, BColumnListView, DividerControl, DocApplication, DocWindow, BSpinField, BStringView, BTextField, BDirectWindow, BAlert, BBox, BButton, BChannelControl, BChannelSlider, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOptionControl, BOptionPopUp, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BSeparator, BShelf, BSlider, BStackedListView, BStackedOutlineView, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, BMediaRoster, BDirectGLWindow, BPrintConfigView, BSpyDisplayModule, BSpyDisplayView, BSpyModule, JobOptionPanel, ConfigPagePanel, ToolsPanel, OldApiPanel, PrintPanelWindow, ControlView, and BSimpleWindow.

const char * Name (   )  const

Name() returns the current name of the BHandler. The string returned by Name() belongs to the BHandler object; it shouldn't be altered or freed. The name is originally set by the constructor.

BHandler * NextHandler (   )  const

NextHandler() returns this object next handler. Returns: NULL if this object is at the end of the chain

status_t Perform (  perform_code  d, void *  arg )  [virtual]

Parameters: d  arg  Reimplemented from BArchivable. Reimplemented in BApplication, BLooper, BDirectWindow, BWindowScreen, BAlert, BBox, BButton, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BShelf, BSlider, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, BDirectGLWindow, and BPrintConfigView.

bool RemoveFilter (  BMessageFilter *  filter  )  [virtual]

Managing a list of BMessageFilter objects associated with the BHandler. RemoveFilter() removes a filter from the list without deleting it. It returns true if successful, and false if it can't find the specified filter in the list (or the list doesn't exist). It leaves the BList in place even after removing the last filter. Parameters: filter  For SetFilterList(), AddFilter(), and RemoveFilter() to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.

virtual BHandler* ResolveSpecifier (  BMessage *  msg, int32  index, BMessage *  specifier, int32  form, const char *  property )  [virtual]

Reimplemented in BApplication, BLooper, BDirectWindow, BAlert, BBox, BButton, BChannelControl, BChannelSlider, BCheckBox, BColorControl, BControl, BDragger, BListView, BMenu, BMenuBar, BMenuField, BOutlineListView, BPictureButton, BPopUpMenu, BRadioButton, BScrollBar, BScrollView, BShelf, BSlider, BStatusBar, BStringView, BTabView, BTextControl, BTextListControl, BTextView, BView, BWindow, BMediaRoster, BDirectGLWindow, and BPrintConfigView.

void SendNotices (  uint32  what, const BMessage *  = 0 )  [virtual]

void SetFilterList (  BList *  filters  )  [virtual]

Managing a list of BMessageFilter objects associated with the BHandler. SetFilterList() assigns the BHandler a new list of filters; the list must contain pointers to instances of the BMessageFilter class or to instances of classes that derive from BMessageFilter. The new list replaces any list of filters previously assigned. All objects in the previous list are deleted, as is the BList that contains them. If list is NULL, the current list is removed without a replacement. Parameters: filters  List of filters For SetFilterList(), AddFilter(), and RemoveFilter() to work, the BHandler must be assigned to a BLooper object and the BLooper must be locked.

void SetName (  const char *  name  )

SetName() assigns the BHandler a new name. The name is originally set by the constructor.

void SetNextHandler (  BHandler *  handler  )  [virtual]

SetNextHandler() reorders the objects in the handler chain so that handler follows this BHandler. This BHandler and handler must already be part of the same chain, and the BLooper they belong to must be locked. The order of objects in the handler chain affects the way in-coming messages are handled (as explained in "Inheritance and the Handler Chain". By default handlers are placed in the order that they're added (through BLooper::AddHandler()) Parameters: handler

status_t StartWatching (  BHandler *  target, uint32  what )

StartWatching() registers the BMessenger or BHandler specified by watcher to be notified whenever the state specified by what changes. Parameters: target  BHandler what  Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid. StartWatching() works by sending a message to the BHandler you want to observe, with a BMessenger back to the observer, so both must be attached to a looper at the time StartWatching() is called. Attention: The forms of StartWatching() and StartWatchingAll() that accept a BHandler can be used to observe a handler that's not yet attached to a looper. However, these only work if the observer and notifier are both in the same looper.

status_t StartWatching (  BMessenger  target, uint32  what )

StartWatching() registers the BMessenger or BHandler specified by watcher to be notified whenever the state specified by what changes. Parameters: target  BMessenger what  Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid. StartWatching() works by sending a message to the BHandler you want to observe, with a BMessenger back to the observer, so both must be attached to a looper at the time StartWatching() is called. Attention: The forms of StartWatching() and StartWatchingAll() that accept a BHandler can be used to observe a handler that's not yet attached to a looper. However, these only work if the observer and notifier are both in the same looper.

status_t StartWatchingAll (  BHandler *  target  )

StartWatchingAll() registers the specified BMessenger or BHandler to be notified when any of the notifer's states change. Parameters: target  Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid. Attention: The forms of StartWatching() and StartWatchingAll() that accept a BHandler can be used to observe a handler that's not yet attached to a looper. However, these only work if the observer and notifier are both in the same looper.

status_t StartWatchingAll (  BMessenger   )

status_t StopWatching (  BHandler *  target, uint32  what )

StopWatching() ceases monitoring of the state what. Parameters: target  BHandler what  Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid.

status_t StopWatching (  BMessenger  target, uint32  what )

StopWatching() ceases monitoring of the state what. Parameters: target  BMessenger what  Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid.

status_t StopWatchingAll (  BHandler *  target  )

StopWatchingAll(), by some odd coincidence, stops all monitoring by the BHandler or BMessenger specified by watcher. Parameters: target  BHandler Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid.

status_t StopWatchingAll (  BMessenger  target  )

StopWatchingAll(), by some odd coincidence, stops all monitoring by the BHandler or BMessenger specified by watcher. Parameters: target  BMessenger Returns: B_OK. No error. B_BAD_HANDLER. The specified BHandler isn't valid.

void UnlockLooper (   )

---

Friends And Related Function Documentation

int32 _get_object_token_ (  const BHandler *   )  [friend]

friend class BLooper [friend]

friend class BMessageFilter [friend]

---

Copyright 2005 by yellowTAB GmbH, Be Inc., Palm Source Inc. and their respective legal successors
All rights reserved.