Installing Project Nile

Print-friendly Version

Project Nile needs to be installed if you plan to export graphics from Adobe Illustrator or Photoshop or convert SVG graphics to a format that allows JavaFX Script to manipulate the layers in the graphic independently. Project Nile has six components:

Project Nile Component	Description
Illustrator Plugin	An Adobe Illustrator CS3 plugin that enables export to FXD file format or JavaFX Script code
Photoshop Plugin	An Adobe Photoshop CS3 plugin that enables export to FXD file format or JavaFX Script code/
SVG Converter	A GUI and command-line tool that enables conversion of SVG graphics to FXD file format or JavaFX Script code
JavaFX Graphics Viewer	A GUI and command-line tool that allows you to view graphics generated by Project Nile.
Library	A library JAR file that must be attached to any application using FXD file format.
Samples	Sample applications that can be built and run using NetBeans IDE with the JavaFX plugin. The samples contain Adobe Illustrator or Adobe Photoshop source files plus all NetBeans project files required to run the application.

Project Nile runs on Windows XP, Windows Vista, or Mac OS X 10.5 (Leopard). See the Release Notes for specific hardware and software requirements.

The Project Nile installer installs the following:

• An export plugin into the Plug-ins directory of Adobe Photoshop and Adobe Illustrator, if those applications are installed.
  
  
• The SVG conversion utility
  
  
• The JavaFX Graphics Viewer, a tool that displays graphics that were exported to either FXD file format or JavaFX Script code
  
  
• The Library and Sample folders

Download and install Project Nile as follows:

1. Download the Project Nile installer file for Windows (an EXE extension) or Mac OS X (a DMG extension).
   
   
2. After the download completes, double-click the EXE or DMG file to run the installer. For Mac OS X, double-click the open-box icon that appears after you start the installer.
   
   
3. Proceed through the installer screens, accepting the license agreement and choosing a location in which to install the files.
   
   
   • For Windows - The default location is C:\Program Files\Sun\Project Nile
   • For Mac OS X - The default location is Macintosh HD/Applications/Project Nile

Any graphics file that can be viewed in Adobe Illustrator or Photoshop can be exported. You can export the graphics file to one of two formats:

• FXD file format (which automatically generates a JavaFX Script code file extending the UiStub class)
  
  
• JavaFX Script code (which extends the CustomNode class and defines the graphic in a single file)

To test the Project Nile plugin in Adobe Illustrator or Photoshop, do the following:

1. Open a graphics file in Adobe Illustrator or Photoshop.
   
   
2. From the main menu, choose one of the following commands:
   
   
   • Adobe Illustrator: File > Export
   • Adobe Photoshop: File > Export > JavaFX Export
   
   
3. In the Export dialog box, choose an export location, and choose JavaFX Data (*.FXD) or JavaFX Script (*.FX) as the file type.
   
   
4. Click Save.
   
   
5. To test the FX or FXD file, run JavaFX Graphics Viewer.

Project Nile includes an SVG Converter utility to convert scalable vector graphics (SVG) images to FXD file format or as JavaFX Script code. The format is determined by the file extension you provide for the output file.

You can run SVG Converter through the graphical user interface or through a command line or shell.

Running SVG Converter From the User Interface

1. Open the SVG Converter in one of the following ways:
   
   
   • For Windows - From the Start menu, choose Project Nile > SVG to JavaFX Converter.
     
     
   • For Windows - In the Project Nile installation directory (by default C:\Program Files\Sun\Project Nile), open the svg folder and double-click the svg2fx.exe file.
     
     
   • For Mac OS X - In the Project Nile Installation directory (by default Macintosh HD/Applications/Project Nile), double-click the SVG Converter file.
   
   
2. Type the source SVG file name, or browse to its location and select it.
   
   
3. Type the destination location and file name with an .fx or .fxd extension.
   
   
4. (Optional) If you selected FX format, type the name of the package for the JavaFX project.
   
   If you do not provide a name for the package, the class name in the JavaFX Script code file will be the same as the name you assigned to the file.
   
   
5. Click Convert.
   
   Note: If the source file or destination folder do not exist, the Convert button stays dimmed.
   
   A status message informs you that the file was successfully converted.
   
   
6. Test the conversion by inspecting the FX or FXD file, or open the file in JavaFX Graphics Viewer.

Running SVG Converter From a Command Line (Windows) or Darwin Shell (Mac OS X)
Use one of the following procedures, based on your operating system.

Windows Operating System

• Open a command prompt, navigate to the svg folder under the Project Nile folder, and run SVG Converter, using the following command line syntax:

  svg2fx [-options] source-file.svg dest-file.fx

  Options include the following:
  
  -c config-file (An advanced option that allows you to specify a configuration file besides the default config.xml).
  -p result-package-name (Specifies the package name for the JavaFX class that is created in the FX output file)
  -r (Removes the number suffix from shape IDs)
  
  For example, the following command converts the file BouncingBalls.svg to BouncingBallsfx and specifies demo as the package name:

  svg2fx -p demo c:\_a\BouncingBalls.svg c:\_a\BouncingBalls.fx

Mac OS X Operating System

