2.1.4. Шина событий

2.1.4.1. Основные положения

  • Шина событий предназначена для обмена сообщениями между выборками, в том числе не связанными отношением мастер-деталь.
  • Шина событий является единой для всего приложения.
  • Шина событий позволяет обеспечивать взаимодействие между выборками по принципам: один к одному, один ко многим, многие к одному и многие ко многим.
  • Шина событий обеспечивает только однонаправленное взаимодействие, предназначенное, прежде всего, для оповещения о происходящих событиях и передачи связанных с этими событиями каких-либо данных.
  • У каждого события передаваемого по Шине событий может быть как множество обработчиков, так и не быть ни одного обработчика вовсе.
  • Обработчики событий не могут прерывать, отменять или изменять порядок вызова других обработчиков этих событий.
  • Порядок вызова обработчиков событий не зависит от порядка их регистрации или каких-либо свойств обработчиков, и не может изменяться каким-либо образом. При отправке событий по Шине необходимо быть уверенным в том, что порядок вызова обработчиков не играет никакой роли, и не будет сказываться на работоспособности приложения.
  • Возникновение исключений в обработчиках события не прерывает процесс вызова других обработчиков этого события.
  • Шина событий не предоставляет возможности получить информацию об обработчиках подписанных на какое-либо событие и их количестве.

2.1.4.2. Событие

Для удобства событие представлено в виде отдельного объекта класса TbtkScriptSelectionEventObject, передаваемого в обработчики событий. Экземпляр этого объекта автоматически создаётся для каждого события, и автоматически разрушается после обработки во всех обработчиках.

2.1.4.2.1. Свойства события

  • Name(String), - системное имя события. Указывается при отсылке.
  • Args(TbtkNamedArg), - набор именованных аргументов данного события. Может быть указано при отсылке.
  • TopicName(String), - имя подписки. Используется для персонализации получателя. Указывается при отсылке.
  • SelectionId(String), - ID выборки, из которой отправили сообщение. Присваивается автоматически.
  • EntityName(String), - системное имя выборки, из которой отправили сообщение. Присваивается автоматически.
  • Representation(String), - отображение выборки, из которой отправили сообщение. Присваивается автоматически.

Все свойства события доступны только на чтение.

Attention

Внимание!!! Значения аргументов свойства Args доступны на запись. Это связано с особенностями реализации этого свойства. Настоятельно не рекомендуется использовать эту особенность в прикладной логике, т.к. изменения этих аргументов могут повлиять на работу ещё не вызванных обработчиков этого события. Кроме того поддержка описанного поведения не гарантируется с выходом новых версий Global.

2.1.4.2.2. Обработчики событий

Обработка всех событий передаваемых по Шине осуществляется в операции выборки HandleEvents. При вызове, в операцию передаётся единственный аргумент, - объект события, класса TbtkScriptSelectionEventObject. Пример обработчика события:

<PASCAL Event>
  case Event.Name of
    'Event1':
    begin
      //какие-либо действия
    end;
    'Event2':
    begin
      //какие-либо действия
    end;
    else
    begin
      //какие-либо действия
    end;
  end;
</PASCAL>

2.1.4.2.3. Подписка на событие

Для обработки событий необходимо подписать выборку на соответствующие события. Делается это вызовом методов Шины Subscribe и Hook.

Подписка по топику(subscribe)
  <PASCAL>
    EventBus.Subscribe(Selection, 'TopicName'); //подписка на событие с указанием топика.
  </PASCAL>
Подписка без топика(hook)
  <PASCAL>
    EventBus.Hook(Selection); //подписка на все события передаваемые по шине.
  </PASCAL>

2.1.4.2.4. Фильтрация событий

При подписке, для более точного определения набора обрабатываемых событий, можно передавать параметры фильтрации. В качестве параметров фильтрации используются следующие свойства события: EventName, TopicName, SelectionId, EntityName и Representation.

<PASCAL>
  EventBus.Subscribe(Selection, 'TopicName', CreateArgs(['EventName', 'TestEvent', 'EntityName', 'Sel_XXX'])); //подписка на событие с дополнительными условиями фильтрации.
  EventBus.Hook(Selection, CreateArgs(['EventName', 'TestEvent', 'EntityName', 'Sel_XXX'])); //подписка на все события, ограниченные фильтром.
</PASCAL>

Changed in version 5.1: До версий 5.0.6 и 5.1 имена параметров фильтрации были не регистрозависимы, а их значения были регистрозависимы. До этих версий, если выборка была подписана на событие с именем “EventTest”, то она не могла обработать событие с именем “EVENTTEST”. При отправке сообщения по шине параметры фильтров EntityName и Representation всегда должны были быть указаны в верхнем регистре. Значение топика должно было указываться в том же регистре, что и при подписке. Начиная с версий 5.0.6 и 5.1 и имена, и значения параметров фильтрации не регистрозависимы.

2.1.4.2.5. Отписка от событий

Для того чтобы отписываться от событий используются методы Unsubscribe и Unhook, в которые должны передаваться такие же параметры, что были переданы при подписке.

<PASCAL>
  EventBus.Unsubscribe(Selection, 'TopicName'); //отписка от события без дополнительных условий фильтрации.
  EventBus.Unsubscribe(Selection, 'TopicName', CreateArgs(['EventName', 'TestEvent', 'EntityName', 'Sel_XXX'])); //подписка от события с дополнительными условиями фильтрации.
  EventBus.Unhook(Selection); //отписка от всех событий передаваемых по шине.
  EventBus.Unhook(Selection, CreateArgs(['EventName', 'TestEvent', 'EntityName', 'Sel_XXX'])); //отписка от всех событий, ограниченные фильтром.
</PASCAL>

2.1.4.3. Отправка события

2.1.4.3.1. Синхронная

Вызов обработчиков событий отправленных синхронно выполняется сразу при отправке.

Пример синхронной отправки:
  <PASCAL>
    EventBus.Send('TopicName', 'EventName');//отправка события без аргументов
    EventBus.Send('TopicName', 'EventName', CreateArgs(['Arg1','Value1','Arg2','Value2']));//отправка события с аргументами
  </PASCAL>

2.1.4.3.2. Асинхронная

Вызов обработчиков событий отправленных асинхронно, откладывается и выполняется с помощью асинхронных команд.

Пример асинхронной отправки:
  <PASCAL>
    EventBus.Post('TopicName', 'EventName');//отправка события без аргументов
    EventBus.Post('TopicName', 'EventName', CreateArgs(['Arg1','Value1','Arg2','Value2']));//отправка события с аргументами
  </PASCAL>

2.1.4.4. События клиента

BeforeOperationExecute
Topic:

Operations
Arguments:
  • OperationName – Системное имя выполняемой операции.
  • OperationCaption – Наименование (заголовок)выполняемой операции.
  • OperationText – Текст выполняемой операции.
  • OperationStack – Стек операций в виде строки. Разделителем является перенос строк.

Отправляется перед выполнением любой паскаль операции.

New in version Global_5.10.16.

New in version Global_5.11.13.

New in version Global_5.12_ms_16.

DockSite.OnPopumMenu
Topic:

ID главной выборки приложения
Arguments:
  • SelectionID – ID выборки, на вкладку которой нажали

Отправляется перед показом всплывающего меню доков.

See also

Pascal события клиента Global.