1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
|
<html dir="ltr"><head>
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">
<META HTTP-EQUIV="assetid" CONTENT="HV01039911"><META NAME="lcid" CONTENT="1033"><title>Responding to form events</title><link rel="stylesheet" type="text/css" href="office10.css"><script type="text/javascript" language="Javascript" src="ExpCollapse.js"></script><script type="text/javascript" language="JavaScript" src="inline.js"></script></head><body><p id="ExpandAllLine" class="ExpFav"><a href="#" onclick="ExpandAll()" onkeypress="ExpandAll()" class="DropDown"><img id="picHeader" border="0" src="expandtri.gif" alt="Show All"><span id="ExpandAll">Show All</span></a></p><h1>Responding to form events</h1><div class="ofvbanav"><span class="ofvbanavreuse" id="seealso" onclick="toggleList()" onkeypress="toggleList()"></span><span class="ofvbanavreuse" id="specifics" onclick="toggleList()" onkeypress="toggleList()"></span></div><p>You can write scripting code to respond to various events that can occur in Microsoft Office InfoPath 2003 as a user fills out a form. In InfoPath, events take the form of <a href="#" class="glossary" onclick="AppendPopup(this,'xdeventhandler')" onkeypress="AppendPopup(this,'xdeventhandler')">event handlers</a> that are created when working with a form in <a href="#" class="glossary" onclick="AppendPopup(this,'xddesignmode')" onkeypress="AppendPopup(this,'xddesignmode')">design mode</a>.</p><p>InfoPath event handlers must be initially created in design mode because, in addition to the scripting declarations that are created in a form's primary scripting file, entries are also made in the <a href="#" class="glossary" onclick="AppendPopup(this,'xdformdefinitionfilexsf')" onkeypress="AppendPopup(this,'xdformdefinitionfilexsf')">form definition (.xsf) file</a>. After you have created an event handler, you should not alter its declaration in the primary scripting file.</p><p>For information about creating the InfoPath event handlers, see <a href="inconAboutTheProgrammingEnvironment.htm" id="HV01039182" lcid=" ">About the programming environment</a>.</p><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Overview of the event objects</a></p><div id="ExpCol" class="collapsed" border="0"><p>The InfoPath object model implements nine event objects; the event object you use is determined by the event handler you use. The following table lists each of the InfoPath event objects, the event handlers they are associated with, and a description of the functionality they provide.</p><table><tr><th>Name</th><th>Event handlers</th><th>Description</th></tr><tr><td><b class="bterm"><a href="xdobjDataDOMEvent.htm" id="HV01021239" lcid=" ">DataDOMEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnBeforeChange.htm" id="HV01021368" lcid=" ">OnBeforeChange</a></b>, <b class="bterm"><a href="xdevtOnValidate.htm" id="HV01021372" lcid=" ">OnValidate</a></b>, <b class="bterm"><a href="xdevtOnAfterChange.htm" id="HV01021366" lcid=" ">OnAfterChange</a></b></td><td>Returns a reference to a form's underlying XML document, the return status, and other properties that contain information about the XML node during an XML <a href="#" class="glossary" onclick="AppendPopup(this,'ofdocumentobjectmodeldom')" onkeypress="AppendPopup(this,'ofdocumentobjectmodeldom')">Document Object Model (DOM)</a> change. Also includes a method for raising an error.</td></tr><tr><td><b class="bterm"><a href="xdobjDocActionEvent.htm" id="HV01021240" lcid=" ">DocActionEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnClick.htm" id="HV01027661" lcid=" ">OnClick</a></b></td><td>Returns a reference to a form's underlying XML document, the return status, and the source XML node during a button click in the form area.</td></tr><tr><td><b class="bterm"><a href="xdobjDocContextChangeEventObject_HV01104103.htm" id="HV01104103" lcid=" ">DocContextChangeEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnContextChange_HV01104102.htm" id="HV01104102" lcid=" ">OnContextChange</a></b></td><td>Returns information about the XML Document Object Model (DOM) node that is the current context of the form's underlying XML document.</td></tr><tr><td><b class="bterm"><a href="xdobjDocEvent.htm" id="HV01021241" lcid=" ">DocEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnSwitchView.htm" id="HV01021371" lcid=" ">OnSwitchView</a></b>, <b class="bterm"><a href="xdevtOnAfterImport.htm" id="HV01021367" lcid=" ">OnAfterImport</a></b></td><td>Returns a reference to a form's underlying XML document during a switch view or form merge operation.</td></tr><tr><td><b class="bterm"><a href="xdobjDocReturnEvent.htm" id="HV01021242" lcid=" ">DocReturnEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnLoad.htm" id="HV01021369" lcid=" ">OnLoad</a></b>, <b class="bterm"><a href="xdevtOnSubmitRequest.htm" id="HV01021370" lcid=" ">OnSubmitRequest</a></b></td><td>Returns a reference to a form's underlying XML document and the return status during the loading or submission of a form.</td></tr><tr><td><b class="bterm"><a href="xdobjMergeEventObject_HV01104134.htm" id="HV01104134" lcid=" ">MergeEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnMergeRequest_HV01104132.htm" id="HV01104132" lcid=" ">OnMergeRequest</a></b></td><td>Returns properties and methods that can be used during an <b class="bterm">OnMergeRequest</b> event to programmatically interact with a form's underlying XML document and to determine merge properties such as the number of files being merged.</td></tr><tr><td><b class="bterm"><a href="xdobjSaveEventObject_HV01104135.htm" id="HV01104135" lcid=" ">SaveEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnSaveRequest_HV01104133.htm" id="HV01104133" lcid=" ">OnSaveRequest</a></b></td><td>Returns a number of properties and methods that can be used during a save operation from the OnSaveRequest event handler to programmatically interact with a form's underlying XML document, determine save properties, and perform the save operation.
</td></tr><tr><td><b class="bterm"><a href="xdobjSignEventObject_HV01104076.htm" id="HV01104076" lcid=" ">SignEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnSign_HV01104072.htm" id="HV01104072" lcid=" ">OnSign</a></b></td><td>Used to add additional data to the digital signature.</td></tr><tr><td><b class="bterm"><a href="xdobjVersionUpgradeEvent.htm" id="HV01021248" lcid=" ">VersionUpgradeEvent</a></b> object</td><td><b class="bterm"><a href="xdevtOnVersionUpgrade.htm" id="HV01021373" lcid=" ">OnVersionUpgrade</a></b></td><td>Returns a reference to a form's underlying XML document, the return status, and the document and solution version numbers during the version upgrade operation.</td></tr></table></div><p><a href="#" class="DropDown" onclick="Outline2()" onkeypress="Outline2()"><img border="0" src="blueup.gif" alt="Show">Using the event objects</a></p><div id="ExpCol" class="collapsed" border="0"><p>As mentioned previously, when you create an event handler, InfoPath creates the event handler's declaration in the form's primary scripting file. In the declaration of the event handler, InfoPath uses <b class="bterm"><i>eventObj</i></b> as the name of the parameter that is passed to the event handler. This parameter contains the event object that is associated with the event handler. For example, when you create the OnLoad event in design mode, InfoPath creates the OnLoad event handler in the scripting file, and then opens the <a href="#" class="glossary" onclick="AppendPopup(this,'xdmicrosoftscripteditormse')" onkeypress="AppendPopup(this,'xdmicrosoftscripteditormse')">Microsoft Script Editor (MSE)</a> so that you can add your scripting code to the following event handler declaration:</p><pre><code>//=======
// The following function handler is created by Microsoft Office InfoPath.
// Do not modify the name of the function or the name and number of arguments.
//=======
function XDocument::OnLoad(eventObj)
{
// Write your code here.
}</code></pre><p>When writing scripting code for an event handler, you can use the properties and methods implemented by the event object that is passed through the <b class="bterm"><i>eventObj</i></b> parameter. For example, in the following <b class="bterm">OnBeforeChange</b> event handler, the <b class="bterm"><a href="xdproNewValue.htm" id="HV01021312" lcid=" ">NewValue</a></b> property of the <b class="bterm">DataDOMEvent</b> event object is used to check the value of the field that was just changed. If it is blank, the <b class="bterm"><a href="xdproReturnMessage.htm" id="HV01021325" lcid=" ">ReturnMessage</a></b> property of the <b class="bterm">DataDOMEvent</b> event object is used to display an error to the user in a dialog box, and the <b class="bterm"><a href="xdproReturnStatus_1.htm" id="HV01021327" lcid=" ">ReturnStatus</a></b> property is set to false, indicating that the changes the user made should not be accepted.</p><pre><code>function msoxd__myField_attr::OnBeforeChange(eventObj)
{
// Determine whether there is a new value.
if (eventObj.NewValue == "")
{
// The value is blank, so display an error message and roll back the changes.
eventObj.ReturnMessage = "You must supply a value for this field.";
eventObj.ReturnStatus = false;
return;
}
}</code></pre><p><b>Note</b> Each of the InfoPath event objects implements different properties and methods. For more information about a particular event object, click the appropriate object in the preceding table.</p></div><script type="text/javascript" language="JScript" src="ofvbanl.js"></script><span id="ofVBAISpan" class="ofvbaispan"><iframe id="ofVBAIFrame" frameborder="0" marginheight="0" marginwidth="4" scrolling="auto" width="100%" src="../links/inconRespondingToFormEvents_l.htm"></iframe></span><center><a href="XMLSchemaCopyright_HV01147162.htm">©2003-2004 Microsoft Corporation. All rights reserved.</a>
Permission to copy, display and distribute this document is available at: <a
href="http://r.office.microsoft.com/r/rlidAWSContentRedir?AssetID=XT010988631033&CTT=11&Origin=HV011232471033"
target="_new">http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp</a></center></body></html>
|
