Adobe Illustrator CS4 Scripting
ReadMe File

______________________________________________________________________

This file has the following sections:
  1. Introduction
  2. Documentation
  3. Sample Scripts
  4. Known Issues
  5. SDK Support and Adobe Partner Programs


***********************************************************
1. Introduction
***********************************************************
To find out what's new in Illustrator CS4 scripting, see
"Adobe Illustrator CS4 Scripting Guide."

To find the latest available information on scripting 
Illustrator, go to:

  http://www.adobe.com/devnet/illustrator/


***********************************************************
2. Documentation
***********************************************************
Adobe Illustrator CS4 Scripting Guide
  File: Illustrator Scripting Guide.pdf

Adobe Illustrator CS4 Scripting Reference: AppleScript
  File: Illustrator Scripting Reference - AppleScript.pdf

Adobe Illustrator CS4 Scripting Reference: JavaScript
  File: Illustrator Scripting Reference - JavaScript.pdf

Adobe Illustrator CS4 Scripting Reference: VBScript
  File: Illustrator Scripting Reference - VBScript.pdf

Adobe Introduction to Scripting
  File: Adobe Intro to Scripting.pdf

JavaScript Tools Guide
  File: JavaScript Tools Guide CS4.pdf


***********************************************************
3. Sample Scripts
***********************************************************
Sample scripts are included in the product installer for Illustrator 
CS4. When Illustrator is installed to its default location, the path 
to the sample scripts is as follows:

  Windows:  
    C:\Program Files\Adobe\Adobe Illustrator CS4\Scripting\Sample Scripts/

  Mac OS: 
    /Applications/Adobe Illustrator CS4/Scripting/Sample Scripts/

Look in these folders and try the supplied samples. The Illustrator 
AppleScript, JavaScript, and VBScript reference documents contain 
many other examples.


***********************************************************
4. Known Issues
***********************************************************
Text selection not set reliably in AppleScript (1436010)

  Affects: AppleScript

  Problem:
    Setting a text selection using AppleScript does not work reliably.
    For example, suppose your script selects a word and subsequently
    checks for a text selection before applying some styling to the 
    selected text:
	
      select word 1 of story 1 of current document
      -- Double the font size of selected text
      set selectedText to selection of current document
      if class of selectedText is text then
	set fontSize to size of selectedText
	set size of selectedText to 2 * fontSize
      end if
        
    The "class of selectedText is text" test in the script above 
    does not work reliably. To reproduce the problem, create text in 
    a document, click the Selection Tool, then run the script above.

  Workaround:
    Style text without using the selection:
	
      -- Double the font size of the first word in the first story
      set fontSize to size of word 1 of story 1 of current document
      set size of word 1 of story 1 of current document to 2 * fontSize
		
_____________________________________________________________________________

Cannot switch hyphenation of a paragraph from off to on (1437421)

  Affects: AppleScript, JavaScript, VBScript

  Problem:
    The samples below fail to turn on hyphenation, if it is already off.

    AppleScript:
      set hyphenation of paragraph 1 of story 1 of document 1 to true
	
    JavaScript:
      app.activeDocument.textFrames[0].paragraphs[0].hyphenation = true;
	
    VBScript:
      Set appRef = CreateObject("Illustrator.Application")			      appRef.ActiveDocument.TextFrames(1).Paragraphs(1).ParagraphAttributes.Hyphenation = true

  Workaround:
    None.
	
_____________________________________________________________________________

Creating and saving a large number of Illustrator files using scripting
may cause Illustrator to crash (1449308)

  Affects: AppleScript, JavaScript, VBScript

  Problem:
    Scripts that create, save, then close a large number of 
    Illustrator files can cause Illustrator to crash.
	
  Workaround:
    Scripts should periodically quit and relaunch Illustrator. The
    recommended maximum number of files to process before relaunching 
    Illustrator is 500.
	
_____________________________________________________________________________
	
Punctuation causes iteration of words to be incorrect (1451863)

  Affects: AppleScript, JavaScript, VBScript

  Problem:
    This JavaScript iterates the words in a sentence containing some
    punctuation:
	
      var docRef = app.documents.add ();
      var tfRef = docRef.textFrames.add();
      tfRef.contents = "This is : a ( test ) of words"
      wordCount = tfRef.words.length;
      for (i = 0; i < wordCount; ++i ) {
	$.writeln (app.activeDocument.textFrames[0].words[i].contents);
      }
	
    The words that should be reported are:

      This
      is
      :
      a
      (
      test
      )
      of
      words
	
    The words that are reported are:

      This
      i
      : 
      	 
      tes
 
      of
      words

  Workaround:
    None.
	
_____________________________________________________________________________

"An Illustrator error occurred: 1346458189 ('PARM')" alert (1459349)

  Affects: JavaScript

  Problem:
    This alert may be popped when badly written scripts are repeatedly 
    run in Illustrator from the ExtendScript Toolkit

    Scripters need to be very careful about variable initialization and 
    namespace conflict when repeatedly pushing a batch of Illustrator scripts
    for execution in Illustrator via the ExtendScript Toolkit (ESTK) in a 
    single Illustrator session. Each script run is executed within the same 
    persistent ExtendScript engine within Illustrator. The ESTK debugger 
    uses BridgeTalk to communicate with Illustrator. One global, persistent 
    ExtendScript engine inside Illustrator handles all BridgeTalk 
    communications. The net effect is that the state of the ExtendScript 
    engine is cumulative across all scripts that ran previously.

    The following issues with script code can cause this problem:

      - Reading uninitialized variables. 
      - Global namespace conflicts, like when two globals from different
        scripts clobber each other.

  Workaround:
    Initialize variables before using them, and consider the scope of 
    your variables carefully. For example, isolate your variables by 
    wrapping them within systematically named functions. Instead of:
	
      var myDoc = app.documents.add();
      // Add code to process myDoc
	
    Wrap myDoc in a function that follows a systematic naming scheme:
	
      function myFeatureNameProcessDoc() {
	var myDoc = app.documents.add();
	// Add code to process myDoc
	}
	myFeatureNameProcessDoc();

