Adobe Illustrator CS3 Scripting
(March 2007)
ReadMe File

______________________________________________________________________


This file has the following sections:
    1. Introduction
    2. Documentation
    3. Sample Scripts
    4. Known Issues



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

To find the latest available information on scripting 
Illustrator visit the URL below:

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


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

Adobe Illustrator CS3 AppleScript Reference
	File: Illustrator CS3 AppleScript Reference.pdf

Adobe Illustrator CS3 JavaScript Reference
	File: Illustrator CS3 JavaScript Reference.pdf

Adobe Illustrator CS3 VBScript Reference
	File: Illustrator CS3 VBScript Reference.pdf

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

JavaScript Tools Guide
	File: JavaScript Tools Guide CS3.pdf


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

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

Mac OS: 
    /Applications/Adobe Illustrator CS3/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 the hyphenation on, 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, and 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.

	Issues with script code that may cause this problem are: 

	  - 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.
	
_____________________________________________________________________________

- Problems executing Illustrator JavaScript from ScriptUI / Flash (1505109)

  Affects:
	JavaScript, ScriptUI Flash Player Control

  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 (page 200 of Adobe Illustrator CS3 
	AppleScript Reference.pdf) is not in Illustrator CS3's 
	AppleScript Dictionary, and it will 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.
	
_____________________________________________________________________________

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

Copyright 2007 Adobe Systems Incorporated. All rights reserved.