Covellite.Events

Список классов проекта Events

Введение

Проект для кода работы с событиями фреймворка.

Подробнее

Классы проекта обеспечивают унификацию сообщений и их независимость от того, в какой операционной системе работает приложение.

Создание нового типа событий

Для создания пользовательского типа событий следует создать класс типа событий (в котором определить идентификаторы событий этого типа) и объявить объект нового типа событий (для удобства использования в этом же классе можно определить класс-контейнер параметров, передаваемых этому событию).

// Класс типа события.
class UserType_t final
{
public:
  // Идентификаторы событий.
  enum Id
  {
    Error = 0,
  };
    
public:
  // Класс параметров события Error.
  class Error final
  {
  public:
    int Code;
    ::std::string Description;
  };
};
  
// Вспомогательный объект для использования события UserType.Error (таким 
// способом достигается уникальность событий, имеющих одинаковые 
// имена/численные значения в разных классах, если же использовать просто
// UserType_t::Error, тип события будет соответствовать типу перечисления и 
// не будет являться уникальным).
namespace { UserType_t UserType; }

Заметки

Разные типы событий могут иметь одинаковые идентификаторы (как имена, так и значения), события с такими идентификаторами будут считаться разными событиями.

Создание класса, который должен реагировать на события

Классу, который должен реагировать на события, необходимо добавить объект класса covellite::events::Events и проинициализировать его в конструкторе, параметром которого может быть один из интерфейсных классов разделов (covellite::app::IApplication, covellite::os::IWindow, covellite::api::IWindow, covellite::rocket::IWindow).

В случае необходимости 'передать дальше' объект событий (например, если требуется встроить клиентсткий код между окнами графического Api и окном GUI, который должен отрисовывать что-либо перед отрисовкой GUI), класс cледует унаследовать от covellite::events::IEvents и реализовать его виртуальный оператор, вернув объект событий.

Заметки

Объект событий в классе хранит все созданные в нем соединения и разрывает их при уничтожении объекта класса (в случае необходимости изменения логики работы программы следует удалить существующий объект событий и создать новый, установив ему новые обработчики событий).

class Window final
{
private:
  covellite::events::Events m_Events;
    
public:
  explicit Window(const covellite::api::IWindow & _Window) :
    m_Events(_Window)
  {
    m_Events[UserType.Error].Connect([](const UserType_t::Error &)
    {
      // Сюда поместить код обработки события UserType.Error.
    });
  }
};

Активация события

Для активации события необходимо вызвать оператор () из функции любого класса, содержащего объект класса событий. В качестве параметра (который предусмотрен только один) может быть передан объект любого класса (тип должен совпадать с типом, указанным у обработчика, в противном случае будет сгенерировано исключение).

covellite::api::Window ApiWindow{ ... };
Window Window{ ApiWindow };
  
const UserType_t::Error Description = { 5, "Error description" }.
  
Window[UserType.Error](Description);

Рекомендации

• Большая часть событий самого фреймворка предназначены для обеспечения логики работы фреймворка и не должны активироваться из клиентского кода (клиентский код может только подписываться и реагировать на них, за редким исключением, например, события завершения работы программы Application.Exit), подробнее см. описание конкретных событий.
• Допускается из обработчика события активировать другие события, однако поскольку при этом возможно зацикливание программы (например, когда обработчик события активирует то же самое событие), рекомендуется из обработчика события активировать события более высокого уровня.
• Структура классов фреймворка создавалась в предположении, что каждый отдельный экран (слой, класс-наследник от covellite::rocket::Layer) программы будет являться отдельным View в рамках паттерна MVC и будет получать необходимые ему данные через Model, тем не менее (для прогресс-бара, например) возможна передача информации посредством специально для этого созданных сообщений, у которых эти данные будут передаваться в качестве параметров.