An object that can be registered to listen for packet events. More...
#include <npacketlistener.h>
Public Member Functions | |
virtual | ~NPacketListener () |
Destroys this listener. | |
void | unregisterFromAllPackets () |
Unregisters this listener from any packets to which it is currently listening. | |
virtual void | packetWasChanged (NPacket *packet) |
Called when the contents of the packet have been changed. | |
virtual void | packetWasRenamed (NPacket *packet) |
Called when the packet label or tags have been changed. | |
virtual void | packetToBeDestroyed (NPacket *packet) |
Called when the packet is about to be destroyed. | |
virtual void | childWasAdded (NPacket *packet, NPacket *child) |
Called when a child packet has been inserted directly beneath the packet. | |
virtual void | childWasRemoved (NPacket *packet, NPacket *child, bool inParentDestructor) |
Called when a child packet has been removed from directly beneath the packet. | |
virtual void | childrenWereReordered (NPacket *packet) |
Called when the child packets directly beneath the packet have been reordered. | |
Friends | |
class | NPacket |
Allow packets to automatically deregister listeners as they are destroyed. |
An object that can be registered to listen for packet events.
A packet listener can be registered to listen for events on a packet by calling NPacket::listen().
Each time that one of the events listed in this class occurs, the packet will call the appropriate routine for all registered packet listeners.
Note that these events are mutually exclusive, i.e., any event will cause at most one routine to be called for each listener. For instance, if a packet is renamed then packetWasRenamed() will be called but packetWasChanged() will not.
No guarantees are made as to the order in which the different packet listeners are notified of an event.
Note that when a listener is destroyed, it is automatically unregistered from any packets to which it is currently listening. Similarly, when a packet is destroyed all listeners are automatically unregistered.
When using multiple threads, there are restrictions upon what any thread other than the main thread may do. If these restrictions are properly adhered to, packet listeners may assume that no routines other than childWasAdded() will be called from a non-main thread. Of course it is up to the multithreading code to ensure that these restrictions are in fact met; see the NThread class notes for further information.
virtual regina::NPacketListener::~NPacketListener | ( | ) | [virtual] |
Destroys this listener.
This listener will be unregistered from any packets to which it is currently listening.
void regina::NPacketListener::childrenWereReordered | ( | NPacket * | packet ) | [inline, virtual] |
Called when the child packets directly beneath the packet have been reordered.
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
Called when a child packet has been inserted directly beneath the packet.
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
child | the child packet that was added. |
void regina::NPacketListener::childWasRemoved | ( | NPacket * | packet, |
NPacket * | child, | ||
bool | inParentDestructor | ||
) | [inline, virtual] |
Called when a child packet has been removed from directly beneath the packet.
Note that the child packet may be about to be destroyed (although this destruction will not have happened yet).
Note also that this packet (the parent) may have already entered its destructor (which removes and destroys all child packets as a matter of course). In this situation it may be unsafe to query or update this packet, and so the third argument inParentDestructor is provided to indicate such a situation.
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
child | the child packet that was removed. |
inParentDestructor | set to true if the parent packet is in fact being destroyed, and the child was simply removed as part of the standard subtree destruction. |
void regina::NPacketListener::packetToBeDestroyed | ( | NPacket * | packet ) | [inline, virtual] |
Called when the packet is about to be destroyed.
Note that this event is called before the packet is destroyed, not after.
When an entire packet subtree is to be destroyed, child packets will notify their listeners of the impending destruction before parent packets will.
Note that the packet will forcibly unregister this listener immediately before packetToBeDestroyed() is called, to avoid any unpleasant consequences if this listener should also try to unregister itself. This means that, by the time this routine is called, this listener will no longer be registered with the packet in question (and any attempt to unregister it again will be harmless).
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
void regina::NPacketListener::packetWasChanged | ( | NPacket * | packet ) | [inline, virtual] |
Called when the contents of the packet have been changed.
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
void regina::NPacketListener::packetWasRenamed | ( | NPacket * | packet ) | [inline, virtual] |
Called when the packet label or tags have been changed.
The default implementation of this routine is to do nothing.
packet | the packet being listened to. |
void regina::NPacketListener::unregisterFromAllPackets | ( | ) |
Unregisters this listener from any packets to which it is currently listening.
friend class NPacket [friend] |
Allow packets to automatically deregister listeners as they are destroyed.