Практическое руководство. Обработка событий форм

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

Обработчики событий InfoPath необходимо всегда создавать в режиме конструктора, поскольку приложение InfoPath автоматически добавляет правильное описание для принятия события в метод InternalStartup и вставляет структуру кода обработчика событий в файл кода формы (FormCode.cs или FormCode.vb). После создания обработчика событий не следует изменять его объявление в файле кода формы.

Сведения о создании обработчиков событий InfoPath см. в статье Практическое руководство. Добавление обработчика событий.

Обзор классов событий

Модель InfoPath, предоставляемая пространством имен Microsoft.Office.InfoPath, внедряет три класса, реализующих 12 событий, которые можно вызвать и обработать с помощью бизнес-логики шаблона формы. В следующей таблице перечисляются все объекты событий InfoPath, объекты, с которыми они связываются, а также описания предоставляемых ими возможностей.

Имя	События	Описание
ButtonEvent	Clicked	Класс ButtonEvent внедряет событие Clicked, вызываемое при щелчке элемента управления Кнопка в форме.
FormEvents	ContextChanged Loading Merge Save Sign Submit VersionUpgrade ViewSwitched	Класс FormEvents внедряет события, специфичные для самого шаблона формы InfoPath: ContextChanged Возникает после изменений контекстных узлов. Loading Возникает после загрузки шаблона формы, но до инициализации каких-либо представлений. Merge Возникает при вызове команды Объединить формы из интерфейса пользователя, либо при запуске InfoPath с параметром командной строки /aggregate. Save Возникает при использовании команд Сохранить и Сохранить как из интерфейса пользователя, либо при использовании методов Save и SaveAs класса XmlForm. Sign Возникает после выбора набора пописываемых данных для подписания в диалоговом окне Цифровые подписи. Submit Возникает при использовании команды Отправить из интерфейса пользователя, либо при использовании метода Submit класса XmlForm. VersionUpgrade Возникает, когда номер версии открываемой формы меньше номера версии исходного шаблона формы. ViewSwitched Возникает после успешного переключения представления формы.
XmlEvent	Changed Changing Validating	Внедряет события, порождаемые изменениями данных в базовом XML-документе экземпляра формы: Changed Возникает после принятия изменений в базовом XML-документе формы и после возникновения события Validating. Changing Возникает после внесения изменений в базовый XML-документ формы, но до принятия этих изменений. Validating Возникает после принятия изменений в базовом XML-документе формы, но до возникновения события Changed. Класс XmlEvent также внедряет свойство RaiseUndoRedoForChanged, которое возвращает или задает вызов события Changed при совершении операции отмены или повтора действия.

Заметка

События Changed и Changing происходят только один раз при внесении изменений в непустое поле формы, а сравнимые события в InfoPath 2003 и объектной модели, совместимой с InfoPath 2003, предоставляемые пространством имен Microsoft.Office.Interop.InfoPath.SemiTrust (OnBeforeChange и OnAfterChange), при изменениях непустого поля активируются дважды: один раз при удалении старого значения и повторно при вставке нового значения.

Обзор класса EventArgs

Каждое из 12 событий использует объект EventArgs, связанный с событием и передаваемый обработчику соответствующих событий для предоставления сведений о состоянии и других возможностей, которые можно использовать в коде обработчика событий. В следующей таблице перечисляются события InfoPath с соответствующими им объектами EventArgs и краткие описания возможностей, предоставляемых свойствами и методами каждого объекта. Подробные сведения о конкретных свойствах и методах объектов можно вызвать, щелкнув имя объекта EventArgs в таблице, а затем щелкнув ссылку "Элементы" в теме.

