Business Shell (BUSH) Guide
Author: Ken Burtch

Home Page | Introduction | Tutorials | Reference | Packages | Hacking

Packages
4.1 Using Packages
4.2 text_io (Console I/O)
4.3 text_io (File I/O)
4.4 sound
4.5 source_info
4.6 System
4.7 numerics
4.8 strings
4.9 command_line
4.10 lock_files
4.11 cgi
4.12 calendar
4.13 units
4.14 arrays
4.15 files
4.16 db (Database)
4.17 stats
4.18 pen
4.19 mysql
4.20 os
| This part of the guide contains detailed descriptions of the BUSH built-in packages. ### 4.18 Pen Package NOTE: This package is under construction. The features have not been finalized. The pen package is the BUSH drawing environment. It is based on the Simple DirectMedia Layer portable drawing environment originally created by Loki Games, a Linux games company. However, the SDL is strictly a hardware interface: it contains few drawing primitives. The pen package extends the SDL for useful drawing. The drawing surface is called a canvas. The canvas can be a window or the hardware screen, but it can also be an off-screen area in memory. The drawing area is divided up into a number of rectangular pixels. To open a new canvas in a X Windows window, use:
    => pen.new_window_canvas( 256, 256, 16, canvas_id )
    => (Assuming canvas_id is a new pen.canvas_id variable)
    => pen.set_title( canvas_id, "Drawing Area" )
This canvas will be 256 pixels wide, 256 pixels high, a minimum of 16-bit colour and it will have an X windows title of "Drawing Area". canvas_id is the id number referring to the canvas. The coordinate system of the canvas has an origin point at the top-left corner of the drawing surface. The coordinate lines actually fall between the pixels so that coordinate (0,0) is actually to the upper-left of the first pixel. The coordinates are floating point numbers representing a percentage of the canvas. The canvas ranges from (0,0) to (100,100). The pen package draws on the canvas using an imaginary pen. The pen has several properties: Position - the location of the pen on the canvas Direction - the angle of rotation of the pen Ink - the solid colour used drawing with the pencil brush Pattern - multi-colour ink used for drawing Brush - how the ink is spread on the canvas Mode - how the ink is combined with the canvas pixels Pen modes include: Off - the pen moves but no drawing takes place Copy - the ink overwrites the existing pixels on the canvas. This is the normal pen mode. Invert - the ink is exclusive-or'd with the pixels. Where the ink is 0%, the canvas is unchanged. Where the ink is 100%, the canvas pixels are transformed to the opposite colour. This is useful for simple hilighting that doesn't lose information on the canvas. Add - adds the canvas pixels to the ink pixels Subtract - removes the canvas pixels from the ink pixels Average - blends the canvas and ink pixels, taking the average value Fade - brighten or darken the canvas pixels Min - where the ink is not 0, choose the darker pixel between the ink and the canvas. If the ink is 0, leave the canvas unchanged. Max - where the ink is not 0, choose the brighter pixel between the ink and the canvas. If the ink is 0, leave the canvas unchanged. The brush describes the pattern the pen will draw with: Pencil - drawing by single pixels of a solid colour ink Smear - (Not complete) Stamp - draw with a pattern aligned to the shape Stretch - (Not complete) Resize the pattern to fit a shape Tile - draw with a pattern aligned to the canvas Not all pen modes are available on all kinds of canvas.
    => pen.set_pen_mode( canvas_id, pen_mode.copy )
    => pen.set_pen_brush( canvas_id, pen_brush.pencil)
    => pen.set_pen_ink( canvas_id, 100, 0, 0 )