• Open the Terminal utility and run SVG Converter by using the following syntax:

  "install-dir/svg2fx" [-options] source-dir/source-file.svg dest-dir/dest-file.fx

  Options include the following:
  
  -c config-file (An advanced option that allows you to specify a configuration file besides the default config.xml).
  -p result-package-name (Specifies the package name for the JavaFX class that is created in the FX output file)
  -r (Removes the number suffix from shape IDs)
  
  For example:

  "/Applications/Project Nile/SVG Converter.app/Contents/MacOS/svg2fx
      /Users/nh/Documents/Cheshire Cat.svg"
  
  "/Users/nh/Documents/Cheshire Cat.fxd"

Use JavaFX Graphics Viewer to display a graphic that was exported or converted to JavaFX Data (FXD) or JavaFX Script (FX). To be viewable, JavaFX Script code must extend the CustomNode class.

You can run JavaFX Graphics Viewer from the user interface or a command line or shell.

Running JavaFX Graphics Viewer From the User Interface

Open an exported FXD format or JavaFX Script code file in JavaFX Graphics Viewer in one of the following ways:

• For Windows - Right-click an FXD file format or JavaFX Script code file and choose Open.
  
  
• For Windows - From the Start menu, choose Project Nile > Media Viewer, then select the FXD or FX file that you want to open.
  
  
• For Windows - In the Project Nile installation directory (by default C:\Program Files\Sun\Project Nile), open the viewer folder, double-click viewer.exe, then select the FXD or FX file to open.
  
  
• For Mac OS X - Control-click an exported FXD file format or JavaFX Script code file and choose Open With > Viewer (default).
  
  
• For Mac OS X - In the Project Nile Installation directory (by default Macintosh HD/Applications/Project Nile), double-click Viewer, then select the FXD file format or JavaFX Script code file to open.
  

JavaFX Graphics Viewer displays the file.

Running JavaFX Graphics Viewer From a Command Line (Windows) or Darwin Shell (Mac OS X)

Windows Operating System

• Open a command prompt and type a command, using the following command line syntax:

  viewer-location\viewer.exe file-location\file-name

  For example:

  "C:\Program Files\Sun\Project Nile\viewer\viewer.exe" c:\temp\SideMenu.fx

Mac OS X Operating System

• Open the Terminal utility and type a shell command, using the following command line syntax:

  viewer-location/viewer file-location/file-name

  For example:

  "/Applications/Project Nile/Viewer.app/Contents/MacOS/viewer"
        "/Users/nh/Documents/JavaFX/Cheshire Cat.fxd"

Project Nile is bundled with four samples:

• Invaders. Shows how JavaFX Script code can be written to take advantage of artwork elements exported from Adobe Illustrator.
  
  
• MediaPlayer. Shows how the skin of an application like a media player can be changed with a single line of JavaFX Script code, using graphics exported from Adobe Illustrator.
  
  
• Puzzle15. Show how to use the JavaFX Loader class to load a set of tiles directly from an FXD file and manipulate them on a canvas.
  
  
• Sidemenu. Shows a static menu of seven items, with button state graphics exported from Adobe Illustrator or Adobe Photoshop. Each menu item is defined by a static graphic, hover-graphic and active area.

For an example of how to set up a sample in the NetBeans IDE, see the Project Nile tutorial entitled Integrating Graphic Assets into your JavaFX Application.

This section includes some common problems that you may experience during export or conversion. For more details on how Adobe Illustrator and Adobe Photoshop are exported, see the section on export in the Release Notes. For limitations with export and conversion, see the section on known issues in the Release Notes.

Adobe Illustrator and Photoshop Export Questions

• Problem: In Adobe Photoshop or Illustrator, when I click File > Export, I can't find the JavaFX export option.
  
  
  • Are you using the correct version of Adobe Photoshop and Illustrator?
    
    This version of Project Nile supports only Adobe Creative Suite 3.0.
    
    
  • Was the plug-in installed properly?
    
    Check that the plug-in was installed properly by looking for the following files in the following directories.
    
    

    Adobe Application	Platform	Plugin Folder Location	Project Nile Plugin File Names
    Photoshop	Windows	Photoshop-install-dir\Plug-ins\Import-Export	PS2JavaFX.8be
    	Mac OS X	Photoshop-install-dir\Plug-ins\Import/Export	PS2JavaFX.plugin
    Illustrator	Windows	Illustrator-install-dir\Plug-ins\Illustrator Formats	AI2JavaFX.aip AI2JavaFX.jar
    	Mac OS X	Illustrator-install-dir\Plug-ins\Illustrator Formats	AI2JavaFX.aip

     
    If not, manually install the plug-ins using the following procedure:
    
    
    1. Navigate to the Project Nile installation folder on your local system.
       
       
       • For Windows - The default Project Nile installation is located in C:\Program Files\Sun\Project Nile.
       • For Mac OS X - The default Project Nile installation is located in Macintosh HD/Applications/Project Nile
       
       
    2. Copy the files from the Adobe Illustrator and Photoshop folders into the appropriate plugin directories in the Adobe applications. Be sure to restart the Adobe application before testing it.
  
  
