.. Автор: Артур Аюханов aka artbear, mailto: artbear@inbox.ru

.. include:: commonchm.txt


#####################################################################
Перехватчик
#####################################################################
..	<chminfo>
		<insert nodes="//common/maininfo/*"/>
		<alinks>_1cpp_hooker_</alinks>
		<klinks>
			Перехватчик
			Hooker
		</klinks>
	</chminfo>

.. contents:: Содержание
	:backlinks: none

**Класс "Перехватчик" / "Hooker".**

Специальный класс, предназначенный для перехвата предопределенных событий
1С и ВК FormEx, вызываемых для групповых контекстов и/или глобального модуля,
с помощью специальных объектов пользовательских классов 1С++.

**Версия: релиз 2.5 и выше.**

**Общая схема перехвата:**

0. Для использования перехвата должна быть включена настройка 1С++
" **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
См. `SettingsManager <SettingsManager.chm::/SettingsManager0.html>`_

1. Необходимо использовать пользовательский класс 1С++, в котором должны
быть определены **обработчики соответствующих событий с названием события**
(ПриЗакрытии, ПриНачалеВыбораЗначения, ПриЗавершенииРаботыСистемы) или
**со специальным названием в виде Событие_НаименованиеСобытия**
(Событие_ПриЗакрытии, Событие_ПриНачалеВыбораЗначения, Событие_ПриЗавершенииРаботыСистемы)

2. Каждый обработчик должен быть определен **с атрибутом Экспорт**, иначе
перехват указанного события будет невозможен.

Например, для перехвата событий ПриЗакрытии и ПриНачалеВыбораЗначения в
классе-перехватчике необходимо написать

	Процедура ПриЗакрытии() Экспорт
	 	// текст обработчика события

	КонецПроцедуры

	Процедура ПриНачалеВыбораЗначения(НужныеПараметры и т.д.) Экспорт
	 	// текст обработчика события

	КонецПроцедуры

Или для перехвата события ПриЗавершенииРаботыСистемы в
классе-перехватчике необходимо написать

	Процедура ПриЗавершенииРаботыСистемы() Экспорт
		// текст обработчика события

	КонецПроцедуры

3. Для включения перехвата конкретного контекста формы нужно использовать
код

	+ ОбъектПерехватчикГК = СоздатьОбъект("КлассПерехватчикГК");
    + Перехватчик = СоздатьОбъект("Перехватчик");
	+ Перехватчик. ПерехватитьСобытияГК_ (КонтФормы, ОбъектПерехватчикГК);

	или

	+ Перехватчик. ПерехватитьСобытияГлобальногоМодуля_ (ОбъектПерехватчикГК);

4. В перехваченном контексте или перехваченном глобальном модуле
**обработчики событий могут вообще отсутствовать или быть определены без
атрибута Экспорт**.

5. После установки перехвата при вызове системой события
управление   будет   передано   в   соответствующий   обработчик   события    в
классе-перехватчике.
В этом случае встроенные обработчики предопределенных событий в
перехваченном контексте или глобальном модуле автоматически вызываться не
будут.
Разработчик сам должен вызвать данные обработчики (см. п.7), когда это
необходимо.

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

	+ ОбъектПерехватчикСобытийГлобальногоМодуля = СоздатьОбъект("КлассПерехватчикСобытийГлобальногоМодуля");
	+ Перехватчик = СоздатьОбъект("Перехватчик");
	+ Перехватчик. ПерехватитьСобытияГлобальногоМодуля_ (ОбъектПерехватчикСобытийГлобальногоМодуля);

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

	Процедура ПриЗакрытии() Экспорт

	+	Перехватчик = СоздатьОбъект("Перехватчик");
	+	СписокАргументов = СоздатьОбъект("СписокЗначений");
	+	Перехватчик. ВызватьОригинальноеСобытиеГК_ (КонтПерехваченнойФормы, "ПриЗакрытии", СписокАргументов);

	КонецПроцедуры

или

	Процедура ПриЗавершенииРаботыСистемы() Экспорт

	+	Перехватчик = СоздатьОбъект("Перехватчик");
	+	СписокАргументов = СоздатьОбъект("СписокЗначений");
	+	Перехватчик. ВызватьОригинальноеСобытиеГК_ (КонтПерехваченнойФормы, "ПриЗавершенииРаботыСистемы", СписокАргументов);

	КонецПроцедуры

При этом неважно, существует ли обработчик в модуле формы или глобальном модуле.

8. **Важно помнить, что после установки перехвата на контекст формы или глобальный модуль
на пользовательский объект-перехватчик добавляется еще одна ссылка.**
В результате деструктор данного объекта-перехватчика будет вызван только
при закрытии формы или завершении работы 1С соответственно или снятии
перехвата вручную.

Например, код

	+ ОбъектПерехватчикГК = СоздатьОбъект("КлассПерехватчикГК");
	+ Перехватчик = СоздатьОбъект("Перехватчик");
	+ Перехватчик. ПерехватитьСобытияГК_ (КонтФормы, ОбъектПерехватчикГК);
	+ ОбъектПерехватчикГК = 0;

не вызывет деструктор немедленно!

9. **Все вышесказанное относится также и к предопределенным событиям ВК FormEx.**

=====================================================================
Методы
=====================================================================
..	<chminfo split="0" splitchild="1">
		<insert nodes="//common/propsmethods/*"/>
	</chminfo>

.. _ПерехватитьСобытияГК:

ПерехватитьСобытияГК / HookEventsOfGroupContext
------------------------------------------------

    **Синтаксис:** ПерехватитьСобытияГК(ГрупповойКонтекстФормы, ОбъектПользовательскогоКлассаОбработчикаПерехвата)

	**Параметры:**
		- **ГрупповойКонтекстФормы** - тип: ГрупповойКонтекст.
        - **ОбъектПользовательскогоКлассаОбработчикаПерехвата**  -  тип:  Класс КОП.

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

    **Описание:** Перехватывает любые предопределенные события контекста формы, как 1С, так и FormEx.
    Снять перехват можно с использованием метода СнятьПерехватСобытийГK_ .

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если первый параметр не является групповым контекстом, выдается исключение.
    В случае, если второй параметр не является пользовательским классом, выдается исключение.

.. _ВызватьОригинальноеСобытиеГК:

ВызватьОригинальноеСобытиеГК / CallOriginalEventOfGroupContext
---------------------------------------------------------------
    **Синтаксис:** ВызватьОригинальноеСобытиеГК(ГрупповойКонтекстФормы, ИмяСобытия, СписокАргументов)

	**Параметры:**
		- **ГрупповойКонтекстФормы** - тип: ГрупповойКонтекст.
        - **ИмяСобытия**  -  тип:  Строка.
		- **СписокАргументов** - тип: СписокЗначений. Список аргументов для данного события.

    **Описание:** Вызывает обработчик события контекста формы, который опреден в модуле этой формы.
    Если обработчика в форме не существует, ошибки не выдается.

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если первый параметр не является групповым контекстом, выдается исключение.
    В случае, если второй параметр не является строкой или строка пуста, выдается исключение.
    В случае, если третий параметр не является списком значений, выдается исключение.

.. _ПолучитьПерехватчикСобытийГК:

ПолучитьПерехватчикСобытийГК / GetHookObjectForEventsOfGroupContext
--------------------------------------------------------------------
    **Синтаксис:** ПолучитьПерехватчикСобытийГК(ГрупповойКонтекстФормы)

	**Параметры:**
		- **ГрупповойКонтекстФормы** - тип: ГрупповойКонтекст.

	**Возвращает:** тип: объект КОП, если для данной формы был включен
	перехват или Неопределено, если нет.

    **Описание:** Возвращает объект-перехватчик событий, если для данной
    формы был включен перехват.

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если параметр не является групповым контекстом, выдается исключение.

.. _СнятьПерехватСобытийГK:

СнятьПерехватСобытийГK / UnHookEventsOfGroupContext
-----------------------------------------------------------------------------------
    **Синтаксис:** СнятьПерехватСобытийГK(ГрупповойКонтекстФормы)

	**Параметры:**
		- **ГрупповойКонтекстФормы** - тип: ГрупповойКонтекст.

    **Описание:** Снимает перехват событий контекста формы, если перехват был
	установлен для данной формы.

	Если на пользовательский объект-перехватчик больше нет ссылок, будет
	вызван деструктор данного объекта.

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если параметр не является групповым контекстом, выдается исключение.

.. _ПерехватитьСобытияГлобальногоМодуля:

ПерехватитьСобытияГлобальногоМодуля / HookEventsOfGlobalModule
--------------------------------------------------------------------
    **Синтаксис:** ПерехватитьСобытияГлобальногоМодуля(ОбъектПользовательскогоКлассаОбработчикаПерехвата)

	**Параметры:**
        - **ОбъектПользовательскогоКлассаОбработчикаПерехвата**  -  тип:  Класс КОП.

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

    **Описание:** Перехватывает любые предопределенные события глобального модуля, как 1С, так и FormEx.
    Снять перехват можно с использованием метода СнятьПерехватСобытийГлобальногоМодуля_ .

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если переданный параметр не является пользовательским классом, выдается исключение.

.. _ВызватьОригинальноеСобытиеГлобальногоМодуля:

ВызватьОригинальноеСобытиеГлобальногоМодуля / CallOriginalEventOfGlobalModule
------------------------------------------------------------------------------
    **Синтаксис:** ВызватьОригинальноеСобытиеГлобальногоМодуля(ИмяСобытия, СписокАргументов)

	**Параметры:**
        - **ИмяСобытия**  -  тип:  Строка.
		- **СписокАргументов** - тип: СписокЗначений. Список аргументов для данного события.

    **Описание:** Вызывает обработчик события глобального модуля, который опреден в глобальном модуле.
    Если обработчика в глобальном модуле не существует, ошибки не выдается.

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
    В случае, если первый параметр не является строкой или строка пуста, выдается исключение.
    В случае, если второй параметр не является списком значений, выдается исключение.

.. _ПолучитьПерехватчикСобытийГлобальногоМодуля:

ПолучитьПерехватчикСобытийГлобальногоМодуля / GetHookObjectForEventsOfGlobalModule
-----------------------------------------------------------------------------------
    **Синтаксис:** ПолучитьПерехватчикСобытийГлобальногоМодуля()

	**Возвращает:** тип: объект КОП, если был включен
	перехват событий глобального модуля или Неопределено, если нет.

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

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.

.. _СнятьПерехватСобытийГлобальногоМодуля:

СнятьПерехватСобытийГлобальногоМодуля / UnHookEventsOfGlobalModule
-----------------------------------------------------------------------------------
    **Синтаксис:** СнятьПерехватСобытийГлобальногоМодуля()

    **Описание:** Снимает перехват событий глобального модуля, если перехват был
	установлен.

	Если на пользовательский объект-перехватчик больше нет ссылок, будет
	вызван деструктор данного объекта.

    Если настройка 1С++ " **ПерехватитьСобытияГК / EnableHookEventsGroupContext** "
    не включена, будет выдано исключение.