These commands set the pen brush to a pencil (single pixels) and the mode to copy (the pencil pixels will overwrite whatever pixels currently on the canvas background). The pen pixels will be bright red. pen.fill_ellipse( c, r )
Fill ellipse bounded by rectangle r in canvas c using the current pen. Example: pen.fill_ellipse( canvas_id, pie_graph_rect ); Ada Equivalent: N/A - Pen.fillRect (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rect | required | the rectangle surrounding ellipse to fill
pen.fill_rect( c, r )
Fill rectange r in canvas c using the current pen. Example: pen.fill_rect( canvas_id, background_rect ); Ada Equivalent: N/A - Pen.fillRect (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rect | required | the rectangle to fill
pen.frame_ellipse( c, r )
Draw an outline around ellipse bounded by rectangle r in canvas c using the current pen. Example: pen.fill_ellipse( canvas_id, pie_graph_rect ); Ada Equivalent: N/A - Pen.frameRect (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rect | required | the rectangle surrounding ellipse to border
pen.frame_rect( c, r )
Draw an outline around rectange r in canvas c using the current pen. Example: pen.frame_rect( canvas_id, background_rect ); Ada Equivalent: N/A - Pen.fillRect (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rect | required | the rectangle to border
b := pen.get_pen_brush( c )
Return the current pen brush for canvas c. Example: pen_brush := pen.get_pen_brush( canvas_id ); Ada Equivalent: N/A - Pen.getPenBrush (BUSH package) Parameters:
b | result | pen.pen_brush | required | the pattern application mode
c | in | pen.canvas_id | required | the drawing area canvas
pen.get_pen_ink( c, r, g, b )
Return the current pen solid drawing colour in canvas c. Example: pen.get_pen_ink( canvas_id, red, green, blue ); Ada Equivalent: N/A - Pen.getPenInk (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rgbcomponent | required | percentage of red in the color
g | in | pen.rgbcomponent | required | percentage of green in the color
b | in | pen.rgbcomponent | required | percentage of blue in the color
m := pen.get_pen_mode( c )
Return the current pen mode for canvas c. Example: pen_mode := pen.get_pen_mode( canvas_id ); Ada Equivalent: N/A - Pen.getPenMode (BUSH package) Parameters:
m | result | pen.pen_mode | required | the pen mode
c | in | pen.canvas_id | required | the drawing area canvas
pen.hline( c, x1, x2, y )
Draw a horizontal line between (x1,y) and (x2,y) on canvas c in the current pen. Example: pen.hline( canvas_id, 0, 100, 50); Ada Equivalent: N/A - Pen.hline (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
x1 | in | pen.coordinate | required | the left-most x coordinate
x2 | in | pen.coordinate | required | the right-most x coordiante
y | in | pen.coordinate | required | the y coordinate
b := pen.in_rect( x, y, r )
True if point (x, y) is inside of rectangle r. Example: b := pen.in_rect( mouse_x, mouse_y, icon_rect ); Ada Equivalent: N/A - Pen.in_rect (BUSH package) Parameters:
b | result | boolean | required | true if ir is contained in or
x | in | pen.coordinate | required | the horizontal position
yr | in | pen.coordinate | required | the vertical position
pen.inset_rect( r, dx, dy )
Change the size of the rectangle by dx horizontal and dy vertical. Negative values cause the rectangle to grow. The center of the rectangle remains unchanged. Example: pen.inset_rect( shrinking_rect, 10, 10 ); -- shrink by 10% of canvas Ada Equivalent: N/A - Pen.inset_rect (BUSH package) Parameters:
r | in out | pen.rect | required | the rectangle to shift
dx | in | pen.coordinate | required | the horizontal change to the left and right
dy | in | pen.coordinate | required | the vertical change to the top and bottom
b := pen.inside_rect( ir, or )
True if ir is a rectangle inside of rectangle or. Example: b := pen.inside_rect( small_rect, big_rect ); Ada Equivalent: N/A - Pen.inside_rect (BUSH package) Parameters:
b | result | boolean | required | true if ir is contained in or
ir | in | pen.rect | required | the inner rectangle
or | in | pen.rect | required | the outer rectangle
pen.intersect_rect( r, r1, r2 )
Calculate the overlap rectangle (if any) between rectangles r1 and r2. Example: pen.intersect_rect( overlap_rect, player_sprite, monster_sprite ); Ada Equivalent: N/A - Pen.intersect_rect (BUSH package) Parameters:
r | out | pen.rect | required | the intersection rect or empty rect if none
r1 | in | pen.rect | required | a rectangle
r2 | in | pen.rect | required | a rectangle
b := pen.is_empty_rect( r )
True if r is a rectangle that contains nothing. Example: bool := pen.is_empty_rect( some_rect ); Ada Equivalent: N/A - Pen.isEmptyRect (BUSH package) Parameters:
c | result | boolean | required | true if rectangle is empty
r | in | pen.rect | required | the rectangle to test
pen.line( c, dx, dy )
Draw a line in the current pen from the current pen position to a new relative position offset by dx and dy. Example: pen.line( canvas_id, 0, 10 ); Ada Equivalent: N/A - Pen.line (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
dx | in | pen.coordiante | required | the horizontal change from the current pen position
dy | in | pen.coordiante | required | the vertical change from the current pen position
pen.line_to( c, x, y )
Draw a line with the pen from the current pen position to a new position (x,y). Example: pen.line_to( canvas_id, 75, 10 ); Ada Equivalent: N/A - Pen.line (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
x | in | pen.coordiante | required | the new horizontal position
y | in | pen.coordiante | required | the new vertical position
pen.move( c, dx, dy )
Move the pen from the current pen position to a new relative position offset by dx and dy. No line will be drawn. Example: pen.move( canvas_id, 0, 10 ); Ada Equivalent: N/A - Pen.move (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
dx | in | pen.coordiante | required | the horizontal change from the current pen position
dy | in | pen.coordiante | required | the vertical change from the current pen position
pen.move_to( c, x, y )
Move the pen from the current pen position to a new position (x,y). No line will be drawn. Example: pen.move_to( canvas_id, 75, 10 ); Ada Equivalent: N/A - Pen.move (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
x | in | pen.coordiante | required | the new horizontal position
y | in | pen.coordiante | required | the new vertical position
pen.new_canvas( h, v, c, id ) pen.new_canvas( s, id )
Create a new drawing area canvas that does not appear on the display. If the first parameter is a string, load the image file from path s into a canvas big enough to hold it. Example: pen.new_canvas( 100, 100, 16, canvas_id ); Example: pen.new_canvas( "company_logo.png", logo_id ); Ada Equivalent: N/A - Pen.newCanvas (BUSH package) Parameters:
h | in | positive | required | the minimum horizontal size in pixels
v | in | positive | required | the minimum vertical size in pixels
c | in | positive | required | the minimum pixel bits (8, 16, 24 or 32)
id | out | pen.canvas_id | required | the identification number for the offscreen canvas
s | in | universal_string | required | the path to a file that SDL_image can load (JPEG, GIF, PNG, etc.)
pen.new_screen_canvas( h, v, c, id )
Create a new drawing area canvas that covers the entire display screen. Example: pen.new_screen_canvas( 100, 100, 16, canvas_id ); Ada Equivalent: N/A - Pen.newScreenCanvas (BUSH package) Parameters:
h | in | positive | required | the minimum horizontal size in pixels
v | in | positive | required | the minimum vertical size in pixels
c | in | positive | required | the minimum pixel bits (8, 16, 24 or 32)
id | out | pen.canvas_id | required | the identification number for the new canvas
pen.new_window_canvas( h, v, c, id )
Create a new drawing area canvas in a separate operating system window. Example: pen.new_window_canvas( 100, 100, 16, canvas_id ); Ada Equivalent: N/A - Pen.newWindowCanvas (BUSH package) Parameters:
h | in | positive | required | the minimum horizontal size in pixels
v | in | positive | required | the minimum vertical size in pixels
c | in | positive | required | the minimum pixel bits (8, 16, 24 or 32)
id | out | pen.canvas_id | required | the identification number for the new canvas
pen.offset_rect( r, dx, dy )
Move rectangle by dx horizontal and dy vertical. The size of the rectangle remains unchanged. Example: pen.offset_rect( player_sprite, 1, 0 ); Ada Equivalent: N/A - Pen.offset_rect (BUSH package) Parameters:
r | in out | pen.rect | required | the rectangle to shift
dx | in | pen.coordinate | required | the horizontal change to the left and right
dy | in | pen.coordinate | required | the vertical change to the top and bottom
pen.set_pen_brush( c, b )
Change the current pen brush (pattern application mode) for canvas c. Example: pen.set_pen_brush( canvas_id ); Ada Equivalent: N/A - Pen.setPenBrush (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
b | result | pen.brush | required | the new pattern application mode
pen.set_pen_ink( c, r, g, b )
Change the current pen solid drawing colour in canvas c. Example: pen.set_pen_ink( canvas_id, red, green, blue ); Ada Equivalent: N/A - Pen.setPenInk (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
r | in | pen.rgbcomponent | required | percentage of red in the color
g | in | pen.rgbcomponent | required | percentage of green in the color
b | in | pen.rgbcomponent | required | percentage of blue in the color
m := pen.set_pen_mode( c )
Change the current pen mode for canvas c. Example: pen_mode := pen.get_pen_mode( canvas_id ); Ada Equivalent: N/A - Pen.getPenMode (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
m | in | pen.pen_mode | required | the pen mode
pen.set_pen_pattern( c, pid )
Change the drawing pattern of canvas c to canvas pid. Example: pen.set_pen_pattern( canvas_id, company_logo_canvas_id ); Ada Equivalent: N/A - Pen.setPenPattern (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
pid | in | pen.canvas_id | required | the canvas to use as the drawing pattern
pen.set_rect( r, l, t, r, b )
Assign coordinates to a rectangle. Example: set_rect( full_canvas, 0, 0, 100, 100 ); Ada Equivalent: N/A - Pen.setRect (BUSH package) Parameters:
r | in | pen.rect | required | the rectangle
l | in | pen.coordinate | required | the left coordinate
| t | in | pen.coordinate | required | the top coordinate
| r | in | pen.coordinate | required | the right coordinate
| b | in | pen.coordinate | required | the bottom coordinate

pen.set_title( c, t )

Change the title of canvas c to string t. On a window canvas, update the window title bar. Example: set_title( canvas_id, "Graph of Results" ); Ada Equivalent: N/A - Pen.setTitle (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
t | in | universal_string | required | the new title

pen.vline( c, x, y1, y2 )

Draw a vertical line between (x,y1) and (x,y2) on canvas c in the current pen. Example: pen.set_vline( canvas_id, 50, 0, 100); Ada Equivalent: N/A - Pen.hline (BUSH package) Parameters:
c | in | pen.canvas_id | required | the drawing area canvas
x | in | pen.coordinate | required | the x coordinate
y1 | in | pen.coordinate | required | the top-most y coordiante
y2 | in | pen.coordinate | required | the bottom-most y coordinate

Back to Top