GETTING STARTED WITH THE ADOBE INDESIGN CS3 PLUG-IN EDITOR

Transcription

1 GETTING STARTED WITH THE ADOBE INDESIGN CS3 PLUG-IN EDITOR

2 2007 Adobe Systems Incorporated. All rights reserved. Getting Started with the Adobe InDesign CS3 Plug-in Editor Technical note #10123 Adobe, the Adobe logo, and InDesign are registered trademarks or trademarks of Adobe Systems Inc. in the United States and/or other countries. Apple and Mac OS are trademarks of Apple Computer, Inc. registered in the United States and other countries Windows is a registered trademark or trademark of Microsoft Corporation in the United States and/or other countries. Java is a trademark of Sun Microsystems, Inc. in the United States and other countries. All other products or name brands are trademarks of their respective owners. All other trademarks are the property of their respective owners. The information in this document is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Adobe Systems Inc. Adobe Systems Inc. assumes no responsibility or liability for any errors or inaccuracies that may appear in this document. The software described in this document is furnished under license and may only be used or copied in accordance with the terms of such license. Adobe Systems Incorporated, 345 Park Avenue, San Jose, California 95110, USA.

3 Contents What is the InDesign plug-in editor? Terminology Overview Installing the development environment Installing Eclipse Installing the InDesign plug-in editor s dependencies Installing the InDesign plug-in editor Running the InDesign plug-in editor Getting started with Eclipse Setting/creating a workspace Opening/closing an existing project Getting started with the Adobe InDesign plug-in editor Creating a new InDesign plug-in project Importing an existing InDesign plug-in project Project files in relation to the workspace Setting workspace-persisted values Setting project-specific values Using the InDesign plug-in editor s GUI FR editor Opening files Saving files Saving to a new file Creating new widgets Changing widget values Hierarchy navigation Setting global-resource values Using the Adobe InDesign plug-in editor s text FR editor Content assistance Error checking Building plug-ins with the InDesign plug-in editor Running the build script Setting build variables Troubleshooting Using the Adobe InDesign plug-in editor with CS Assistance

4 Contents Documentation Cheat sheets Widget documentation ODF Doc Advanced feature: adding new widget images Getting Started with the Adobe InDesign CS3 Plug-in Editor

5 What is the InDesign plug-in editor? Getting Started with the Adobe InDesign CS3 Plug-in Editor This document describes how to get started using the Adobe InDesign CS3 plug-in editor. The target audience for this document is InDesign plug-in developers who need to edit ODFRez files. What is the InDesign plug-in editor? The InDesign plug-in editor is a set of plug-ins for Eclipse, which provide a platform for the creation and modification of plug-ins for InDesign. The editor provides functionality to generate, edit (both textually and graphically), and build InDesign plug-ins. See Figure 1 for a graphical overview of the plug-in editor in use. FIGURE 1 The InDesign plug-in editor in use The InDesign plug-in editor was developed using the following: Getting Started with the Adobe InDesign CS3 Plug-in Editor 5

6 Terminology Eclipse (and the Eclipse GEF) ANTLR The Saxon XSLT Processor from Michael Kay Xerces Terminology These terms may already be familiar to you, if you have experience with Eclipse. Eclipse Eclipse is an open-source IDE developed by the Eclipse Foundation. It forms the basis for the InDesign plug-in editor. Perspective A perspective is a set of views. By using different perspectives, the user can save the layout of the workbench in multiple ways, if desired. It is then possible to alternate among these perspectives with the click of a button. The InDesign plug-in editor automatically opens a perspective with the GUI FR editor. This makes the process of editing much simpler. Project In Eclipse, a project is a set of zero or more files and folders, grouped into a project folder, within a workspace. It is the base item you see in the workspace navigation views within Eclipse. View In Eclipse, a view is a panel within the workbench. The InDesign plug-in editor makes extensive use of views, with examples including the outline, properties, and widget views used by the GUI FR editor. These may be opened, closed, and moved around the screen to suit the user. Workbench Eclipse s workbench is the instance of the Eclipse user interface with which the user interacts. One instance of Eclipse may have multiple workbenches. Workspace In Eclipse, a workspace is a location on disk where current projects are stored. This directory should not be used for anything else; for example, the root of the SDK. Overview There are two ways to obtain and use the InDesign CS3 plug-in editor. You may either download a complete Eclipse distribution, containing the editor, or you may download a set of plugins for Eclipse. The latter will allow you to integrate the editor with your current working environment. The former will require minimal user setup. For users unfamiliar with Eclipse it is recommended that they begin with the complete distribution. To get started using the full distribution of the InDesign CS3 plug-in editor, simply check te dependencies and then download, extract and run it. To get started using the InDesign CS3 plug-in editor, follow these steps: 6

