<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="dispatch.xsl" ?>
<Object name="Macro" project="SuperEdi">
  
  <Title>Macro Object</Title>
  
  <Description>Represents an add-in that is executed in SuperEdi.
    Add-ins are installed by setting a few registry keys.
    HKEY_CURRENT_USER\Software\WoLoSoft\SuperEdi\Macros\&lt;add-in name&gt;
    FileName (REG_SZ) specifies the full path name of the add-in file.
    Startup (REG_BINARY) specifies if the add-in is started automatically.
  </Description>
  
  <KeyWords>Macro, AddIn, AddCode, Create, Dispatch, Enabled, FileName,
    Name, Startup
  </KeyWords>

  <!-- properties -->

  <Property name="Dispatch"  type="IDispatch" write="no">
    <Description>Returns the dispatch interface of the current add-in.
       The Dispatch object provides access to variables and functions that
       are defined within the add-in. Scripts can use this object
       to query status information from the add-in or they can call
       functions that are provided by the add-in.</Description>
  </Property>

  <Property name="Enabled"  type="boolean">
    <Description>Returns or sets if the current add-in is running.
    </Description>
  </Property>
  
  <Property name="FileName"  type="string">
    <Description>Returns the file name from which the current add-in
      has been loaded. The file name property is empty when the add-in
      was initialized with the Create method. Changing the
      file name will unload the current add-in and load the new add-in
      from the specified file. The script language will be determined
      from the file extension. Therefore you should use the extensions
      .vbs for VBScript, .js for JScript or .pls for PerlScript.
      The add-in will be be disabled by default when it's loaded from a
      file. It can be enabled by setting the Enabled property to true.
    </Description>
  </Property>

  <Property name="Name"  type="string" write="no">
    <Description>Returns the name of the add-in.</Description>
  </Property>

  <Property name="Startup"  type="boolean">
    <Description>Returns or sets if the add-in is started automatically by 
      SuperEdi.
    </Description>
  </Property>

  <!-- methods -->

  <Method name="AddCode">
    <Description>Adds a piece of script code to the add-in. Specify the script
      language usng the Create method before the first call to AddCode.
      This method adds additional code to the already existing 
      add-in. It does not replace it. The code must be written in the scripting 
      language that was set by Create and it should be tested for syntactical
      correctness before calling AddCode.
    </Description>
    <Syntax>macro.AddCode( code )</Syntax>
    <Parameter name="code" type="string">
      <Description>script code written in the language that was set by Create</Description>
    </Parameter>
  </Method>
  
  <Method name="Create">
    <Description>Creates a new add-in and removes any previous code. Call this
      method before adding source code to the add-in with AddCode. The add-in is
      initially disabled. To enable it, set the Enabled property to true.
    </Description>
    <Syntax>macro.Create( language )</Syntax>
    <Return type="boolean" />
    <Parameter name="language" type="string">
      <Description>scripting language name, for example, VBScript, JScript or PerlScript.</Description>
    </Parameter>
  </Method>

  <Example language="JScript">
var macro = Application.Macros.Add("Test");
macro.Create( "VBScript" );
var code = "Sub Application_Shutdown()\n";
code    += "  Application.MessageBox \"Shutdown\"\n"
code    += "End Sub\n";
macro.AddCode( code );
macro.Enabled = true;
  </Example>

</Object>