summaryrefslogtreecommitdiff
path: root/graphics/jpicedt/doc/scripting.html
blob: 8e054d51d6dd3c2ea68a42d2de3690b8c8820745 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
	<HEAD>
    <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
	<META key="author" CONTENT="Sylvain Reynal">
    <TITLE>jPicEdt 1.3.2 Help Content </TITLE>
</HEAD>

<BODY BGCOLOR="#ffffff">

  	<H2>Using and writing BeanShell scripts</H2>

  	<p>
	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.
	</p>
	
	<p>
	A comprehensive documentation about BeanShell can be found at :
	<a href="http://www.beanshell.org">www.beanshell.org</a>. Yet scrutinizing into
	the scripts shipped with jPicEdt is a good starting point. You might also need the 
	<b>jPicEdt API documentation</b> at some point (please download it from www.jpicedt.org), 
	especially if you would like to
	write scripts involving complex operations. The <b>jpicedt.JPicEdt</b> class offers
	a variety of static methods (e.g. <code>JPicEdt.newBoard()</code>) 
	that might fullfill basic needs. Other classes of importance are :
	</p>
	<ul>
	<li><b>jpicedt.ui.MDIManager</b> for managing drawing-boards (creating a new board, moving it, cascading boards,...)</li>
	<li><b>jpicedt.ui.PEDrawingBoard</b> and <b>jpicedt.graphic.PECanvas</b> (PEDrawingBoard comprises a PECanvas
		and a PEScrollPane) for interacting with selected objects, zooming, performing I/O operations, or even
		fiddling about with the UndoManager :-), ...</li>
	<li><b>jpicedt.graphic.model.Drawing</b> for adding objects to a drawing-board ;</li>
	<li><b>jpicedt.graphic.model.Element</b> and concrete implementations (ellipses, rectangles,...) 
		for altering objects shape and attributes ;</li>
	<li><b>jpicedt.graphic.view.View</b> and concrete implementations (ellipses, rectangles,...) 
		for changing how object LOOK on the screen (but not how they're formatted to a LaTeX string);</li>
	<li><b>jpicedt.graphic.toolkit.EditorKit</b> for changing the way objects are edited with the mouse 
		(that is, either altering existing behaviours, or adding new ones).</li>
	<li>Classes in the <b>jpicedt.format.*</b> 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,...).</li>
	</ul>
	</p>
	<p>
	All those classes are easily extensible, and can be plugged to each other (well, the so famous
	View-Model-Controller scheme, like...).
	Besides, <b>jpicedt.JPicEdt</b> and <b>jpicedt.graphic.toolkit.EditorKit</b> contains a variety
	of <i>Actions</i> (implemented as static classes) that you can subclass, then add to your own graphical
	interface. Look at the documentation in <b>jpicedt.graphic.toolkit.PEAction</b> to know what is an 
	<i>Action</i> and how you may use it into your own code.
	</p>
	<p>
	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 :
	</p>
	<ul>
	<li><b>board()</b> : return the currently selected PEDrawingBoard, or null if there's no open board ;</li>
	<li><b>canvas()</b> : return a reference to the active PECanvas, i.e. being hosted by the currently selected PEDrawingBoard ;</li>
	<li><b>drawing()</b> : return a reference to the Drawing (aka MODEL) attached to the active PECanvas ;</li>
	<li><b>editorkit()</b> : return a reference to the EditorKit (aka CONTROLER) attached to the active PECanvas ;</li>
	<li><b>mdimgr</b> : predefined variable referencing the current MDIManager.</li>
	<li><b>clipboard</b> : 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.</li>
	<li><b>preferences</b> : predefined variable referencing a Properties object holding user's prefs.</li>
	</ul>
   
   	<h2>OK, where do I put my scripts ?</h2>
	<p>
	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 <code>source(path_to_other_script)</code> command, and even add your own classes by using
	the <code>addClassPath()</code> command.
	</p>
	<p>
	Use the BSH console to test your script, then put them in the script-directory and they'll show up!
	</p>
</BODY>
</HTML>