This script is used to specify additional settings in the Setup dialog that appears the first time the user runs Stonefield Query. With this script, you can add your own custom settings. Stonefield Query doesn't use these settings, but another of your scripts could, by calling either the GetRegistryValue or GetINIValue methods of the Application object (depending on where you decide to store the value) to retrieve the setting and then doing something with it.

You can validate the values the user enters in your custom settings by creating a Setup.Validate script, and receive notification about changes when the user clicks the Finish button by creating a Setup.Changed script.

You may want to allow the user to change the values for these settings in the Options dialog. In that case, use the same code you have in Setup.Settings in an Options.Settings script to have the custom settings appear in the Options dialog as well. The best way to do that is to create a user-defined script with the necessary code and call that script from both Options.Settings and Setup.Settings.

Parameters
A reference to the Stonefield Query Application object.

Return Value
An XML string defining the settings to display in the Setup dialog. The format for the XML is as follows:

<settings>
      <setting>
        <page>Page to display setting on</page>
        <description>Setting description</description>
        <caption>Caption for control</caption>
        <type>Type of control</type>
        <key>Registry key</key>
        <left>Left position of the control</left>
        <top>Top position of the control</top>
        <default>Default value</default>
        <encryptkey>Key to use for encryption</encryptkey>
        <filetype>File type</filetype>
        <filedesc>File type description</filedesc>
        <script>Script name</script>
        <restart>Yes or No</restart>
        <storage>i or Registry</storage>
      </setting>
      <setting>
        <page>Page to display setting on</page>
        <description>Setting description</description>
        <caption>Caption for control</caption>
        <type>Type of control</type>
        <key>Registry key</key>
        <left>Left position of the control</left>
        <top>Top position of the control</top>
        <default>Default value</default>
        <encryptkey>Key to use for encryption</encryptkey>
        <filetype>File type</filetype>
        <filedesc>File type description</filedesc>
        <script>Script name</script>
        <restart>Yes or No</restart>
        <storage>Data or Registry</storage>
      </setting>
      ...
</settings>

The following elements are available:

• page: the page the setting should appear on. If not specified, each option appears on its own page titled "Additional Settings n", where "n" indicates the additional settings page number. Otherwise, the value specified creates a custom page with that name.

• description: the description for the setting. This description appears at the top of the custom page to provide instructions to the user about what the setting is for. If several controls appear on the same page, only the description from the first setting is used. This element is optional.

• caption: the caption for the control (for example, "Location of AR data" in the image above).

• type: the type of data entry control used for this setting. The choices are:

  • Checkbox: indicates the setting is a Yes/No value and a check box is used.

  • Textbox: indicates the setting is a string and a text box is used.

  • Password: indicates the setting is a string that should be stored as an encrypted value. A text box is used and characters entered by the user are displayed as "*".

  • Directory: use this value when the setting is a directory name; a text box with a button the user can click to display existing directories is used.

  • File: this value means the setting is a file name; a text box with a button the user can click to display file names is used.

  • Dropdown: indicates a drop-down control is used, filled with values returned from the user script specified in the "script" element. Note that the script specified must accept a parameter (a reference to SQApplication).

• key: the Registry key under HKEY_CURRENT_USER\Software\CompanyName\ApplicationName\Options (where CompanyName and ApplicationName are the values of the Company Name and Application Name configuration settings) that holds the value for the setting. Alternatively, if you're storing values in Data.ini, this is the key value under the Options section.

• left: the left position (in pixels, measured from the left edge of the dialog) of the control for this setting. Specify 0 or omit this element to place the control at the next available position.

• top: the top position (in pixels, measured from the top edge of the dialog) of the control for this setting. Specify 0 or omit this element to place the control at the next available position.

• default: the default value for the setting. This element is optional.

• encryptkey: the key to use to encrypt the value if "Password" is specified for the type element. This element may be omitted (and is ignored if it's included) for other types.

• filetype: the type of file to use, specified as "*." followed by the extension (for example, " *.ini"), if type is "File." This element may be omitted (and is ignored if it's included) for other types.

• filedesc: the description for the file type, such as "INI Files (*.ini)", if type is "File." This element may be omitted (and is ignored if it's included) for other types.

• script: the name of a script that returns XML specifying the options for a drop-down list, if type is "Dropdown;" this element may be omitted (and is ignored if it's included) for other types. The script must accept a parameter (a reference to the SQApplication object) and return an XML string with the following format:

    <values>
          <value>first value to display</value>
          <value>second value to display</value>
          ...
    </values>
  

• restart: this setting is ignored if used in Setup.Settings.

• storage: specify "Data" for the value to tell Stonefield Query to store this setting in Data.ini in the Data subdirectory of the Stonefield Query program folder (meaning it's global for all users). Omit this element or specify "Registry" to store the setting in the Windows Registry (meaning it's user-specific).

Example
See the examples in Options.Settings. Note that although "restart" is specified, since this is the same script used by Options.Settings, it's ignored in this case.