Description
Events let use listen to database changes, like changing the field or entity, adding or removing entities. Make sure
- To pair adding a listener with removing a listener to prevent memory leaks
- all events handlers have try/catch block to prevent exception being fired from event handlers
Following events are available:
Event | Description |
---|---|
Field value changed | It is fired when provided field value change (any entity) |
Entity is updated | It is fired when provided entity value change (any field) |
Entity is deleted | It is fired when provided entity deleted |
Any entity is updated | It is fired when any entity updated (any field) |
Any entity is added | It is fired when new entity is added |
Any entity is deleted | It is fired when any entity deleted |
Before any entity deleted | It is fired before any entity is deleted |
Batch update event | Batch update event is fired when BGRepo.I.Events.Batch(Action action); method is used. When this method is used, no individual events will be fired while action is being executed, and one single batch event will be fired when action is executed. This is required for performance's sake when massive changes to database should be done without firing individual events |
Any change event | It is fired on any database change |
Example
The following class demonstrates the usage of events. The example code does not use code generation feature, so if you use CodeGen addon, the following code can be simplified
Press to see the code
using BansheeGz.BGDatabase;
using UnityEngine;
public class EventListenersDemo : MonoBehaviour
{
void Start() => AddListeners();
private void OnDestroy() => RemoveListeners();
private void AddListeners()
{
//get target objects
var meta = BGRepo.I["MyTable"];
var field = meta.GetField("name");
var entity = meta.GetEntity(0);
//listen to some field change
field.ValueChanged += FieldChanged;
//listen to particular entity (row)
meta.AddEntityUpdatedListener(entity.Id, EntityUpdated);
meta.AddEntityDeletedListener(entity.Id, EntityDeleted);
//listen to all entities (rows) of particular table (meta)
meta.AnyEntityUpdated += SomeEntityUpdated;
meta.AnyEntityAdded += SomeEntityAdded;
meta.AnyEntityBeforeDeleted += SomeEntityBeforeDeleted;
meta.AnyEntityDeleted += SomeEntityDeleted;
//listen to batch events (any table). See BatchEventExample method below for more information
BGRepo.I.Events.OnBatchUpdate += BatchUpdate;
//listen on any change events (any table)
BGRepo.I.Events.OnAnyChange += AnyChange;
}
//always match adding listeners with removing listeners to prevent memory leak
private void RemoveListeners()
{
//get target objects
var meta = BGRepo.I["MyTable"];
var field = meta.GetField("name");
var entity = meta.GetEntity(0);
meta.RemoveEntityUpdatedListener(entity.Id, EntityUpdated);
meta.RemoveEntityDeletedListener(entity.Id, EntityDeleted);
meta.AnyEntityUpdated -= SomeEntityUpdated;
meta.AnyEntityAdded -= SomeEntityAdded;
meta.AnyEntityBeforeDeleted -= SomeEntityBeforeDeleted;
meta.AnyEntityDeleted -= SomeEntityDeleted;
field.ValueChanged -= FieldChanged;
BGRepo.I.Events.OnBatchUpdate -= BatchUpdate;
BGRepo.I.Events.OnAnyChange -= AnyChange;
}
//------------------------------------------------
// Field changed
//------------------------------------------------
private void FieldChanged(object sender, BGEventArgsField e)
{
if (e is BGEventArgsFieldWithValue<string> ev) Debug.Log($"The field {ev.Field.Name} for entity {ev.Entity.Name} was changed {ev.OldValue} -> {ev.NewValue}");
else Debug.Log($"The field value was changed, entity={e.Entity.Name}");
}
//------------------------------------------------
// any entity (row)
//------------------------------------------------
private void SomeEntityUpdated(object sender, BGEventArgsAnyEntityUpdated e)
{
if (e is BGEventArgsAnyEntityUpdatedWithValue ev) Debug.Log($"The field {ev.GetField().Name} for entity {ev.Entity.Name} was changed {ev.GetOldValue()} -> {ev.GetNewValue()}");
else Debug.Log("The entity Updated " + e.Entity.Name);
}
private void SomeEntityAdded(object sender, BGEventArgsAnyEntity e) => Debug.Log($"The entity is added {e.Entity.Id}");
private void SomeEntityBeforeDeleted(object sender, BGEventArgsAnyEntity e)=> Debug.Log($"The entity is about to be deleted {e.Entity.Id}");
private void SomeEntityDeleted(object sender, BGEventArgsAnyEntity e) => Debug.Log($"The entity is deleted {e.Entity.Id}");
//------------------------------------------------
// particular (provided) entity (row)
//------------------------------------------------
private void EntityDeleted(object sender, BGEventArgsEntity e) => Debug.Log($"The Entity was deleted {e.Entity.Id}");
private void EntityUpdated(object sender, BGEventArgsEntityUpdated e) => Debug.Log($"The Entity was updated {e.Entity.Name}");
//------------------------------------------------
// Batch update
//------------------------------------------------
private void BatchUpdate(object sender, BGEventArgsBatch e) => Debug.Log($"Batch update. Use WasEntitiesAdded/WasEntitiesDeleted/WasEntitiesUpdated methods to find out if entities were modified");
//this method provide example how batch event is fired
private void BatchEventExample()
{
BGRepo.I.Events.Batch(() =>
{
//all individual events inside this method will be disabled. One batch event will be fired when this action is executed
//update all "name" field values for the first table
BGRepo.I.GetMeta(0).ForEachEntity(entity => entity.Name += " [Updated]");
});
}
//------------------------------------------------
// Any change
//------------------------------------------------
private void AnyChange(object sender, BGEventArgsAnyChange e) => Debug.Log($"Some change was made to the database");
}