Шина Событий
----------------------------------------------------------------------

.. pas:attribute:: EventBus: TbtkScriptEventBusObject

  Объект, реализующий методы для работы с шиной событий.

  Атрибут только для чтения

  :rtype: TbtkScriptEventBusObject


TbtkScriptSelectionEventObject
``````````````````````````````````````````````````````````````````````

.. pas:class:: TbtkScriptSelectionEventObject

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

  .. warning:: |not_supported|


  .. pas:attribute:: Representation: String

    Отображение выборки, из которой отправили сообщение. Присваивается
    автоматически.

    Атрибут только для чтения

    :rtype: String


  .. pas:attribute:: EntityName: String

    Системное имя выборки, из которой отправили сообщение. Присваивается
    автоматически.

    Атрибут только для чтения

    :rtype: String


  .. pas:attribute:: SelectionId: String

    ID выборки, из которой отправили сообщение. Присваивается автоматически.

    Атрибут только для чтения

    :rtype: String


  .. pas:attribute:: TopicName: String

    Имя подписки. Указываются при отсылке для персонализации получателя.

    Атрибут только для чтения

    :rtype: String


  .. pas:attribute:: Args: TbtkNamedArgs

    Набор именованных аргументов данного события. Может быть указано при
    отсылке.

    :rtype: TbtkNamedArgs

    .. attention::

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

  .. pas:attribute:: Name: String

    Системное имя события. Указывается при отсылке.

    Атрибут только для чтения

    :rtype: String


TbtkScriptEventBusObject
``````````````````````````````````````````````````````````````````````

.. pas:class:: TbtkScriptEventBusObject

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

  -  Шина событий предназначена для обмена сообщениями между выборками, в
     том числе не связанными отношением мастер-деталь.

  -  Шина событий является единой для всего приложения.

  -  Шина событий позволяет обеспечивать взаимодействие между выборками по
     принципам: один к одному, один ко многим, многие к одному и многие ко
     многим.

  -  Шина событий обеспечивает только однонаправленное взаимодействие,
     предназначенное, прежде всего, для оповещения о происходящих событиях
     и передачи связанных с этими событиями каких-либо данных.

  -  У каждого события передаваемого по Шине событий может быть как
     множество обработчиков, так и не быть ни одного обработчика вовсе.

  -  Обработчики событий не могут прерывать, отменять или изменять порядок
     вызова других обработчиков этих событий.

  -  Порядок вызова обработчиков событий не зависит от порядка их
     регистрации или каких-либо свойств обработчиков, и не может
     изменяться каким-либо образом. При отправке событий по Шине
     необходимо быть уверенным в том, что порядок вызова обработчиков не
     играет никакой роли, и не будет сказываться на работоспособности
     приложения.

  -  Возникновение исключений в обработчиках события не прерывает процесс
     вызова других обработчиков этого события.

  -  Шина событий не предоставляет возможности получить информацию об
     обработчиках подписанных на какое-либо событие и их количестве.

  .. pas:method:: Unhook(Selection: TbtkScriptSelectionObject; FilterArgs: TbtkNamedArgs=nil)

    Отписка от всех событий, ограниченных фильтром.

    :param TbtkScriptSelectionObject Selection:
      Выборка для которой осуществляется отписка.

    :param TbtkNamedArgs FilterArgs:
      Настройки фильтрации, для которых необходимо осуществить отписку.

    .. code-block:: delphi
      :caption: Пример использования

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


  .. pas:method:: Unsubscribe(Selection: TbtkScriptSelectionObject; TopicName: String; FilterArgs: TbtkNamedArgs=nil)

    Отписка от событий, по топику и фильтрам.

    :param TbtkScriptSelectionObject Selection:
      Выборка для которой осуществляется отписка.

    :param String TopicName:
      Имя подписки.

    :param TbtkNamedArgs FilterArgs:
      Настройки фильтрации, для которых осуществляется отписка.

    .. code-block:: delphi
      :caption: Пример использования

      <PASCAL>
        //отписка от события без дополнительных условий фильтрации.
        EventBus.Unsubscribe(Selection, 'TopicX');

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


  .. pas:method:: Hook(Selection: TbtkScriptSelectionObject; FilterArgs: TbtkNamedArgs=nil)

    Подписка на все события, ограниченные фильтром.

    :param TbtkScriptSelectionObject Selection:
      Выборка для которой осуществляется подписка.

    :param TbtkNamedArgs FilterArgs:
      Настройки фильтрации, для которых осуществляется подписка.

    .. code-block:: delphi
      :caption: Пример использования

      <PASCAL>
        EventBus.Hook(Selection); //подписка на все события передаваемые по шине.
        EventBus.Hook(Selection, CreateArgs(['EventName', 'TestEvent'])); //подписка на все события, ограниченные фильтром.
      </PASCAL>
      
    .. seealso:: :ref:`События шины, отправляемые клиентом Global<event_bus_events>`.


  .. pas:method:: Subscribe(Selection: TbtkScriptSelectionObject; TopicName: String; FilterArgs: TbtkNamedArgs=nil)

    Подписка на события для конкретного топика.

    :param TbtkScriptSelectionObject Selection:
      Выборка для которой осуществляется подписка.

    :param String TopicName:
      Имя подписки.

    :param TbtkNamedArgs FilterArgs:
      Настройки фильтрации, для которых осуществляется подписка.

    .. code-block:: delphi
      :caption: Пример использования

      <PASCAL>
        //подписка на событие без дополнительных условий фильтрации
        EventBus.Subscribe(Selection, 'TopicX');

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

    .. seealso:: :ref:`События шины, отправляемые клиентом Global<event_bus_events>`.
    
    
  .. pas:method:: Post(TopicName, EventName: String; EventArgs: TbtkNamedArgs=nil)

    Асинхронная отсылка сообщений.

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

    :param String TopicName:
      Имя подписки.

    :param String EventName:
      Имя отправляемого события.

    :param TbtkNamedArgs EventArgs:
      Аргументы события. Для создания и передачи аргументов можно использовать
      метод :pas:class:`TatInternalObject.CreateArgs`

    .. code-block:: delphi
      :caption: Пример использования

      <PASCAL>
        //отправка события без аргументов
        EventBus.Post('TopicName', 'EventName');

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


  .. pas:method:: Send(TopicName, EventName: String; EventArgs: TbtkNamedArgs=nil)

    Синхронная отсылка сообщений.

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

    :param String TopicName:
      Имя подписки.

    :param String EventName:
      Имя отправляемого события.

    :param TbtkNamedArgs EventArgs:
      Аргументы события. Для создания и передачи аргументов можно использовать
      метод :pas:class:`TatInternalObject.CreateArgs`

    .. code-block:: delphi
      :caption: Пример использования

      <PASCAL>
        //отправка события без аргументов
        EventBus.Send('TopicName', 'EventName');

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