An object that can be registered to listen for packet events. More...

#include <packet/packet.h>

Public Member Functions
Constructors and Destructors
virtual	~PacketListener ()
	Destroys this listener. More...

Packet Listener Interface
class	Packet
	Allow packets to automatically deregister listeners as they are destroyed. More...

bool	isListening () const
	Determines whether this object is listening for events on any packets at all. More...

void	unlisten ()
	Unregisters this listener from all packets to which it is currently listening. More...

void	unregisterFromAllPackets ()
	Deprecated routine that unregisters this listener from any packets to which it is currently listening. More...

virtual void	packetToBeChanged (Packet &packet)
	Called before the contents of the packet are to be changed. More...

virtual void	packetWasChanged (Packet &packet)
	Called after the contents of the packet have been changed. More...

virtual void	packetToBeRenamed (Packet &packet)
	Called before the packet label or tags are to be changed. More...

virtual void	packetWasRenamed (Packet &packet)
	Called after the packet label or tags have been changed. More...

virtual void	packetBeingDestroyed (PacketShell packet)
	Called as the packet is being destroyed. More...

virtual void	childToBeAdded (Packet &packet, Packet &child)
	Called before a child packet is to be inserted directly beneath the packet. More...

virtual void	childWasAdded (Packet &packet, Packet &child)
	Called after a child packet has been inserted directly beneath the packet. More...

virtual void	childToBeRemoved (Packet &packet, Packet &child)
	Called before a child packet is to be removed from directly beneath the packet. More...

virtual void	childWasRemoved (Packet &packet, Packet &child)
	Called after a child packet has been removed from directly beneath the packet. More...

virtual void	childrenToBeReordered (Packet &packet)
	Called before the child packets directly beneath the packet are to be reordered. More...

virtual void	childrenWereReordered (Packet &packet)
	Called after the child packets directly beneath the packet have been reordered. More...

virtual void	childToBeRenamed (Packet &packet, Packet &child)
	Called before one of this packet's immediate children has its label or tags changed. More...

virtual void	childWasRenamed (Packet &packet, Packet &child)
	Called after one of this packet's immediate children has its label or tags changed. More...