7 Installing the development environment 1. Verify that you have all required components of the development environment for your operating system, as described in Installing the development environment on page Either download the InDesign plug-in editor Eclipse distribution, or download and install the version of Eclipse you wish to use, following the instructions in Installing Eclipse on page If you are not using the full distribution, update Eclipse with the dependencies necessary for the InDesign plug-in editor. Follow the instructions in Installing the InDesign plug-in editor s dependencies on page If necessary, download and install the InDesign plug-in editor plug-ins. Follow the instructions in Installing the InDesign plug-in editor on page Create or import an InDesign plug-in. Use the steps in Creating a new InDesign plug-in project on page 13 and Importing an existing InDesign plug-in project on page 14. Installing the development environment To run the InDesign plug-in editor, you must have the components listed in Table 1. If you download the full distribution of the InDesign CS3 plug-in editor, you will not need to download Eclipse or its plug-ins. TABLE 1 Supported development platforms and required components Platform Component Notes Windows XP SP2 or later (Vista) InDesign CS3 SDK Eclipse (preferred) or later Eclipse Graphical Editing Framework or later ANTLR 2.7 Eclipse C Development Tools (optional) Visual Studio 2005 JRE (Java runtime environment) 1.5 or later The plug-in editor also may work with CS2, but we recommend you use CS3. The plug-in editor has been tested with Eclipse and 3.3. The Eclipse GEF version must match the Eclipse installation you use. For example, you cannot use GEF 3.3 with Eclipse 3.2. ANTLR s retrieval is described in Installing the InDesign plug-in editor s dependencies on page 9. You may install Eclipse s CDT. This makes C programming easier; however, it is not required for the plug-in editor to run. To compile Plug-ins developed with the InDesign plug-in editor, Visual Studio 2005 must be installed. If you do not already have this, you can get it from Getting Started with the Adobe InDesign CS3 Plug-in Editor 7

8 Installing Eclipse Platform Component Notes Mac OS 10.4 or later InDesign CS3 SDK Eclipse (preferred) or later Eclipse Graphical Editing Framework (GEF) or later ANTLR 2.7 Eclipse C Development Tools (optional) XCode or later JRE (Java runtime environment) 1.5 or later The plug-in editor also may work with CS2, but we recommend you use CS3. The plug-in editor has been tested with Eclipse and 3.3. The Eclipse GEF version must match the Eclipse installation you use. For example, you cannot use GEF 3.3 with Eclipse 3.2. ANTLR s retrieval is described in Installing the InDesign plug-in editor s dependencies on page 9. You may install Eclipse s CDT. This makes C programming easier; however, it is not required for the plug-in editor to run. XCode must be present to allow the compilation of developed plug-ins. If your Mac OS installation gets updates from Apple, this should be present. Installing Eclipse 1. If you do not already have a copy of the JRE for your operating system, go to and get version 1.5 or later. On Mac OS, this should not be necessary if you have accepted software updates from Apple. 2. Go to and download version of Eclipse for your operating system. See Figure 2. NOTE: You may install a later version (3.3), but we recommend The InDesign plug-in editor will not work with an earlier version of Eclipse than Once the download completes, extract the archive into the directory where you want Eclipse to be installed. For example, in Windows, you may want to unzip it to C:\Program Files. 8

9 Installing the InDesign plug-in editor s dependencies FIGURE 2 Installing the InDesign plug-in editor s dependencies Before installing the InDesign plug-in editor itself, you must update Eclipse with the required libraries. Follow these steps: 1. Open the directory where you installed Eclipse, and run the Eclipse application. This brings up a box asking you to choose a workspace. For more information on what this means, see Setting/creating a workspace on page Once you choose your workspace, you will see the screen shown in Figure 3. Choose Help > Software Updates > Find and Install. 3. Select Search for New Features to Install, and click Next. You will see a list of update sites of which Eclipse is aware. To install the InDesign plug-in editor s dependencies, you need to add three new Remote Sites. 4. For each of the items below, click New Remote Site and enter the details: ANTLR GEF Getting Started with the Adobe InDesign CS3 Plug-in Editor 9

