danger.app
Class Listener

java.lang.Object
  danger.app.Listener

Direct Known Subclasses:

Application, BatteryMonitor, DeviceList, NotificationManager, PhotoGallery, PreviewTone, SettingsDB, ToneGallery, ToolTipHandler, View

public class Listener
extends Object

Base class for things that can receive events.

Constructor Summary

Listener()
Construct an instance.

Listener(Dispatcher d)
Construct an instance.

Method Summary

void	cancelEvents(int type, int what) Cancel all events of the given type and subtype that this instance's Dispatcher has queued.
boolean	childEventPump() Invokes childRun() on this Listener's Dispatcher.
boolean	childEventPumpDone() Invokes childRunDone() on this Listener's Dispatcher.
boolean	eventProblem(Event event, Throwable ex) Handle an exception caused by event processing.
boolean	isDispatchingThread() Invokes isDispatchingThread() on this Listener's Dispatcher.
boolean	receiveEvent(Event e) Entry point for event processing.
protected boolean	receiveEventInternal(Event e) Internal entry point for event processing.
void	sendEvent(Event e) Send the given Event object.
void	sendEvent(int type) Construct and send an event.
void	sendEvent(int type, int what) Construct and send an event.
void	sendEvent(int type, int what, int data) Construct and send an event.
void	sendEvent(int type, int what, int data, Object arg) Construct and send an event.
void	sendLowPriorityEvent(Event e) Send the given Event object.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Listener

public Listener()

Construct an instance. Its dispatcher will be the current application's dispatcher. If calling thread is not part of an application, then the dispatcher will be null (and a warning to that effect will be issued to the log).

Listener

public Listener(Dispatcher d)

Construct an instance. Its dispatcher will be set to the one given. If passed as null then the dispatcher will be set to the current application's dispatcher; in this case, if the calling thread is not part of an application, then the dispatcher will be null (and a warning to that effect will be issued to the log).

Parameters:

d - null-ok; the dispatcher for the listener, or null to use the current application's dispatcher

Method Detail

receiveEvent

public boolean receiveEvent(Event e)

Entry point for event processing. This method is called from a Dispatcher when it reads an Event in its queue that is targetted at this instance. The default behavior is to do nothing and return false. Subclasses are expected to override this method to do something more useful.

Parameters:

e - non-null; the event to process

Returns:

whether (true) or not (false) this method actually handled the event to completion

eventProblem

public boolean eventProblem(Event event,
                            Throwable ex)

Handle an exception caused by event processing. This method is called by a Dispatcher's run loop when it catches any exception (in the generic sense, that is any Throwable). The method should handle the exception in an appropriate way and then indicate (by the return value) whether or not the dispatcher should continue to run.

By default, this just calls the same-named method on this instance's Dispatcher.

Parameters:

event - non-null; the event whose processing caused the exception

ex - non-null; the exception that was thrown

Returns:

whether (true) or not (false) to continue running the dispatcher loop

sendEvent

public final void sendEvent(Event e)

Send the given Event object. This queues the given event for eventual receipt. This method will return immediately upon queuing; that is, it won't wait for the event to be processed.

Parameters:

e - non-null; the event to queue up

sendLowPriorityEvent

public final void sendLowPriorityEvent(Event e)

Send the given Event object. This queues the given event for eventual receipt after all events sent to the same dispatcher with sendEvent() and all expired timers have completed. This method will return immediately upon queuing; that is, it won't wait for the event to be processed.

Parameters:

e - non-null; the event to queue up

sendEvent

public final void sendEvent(int type,
                            int what,
                            int data,
                            Object arg)

Construct and send an event. This initializes an Event using the given arguments (recycling a used event if possible), targetting this instance, and then queues it up by calling sendEvent(Event).

Parameters:

type - the type of the event

what - the sub-type of the event

data - additional data for the event

arg - null-ok; an object related to the event

sendEvent

public final void sendEvent(int type,
                            int what,
                            int data)

Construct and send an event. This initializes an Event using the given arguments (recycling a used event if possible), targetting this instance, and then queues it up by calling sendEvent(Event).

Parameters:

type - the type of the event

what - the sub-type of the event

data - additional data for the event

sendEvent

public final void sendEvent(int type,
                            int what)

Construct and send an event. This initializes an Event using the given arguments (recycling a used event if possible), targetting this instance, and then queues it up by calling sendEvent(Event).

Parameters:

type - the type of the event

what - the sub-type of the event

sendEvent

public final void sendEvent(int type)

Construct and send an event. This initializes an Event using the given arguments (recycling a used event if possible), targetting this instance, and then queues it up by calling sendEvent(Event).

Parameters:

type - the type of the event

cancelEvents

public final void cancelEvents(int type,
                               int what)

Cancel all events of the given type and subtype that this instance's Dispatcher has queued.

Parameters:

type - the type of the event(s) in question

what - the sub-type of the event(s) in question

childEventPump

public final boolean childEventPump()

Invokes childRun() on this Listener's Dispatcher.

Returns:

the return value of childRun()

See Also:

Dispatcher.childRun()

childEventPumpDone

public final boolean childEventPumpDone()

Invokes childRunDone() on this Listener's Dispatcher.

Returns:

the return value of childRunDone()

See Also:

Dispatcher.childRunDone()

isDispatchingThread

public final boolean isDispatchingThread()

Invokes isDispatchingThread() on this Listener's Dispatcher.

Returns:

the return value of isDispatchingThread()

See Also:

Dispatcher.isDispatchingThread()

receiveEventInternal

protected boolean receiveEventInternal(Event e)

Internal entry point for event processing. This method is called before receiveEvent(danger.app.Event) by a Dispatcher. If this method consumes the event (that is, returns true), then nothing more is done with the event. Otherwise, receiveEvent gets a crack at it. This dispatch order allows listeners to handle essential events without the danger of them being trampled in the receiveEvent() of subclasses.

Parameters:

e - non-null; the event to process

Returns:

whether (true) or not (false) this method actually handled the event to completion