virtual void	packetToBeChanged (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	packetWasChanged (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	packetToBeRenamed (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	packetWasRenamed (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	packetToBeDestroyed (PacketShell) final
	A placeholder for an old callback function that is no longer used. More...

virtual void	childToBeAdded (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childWasAdded (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childToBeRemoved (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childWasRemoved (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childrenToBeReordered (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childrenWereReordered (Packet *) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childToBeRenamed (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

virtual void	childWasRenamed (Packet , Packet ) final
	A placeholder for an old form of a callback function that is no longer used. More...

	PacketListener ()=default
	Default constructor. More...

	PacketListener (const PacketListener &src)
	Copy constructor. More...

PacketListener &	operator= (const PacketListener &src)
	Copy assignment operator. More...

void	swapListeners (PacketListener &other)
	Swap operation. More...

Detailed Description

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 Packet::listen().

Each time that one of the events listed in this class occurs, the packet will call the appropriate callback routine for all registered listeners.

These events come in future/past pairs: packetToBeChanged() and packetWasChanged(), childToBeAdded() and childWasAdded(), and so on. These event pairs are mutually exclusive: any event will cause at most one pair of callback routines to be called for each (packet, listener) pair. For instance, if a packet is renamed then packetToBeRenamed() and packetWasRenamed() will be called but packetToBeChanged() and packetWasChanged() will not.

As a special case, when a packet is destroyed there is only the one event packetBeingDestroyed(), since this is called during the packet destructor (at a time when the set of listeners is still available, but some of the other packet data may have already been destroyed).

No guarantees are made as to the order in which the different packet listeners are notified of an event.

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.

To listen for packet events using your own callback routines, you would typically implement a subclass of PacketListener that overrides only those callbacks that you are interested in. Be aware that:

Callbacks are called for each listener, one at a time, in the same thread in which the event occurred.
Callbacks can safely add new packet listeners, but there is no guarantee as to whether or not the new listeners will be notified of the specific event currently being processed.
Callbacks can safely remove other listeners, but they must not remove the listener whose callback is currently being called. The one exception to this is packetBeingDestroyed(), which will explicitly remove each listener before its callback is called (which means, for example, the listener can safely delete itself).

Warning: Subclass authors should be aware of the default copy semantics that this base class provides. In particular, this base class provides a protected copy constructor and copy assignment operator that will change which packets are being listened to (in the "obvious" way). As a subclass author, you should understand this inherited behaviour if your subclass constructors and/or assignment operators use these base class operations implicitly.; At the time of writing (admittedly long ago now), Qt has only limited support for multithreading. When working with an existing packet tree in a new thread (not the main thread), the only modification that you may make is to insert new packets. Modifications of any other type (such as changing, renaming, deleting or reordering existing packets) could lead to a crash within Qt or Xlib when running the GUI. Of course, a new thread may create, modify and delete its own temporary packet trees as it chooses (and it may in fact insert them into a pre-existing packet tree once all modifications are completed). Assuming these restrictions are respected, packet listeners may assume that no routines other than childWasAdded() will be called from a non-main thread.

Python: You can happily make a pure Python subclass of PacketListener, and packets will call whichever functions you override when events occur, just as they would for a native C++ subclass.

Constructor & Destructor Documentation

◆ ~PacketListener()

regina::PacketListener::~PacketListener ( )

inlinevirtual

Destroys this listener.

This listener will be unregistered from any packets to which it is currently listening.

◆ PacketListener() [1/2]

regina::PacketListener::PacketListener ( )

protecteddefault

Default constructor.

The new listener will not be listening to any packets.

◆ PacketListener() [2/2]

regina::PacketListener::PacketListener ( const PacketListener & src )

protected

Copy constructor.

The new listener will be registered as listening to the same packets as src.

Parameters

src	the listener to copy.

Member Function Documentation

◆ childrenToBeReordered() [1/2]

virtual void regina::PacketListener::childrenToBeReordered ( Packet & packet )

inlinevirtual

Called before the child packets directly beneath the packet are to be reordered.

Once the reordering is done, childrenWereReordered() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

◆ childrenToBeReordered() [2/2]

virtual void regina::PacketListener::childrenToBeReordered ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childrenToBeReordered() callback now takes its argument by reference, not by pointer.

Python: In Python, childrenToBeReordered() refers to the new (reference-based) form of this callback.

◆ childrenWereReordered() [1/2]

virtual void regina::PacketListener::childrenWereReordered ( Packet & packet )

inlinevirtual

Called after the child packets directly beneath the packet have been reordered.

Before this reordering is done, childrenToBeReordered() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

◆ childrenWereReordered() [2/2]

virtual void regina::PacketListener::childrenWereReordered ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childrenWereReordered() callback now takes its argument by reference, not by pointer.

Python: In Python, childrenWereReordered() refers to the new (reference-based) form of this callback.

◆ childToBeAdded() [1/2]

virtual void regina::PacketListener::childToBeAdded	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called before a child packet is to be inserted directly beneath the packet.

Once the child is inserted, childWasAdded() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to.
child	the child packet to be added.

◆ childToBeAdded() [2/2]

virtual void regina::PacketListener::childToBeAdded	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childToBeAdded() callback now takes its arguments by reference, not by pointer.

Python: In Python, childToBeAdded() refers to the new (reference-based) form of this callback.

◆ childToBeRemoved() [1/2]

virtual void regina::PacketListener::childToBeRemoved	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called before a child packet is to be removed from directly beneath the packet.

Once the child is removed, childWasRemoved() will be called also.

Since Regina 7.0, this routine is no longer called from within either the parent or child packet's destructor. In particular, when a parent packet is destroyed, although it orphans all of its children as part of the destruction process, it does not call childToBeRemoved() or childWasRemoved when this happens.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to, or `null` if this routine is being called from within this packet's destructor.
child	the child packet to be removed.

◆ childToBeRemoved() [2/2]

virtual void regina::PacketListener::childToBeRemoved	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childToBeRemoved() callback now takes its arguments by reference, not by pointer, and is no longer called from within either the child or parent destructor.

Python: In Python, childToBeRemoved() refers to the new (reference-based) form of this callback.

◆ childToBeRenamed() [1/2]

virtual void regina::PacketListener::childToBeRenamed	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called before one of this packet's immediate children has its label or tags changed.

Before this change, childToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to.
child	the child packet to be renamed.

See also: packetToBeRenamed()

◆ childToBeRenamed() [2/2]

virtual void regina::PacketListener::childToBeRenamed	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childToBeRenamed() callback now takes its arguments by reference, not by pointer.

Python: In Python, childToBeRenamed() refers to the new (reference-based) form of this callback.

◆ childWasAdded() [1/2]

virtual void regina::PacketListener::childWasAdded	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called after a child packet has been inserted directly beneath the packet.

Before this child is added, childToBeAdded() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to.
child	the child packet that was added.

◆ childWasAdded() [2/2]

virtual void regina::PacketListener::childWasAdded	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childWasAdded() callback now takes its arguments by reference, not by pointer.

Python: In Python, childWasAdded() refers to the new (reference-based) form of this callback.

◆ childWasRemoved() [1/2]

virtual void regina::PacketListener::childWasRemoved	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called after a child packet has been removed from directly beneath the packet.

Before the child is removed, childToBeRemoved() will be called also.

Since Regina 7.0, this routine is no longer called from within either the parent or child packet's destructor. In particular, when a parent packet is destroyed, although it orphans all of its children as part of the destruction process, it does not call childToBeRemoved() or childWasRemoved when this happens.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to, or `null` if this routine is being called from within this packet's destructor.
child	the child packet that was removed.

◆ childWasRemoved() [2/2]

virtual void regina::PacketListener::childWasRemoved	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childWasRemoved() callback now takes its arguments by reference, not by pointer, and is no longer called from within either the child or parent destructor.

Python: In Python, childWasRemoved() refers to the new (reference-based) form of this callback.

◆ childWasRenamed() [1/2]

virtual void regina::PacketListener::childWasRenamed	(	Packet &	packet,
		Packet &	child
	)

inlinevirtual

Called after one of this packet's immediate children has its label or tags changed.

Before this change, childToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet	the packet being listened to.
child	the child packet that was renamed.

See also: packetWasRenamed()

◆ childWasRenamed() [2/2]

virtual void regina::PacketListener::childWasRenamed	(	Packet *	,
		Packet *
	)

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the childWasRenamed() callback now takes its arguments by reference, not by pointer.

Python: In Python, childWasRenamed() refers to the new (reference-based) form of this callback.

◆ isListening()

bool regina::PacketListener::isListening ( ) const

inline

Determines whether this object is listening for events on any packets at all.

Returns: true if and only if this object is listening on at least one packet.

◆ operator=()

PacketListener & regina::PacketListener::operator= ( const PacketListener & src )

protected

Copy assignment operator.

This listener will be unregistered from whatever packets it is currently listening to, and instead will be registered as listening to the same packets as src.

Parameters

src	the listener to copy.

Returns: a reference to this packet listener.

◆ packetBeingDestroyed()

virtual void regina::PacketListener::packetBeingDestroyed ( PacketShell packet )

inlinevirtual

Called as the packet is being destroyed.

By the time this function is called, we are already inside the Packet destructor, and so most Packet member functions are no longer safe to call. Therefore the argument that is passed to this routine is a PacketShell, which exposes only those member functions of Packet that are still safe to call at this time. Importantly, you can safely compare a PacketShell against a Packet pointer, in case you need to identify which particular packet is being destroyed.

When a packet is destroyed, it will automatically unregister each listener before calling packetBeingDestroyed() on that listener. Therefore, for this (and only this) callback, it is safe for a listener to unregister itself (since this will be a harmless operation that does nothing). In particular, this makes it safe for a listener to delete itself during this callback.

When an entire packet subtree is to be destroyed, child packets will notify their listeners of the impending destruction before parent packets will.

The default implementation of this routine is to do nothing.

Parameters

packet gives access to the packet being listened to.

◆ packetToBeChanged() [1/2]

virtual void regina::PacketListener::packetToBeChanged ( Packet & packet )

inlinevirtual

Called before the contents of the packet are to be changed.

Once the contents are changed, packetWasChanged() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

◆ packetToBeChanged() [2/2]

virtual void regina::PacketListener::packetToBeChanged ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the packetToBeChanged() callback now takes its argument by reference, not by pointer.

Python: In Python, packetToBeChanged() refers to the new (reference-based) form of this callback.

◆ packetToBeDestroyed()

virtual void regina::PacketListener::packetToBeDestroyed ( PacketShell )

inlinefinalvirtual

A placeholder for an old callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

This callback has been renamed to packetBeingDestroyed(), to emphasise the fact that we are already well inside the packet destructor when this is called.

Python: Not present, since Python does not provide a mechanism such as final to prevent subclasses from overriding a function.

◆ packetToBeRenamed() [1/2]

virtual void regina::PacketListener::packetToBeRenamed ( Packet & packet )

inlinevirtual

Called before the packet label or tags are to be changed.

Once the label or tags are changed, packetWasRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

See also: childToBeRenamed()

◆ packetToBeRenamed() [2/2]

virtual void regina::PacketListener::packetToBeRenamed ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the packetToBeRenamed() callback now takes its argument by reference, not by pointer.

Python: In Python, packetToBeRenamed() refers to the new (reference-based) form of this callback.

◆ packetWasChanged() [1/2]

virtual void regina::PacketListener::packetWasChanged ( Packet & packet )

inlinevirtual

Called after the contents of the packet have been changed.

Before the contents are changed, packetToBeChanged() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

◆ packetWasChanged() [2/2]

virtual void regina::PacketListener::packetWasChanged ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the packetWasChanged() callback now takes its argument by reference, not by pointer.

Python: In Python, packetWasChanged() refers to the new (reference-based) form of this callback.

◆ packetWasRenamed() [1/2]

virtual void regina::PacketListener::packetWasRenamed ( Packet & packet )

inlinevirtual

Called after the packet label or tags have been changed.

Before the label or tags are changed, packetToBeRenamed() will be called also.

The default implementation of this routine is to do nothing.

Parameters

packet the packet being listened to.

See also: childWasRenamed()

◆ packetWasRenamed() [2/2]

virtual void regina::PacketListener::packetWasRenamed ( Packet * )

inlinefinalvirtual

A placeholder for an old form of a callback function that is no longer used.

This has been kept but marked final to force a compile error if any subclass attempts to remimplement it.

The new form of the packetWasRenamed() callback now takes its argument by reference, not by pointer.

Python: In Python, packetWasRenamed() refers to the new (reference-based) form of this callback.

◆ swapListeners()

void regina::PacketListener::swapListeners ( PacketListener & other )

protected

Swap operation.

This listener will be unregistered from whatever packets it is currently listening to and instead will be registered as listening to the same packets that src was originally listening to, and vice versa.

This operation is not constant time, since it needs to perform an internal adjustment for each packet that is affected.

Parameters

other the listener to swap with this.

◆ unlisten()

void regina::PacketListener::unlisten ( )

Unregisters this listener from all packets to which it is currently listening.

◆ unregisterFromAllPackets()

void regina::PacketListener::unregisterFromAllPackets ( )

inline

Deprecated routine that unregisters this listener from any packets to which it is currently listening.

Deprecated:: This routine has been renamed to unlisten().

Friends And Related Function Documentation

◆ Packet

friend class Packet

friend

Allow packets to automatically deregister listeners as they are destroyed.

The documentation for this class was generated from the following file:

packet/packet.h

Public Member Functions

Packet Listener Interface

Detailed Description

Constructor & Destructor Documentation

◆ ~PacketListener()

◆ PacketListener() [1/2]

◆ PacketListener() [2/2]

Member Function Documentation

◆ childrenToBeReordered() [1/2]

◆ childrenToBeReordered() [2/2]

◆ childrenWereReordered() [1/2]

◆ childrenWereReordered() [2/2]

◆ childToBeAdded() [1/2]

◆ childToBeAdded() [2/2]

◆ childToBeRemoved() [1/2]

◆ childToBeRemoved() [2/2]

◆ childToBeRenamed() [1/2]

◆ childToBeRenamed() [2/2]

◆ childWasAdded() [1/2]

◆ childWasAdded() [2/2]

◆ childWasRemoved() [1/2]

◆ childWasRemoved() [2/2]

◆ childWasRenamed() [1/2]

◆ childWasRenamed() [2/2]

◆ isListening()

◆ operator=()

◆ packetBeingDestroyed()

◆ packetToBeChanged() [1/2]

◆ packetToBeChanged() [2/2]

◆ packetToBeDestroyed()

◆ packetToBeRenamed() [1/2]

◆ packetToBeRenamed() [2/2]

◆ packetWasChanged() [1/2]

◆ packetWasChanged() [2/2]

◆ packetWasRenamed() [1/2]

◆ packetWasRenamed() [2/2]

◆ swapListeners()

◆ unlisten()

◆ unregisterFromAllPackets()

Friends And Related Function Documentation

◆ Packet