regina::PacketListener Class Reference
Basic Packet Types

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

`#include <packet/packetlistener.h>`

Inheritance diagram for regina::PacketListener:

## Public Member Functions

Constructors and Destructors
virtual | ~PacketListener ()
| Destroys this listener. More...
Packet Listener Interface
void | unregisterFromAllPackets ()
| 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 | packetToBeDestroyed (Packet *packet)
| Called before the packet is about to be 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, bool inParentDestructor)
| Called before a child packet is to be removed from directly beneath the packet. More...
virtual void | childWasRemoved (Packet *packet, Packet *child, bool inParentDestructor)
| 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...

## Friends

class | Packet
| Allow packets to automatically deregister listeners as they are destroyed. 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 routine for all registered packet 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 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 future event packetToBeDestroyed() with no matching "past" event, since after the packet has been destroyed the set of listeners is no longer available.

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.

Warning
  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:
  Not present.

## Constructor & Destructor Documentation

## ~PacketListener()

virtual regina::PacketListener::~PacketListener | ( |  | ) |

virtual

Destroys this listener.

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

## Member Function Documentation

## childrenToBeReordered()

void regina::PacketListener::childrenToBeReordered | ( | Packet * | packet | ) |

inline virtual

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.

## childrenWereReordered()

void regina::PacketListener::childrenWereReordered | ( | Packet * | packet | ) |

inline virtual

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.

## childToBeAdded()

void regina::PacketListener::childToBeAdded | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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

Once the child is removed, 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.

## childToBeRemoved()

void regina::PacketListener::childToBeRemoved | ( | Packet * | packet,
|  | Packet * | child,
|  | bool | inParentDestructor
| ) |  |

inline virtual

Called before a child packet is to be 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). Once the child is removed, childWasRemoved() will be called also.

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.

Parameters

  packet | the packet being listened to.
  child | the child packet to be 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.

## childToBeRenamed()

void regina::PacketListener::childToBeRenamed | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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()

## childWasAdded()

void regina::PacketListener::childWasAdded | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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.

## childWasRemoved()

void regina::PacketListener::childWasRemoved | ( | Packet * | packet,
|  | Packet * | child,
|  | bool | inParentDestructor
| ) |  |

inline virtual

Called after 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). Before this child is removed, childToBeRemoved() will be called also.

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.

Parameters

  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.

## childWasRenamed()

void regina::PacketListener::childWasRenamed | ( | Packet * | packet,
|  | Packet * | child
| ) |  |

inline virtual

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()

## packetToBeChanged()

void regina::PacketListener::packetToBeChanged | ( | Packet * | packet | ) |

inline virtual

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.

## packetToBeDestroyed()

void regina::PacketListener::packetToBeDestroyed | ( | Packet * | packet | ) |

inline virtual

Called before the packet is about to be destroyed.

Note that there is no matching function called after the packet is destroyed, since the set of listeners will no longer be available at that stage.

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.

Parameters

  packet | the packet being listened to.

Reimplemented in regina::Script.

## packetToBeRenamed()

void regina::PacketListener::packetToBeRenamed | ( | Packet * | packet | ) |

inline virtual

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()

## packetWasChanged()

void regina::PacketListener::packetWasChanged | ( | Packet * | packet | ) |

inline virtual

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.

Reimplemented in regina::SnapPeaTriangulation.

## packetWasRenamed()

void regina::PacketListener::packetWasRenamed | ( | Packet * | packet | ) |

inline virtual

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()

Reimplemented in regina::Script.

## unregisterFromAllPackets()

void regina::PacketListener::unregisterFromAllPackets | ( |  | ) |

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

## 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/packetlistener.h

Copyright © 1999-2016, The Regina development team
This software is released under the GNU General Public License, with some additional permissions; see the source code for details.
For further information, or to submit a bug or other problem, please contact Ben Burton (bab@maths.uq.edu.au).