Pad++ Reference Manual

KPL-Pad++ Interface

As described in the section above on KPL ITEMS, Kpl is a byte-compiled language that comes with Pad++ that is typically used for creating new objects. It is a general-purpose language, and has the ability to call certain Pad++ rendering routines. Some basic documentation is available with the Pad++ release in doc/kpl.troff.

There are two ways to interact with Kpl. The first is to make a Pad++ Kpl item with a Kpl renderscript (described above). In this case, every time the item is rendered, the Kpl script will be executed. The second method is to use the kpl command available directly from Tcl. The kpl command has the following format:

kpl subcommand [args ...]

Where subcommand must be one of the following:

eval string

: Byte-compiles and evaluates string as a Kpl script.

push value

: Pushes value onto the top of the Kpl stack.

pop

: Pops the top element off of the Kpl stack and returns it.

get name

: Returns the current value of the Kpl variable, name.

set name value

: Sets the Kpl variable name to value.

There are several Kpl commands available for interacting with the Tcl environment, and for rendering directly onto the Pad++ surface (when within a render callback). They are organized into a few groups as follows:

These commands provide a mechanism for accessing Tcl variables from Kpl.

tclset name value

: Sets the global Tcl variable name to value.


tclset2 array_name element value

: Sets the global Tcl array array_name(element) to value.


tclget name

: Returns the value of the global Tcl variable name.


tclget2 array_name element

: Returns the value of the global Tcl array array_name(element).


tcleval tcl_string

: Evaluates the Tcl string tcl_string.

These commands provide basic drawing capability.

drawborder llcorner urcorner width border relief

: Draws a 3D border within the rectangle specified by llcorner and urcorner (where each of those are 2D vectors). Width specifies the zoomable width of the border. Border specifies the border color and must have been previously allocated with the Pad++ allocborder command. Relief specifies the style of border, and must be one of: "raised", "flat", "sunken", "groove", "ridge", "barup", or "bardown".


drawline vector

: Draws a line specified by vector. As Kpl vectors may be up to 16-dimensional, this vector can specify up to 8 (x, y) points. This routine will draw a line connecting as many points as are specified within vector.


drawimage imagetoken x y

: Draws the image specified by imagetoken at the point (x, y). (Also see image commands as well as the description of image items). This command can only be called within a render callback.


drawpolygon vector

: Draws a polygon specified by vector. As Kpl vectors may be up to 16-dimensional, this vector can specify up to 8 (x, y) points. This routine will draw a closed polygon connecting as many points as are specified within vector.


drawtext text position

: Draws text. Text specifies the text to be drawn. Position specifies the where the text gets drawn. Position is a two-dimensional vector specifying the (x, y) position. (Also see the KPL setcolor, setfont, and setfontheight commands.)


getlevel

: Returns the current refinement level.


getsize

: Returns the current size of the object, where size is the larger of the width and height.


renderitem tagOrId

: During a render callback triggered by the -renderscript option, this function actually renders the object. During a -renderscript callback, all the items specified by tagOrId are rendered (and the current item is not rendered unless it is in tagOrId). This function may only be called during a render callback.

setabslinewidth width

: Sets the current drawing with to an absolute width. All lines will be drawn with this width. This is an absolute width, so this specifies the width independent of the current view. I.e., the line width will not change as the view changes.


setcapstyle capstyle

: Sets the capstyle of lines for drawing. Capstyle may be any of: "butt", "projecting", or "round".


setcolor color

: Sets the current drawing color to color. Note that color must have been previously allocated by the alloccolor Pad++ command.


setfont font

: Specifies the font to be used for rendering text for this item. Font must specify a filename which contains an Adobe Type 1 font, or the string "Line" which causes the Pad++ line-font to be used. Defaults to "Times-12". (Also see the setfontheight command.)


setfontheight height

: Sets the height of the font for future drawing with render callbacks. Height is specified in pixels. (Also see the setfont command).


setjoinstyle joinstyle

: Sets the joinstyle of lines for drawing. Joinstyle may be any of: "bevel", "miter", or "round".


setlinewidth width

: Sets the current drawing width to a zoomable width. All lines will be drawn with this width. This is a zoomable width, so this specifies the width as it will look when the view has a magnification of 1.0.

These commands provide drawing commands in a style much like postscript.

closepath

: Specifies the end of a path.


curveto vector

: Draws a bezier curve. Here, vector is a six-dimensional vector. The current point plus these three points specify four points which control the bezier curve.


fill

: Fills the current path.


lineto vector

: Specifies a straight line in the current path from the current point to (x, y) specified by vector. Makes (x, y) the current point.


moveto vector

: Moves the current point within the current path to (x, y) specified by vector.


newpath

: Specifies the beginning of a new path.


stroke

: Draws the current path with an outline only - the path is not filled.

These commands provide control over refinement.

interrupted

: Returns true (1) if there has been an event during this render to interrupt it. It is up to objects that take very long to render themselves to check this flag during the rendering. If it is true (i.e., the render has been interrupted), then the Kpl render routine should return immediately - without completing the render. Generally, renders at refinement level 0 should always be quite fast, but further refinement levels can take an arbitrarily long time to render as long as they are interruptible.

refine

: Specifies that this item wants to be refined. Pad++ will schedule a refinement, and at some point in the near future, the item will be re-rendered at the next higher refinement level. An item can use the current level in conjunction with this command to render itself simply at first, and then fill in more and more detail when it is refined.

Here is an example that creates a Kpl item with a renderscript that exercises some of the commands described here.

				# Tcl code to load Kpl code and to create
				# Pad++ Kpl item.
kpl eval 'triangle.kpl source
set pen [.pad alloccolor brown]
.pad create kpl -bb {-10:-10 110:110} -renderscript {test_drawing}

				/* Kpl code (in a separate file)
				   to test the drawing commands */
{
					/* Draw a looping bezier curve */
	3 setlinewidth
	'pen1 tclget setcolor
	newpath
		0:0 moveto
		200:75:-100:75:100:0 curveto
	stroke

					/* Draw a filled square */
	'pen2 tclget setcolor
	newpath
		0:0 moveto
		50:0 lineto
		50:50 lineto
		0:50 lineto
	fill

					/* Draw a square outline */
	'pen3 tclget setcolor
	newpath
		0:0 moveto
		50:0 lineto
		50:50 lineto
		0:50 lineto
		0:0 lineto
	stroke

					/* Draw a square outline 
					with an absolute width */
	1 setabslinewidth
	'pen4 tclget setcolor
	newpath
		0:0 moveto
		50:0 lineto
		50:50 lineto
		0:50 lineto
		0:0 lineto
	stroke

					/* Cause one level of refinement.  
					Notice the bezier curve is rendered
					at low-resolution at first, 
					and then improves with refinement. */
	getlevel => i
	i 1 < (
		refine 
	)
} -> test_drawing

Pad++ Reference Manual - 20 JUN 1997

Web Accessibility