_____________________________________________________________________________

Illustrator's application window and document windows are not displayed
when Illustrator is started from VBScript (1482072)

  Affects: VBScript

  Problem:
    When Illustrator is started by a VBScript, the main application window
    and any document windows that are subsequently opened are not displayed. 

  Workaround:
    Make sure Illustrator is running before you run your VBScript.
	
_____________________________________________________________________________

There are problems executing Illustrator JavaScript from ScriptUI / 
Flash (1505109)

  Affects: JavaScript, Flash, ScriptUI'd Flash Player

  Problem:
    You can load and play a Flash movie using the Flash Player control
    provided by ScriptUI (see "JavaScript Tools Guide"). A Flash 
    control can use the ExternalInterface.call() method to call a 
    JavaScript function. If that function makes a direct call to 
    Illustrator's JavaScript APIs, problems can occur. Some 
    Illustrator JavaScript APIs require a context that is not 
    available in the ExtendScript instance that executes the 
    function. For example, calling the function below results 
    in a script alert, "Error: there is no document":
	
      function newRectangle() {
	try {
	  if (app.documents.length == 0) app.documents.add();
	  var pathRef = activeDocument.pathItems.rectangle(600, 200, 100, 120);
	  var left = (Math.random() * 100) + 150;
	  var top = (Math.random() * 100) + 200;
	  pathRef.position = new Array( left, top );
	} catch(e) {
	  alert (e);
	}
      }

  Workaround:
    Execute your Illustrator JavaScript through BridgeTalk:
	
      function newRectangle() {
	try {
	  var bt = new BridgeTalk();
	  bt.target = "illustrator";
	  bt.body = "{\n" +
	  "if (app.documents.length == 0) app.documents.add();\n" +
	  "var pathRef = activeDocument.pathItems.rectangle(600, 200, 100, 120);\n" +
	  "var left = (Math.random() * 100) + 150;\n" +
	    "var top = (Math.random() * 100) + 200;\n" +
	    "pathRef.position = new Array( left, top );\n"
	    + "}\n";
	  bt.send();
	} catch(e) {
	  alert (e);
	}
      }
		
_____________________________________________________________________________

AppleScript add document command does not work (1508923)

  Affects: AppleScript

  Problem:
    The "add document" command is not in Illustrator CS3's AppleScript 
    Dictionary, and it does not work.

  Workarounds:
    1. Use the existing "make new document" command.
	
    2. Use JavaScript "app.documents.addDocument()" to create a document
       from a preset, and use the "do javascript" command to invoke your
       JavaScript from AppleScript. For example:
	
         do javascript "var myPreset=app.getPresetSettings(\"Print\");app.documents.addDocument(\"Print\",myPreset);"

    3. Use JavaScript or VBScript instead of AppleScript. 

       JavaScript example:
         var myPreset = app.getPresetSettings("Print");
         app.documents.addDocument("Print", myPreset );
			
       VBScript example:
         Set app = CreateObject("Illustrator.Application")
         Set myPreset = app.GetPresetSettings("Print")
         app.Documents.AddDocument "Print", myPreset	

_____________________________________________________________________________

AppleScripts saved as application (.app) format may not run on Mac OS 
10.5.x (1511599)

  Affects: AppleScript

  Problem:
    AppleScripts saved with File Format set to "application" may not
    run properly on the Leopard (10.5.x) Mac OS X operating system.
    To correct the problem:
	
	1. Open the AppleScript in AppleScript Script Editor.
	2. Choose File > Save As...
	3. Set File Format to "application bundle".
	4. Click Save and choose to replace the existing file if prompted.

_____________________________________________________________________________
OMV scripting dictionary documents the class "AISaveOptions" for use when 
saving files (1882112)

  Affects: JavaScript
	
  Problem:
    The OMV scripting dictionary documents the "AISaveOptions" class
    for use when saving files. This is incorrect: the class that 
    should be used is "IllustratorSaveOptions," as documented in
    "Adobe Illustrator CS4 JavaScript Reference."

	
***********************************************************
5. SDK Support and Adobe Partner Programs 
***********************************************************
If you require SDK support for the Illustrator CS4 SDK,
you may purchase single or multi-pack SDK support cases.
Information on purchasing SDK support cases can be found at:

  http://partners.adobe.com/public/developer/support/index.html

Information on Adobe support, in general, may be found at:

  http://www.adobe.com/support/programs/

If you are a partner who extends, markets, or sells Adobe
products or solutions, you should consider membership in
the Adobe Partner Connection Solution Partner Program. 
The Solution Partner Program provides development support,
access to timely product information, as well as various
marketing benefits. To learn more about the program, point
your browser to:

http://go.adobe.com/kb/cs_cpsid_50036_en-us
	
_____________________________________________________________________________
Copyright 2008 Adobe Systems Incorporated. All rights reserved.

Adobe and Illustrator are registered trademarks or trademarks of Adobe 
Systems Incorporated in the United States and/or other countries. Windows
is a registered trademark or trademark of Microsoft Corporation in the 
United States and/or other countries. Macintosh is a trademark of Apple 
Computer, Incorporated, registered in the United States and other countries.
All other brand and product names are trademarks or registered trademarks of 
their respective holders.
_____________________________________________________________________________