Advanced users can create custom JavaScript programs that run in PhotoGrok. These scripts can control how the tree is filtered, collect data about the images and even draw on the main image screen. Scripts are useful when used in conjunction with JavaScript filters. The scripting window is opened by pressing Ctrl+Shift+J. There is a small API to communicate with PhotoGrok. Scripts are saved with settings. The following functions can be called:

• getMap() : Returns a Java HashMap for persisting information. The "Clear Map" button removes all entries from the map.
• showMessage(msg) : Displays a message dialog to the user. Typically called from done() callback function.
• request(label) : Returns a value entered by the user. "label" is displayed above the text input on the dialog.
• convertDate(date) : Takes a date in ExifTool's default format and returns a JavaScript date object.
• dec(shutterspeed) : Takes an ExifTool ShutterSpeed value and converts it to a decimal number.
• done() : Callback function called when the tree or catalog build is complete. Useful for displaying information. Use 'background' function (below) if you need to execute a long-running task.

New functions in PhotoGrok 2.41:

• buildTree(fromCatalog, doneFunc) : Runs a tree build. Boolean "fromCatalog" determines whether to build from catalog or real time. "doneFunc" is a function to run when build is complete. This function does nothing if called during another tree or catalog build.
• getNodes() : Returns an array of all nodes in the tree. Each node object has a "name" and "dir" property.
• selectNode(node) : Expands the tree and selects the "node". See getNodes() for details on obtaining node objects
• setExtensions(ext) : Sets the extensions in preferences. "ext" is a comma-delimited string of file extensions.
• getTagValue(tag) : Returns the value for "tag" string from the list of exif data on the screen.
• getExifData(dir, file) : Returns a complete list of exif data including custom tags for the given directory and file. Calls ExifTool so can be expensive.
• background(bgFunc, doneFunc) : Runs "bgFunc" function in a background thread (while blocking user input). "doneFunc" executes when background thread finishes (can be null).
• setPainter(painterFunc) : The painterFunc function (details below) allows drawing on the main PhotoGrok image panel. Can be used to implement histograms, etc.
• onBuildTree(fromCatalog) : Callback function fired when a tree build is executed. "fromCatalog" will be true if tree built from catalog.
• onBuildCatalog() : Callback function fired when a catalog build is executed.
• onLoadSettings() : Called when a new setting preset is loaded. Call buildTree function to create auto-executing preset.

New functions in PhotoGrok 2.42:

• setThumbnailPainter(painterFunc) : Sets a painter function for thumbnails and the popup preview.

New functions in PhotoGrok 2.43:

• addMenuCommand(label, function(nodes[]){}) : Add a command to the popup menu for an image/tree node. The function will execute against all selected nodes when executed. See examples.
• execExifTool(array) : Pass in an array of strings containing Exiftool command line options. Returns output from ExifTool as an array of strings.
• execCommand(dir, cmdarray) : Runs a external program. String dir is the directory to run in (can be null) and cmdarray is a string array containing the command and arguments to run. Since 2.45 returns object with returnCode and response. returnCode is an int and response is an array of strings containing output of command.
• xzCompress(dir, filename) : Compress a file. The output file is saved to the same directory as the original with an .xz extension. Returns true if successful.
• xzDecompress(dir, filename) : Decompress an .xz file. Output file is saved to same directory minus the .xz extension. Returns false if action fails, the file doesn't end in .xz or the decompressed file already exists.
• setScanDirs(boolean, array) : Set directories to be scanned by the tree build process. Boolean true to scan subdirectories. Array is JavaScript string array of directories to scan.
• setTags(tags) : Sets the tags used for building a dynamic tree. Argument is a comma-delimited list of ExifTool/PhotoGrok tags.
• copyTree(node, string) : Copy a tree structure to destination directory (similar to popup menu's "copy tree"). Node is a treenode (see getNodes function). String is destination directory. Function does nothing if tree or catalog build is running.
• importCatalog() : Imports files into catalog based on current settings. Use setExtensions and setScanDirs functions to change which dirs/files are scanned. Does nothing if tree build or catalog import already running.
• refreshFile(dir, file) : Refreshes/adds a file's data into the current catalog. If file doesn't exist in filesystem the file's data is removed from the catalog. Returns true if successful. Does nothing if tree build or catalog import currently running.
• setStatusText(txt, boolean) : Set the status bar message to txt. Boolean flag to show spinning busy icon. Pass null to clear status message.

New functions in PhotoGrok 2.55:

• setPreviewPainter(painterFunc) : Sets a painter function for the rollover preview image.

New functions in PhotoGrok 2.56:

• clearConsole() : Programmatically clears the console (CTRL+SHIFT+C to show console). Use print("") function to write text to console from scripts.
• addMenuCommand(label, function(nodes[]){}, menu) : Added optional third "menu" parameter to create a submenu. All items with the same "menu" name will appear on a corresponding submenu.
• addUserCommand(label, function(){}, menu) : Add top-level menu item meant for global functions. The optional "menu" parameter defines a submenu. See JHLabs image filter example.

Modified functions in PhotoGrok 2.57:

• addMenuCommand(label, function(nodes[], label, menu){}, menu) : Passed in function can optionally accept menu name and submenu name.
• addUserCommand(label, function(label, menu){}, menu) : Passed in function can optionally accept menu name and submenu name.

Modified functions in PhotoGrok 2.58:

• Enabled Nashorn scripting enhancements for Java 8 and above. Allows use of readFully and load. See nashorn documentation for details.
• readFromURL(url) : Read text from a web resource. Intending for loading JS libraries.
• getPanelImage(): Returns the scaled BufferedImage being displayed. Use for temporary manipulation - this is not a painter. See examples.
• setPanelImage(image): Sets the currently displayed image and repaints the screen. Only for temporary filtering, etc. Image is lost when a new photo is selected.

Modified functions in PhotoGrok 2.59:

• Added preprocessor directives to allow choice of scripting engine and configuration parameters. See scripts.txt.
• getPanelImageProps(): returns map with information about displayed image. properties: offsetX, offsetY, visibleRect (x, y, w, h).
• onImageChanged(path): Callback with file path when image changes.
• onImageZoomed(path): Callback with file path when image zooming is complete.
• onImageDragged(path): Callback with file path when image dragging is complete.
• onImageResized(path): Callback with file path when image resizing is complete.
• script_engine_name: property containing engine name (rhino, nashorn)

JavaScript filters (including those defined in custom tags) run in the same scope and therefore can access variables and functions from the main script - a filter is called against every image as the tree is created. Global variables are cleared between each execution. Use getMap() to persist data if necessary. The main script is evaluated when the script window is closed, when a new setting is loaded and when a tree or catalog is built manually (not through automated script functions).

Scripts can call the full Java API (see Java's Rhino and/or Nashorn documentation).

Starting with version 2.41, advanced users can write JavaScript functions that can paint on the main image screen. This can be used to implement histograms (see example) to things like face recognition and image filters. In version 2.42, the "Apply Painter" checkbox in preferences allows a painted image to be exported. A painter is defined and registered as follows:

setPainter(function(gfx, scaledImage, fullImage, painterProps){
	// draw the file name on the image
	gfx.setColor(Color.RED);
	gfx.drawString(painterProps.file, 20, 50);
});

Function Parameters:

• gfx : Java Graphics/Graphics2D context
• scaledImage : Java BufferedImage containing scaled image displayed on main screen
• fullImage : Java BufferedImage containing full image data
• painterProps : Object containing useful values about the current environment

painterProps Properties:

• imageX : x coordinate of scaled image on screen
• imageY : y coordinate of scaled image on screen
• viewWidth : total width of view
• viewHeight : total height of view
• fullScreen : true if image in fullscreen mode (slideshow or single image)
• dragging : true if image is being dragged
• zooming : true if image is being zoomed
• resizing : true if image is being resized by user
• file : file name of current image
• dir : directory of current image
• getImageRect(image) : Since 2.42. Return rectangle object with x, y, width, height representing visible bounds of displayed image