10 Installing the InDesign plug-in editor s dependencies CDT 5. Ensure that only the three items above are checked (as shown in Figure 4). Click Finish. 6. Eclipse contacts the update sites and, for each one, prompts you to select a local mirror. Each time, choose the mirror closest to you, and click OK. 7. Eclipse presents you with a list of available updates. To view the correct version, you may have to uncheck the box marked Show the latest version of a feature only. The features you should select are as follows: For ANTLR: cat > org.antlr.ui For GEF: The version of GEF that most closely matches (but does not exceed) the version of Eclipse you installed. This must be no earlier than For CDT (optional): The release of CDT Main matching your Eclipse version. 8. Click Next, and follow the on-screen installation instructions. Eclipse restarts several times before the process is complete. 9. Once it finishes, close the Eclipse workbench. You are now ready to download and install the InDesign plug-in editor. FIGURE 3 Installing updates within Eclipse 10

11 Installing the InDesign plug-in editor FIGURE 4 Selecting update sites Installing the InDesign plug-in editor To install the InDesign plug-in editor as a set of plug-ins on Windows, follow these steps: 1. Retrieve the archive from Adobe Labs ( 2. Unzip the archive to Eclipse s folder. For example, if you unzipped Eclipse to C:\Program Files, you would unzip the archive to C:\Program Files\eclipse. To install the InDesign plug-in editor as a set of plug-ins on Mac OS, follow these steps: 1. Retrieve the archive from Adobe Labs ( 2. Put the WidgetFiles directory into../eclipse/. 3. Move the files inside Plugins to../eclipse/plugins/. Do not copy the entire directory, as this would overwrite Eclipse s original plug-ins directory. After installing the InDesign plug-in editor, perform the following platform-independent setup steps: 1. Navigate to the Eclipse directory, and double-click the Eclipse application to start it. 2. Choose Window > Preferences. This brings up a new window containing preferences for the different aspects of Eclipse. 3. From the list on the left of the window, select InDesign Plug-in Preferences. Getting Started with the Adobe InDesign CS3 Plug-in Editor 11

12 Running the InDesign plug-in editor 4. Set either the Visual Studio or XCode Path to the correct location on your hard disk. 5. Set the SDK Path. This is the SDK s root folder, which contains the sub-directories build, source, devtools, etc. 6. Click OK, and close Eclipse. Running the InDesign plug-in editor To begin working with the InDesign plug-in editor, simply start the Eclipse application, in the same way you did when you installed dependencies. When Eclipse starts, you will see the Welcome screen. To access Eclipse s workbench, click the arrow to the right of the screen, as shown in Figure 5. FIGURE 5 The Workbench icon Getting started with Eclipse If you have not used the Eclipse IDE before, take a few moments to familiarize yourself with it. If you used Eclipse previously, this section may not be of use to you; proceed to Getting started with the Adobe InDesign plug-in editor on page 13. What follows is a very brief overview of some of the areas in which the InDesign plug-in editor is particularly reliant on Eclipse. For more detailed information, see Eclipse s offline and online documentation. Setting/creating a workspace In Eclipse, workspaces are directories on your local drive that contain the projects you are currently editing or have previously edited, along with information about the state of the workbench (Eclipse s user interface). A single copy of Eclipse may use several workspaces, to allow for the separation of editing environments. See Figure 6. 12

13 Getting started with the Adobe InDesign plug-in editor FIGURE 6 Choosing a workspace When you start Eclipse, you are prompted to enter a directory that will be used as the workspace. We recommend you create an entirely new directory for this, rather than using an existing one. To change workspaces after starting Eclipse, choose File > Switch Workspace. Opening/closing an existing project In Eclipse, when projects are deleted in the IDE, the folders they point to in the workspace are not necessarily deleted with them. Project deletion is a means of limiting how many projects users see in the workbench. With a standard Eclipse creation wizard, if you enter the name of a project whose reference still exists (if the project itself is not open but was previously created and deleted), the old project is re-opened. This behavior carries over into the InDesign plug-in editor s New Project wizard (see Creating a new InDesign plug-in project on page 13). Getting started with the Adobe InDesign plug-in editor Once you start the InDesign plug-in editor and select your workspace, you will see the standard Eclipse IDE. To begin editing an InDesign plug-in, you must first create or import one. You can do so by following the instructions in this section. If you want a guided tutorial of anything presented here, the InDesign plug-in editor comes with several, designed to walk you through the processes involved. They can be accessed by choosing Help > Cheat Sheets. Creating a new InDesign plug-in project To create a new InDesign plug-in project, right-click (or control-click on Mac OS) on the Package Explorer pane and choose New > Project. This opens the New Project wizard. Choose InDesign Plug-in Development > New InDesign Plug-in Project (see Figure 7). The wizard Getting Started with the Adobe InDesign CS3 Plug-in Editor 13

14 Getting started with the Adobe InDesign plug-in editor guides you through the creation of a new InDesign plug-in project, using the same interface as DollyXS. For more detail on the plug-in generation process, see the section on Using DollyXS to generate a dialog-based plug-in project in the InDesign CS3 SDK s Working With Plug-ins technical note. FIGURE 7 Creating a new project Importing an existing InDesign plug-in project 1. To import an existing plug-in project, such as the SDK sample TransparencyEffectUI, context-click on the Package Explorer (the left-hand pane) and choose Import. 2. Choose InDesign Plug-in Development > Import InDesign Plug-in Project. You will see the screen shown in Figure You are prompted to enter a Project Name, source directories, and root FR files for both Windows and Mac OS. In most cases (like the SDK samples), these are the same for both platforms. 4. The Project Name is the name Eclipse will use to refer to your imported project. It also is the name used to create the directory within the workspace for your project. If you were importing the TransparencyEffectUI SDK sample, this would be: Project Name - TransparencyEffectUI 14

15 Getting started with the Adobe InDesign plug-in editor 5. The Windows and Mac OS source folders are the directories where plug-in code for both platforms is located. These may (and in the samples certainly will) be the same. In our TransparencyEffectUI sample, we would set these as follows: Windows: SDK_DIRECTORY/source/sdksamples/transparencyeffectui/ Mac OS: SDK_DIRECTORY/source/sdksamples/transparencyeffectui/ 6. The Windows and Mac OS Root FR files are the files, relative to each directory, we will use as the umbrella file for the plug-in. Each should import all the necessary dependencies and user-interface resources. If you generated your plug-in with DollyXS, this is the file named with the value you previously supplied as the plug-in s Short Name. For our example, these would be set as follows: Windows: /TranFXUI.fr Mac OS: /TranFXUI.fr 7. Click Next to move to the next screen. It contains information related to the building of the plug-in. You need to enter only one value, the location of the plug-in project file for your operating system You can leave the other field empty. For Windows, this is the Visual Studio project used to compile your plug-in. In our example, this would be SDK_DIRECTORY/build/win/prj/TransparencyEffectUI.vcproj. For Mac OS, this is the XCode project used to compile your plug-in. In our example, this would be SDK_DIRECTORY/build/mac/prj/TransparencyEffectUI.sdk.xcodeproj. Getting Started with the Adobe InDesign CS3 Plug-in Editor 15

16 Getting started with the Adobe InDesign plug-in editor FIGURE 8 InDesign plug-in project creation wizard for Windows and Mac OS Project files in relation to the workspace When the InDesign plug-in editor creates or imports a project, it does not do so locally to the workspace. To put it another way, the editor does not copy or create the files or folders into a directory within the workspace. Instead, it creates a reference (or link) to the plug-in s position in the file system. This means you do not have to copy files into or out of Eclipse to edit them, and you can maintain the hierarchy of directories that you want. Setting workspace-persisted values Persisted values are extremely important and must be addressed before you begin editing a plug-in. Most importantly, you must set the SDK folder to point at the correct location. This is the root of your SDK (the directory that contains Build, Source, and devtools.). You can set this value, along with several other preferences, by choosing Window > Preferences > InDesign plug-in editor. See Figure 9 and Figure

17 Getting started with the Adobe InDesign plug-in editor FIGURE 9 Setting workspace preferences Getting Started with the Adobe InDesign CS3 Plug-in Editor 17

18 Getting started with the Adobe InDesign plug-in editor FIGURE 10 InDesign plug-in workspace preferences You also should ensure that either Visual Studio location or XCode location is set correctly, depending on the platform. These are used when you try to build a plug-in project. In this panel, you also can set any predefined symbols for the internal compiler. For example, if you want to use the statement #ifdef MAC, you must define MAC here, if you want it to be read. If all your #ifdef statements have an #else, you are free to ignore this. If you have a statement that requires one of a set of symbols to be defined (or you simply want to use the MACdefined value), this is where you must define it; otherwise, the widget it affects is considered to have an error (and is not graphically editable). There also are options to control the display of images (for a more WYSIWYG experience) and to show an approximation of how the resource would appear using EVE. The former shows an icon for a limited number of widgets and is user-extendable. For information on adding more widget images, see Advanced feature: adding new widget images on page 34. Displaying EVE stops you from graphically editing the resource tree. This is because the changes you make do not necessarily update the view, so the link between the user input and the display would be unclear. EVE display is not intended for constant use; it should be used by the developer to check that widgets are positioned as anticipated. 18

19 Getting started with the Adobe InDesign plug-in editor Setting project-specific values Along with the settings that affect every project, there are settings that can be edited on a project-by-project basis. To access these, right-click on the project you want to edit and choose Properties. Then choose InDesign Plug-in Editing. See Figure 11 and Figure 12. FIGURE 11 Setting project-specific properties Getting Started with the Adobe InDesign CS3 Plug-in Editor 19

20 Getting started with the Adobe InDesign plug-in editor FIGURE 12 InDesign plug-in project-specific properties Here, you can set the Build values for your plug-in, as well as the files to use as Root and any extra directories they may need to use. These extra directories are used both when building the plug-in for export to InDesign and when parsing the plug-in within the InDesign plug-in editor. 20

21 Using the InDesign plug-in editor s GUI FR editor Using the InDesign plug-in editor s GUI FR editor To get started graphically editing an InDesign plug-in, we recommend you open the root FR file, marked in the Navigation pane (see Figure 13). This opens all graphical resources found in the plug-in. If you choose another file, it may still work, depending on how your imports are organized, but we do not recommend this. FIGURE 13 Finding the root FR file Opening files Saving files When you open the FR file for graphical editing, the InDesign plug-in editor opens a perspective within Eclipse designed for this purpose. This means it opens several other views around the main editor, in which information is displayed. You can manually select a perspective by clicking on the button to the top right of the workbench. Opening the resources takes a moment, as the InDesign plug-in editor must parse them each time to ensure accuracy. Once they have opened, you can begin moving and resizing the objects as you would in any graphical editor. If the file you open uses values declared outside your plug-in, and the InDesign plug-in editor cannot locate the correct file, you may experience unexpected behavior. If the required value is a reference to other values, the parser will fail to recognize the widget in question. This is because it will be thought to have an inadequate number of arguments. If, however, the value is located within the frame of the widget, it is displayed. The InDesign plug-in editor will try to draw the widget using the frame values it has, meaning it may not be created as you would expect. Since the InDesign plug-in editor is designed for graphically editing these files, and the output for each of the four frame values is a single number (not a mathematical string and not using references), we recommend users not provide complex statements for frame values (especially those that use externally declared integers). The manner in which the GUI plug-in editor saves files requires you to be aware of it. Because it opens resources from every FR file in the plug-in, not just the file you directly opened, it also Getting Started with the Adobe InDesign CS3 Plug-in Editor 21

22 Using the InDesign plug-in editor s GUI FR editor must also save them back into these files. This means it saves multiple files at once, from a single save command. Saving to a new file If you want to save a resource tree to a new file, you cannot Save As, as you would with other files. Instead, you should edit the name of the file that the specific resource (either root or within the hierarchy) is saved to within the GUI Editor. See Figure 14. FIGURE 14 Editing the root file for a specific FR tree This can be done for the entire resource tree on the Properties Pane (to the right of the screen), by changing the value under Source File. To change only one widget (and any children it may have), change its Source File within the Widget View tab (also on the right of the display). See Figure 15. FIGURE 15 Editing the file for an element within the FR tree While this updates where the widgets are saved and their parent s reference to them, it does not delete the file from which they originated. If the relocated widgets entered the hierarchy through an internal include, where the #include statement was within another widget s child list, and the original file has no remaining elements, the widgets are not removed from that file. This is because one file may be included within many others, and we do not want to introduce problems with other widget trees. 22

23 Using the InDesign plug-in editor s GUI FR editor Creating new widgets To create a new widget within an existing resource hierarchy, you simply need to drag it from the Widgets panel at the bottom right of the page (see Figure 16). This lists the widget types imported into, or created within, the plug-in files, organized by inheritance. FIGURE 16 Widgets available for creation by drag and drop To create a new widget, drag the name of the one you want to instantiate into the graphical editing view. To create it at a particular position in the hierarchy, drag it onto the widget that you want to be its parent. When you create a new widget, you also must set its values before it will properly compile. For information on how to do this, see the Adding a TextEditBox widget section of Working With Plug-ins, packaged with the InDesign CS3 SDK. Changing widget values Changing the frame of a widget can be done by simply moving or resizing the widget in the graphical pane. It also can be achieved by directly modifying its frame values. These can be found, along with all the other editable values for the selected widget, in the Widget View in the right sidebar (see Figure 17). Getting Started with the Adobe InDesign CS3 Plug-in Editor 23

24 Using the InDesign plug-in editor s GUI FR editor FIGURE 17 Editing widget-specific values Here, you can change any of the values that will be saved back to the originating file as part of the resource. Many of these, not simply the frame, are reflected in the graphical view. For example, to change the displayed string for a check-box widget in the TransparencyEffectUI sample, we would do the following: 1. Open the root FR file, and select the resource tree we want to edit. 2. Select the widget with the string Preview. This brings up the details for this widget in the Widget View on the right-hand side of the workbench. 3. In the Widget View, click in the box for the final element, with the text Pre&view. 4. Change this to My Checkbox Value, and click on the main window. The check box is updated with the new string. Hierarchy navigation While navigation through the hierarchy can be done on the graphical-editor display, this can be difficult if widgets are closely positioned. To make this process easier, you can use the Outline panel in the right sidebar, which displays a list of all resources, sorted into a tree. See Figure

25 Using the InDesign plug-in editor s GUI FR editor FIGURE 18 Selecting a widget in the outline hierarchy When you select a widget here, it is selected in the graphical editor, and you also have access to its information in the Widget View pane. Conversely, if you select a widget in the graphical editor, the selection is reflected in this hierarchy. Setting global-resource values There also are some global values that apply to the whole of the resource tree: these are the Source File that represents where the tree is saved (unless contradicted by the value within a specific widget) and the Locale identifier. The Locale determines what text strings is displayed in both InDesign and the InDesign plug-in editor. FIGURE 19 Setting global values for the FR tree See Figure 19. To change the Locale for a resource tree, you may do so here. When you save this resource back to the file it was extracted from (or to a new file), it will have the new Locale. For example, in the TransparencyEffectUI sample, there is a resource declared with this text; resource TranFxUIDialogWidget (ksdkdefdialogresourceid + index_enus) If we change the Locale for this resource to index_jajp, this becomes: resource TranFxUIDialogWidget (ksdkdefdialogresourceid + index_jajp) Getting Started with the Adobe InDesign CS3 Plug-in Editor 25

26 Using the Adobe InDesign plug-in editor s text FR editor When you change this value, the InDesign plug-in editor automatically updates all text strings displayed within the resource to the chosen Locale. If, for any value, the key is not recognized, the key itself appears in its place. Using the Adobe InDesign plug-in editor s text FR editor Graphical editing is not the only benefit provided by the InDesign plug-in editor. There also is an ODFRez Text Editor. To use this, right-click any FR file in the tree and choose Open With > Text FR Editor. You are presented with a view of the FR file similar to that which you would see on opening a Java file. As in the Java view, selecting a resource in the right-hand pane moves the main editor pane to a point where it can be properly viewed. Follow these steps: 1. To begin using this, open an InDesign plug-in project. 2. Open the Win or Mac directory, depending on which file you want to edit. 3. Context-click on any FR file in the tree, and choose Open With > Text FR Editor. 4. To navigate to a specific resource, click it in the Outline View. Content assistance One of the benefits of using the InDesign plug-in editor s text FR Editor, compared to a simple text editor, is that it offers basic content assistance. This means if you want to add a new resource to the file, you can begin typing its name and press Ctrl-Space. This brings up a popup menu showing the possible completions. Selecting one of these inserts a template of the widget (or keyword), with some completions of content to help you finish it. See Figure

27 Using the Adobe InDesign plug-in editor s text FR editor FIGURE 20 Content assistance Error checking For example, to edit the TransparencyEffectUI SDK sample s file, TranFXUI.fr, follow these steps: 1. Navigate to the position in the file where we want to insert content. In TranFXUI.fr this could be the TranFXUIDialogWidget resource. To move to this quickly, select it in the outline view on the right-hand side of the workbench. 2. Position the cursor in its child list, after the opening brace ({) but before the first child, and press Ctrl-Space. This brings up a list of possible completions. 3. Begin typing the name of a widget you want to insert. In this example, you could type def and then select DefaultButtonWidget. This is inserted into the file. 4. Replace the values for the newly inserted widget with the ones you want it to use. For more information on these values, and what else you must do for your newly created widget, see the Working With Plug-ins technical note. The InDesign plug-in editor s text FR editor uses the same parser used to graphically display files to validate text input. If it recognizes a mistake in your FR file, it highlights it. This should not be considered a definitive statement, and it may be affected by import issues, but it is useful in analyzing and debugging problems with FR resources. To use the error-checking function, in the TranFXUI.fr example, follow these steps: Getting Started with the Adobe InDesign CS3 Plug-in Editor 27

28 Building plug-ins with the InDesign plug-in editor 1. Context-click the TranFXUI.fr file, and choose Open With > Text FR Editor. 2. Navigate to the TranFXUIDialogWidget resource, by clicking its name in the outline view. 3. Position the cursor at the end of the following line: ktranfxuidialogtitlekey, // Dialog name 4. Press Enter, and type anothervalue. 5. Save the file (by either clicking the icon in the top left or pressing Ctrl-S). The affected widget is underlined in red. This indicates an error and attempts to indicate where in the widget the error was encountered. See Figure 21. FIGURE 21 Error checking Building plug-ins with the InDesign plug-in editor Your created/imported plug-ins can be built on both Windows and Mac OS, as long as either Visual Studio 2005 or XCode is present. You also must set the correct directory for the one you want to use, as described in Installing the InDesign plug-in editor on page 11. You also must ensure that the project file for your environment is set correctly for the project. For information on checking this, see Setting build variables on page 30. Running the build script To start the build process, look for a file within the project s root folder entitled build.xml. Right click on this, and choose Run As > Ant Script. This opens a console at the bottom of the screen, and the script executes in it. See Figure

29 Building plug-ins with the InDesign plug-in editor FIGURE 22 Building an InDesign plug-in project This process performs two builds. The first build uses the ODFRC compiler. We use this to validate the resource files, by compiling them separately from the rest of the project. This reports errors specifically related to the plug-in you are building. The second build, of the plug-in s project file, uses Visual Studio 2005 or XCode; it provides you with output to help track down any issues. The build process is intended as a time saver, and any issues found with it (particularly when building the project) should be addressed or debugged within the environment that is being called (Visual Studio or XCode). In our TransparencyEffectUI example, the process is as follows: 1. Unless you already have open a project we want to build, create or import an InDesign plug-in project. For our example, import the TransparencyEffectUI SDK sample, as described in Importing an existing InDesign plug-in project on page Expand this project in the Package Explorer/Navigation view, and context-click the file build.xml. This is created by the import process and (unlike the plug-in files) stored in the workspace. Getting Started with the Adobe InDesign CS3 Plug-in Editor 29

30 Troubleshooting 3. From the pop-up menu, choose Run As > Ant Build. This opens a console in the panel along the bottom of the screen. This console displays the output of the build. If you are building the TransparencyEffectUI sample, the ODFRC build fails. The reasons for this, and how we address them, are outlined below. Setting build variables Build variables are set using the information given during project creation/importing. If you want to edit or add to these (you may find this necessary, if you want to add extra folders to search for files, for example), you can do this in the project properties page. To do this, rightclick on the project you want to edit, and choose Properties. Choose InDesign plug-in editor, and you are given the editable build values. If you change them or the external IDE location, the build script is updated automatically. These values are used for an initial ODFRC compilation, but only those set in the referenced project file are used for the full build. It is essential that you update these values if you want to use ODFRC compilation. To resolve the ODFRC build issue for the TransparencyEffectUI sample, you must add to its build variables; specifically, you must add a reference to TransparencyEffect. Follow these steps: 1. Context-click on the TransparencyEffectUI project, and choose Properties. 2. Choose ID Plug-in Project. 3. In the Additional Build Directories, add: SDK_DIRECTORY/source/sdksamples/transparencyeffect/ 4. Click OK, and run the build script again. This time, it should complete successfully. For more information on setting these, refer to Setting project-specific values on page 19 Troubleshooting Table 2 contains previously encountered issues arising from the use of the InDesign plug-in editor, along with information to help you resolve them. TABLE 2 Troubleshooting guide Issue Error: Can t find SDKODFRCOptions.rsp Resolution You probably did not correctly set the Depot location in the Preferences tab. To do this, choose Window > Preferences > InDesign plug-in editor, and set the Code Depot to point at the right folder. 30

31 Using the Adobe InDesign plug-in editor with CS2 Issue Unrecognized widgets or unexpected display How do I re-open a project where I chose to delete project files when deleting the project in Eclipse? I can t see a particular view, how can I get it to appear? Resolution There are many causes for this, and the specific error should be printed to the console. If several files have not been found, check to ensure that the SDK path is set correctly. If an error is reported with a #define statement (or similar), ensure that at least one of the options for the #tree is defined in the preferences panel. (If there is an #else, this should not be necessary.) You may be able to gather more information about why the widget was not recognized by opening the file that contains it in the text FR editor. This should underscore in red the area that is not understood. If you completely deleted the project, and so are unable to re-create it from its reference within the workspace, you must import it as a pre-existing project. To do this, you must know the location on disk where you generated or previously located the plug-in files. For detailed instructions for importing plug-ins, see Importing an existing InDesign plug-in project on page 14. If a view is not present or you want to access further views, you can do so by choosing Window > Show View > Other. If the view you want to see is one specific to InDesign editing, it will be located in InDesign Plug-in Editing. You also may want to see the Outline and Properties views; these are under General. Using the Adobe InDesign plug-in editor with CS2 Though the InDesign plug-in editor is designed for use with InDesign CS3, it can be used with earlier versions. To do this, you need to substitute the widget files for a documented copy, for the version of InDesign you want to use. If you look in the WidgetFiles directory, within the folder where you installed the InDesign plug-in editor, you will see that for each.fh file there also is a.fh.cs2 file. To make full use of the InDesign plug-in editor with CS2, you must substitute these files for their.fh counterparts, by removing the.cs2 suffix from the filenames. If you want to use an earlier version of InDesign than CS2, you must document and substitute the files for this yourself. Assistance Documentation The InDesign plug-in editor documentation is under Help > Help Contents > InDesign plug-in editor for InDesign CS3. It duplicates much of the information found in this guide within Eclipse s own help system. Getting Started with the Adobe InDesign CS3 Plug-in Editor 31

32 Assistance Cheat sheets There are several cheat sheets. These walk users through the core functions of the InDesign plug-in editor, by explaining what is required at each step; for instance, creating a new project, importing an existing project, or building the result. They are under Help > Cheat Sheets. Widget documentation To generate documentation on the widgets available for a specific project, right-click the project and choose InDesign plug-in editor > Generate Widget Documentation. See Figure 23. This creates two new HTML files, one each for the Windows and Mac trees. The files contain detailed information about the widgets available, their attributes, and the source of each attribute. FIGURE 23 Generating widget documentation This information is compiled using ODF Doc++, so if you want it to provide the maximum amount of information for your own, custom widgets, document them in this style. 32

33 Assistance ODF Doc++ The InDesign plug-in editor also uses a new documentation method for FR files, modelled after traditional Doc++ comments. Using this method, we place a statement wrapped in /**...*/ immediately before a widget type declaration. This value is analyzed and used to assign higher-level associations to the base values (e.g., int and string.) that compose the resource. Since the majority of widgets make extensive use of other widgets, not just as super types but also to import values into them, ODF Doc++ employs a hierarchical model. What this means is that even if you choose not to provide marked-up definitions for a custom resource you create, it still benefits if it uses resources that do provide such definitions (a group that includes all core resources). An example of an ODF Doc++ comment is shown below: /** * Description of widget... OLD_NAME NEW_NAME (:comment/description) NAME ([val1,val2,enum:e1]) (:comment/description) */ ODF Doc++ uses a simple syntax for data entry. There are two main creates a new ODF entry in the list for this object and gives it the assignable values (if supplied) and the comment/description (again, refers to a declared value in the super type or other included widget and allows the writer to change its name. This is useful, for example, if you want a widget whose parent displays alignment to ignore it. It is possible to assign a statement only to a base type (i.e., an int, string, etc.), not to an imported/super type object (though you are free to redefine the base types they confer). If there is a potential conflict between possible values (for example, if a super type has two values with the same name ), the InDesign plug-in editor always takes the first. To be sure you are redefining the value you intend to, you should redefine all potential matches, even if it is simply back to the original value. The name given can be supplied in two ways. To simply assign a name for a parameter and have that be displayed when the InDesign plug-in editor refers to it, a simple name suffices. The InDesign plug-in editor s ODF Doc++ implementation also allows for the use of keywords. Currently, this is limited to the following values (listed with their purposes): X_COORD, Y_COORD Used to point to spatial coordinates. RSRC_ID, PLUGIN_ID Used to indicate the resource and plug-in ids of a widget. STRING, CONTROL_LABEL Used to flag a string object and potentially a control label to be displayed. FRAME_X, FRAME_Y, FRAME_W, FRAME_H The coordinates of a frame s four points. WIDGET_ID The main identifier for a widget. Getting Started with the Adobe InDesign CS3 Plug-in Editor 33

34 Assistance ASSOC_WIDGET_ID, ASSOC_ACTION_ID Used to associate widgets and actions. ARRAY, CHILD_ARRAY Used to declare array objects and those arrays that support children. ALIGNMENT Controls how text/image output is aligned. EVE_INFO Allows the recognition of data controlling the display of EVE widgets. Advanced feature: adding new widget images If you want to add more images, you should add them to the com.adobe.devtech.idsdk.freditor.jar file in the icons directory. These images should be in PNG format and take the name of the widget they represent. For example, if you want to show a small, non-stretched image that moves with alignment (like a check box), name the file $widgetname$_nostretch.png. If a widget does not have an image assigned with it, it tries to retrieve one for its supertype. This process continue until the base Widget type is reached. This ensures the maximum amount of functionality with the minimum footprint. 34