• Problem: How do I decide whether to export to FXD file format or FX source code?
  
  In a production environment, the best option is to export to the FXD file format (with an .fxd extension). When this option is selected, the plugin generates two files:
  
  
  • An FXD file, which contains only the graphics definitions. This file is not compiled during runtime but rather is loaded as a resource file.
    
    
  • A JavaFX Script code file, which serves as an interface for the generated FXD file. This file is compiled to bytecode.
  
  There are two advantages to selecting the FXD option:
  
  
  • If large graphics are compiled they can run into Java VM limitations. Saving to FXD format keeps the graphic from being compiled.
    
    
  • Keeping the graphic in a file separate from the JavaFX Script code preserves the distinction between designer and developer ownership. The designer can own the FXD file, and the developer can own the separate JavaFX Script code that is generated along with the graphic.
  
  Choose the FX source option (with an .fx extension) for smaller graphics only. When you export a graphics file to JavaFX Script code, it is generated as source in a single file, mixing both the actual graphics and the interface that the developer uses for accessing the graphics. Everything in the file will be compiled to bytecode, and because of this you may encounter Java VM limitations.

SVG Conversion Problems

• Problem: I get errors after a command line conversion from an SVG file.
  
  
  • Is the error an unsupported element?
    
    SVG <mask> and <filter> elements are not supported in this release.
    
    
  • Is the error for a duplicate ID?
    
    The SVG file should not contain duplicate IDs. Make sure your SVG file is valid before conversion.
    
    
  • Is the error for an unknown Tspan class?
    
    Tspan is not supported. See the Release Notes for more information.

JavaFX Graphics Viewer Problems

• Problem: I can't see the exported graphic in JavaFX Graphics Viewer.
  
  
  • Was the FXD conversion successful?
    
    When an Adobe Photoshop or Illustrator file is exported to JavaFX Data (FXD) format, here is what happens:
    
    
    • A file with an .fxd extension is created, in which each layer in the Adobe Photoshop or Adobe Illustrator file is defined as a group, with an ID value that is identical to the layer name.
      
      
    • A JavaFX Script code file is also created, with the same name as the FXD file with the letters UI appended. (For example, if the .fxd file is named test.fxd, then this file will be named testUI.fx.) The file defines a class that extends UIStub. Each graphical element with a custom name is exposed as an attribute in the class.
      
      
    • If the graphic includes custom fonts, the fonts are exported as True Type Font (.ttf) files.
      
      
    
    If the exported FXD format file is not displayed correctly in JavaFX Graphics Viewer, try this troubleshooting procedure.
    
    
    1. Open Adobe Photoshop or Illustrator, then open one of the sample files that is provided with either application.
       
       
    2. Export the Photoshop or Illustrator file to FXD file format.
       
       
    3. Test the exported file in JavaFX Graphics Viewer.
       
       If the FXD format file is not displayed correctly, examine the FXD file to see if each layer is defined as a group. Report an issue if necessary.
       
       
    4. If the FXD file exported from the sample is displayed correctly, open your own graphics file and repeat the process of checking the PNG files and FXD file to ensure that each layer exported correctly.
    
    
  • Was the FX conversion successful?
    
    When an Adobe Photoshop or Adobe Illustrator file is exported to JavaFX Script (FX), here is what happens:
    
    
    • The output is a source file which contains a class extending the javafx.gui.CustomNode class.
      
      
    • Each layer in the Photoshop or Illustrator file is defined as a group, with an ID value that is identical to the layer name.
      
      
    • Each graphical element with a custom name is exposed as an attribute in the class.
    
    If JavaFX Graphics Viewer does not display an exported JavaFX Script code file correctly, try this troubleshooting procedure.
    
    
    1. Try exporting the graphics file in FXD file format and test it in JavaFX Graphics Viewer.
       
       If the FXD file format is not displayed correctly, follow the previous steps on troubleshooting an FXD export.
       
       
    2. If the FXD file format is displayed correctly, the problem lies with the JavaFX Script code.

To uninstall Project Nile on a Windows operating system:

1. From Control Panel, choose Add or Remove Programs. Select Project Nile and click Remove.
   
   The Adobe Illustrator and Adobe Photoshop plugins will be uninstalled during this process for Windows.

To uninstall Project Nile on a Mac OS X operating system:

1. Navigate to the Project Nile installation folder.
   
   By default the path is Macintosh HD/Applications/Project Nile
   
   
2. Drag the Project Nile icon to the Trash.
   
   
3. Manually delete the plug-ins for Adobe Illustrator and Adobe Photoshop, if they are installed, by dragging them to the Trash:
   
   
   • In the Adobe Illustrator installation folder, the path is Plug-Ins/Illustrator Formats/AI2JavaFX.aip
   • In the Adobe Photoshop installation folder, the path is Plug-ins\Import/Export/PS2JavaFX.plugin/PS2JavaFX.plugin

Uninstalling Project Nile will not delete any samples that you have place in your NetBeans Projects folder.

• Release Notes for Project Nile Preview
• Integrating Graphic Assets into your JavaFX Application
• JavaFX Technology Downloads
• JavaFX.com
• JavaFX Developer home page