Events can be subscribed at different layers:
- on a Child
- on a Parent
- on a Composite
- on a Composite's Container
(e.g. the Grid of a GridComposite.)
The main methods for subscribing events are likely SubscribeEventOnChild<K, T> for subscribing to an event on a child and SubscribeEventOnParent<T> for subscribing events on a parent.
When in doubt, stick with SubscribeEventOnChild<K, T> and SubscribeEventOnParent<T>.
You may also note that a subset of common subscriptions are defined in Settings, i.e.
, and SelectionChanged
. With MouseSingleClick and MouseDoubleClick, the defined event subscription is applied to each and every Composite that will get added to the parent (although a Predicate filter is
available.) Moreover, there is the ability to apply a settings-defined event subscription "on-the-fly", for instance, after a Composite has been unsubscribed, in order to re-subscribe it. SelectionChanged is subscribed just to the parent, not to
each child; it merely gets fired when each child is selected. If you need to unset one of these event settings, call
. This is not
the same as unsubscribing; this only clears the settings for any Composites added to the parent in the future.
All other subscriptions are defined directly (e.g. on a specific
Border, Parent, Child, or Container) without referencing any Settings.
is subscribed on the Composite's Container, e.g. if a GridComposite, it will subscribe the event on the Grid internal to the Composite.
is for subscribing on a Composite, i.e. the root Border of a Composite. (In WPF Composites, the Border serves a role similar to a DIV tag in HTML.)
are for subscribing to DependencyPropertyChanged events. This is a change as of Version 5.0.
Here is the full list of methods for subscribing events:
The Reactive Framework (Rx) is used to assist with unsubscribing events. Rx returns an IDisposable when an event is subscribed to. This IDisposable may later be disposed in order to unsubscribe. WPF Composites stores all IDisposables in a DisposablesDictionary
within the SettingsDictionary found on the parent's Tag.
There are multiple unsubscribe methods that will call into this dictionary for you, including a comprehensive
at the parent level which will unsubscribe all IDisposables as well as any scrollviewer events on the parent. However, DisposeEvents will
recurse down thru any nested parents that are children within the parent and which may house their own IDisposables.
For this reason, the Selectors Engine was enhanced to now support the new DisposeEventsOnAllParents
method that will recurse down thru any nested parents that are children within the parent.
When unsubscribing an entire UserControl or Window, stick with DisposeEventsOnAllParents();
Unsubscribing events may be important to prevent accidentally keeping objects alive longer than necessary, as handles to objects caused by events may prevent objects from being garbage collected.
Here is the full list of methods for unsubscribing (excluding DisposeEvents and any Selectors Engine methods):