![](top.gif)
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
![](top.gif)
Copyright Computer Science Department, The University of New Mexico
Web Accessibility