July 9, 1996
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 allocimage, freeimage, and info commands as well as the description of image items). This command can only be called within a render callback.
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.drawpolygonvector
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".
Sets the current drawing color to color. Note that color must have been previously allocated by thesetcolorcolor
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 "System" which causes the Pad++ line-font to be used. Defaults to "System". (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).
Sets the joinstyle of lines for drawing. Joinstyle may be any of: "bevel", "miter", or "round".setjoinstylejoinstyle
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.setlinewidthwidth
These commands provide drawing commands in a style much like postscript.
closepath
Specifies the end of a path.
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.curvetovector
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.
Draws the current path with an outline only - the path is not filled.stroke
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
Generated with Harlequin WebMaker