Событие	Класс EventsArgs	Описание
Clicked	ClickedEventArgs	Возвращает идентификатор элемента управления. Возвращает объект XPathNavigator, располагающийся в наиболее вложенном XML-узле базового XML-документа формы, содержащего элемент управления Кнопка.
ContextChanged	ContextChangedEventArgs	Возвращает тип изменения контекста, выполняемого при возникновении события. Возвращает значение, указывающее, возникает ли событие изменения контекста в ответ на операцию отмены или повтора действия. Возвращает ссылку на объект XPathNavigator, расположенный в контекстном узле, породившем событие.
Loading	LoadingEventArgs	Указывает представление для открытия формы после загрузки. Возвращает ссылку на объект XmlFormCancelEventArgs. Возвращает объект IDictionary, содержащий все входные параметры, указанные с помощью параметра командной строки /InputParameters или с помощью параметров запроса в URL-адресе для открытия формы.
Merge	MergeEventArgs	Возвращает ссылку на объект XmlFormCancelEventArgs. Возвращает количество форм, объединенных в операции объединения. Возвращает индекс объединяемой в данный момент формы (начиная с нуля). Возвращает или задает значение, которое используется с свойством Cancel для определения выбора отмены только текущей формы или всей операции объединения. Возвращает объект XPathNavigator, расположенный в корневом узле базового XML-документа объединяемой в данный момент формы.
Save	SaveEventArgs	Выполняет запрошенную пользователем операцию сохранения. Возвращает ссылку на объект SaveCancelEventArgs, который можно использовать для отмены события. Возвращает имя файла для использования в обработчике событий применительно к данному событию. Возвращает выбор для операции сохранения: "сохранить" или "сохранить как".
Sign	SignEventArgs	Возвращает или задает факт отображения диалогового окна Цифровые подписи. Возвращает набор подписываемых данных, порождаемых событием.
Submit	SubmitEventArgs	Возвращает ссылку на объект XmlFormCancelEventArgs для отмены события.
VersionUpgrade	VersionUpgradeEventArgs	Возвращает ссылку на объект XmlFormCancelEventArgs для отмены события. Возвращает номер версии обновляемого документа формы. Возвращает номер версии шаблона формы, связанного с обновляемой формой.
ViewSwitched	ViewSwitchedEventArgs	Класс ViewSwitchedEventArgs не предоставляет свойств и методов для событий, отличных от наследуемых из объекта System.Object.
Changed	XmlEventArgs	Возвращает объект XPathExpression, содержащий выражение XPath, которое возвращает изменяемый в данный момент узел. Возвращает новое значение изменяемого узла. Возвращает объект XPathNavigator, указывающий на узел, являющийся родительским для удаляемого узла. Возвращает исходное значение изменяемого узла. Возвращает номер XmlOperation, указывающую тип операции, возникшей при изменении узла. Возвращает объект XPathNavigator, указывающий на изменяемый узел. Возвращает значение, указывающее, является ли изменяемый узел компонентом операции отмены или повтора действия.
Changing	XmlChangingEventArgs	Возвращает объект XmlFormCancelEventArgs, связанный с событием. Наследует все возможности, перечисленные выше для объекта XmlEventArgs.
Validating	XmlValidatingEventArgs	Создает объект FormError, содержащий настраиваемые сведения об ошибках с указанными значениями, и добавляет его в объект FormErrorCollection в форме. Наследует все возможности, перечисленные выше для объекта XmlEventArgs.

Использование объектов EventArgs

При создании обработчика событий приложение InfoPath создает объявление обработчика событий в коде формы проекта. В объявлении обработчика событий приложение InfoPath использует e в качестве имени параметра, передаваемого обработчику событий. Этот параметр содержит объект EventArgs, который связан с обработчиком событий и используется для предоставления сведений о состоянии и других возможностей при возникновении события.

Например, при создании обработчика событий Loading в режиме конструктора (что осуществляется путем последовательного выбора в меню Сервис пунктов Программирование и Событие Loading) приложение InfoPath добавляет объявление обработчика событий, получающего объект LoadingEventArgs из файла кода формы, а затем открывает редактор кода, чтобы предоставить возможность добавить пользовательский код в данное объявление обработчика событий.

public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
   // Write your code here.
}

Public Sub FormEvents_Loading(ByVal sender As Object, _
   ByVal e As LoadingEventArgs)
   ' Write your code here.
End Sub

При написании кода для обработчика событий можно использовать свойства и методы, реализуемые объектом EventArgs, который передается через параметр e. Например, в следующем обработчике событий Changing свойство NewValue объекта XmlChangingEventArgs (который наследуется из класса XmlEventArgs) используется для проверки значения только что измененного поля. Если пользователь изменил поле и оставил его пустым, то предоставляется доступ к свойству Message класса XmlFormCancelEventArgs с помощью свойства CancelableArgs объекта XmlChangingEventArgs для отображения пользователю ошибки, а для свойства XmlFormCancelEventArgs.Cancel устанавливается значение true для отмены события и отката внесенных пользователем изменений.

public void field1_Changing(object sender, LoadingEventArgs e)
{
   // Determine whether there is a new value.
   if (e.NewValue == "")
   {
      // The value is blank, so display an error message
      // and roll back the changes.
      e.CancelableArgs.Message = 
         "You must supply a value for this field.";
      e.CancelableArgs.Cancel = true;
      return;
   }
}

Public Sub field1_Changing(ByVal sender As Object, _
   ByVal e As LoadingEventArgs)

   ' Determine whether there is a new value.
   If (e.NewValue = "") Then
      ' The value is blank, so display an error message 
      ' and roll back the changes.
      e.CancelableArgs.Message = _
         "You must supply a value for this field."
      e.CancelableArgs.Cancel = True
      Return
   End If
End Sub