Using and writing BeanShell scripts

jPicEdt now supports scripting (aka "macros") through an embedded BeanShell interpreter. BeanShell is a lightweight, extensible and embedabble scripting extension to Java, written by Pat Niemeyer (pat@pat.net). It follows the Java grammar (though with higher tolerance towards syntax errors ; in particular it has weak typing capabilities), hence anyone having a smattering of Java can write BeanShell scripts.

A comprehensive documentation about BeanShell can be found at : www.beanshell.org. Yet scrutinizing into the scripts shipped with jPicEdt is a good starting point. You might also need the jPicEdt API documentation at some point (please download it from www.jpicedt.org), especially if you would like to write scripts involving complex operations. The jpicedt.JPicEdt class offers a variety of static methods (e.g. JPicEdt.newBoard()) that might fullfill basic needs. Other classes of importance are :

• jpicedt.ui.MDIManager for managing drawing-boards (creating a new board, moving it, cascading boards,...)
• jpicedt.ui.PEDrawingBoard and jpicedt.graphic.PECanvas (PEDrawingBoard comprises a PECanvas and a PEScrollPane) for interacting with selected objects, zooming, performing I/O operations, or even fiddling about with the UndoManager :-), ...
• jpicedt.graphic.model.Drawing for adding objects to a drawing-board ;
• jpicedt.graphic.model.Element and concrete implementations (ellipses, rectangles,...) for altering objects shape and attributes ;
• jpicedt.graphic.view.View and concrete implementations (ellipses, rectangles,...) for changing how object LOOK on the screen (but not how they're formatted to a LaTeX string);
• jpicedt.graphic.toolkit.EditorKit for changing the way objects are edited with the mouse (that is, either altering existing behaviours, or adding new ones).
• Classes in the jpicedt.format.* package, for interacting with content-types, i.e. changing the way objects are formatted to LaTeX and/or TeX-file are parsed for a given format (LaTeX, eepic,...).

All those classes are easily extensible, and can be plugged to each other (well, the so famous View-Model-Controller scheme, like...). Besides, jpicedt.JPicEdt and jpicedt.graphic.toolkit.EditorKit contains a variety of Actions (implemented as static classes) that you can subclass, then add to your own graphical interface. Look at the documentation in jpicedt.graphic.toolkit.PEAction to know what is an Action and how you may use it into your own code.

For convenience, some useful variables and methods have been predefined, and are available on start-up both in the BSH Console, and from scripts being run from the script-menu. These are :

• board() : return the currently selected PEDrawingBoard, or null if there's no open board ;
• canvas() : return a reference to the active PECanvas, i.e. being hosted by the currently selected PEDrawingBoard ;
• drawing() : return a reference to the Drawing (aka MODEL) attached to the active PECanvas ;
• editorkit() : return a reference to the EditorKit (aka CONTROLER) attached to the active PECanvas ;
• mdimgr : predefined variable referencing the current MDIManager.
• clipboard : predefined variable referencing the local clipboard shared across all drawing boards (as opposed to the system's clipboard, which you can access from jPicEdt using the Paste Special menu item, yet which doesn't accept anything else but text data) ; needed for copying and pasting things from/into a PECanvas.
• preferences : predefined variable referencing a Properties object holding user's prefs.

OK, where do I put my scripts ?

User's scripts must reside in the "macros" subdirectory of the user-settings directory (for instance, /home/user/.jpicedt/macros on Unix). Scripts must have a ".bsh" extension. Names having underscores will have these replaced by white-spaces in the script-menu (e.g. Repeat_copy.bsh will show up as "Repeat copy"). You can call other scripts from inside a script by using the BSH source(path_to_other_script) command, and even add your own classes by using the addClassPath() command.

Use the BSH console to test your script, then put them in the script-directory and they'll show up!