* * * * * * * * * * * * * * * * * * * * * * * Tasks & Functions in the * * * * Ultra-SiMPLE System Library * * * * * * (Unabridged) * * * * * * * * * * * * * * * * * * * * * * * -------------------------------------------------------------------------------- COLORS ------ Only 16 colors were available in Pro-SiMPLE. Consequently, any one of those colors (0-15) could easily be specified using a single container of type Int. In Ultra-SiMPLE millions of colors are available. An Ultra-SiMPLE color is specified by indicating how much of each primary color (Red, Green, and Blue) is present. (Each of these three color components can have a value in the range 0-255.) So it might seem that a color specifier would now require the use of three separate containers instead of just one. However, to avoid the inconvenience of having to deal with such "excess baggage" the three color components are merely crammed into a single container of type Int2. (We will usually refer to such a quantity as an RGB value.) Because SiMPLE can easily distinguish a container of type Int from a con- tainer of type Int2 there should be no confusion as to which type of color specifier is being used when invoking a task or function that uses a color value as one of its calling parameters. (In most cases, the documentation will explicitly indicate that the color value's range is 0-15 if a calling parameter is restricted to only Int color values.) _____________________________________________________________________________ The following tasks/functions allow the programmer to specify/retrieve color values for displaying text. Name: Operation: ----- ---------- Forecolor (color) Specifies the foreground color to be used for dis- playing text. Backcolor (color) Specifies the background color to be used for dis- playing text. Getforecolor ( ) Retrieves the foreground color (RGB) currently being used for displaying text. Getbackcolor ( ) Retrieves the background color (RGB) currently being used for displaying text. _____________________________________________________________________________ The following tasks allow the programmer to specify a color (expressed either as an integer, or as an RGB value) to be used for drawing shapes and lines. (The default color in each case is: white.) Name: Operation: ----- ---------- Pointcolor (color) Specifies the color to be used for plotting points. Linecolor (color) Specifies the color to be used for drawing lines. Solidcolor (color) Specifies the color to be used for drawing either solid shapes or filled shapes. _____________________________________________________________________________ The following Int2 functions allow the programmer to retrieve RGB color values that have been previously set. Name: Operation: ----- ---------- Getpointcolor ( ) Retrieves the RGB color used for plotting points. Getlinecolor ( ) Retrieves the RGB color used for drawing lines. Getsolidcolor ( ) Retrieves the RGB color used for drawing either solid shapes or filled shapes. _____________________________________________________________________________ The following functions perform miscellaneous color operations. Name: Operation: ----- ---------- Rgb (r, g, b) "Crams" the three color components (r, g, and b) into a single container of type Int2. Rvalue (rgb) Retrieves the Red component (0-255) of the speci- fied RGB value. Gvalue (rgb) Retrieves the Green component (0-255) of the speci- fied RGB value. Bvalue (rgb) Retrieves the Blue component (0-255) of the speci- fied RGB value. Colortorgb (color) Converts a Pro-SiMPLE color (0-15) into its RGB equivalent. Rgbtocolor (rgb) Converts an RGB color into its nearest Pro-SiMPLE equivalent (0-15). Rainbow (index) Returns one of 384 RGB values representing a cyclic color spectrum - Red...Orange...Yellow...Green... Blue...Violet...Red - depending on the value spe- cified by index. (Note: The calling parameter, index, is treated cyclically; therefore it is un- bounded.) _____________________________________________________________________________ NUMBER-TO-NUMBER CONVERSIONS ---------------------------- Name: Type: Operation: ----- ----- ---------- Float (x) [or, Decimal] Float Converts x into a floating point num- ber. Float2(x) [or, Decimal2] Float2 Converts x into a double precision floating point number. Int (x) [or, Whole] Int Converts x into an integer number. Int2 (x) [or, Whole2] Int2 Converts x into a double precision integer number. ______________________________________________________________________________ NUMBER-TO-TEXT CONVERSIONS -------------------------- Name: Type: Operation: ----- ----- ---------- Itot (x) [or, Wtot] Text Converts integer x into a text string. I2tot (x) [or, W2tot] Text Converts double precision integer x into a text string. Ftot (x) [or, Dtot] Text Converts floating point x into an 8-digit text string. Ftot (x, n) [or, Dtot] Text Converts floating point x into a text string. (n: the number of digits desired) F2tot (x) [or, D2tot] Text Converts double precision floating point x into a 16-digit text string. F2tot (x, n) [or, D2tot] Text Converts double precision floating point x into a text string. (n: the number of digits desired) Money (x) Text Converts x into a text string dis- playing the value as dollars and cents, rounded to the nearest cent. (e.g., the value: 123.4567 would convert to the string: $123.46) _____________________________________________________________________________ TEXT-TO-NUMBER CONVERSIONS -------------------------- Name: Type: Operation: ----- ----- ---------- Ttoi (t) [or, Ttow] Int Converts text string t into an integer number. Ttoi2 (t) [or, Ttow2] Int2 Converts text string t into a double precision integer number. Ttof (t) [or, Ttod] Float Converts text string t into a float- ing point number. Ttof2 (t) [or, Ttod2] Float2 Converts text string t into a double precision floating point number. _____________________________________________________________________________ HEXADECIMAL CONVERSIONS ----------------------- Name: Type: Operation: ----- ----- ---------- Hex (num) Text Converts the Int2 num into the Ascii string representing its hexadecimal value. Unhex (hex) Int2 Converts the hexadecimal text string hex into its equivalent Int2 value. (If hex consists of more than 8 "digits", then only the right-most 8 are recognized.) _____________________________________________________________________________ CASE CONVERSIONS ---------------- Name: Type: Operation: ----- ----- ---------- Upper (t) Text Converts the specified text string to uppercase. Lower (t) Text Converts the specified text string to lowercase. _____________________________________________________________________________ DISK I/O _____________________________________________________________________________ Name: Mkdir (Text path) Type: Task Operation: Creates a directory (specified by path) ____________________________________________________________________________ Name: Rmdir (Text path) Type: Task Operation: Deletes the directory (specified by path) ____________________________________________________________________________ Name: Existdir (Text path) Direxist (Text path) Type: Int function Operation: Does the directory (specified by path) exist? Returns with: TRUE, if the directory was found FALSE, otherwise _____________________________________________________________________________ Name: Verifyfolder (Text path) Type: Int function Operation: Does the folder (specified by path) exist and, if so, is it writable? (If "path" is a null string, the folder being specified is the current device's root directory.) Returns: 0: The folder was not found 1: The folder was found but it is not writable 2: The folder was found and it is writable _____________________________________________________________________________ Name: Existfile (Text path) Fileexist (Text path) Type: Int function Operation: Does the file (specified by path) exist? Returns with: TRUE, if the file was found FALSE, otherwise _____________________________________________________________________________ Name: Copyfile (Text src, Text dst) Type: Task Operation: Copies the file (specified by "src") to a new file (specified by "dst"). _____________________________________________________________________________ Name: Renamefile (Text src, Text dst) Type: Task Operation: Renames the file (specified by "src") to a new file (specified by "dst"). If "src" and "dst" are in different folders, the file is moved to "dst". _____________________________________________________________________________ Name: Deletefile (Text name) Type: Task Operation: Deletes the file specified by "name". _____________________________________________________________________________ Name: Getpath (Text path) Type: Text function Operation: Returns the base path of the "path" parameter. (The base path is the path minus the file mame.) _____________________________________________________________________________ Name: Getname (Text path) Type: Text function Operation: Returns the raw name of the file in the "path" parameter. (The raw name is the name minus the extension.) _____________________________________________________________________________ Name: Getext (Text path) Type: Text function Operation: Returns the extension of the file in the "path" parameter. (If the file has no extension, a null string is returned.) _____________________________________________________________________________ Reading/Writing Files In Pro-SiMPLE all disk files were accessed through "channels" (disignated by the letters A-G). You would first assign a file to one of these channels (by using the appropriate "open" task). Then you would proceed to write/read data to/from the file. To provide compatibility with Pro-SiMPLE, Ultra-SiMPLE also provides you with this same "channel" method of accessing disk files. But there is also a slightly better way to do it: You still use an "open" command to open the file. But instead of YOU as- signing a "channel" to the file, Ultra-SiMPLE assigns TO YOU an identifier called a "handle" (not to be confused with a library "handle" such as @toys). The handle to a file is merely a numerical value that uniquely identifies the file in subsequent input/output operations. (You can think of a file handle as being a "channel" that is identified by a NUMBER instead of a LETTER.) _____________________________________________________________________________ Name: Openfile (Text op) Type: Int Operation: Opens a specified disk file for either reading, writing, or appending. Enter with: op: A text string indicating the type of operation ("read ", "write ", or "append "), followed by the name of the file (or path) to be opened. Returns: A handle to the specified file. Example: handle=open file ("write c:\\data.xyz") _____________________________________________________________________________ Name: Writefile (Int handle, (anything), Int err) Type: Task Operation: Writes any type of data (Int, Float, etc) to a file. [If "anything" is a text string, automatically writes a cr-lf at the end.] Enter with: handle, the handle of the output file. (anything), the data to be written. Return with: err: 0, No error occurred while writing. 1, An error occurred while writing. Example: Write file (handle, 3.1416, err) _____________________________________________________________________________ Name: Readfile (Int handle, (anything), Int eof) Type: Task Operation: Reads any type of data (Int, Float, etc) from a file. Enter with: handle, the handle of the input file. (anything) an appropriate container for receiving the data. Return with: (anything), the data. eof: 1, End-of-file was encountered. 0, No end-of-file was encountered. Example: Read file (handle, data, eof) _____________________________________________________________________________ Name: Writefilebyte (Int handle, Int val, Int err) Type: Task Operation: Writes 8 bits of data to a file. Enter with: handle, the handle of the output file. val, the 8-bit quantity to be written. Return with: err: 0, No error occurred while writing. 1, An error occurred while writing. _____________________________________________________________________________ Name: Readfilebyte (Int handle, Int val, Int eof) Type: Task Operation: Reads 8 bits of data from a file. Enter with: handle, the handle of the input file. val, a container (of type Int) for receiving the data. Return with: val, the 8-bit quantity. eof: 1, End-of-file was encountered. 0, No end-of-file was encountered. _____________________________________________________________________________ Name: Closefile (Int handle) Type: Task Operation: Closes a file for further input or output. Calling Parameter: handle, the handle of the file to be closed. _____________________________________________________________________________ Example ------- The following program reads and displays the DISK.AID file (located in the system library): Text data Int eof handle = open file ("READ \\SiMPLE\\L\\W\\S\\DISK.AID") Do read file (handle, data, eof) If eof Break Display data Loop close file (handle) _____________________________________________________________________________ DISPLAYING INFORMATION _____________________________________________________________________________ Name: Cls Cls (Int color) Cls (Int2 color) Type: Task Operation: Clears the screen to the specified color. (If no color is specified, clears to black.) _____________________________________________________________________________ Name: Output Output ( info ) Type: Task Operation: Displays the specified info (followed by a cr-lf) either onto the screen, or into an output text file named "output.txt" (in the current project), depen- ding on the mode of outputting currently selected. (See the Outputmode task below.) If no calling parameter is supplied, simply outputs a cr-lf. Calling parameter: info: the information (of any type) to be output _____________________________________________________________________________ Name: Out Out ( info ) Type: Task Operation: Displays the specified info (without a cr-lf) either onto the screen, or into an output text file named "output.txt" (in the current project), depen- ding on the mode of outputting currently selected. (See the Outputmode task below.) If no calling parameter is supplied, simply returns without doing anything. Calling parameter: info: the information (of any type) to be output _____________________________________________________________________________ Name: Outputmode (Int mode) Type: Task Operation: Sets the mode in which the Output task (see above) is to perform. Calling parameter: mode=1, send output to the screen [default] mode=2, send output to a local text file named "OUTPUT.TXT" mode=3, send output to both screen and the text file Note: When using "Drag & Drop" mode, the "OUTPUT.TXT" file will be located in SiMPLE's "PROJECT" folder. _____________________________________________________________________________ Name: Outtextxy (Int x, Int y, Text t) Outtextxy (Int x, Int y, Text t, Int s) Outtextxy (Int x, Int y, Text t, Int s, Text f) Type: Task Operation: Displays a text string at the specified x,y graphics coordinates. (No cr-lf is performed.) Calling parameters: x, the x-coordinate at which the string is to appear y, the y-coordinate at which the string is to appear t, the text string to be displayed Optional parameters: s, the size of the font [If s > zero, it specifies the cell height of the font. If it is less than zero, it specifies the character height of the font. (Character height is the cell height minus the internal leading.)] f, the name of the font to be used. (If not speci- fied, "fixedsys" is used.) Example: The following program will display the word "SiMPLE" in big blue Courier letters on a yellow background: cls (8); forecolor (9); backcolor (14) outtextxy (100, 50, "SiMPLE", 96, "Courier") _____________________________________________________________________________ Name: Font (Int fontid) Type: Task Operation: Selects one of three slightly different 8x15 fonts to be used when using the Display keyword to dis- play information on the screen. Calling parameter: fontid, the font number (0-2) to be used (Default=0) _____________________________________________________________________________ Name: Scrollingspeed (Int speed) Type: Task Operation: Selects one of four speeds to be used for scrolling the screen. Calling parameter: speed, the scrolling speed (1-4) to be used (Default=4) _____________________________________________________________________________ Name: Crlf Type: Task Operation: Clears to the end of the current line, then generates a "carriage-return/line-feed". _____________________________________________________________________________ Name: Crlfx Type: Task Operation: Generates a "carriage-return/line-feed" only. _____________________________________________________________________________ Name: Clreol Type: Task Operation: Clears from the current text cursor position to the end of the line. _____________________________________________________________________________ Name: Htab (Int x) Type: Task Operation: Horizontal tab to the specified position on the text cursor's current line. Calling parameter: x: the horizontal position to which you wish to tabulate. 1 represents the left-most column. _____________________________________________________________________________ Name: Tabxy (Int x, Int y) Type: Task Operation: Performs a simultaneous Htab and Vtab operation. Calling parameters: x: the horizontal position to which you wish to tabulate. y: the vertical position to which you wish to tabulate. _____________________________________________________________________________ Name: Vtab (Int y) Type: Task Operation: Vertical tab to the specified position on the text cursor's current column. Calling parameter: y: the vertical position to which you wish to tabulate. 1 represents the top-most line. (The horizontal position remains unchanged.) _____________________________________________________________________________ Name: Wherex ( ) Type: Int function Operation: Returns the current x position of the text cursor. Calling parameter: None _____________________________________________________________________________ Name: Wherey ( ) Type: Int function Operation: Returns the current y position of the text cursor. Calling parameter: None _____________________________________________________________________________ Name: Scrollscreen (Int dx, Int dy) Scrollscreen (Int dx, Int dy, Int a, Int b, \ Int c Int d) Type: Task Operation: Scrolls the screen (up/down, left/right) by a speci- fied number of pixels. Calling parameters: dx - The horizontal scrolling increment dy - The vertical scrolling increment a,b,c,d - The rectangular portion of the screen to be scrolled. (If not specified, the entire screen is scrolled.) _____________________________________________________________________________ The following tasks/functions allow the programmer to specify/retrieve color values for displaying text. Name: Operation: ----- ---------- Forecolor (color) Specifies the foreground color to be used for dis- playing text, and sets the background mode to OPAQUE. Backcolor (color) Specifies the background color to be used for dis- playing text. If color<0, sets the background mode to TRANSPARENT. Getforecolor (color) Retrieves the foreground color (RGB) currently being used for displaying text. Getbackcolor (color) Retrieves the background color (RGB) currently being used for displaying text. _____________________________________________________________________________ Name: Backmode (Int mode) Type: Task Operation: Sets the specified background mode. The background mode defines whether the system removes existing background colors on the screen before drawing text. Calling parameter: mode - Specifies the background mode to be set. This parameter can be one of the following values: (2) OPAQUE - Background is filled with the current background color be- fore the text is drawn. (This is the default mode.) (1) TRANSPARENT - Background is not changed before drawing. _____________________________________________________________________________ Name: Getbackmode ( ) Type: Int function Operation: Returns the current background mode: (2) OPAQUE (1) TRANSPARENT _____________________________________________________________________________ FRAMES _____________________________________________________________________________ Name: Frame Type: Task Operation: Draws a gray "3-D" frame around the edge of the screen. Calling parameters: (none) Note: The remaining "active" area of the screen (in 640x480 mode) will then be contained in the rectangle: [24,24]______________________ | | | | | | | | |______________________| [615,455] _____________________________________________________________________________ Name: Frame (Int color) Type: Task Operation: Draws a "3-D" frame (in the specified color) around the edge of the screen. Calling parameter: color: the color (0-15) of the frame Note: The remaining "active" area of the screen (in 640x480 mode) will then be contained in the rectangle: [24,24]______________________ | | | | | | | | |______________________| [615,455] _____________________________________________________________________________ Name: Frame (Int a, Int b, Int c, Int d) Type: Task Operation: Draws a gray "3-D" frame around the specified region of the screen. Calling parameters: a,b: the coordinates of the upper left corner of the region to be framed c,d: the coordinates of the bottom right corner of the region to be framed _____________________________________________________________________________ Name: Frame (Int a, Int b, Int c, Int d, Int color) Type: Task Operation: Draws a "3-D" frame (in the specified color) around the specified region of the screen. Calling parameters: a,b: the coordinates of the upper left corner of the region to be framed c,d: the coordinates of the bottom right corner of the region to be framed color: the color (0-15) of the frame _____________________________________________________________________________ Name: Getoutline (Int xul, Int yul, Int xlr, Int ylr) Type: Task Operation: Returns the coordinates of the "outline rectangle" for the previously drawn "3-D" frame. (The outline rect- angle is the thin line that separates the outside edge of the frame from the background.) Returned parameters: xul,yul: the coordinates of the upper left corner of the outline rectangle xlr,ylr: the coordinates of the lower right corner of the outline rectangle _____________________________________________________________________________ Name: Framedtext (Text mess) Type: Task Operation: Draws a gray "3-D" frame containing a B/W message. (Use the Tabxy task to specify the location at which the message is to appear.) Calling parameter: mess: the text string to be displayed (16 lines max) Example: Call Tabxy (35, 14) Call Framedtext (" - Game Over -\nThanks For Playing") _____________________________________________________________________________ Name: Framedtext (Text mess, Int fore, Int back) Type: Task Operation: Draws a gray "3-D" frame containing a colored message. (Use the Tabxy task to specify the location at which the message is to appear.) Calling parameters: mess: the text string to be displayed (16 lines max) fore: the foreground color (0-15) of all the text back: the background color (0-15) of all the text frame: the color (0-15) of the frame _____________________________________________________________________________ Name: Framedtext (Text mess, Int fore, Int back, Int frame) Type: Task Operation: Draws a "3-D" frame (in a specified color) containing a colored message. (Use the Tabxy task to specify the location at which the message is to appear.) Calling parameters: mess: the text string to be displayed (16 lines max) fore: the foreground color (0-15) of all the text back: the background color (0-15) of all the text frame: the color (0-15) of the frame _____________________________________________________________________________ GRAPHICS _____________________________________________________________________________ Name: Plot (Int x, Int y) Type: Task Operation: Plots a pixel (in the specified Pointcolor) at location x,y. Calling parameters: x: x coordinate y: y coordinate _____________________________________________________________________________ Name: Putpixel (Int x, Int y, Int color) Putpixel (Int x, Int y, Int2 color) Putrgbpixel (Int x, Int y, Int2 color) Type: Task Operation: Plots a pixel (in the specified color) at location x,y. Calling parameters: x: x coordinate y: y coordinate color: color value _____________________________________________________________________________ Name: Getpixel (Int x, Int y) Type: Int function Operation: Returns the color value of the pixel located at x,y. Calling parameters: x: x coordinate y: y coordinate _____________________________________________________________________________ Name: Getrgbpixel (Int x, Int y) Type: Int2 function Operation: Returns the RGB color value of the pixel located at x,y. Calling parameters: x: x coordinate y: y coordinate _____________________________________________________________________________ Name: Linesize (Int thick) Type: Task Operation: Establishes how thick lines are to be drawn. Calling parameter: thick: the thickness (in pixels) of the lines (default=1) _____________________________________________________________________________ Name: Getlinesize ( ) Type: Int function Operation: Returns the currently established thickness of the lines that are being drawn. _____________________________________________________________________________ Name: Linestyle (Int style) Type: Task Operation: Establishes the style in which lines are to be drawn. Calling parameter: style: 0 - Creates a solid pen. (Default) 1 - Creates a dashed pen. (Valid only when the line size is 1.) 2 - Creates a dotted pen. (Valid only when the line size is 1.) 3 - Creates a pen with alternating dashes and dots. (Valid only when the line size is set to 1.) 4 - Creates a pen with alternating dashes and double dots. (Valid only when the line size is set to 1.) _____________________________________________________________________________ Name: Getlinestyle ( ) Type: Int function Operation: Returns the currently established style in which lines are being drawn. _____________________________________________________________________________ Name: Penmode (Int mode) Type: Int function Operation: Sets the current drawing mode. The drawing mode specifies how the colors of the pen and the interior of filled objects are combined with the color already on the screen. Calling parameter: mode: Specifies the new drawing mode. This parameter can be one of the following values: 1 - R2_BLACK Pixel is always black. 2 - R2_NOTMERGEPEN Pixel is the inverse of the R2_MERGEPEN color. 3 - R2_MASKNOTPEN Pixel is a combination of the colors common to both the screen and the inverse of the pen. 4 - R2_NOTCOPYPEN Pixel is the inverse of the pen color. 5 - R2_MASKPENNOT Pixel is a combination of the colors common to both the pen and the inverse of the screen. 6 - R2_NOT Pixel is the inverse of the screen color. 7 - R2_XORPEN Pixel is a combination of the colors that are in the pen and in the screen, but not in both. 8 - R2_NOTMASKPEN Pixel is the inverse of the R2_MASKPEN color. 9 - R2_MASKPEN Pixel is a combination of the colors common to both the pen and the screen. 10 - R2_NOTXORPEN Pixel is the inverse of the R2_XORPEN color. 11 - R2_NOP Pixel remains unchanged. 12 - R2_MERGENOTPEN Pixel is a combination of the screen color and the inverse of the pen color. 13 - R2_COPYPEN Pixel is the pen color. (This is the default.) 14 - R2_MERGEPENNOT Pixel is a combination of the pen color and the in- verse of the screen color. 15 - R2_MERGEPEN Pixel is a combination of the pen color and the screen color. 16 - R2_WHITE Pixel is always white. Returns: The return value specifies the previous drawing mode. _____________________________________________________________________________ The following tasks allow the programmer to specify a color (expressed either as an integer, or as an RGB value) to be used for drawing shapes and lines. (The default color in each case is: white.) Name: Operation: ----- ---------- Pointcolor (color) Specifies the color to be used for plotting points. Linecolor (color) Specifies the color to be used for drawing lines. Solidcolor (color) Specifies the color to be used for drawing either solid shapes or filled shapes. _____________________________________________________________________________ The following tasks allow the programmer to draw lines in the specified Linecolor. (All parameters are integers.) Name: Operation: ----- ---------- Line (a,b,x,y) Draws a line between the points a, b and x, y. Lineto (a,b) Draws a line from the current position to a,b. Linerel (dx,dy) Draws a line from the current position to the new position: current position +dx, current position located dx,dy pixels away. Moveto (a,b) Establishes a,b as the new current position. Moverel (dx,dy) Establishes a new current position at: current position +dx, current position +dy. _____________________________________________________________________________ The following tasks allow the programmer to draw triangles. In each case, (a,b) and (c,d) and (e,f) specify the coordinates of the triangle's vertices. (All parameters are integers.) Name: Operation: ----- ---------- Triangle (a,b,c,d,e,f) Draws a hollow triangle Solidtriangle (a,b,c,d,e,f) Draws a solid triangle Filledtriangle (a,b,c,d,e,f) Draws a filled triangle _____________________________________________________________________________ The following Tasks allow the programmer to draw squares. In each case, x and y specify the coordinates of the center of the square, and r specifies the "radius" of the square (i.e., the distance from the center to any side). (All parameters are integers.) Name: Operation: ----- ---------- Square (x,y,r) Draws a hollow square Solidsquare (x,y,r) Draws a solid square Filledsquare (x,y,r) Draws a filled square _____________________________________________________________________________ The following tasks allow the programmer to draw rectangles. In each case, a and b specify the coordinates of the upper left hand corner of the rectangle, and x and y specify the bottom right hand corner. (All para- meters are integers.) Name: Operation: ----- ---------- Rectangle (a,b,x,y) Draws a hollow rectangle Solidrectangle (a,b,x,y) Draws a solid rectangle Filledrectangle (a,b,x,y) Draws a filled rectangle _____________________________________________________________________________ The following tasks allow the programmer to draw rectangles with round cor- ners. In each case, a and b specify the coordinates of the upper left hand corner of the rectangle, x and y specify the bottom right hand corner, and h and v specify the size of the ellipse to be used for the corners. (All parameters are integers.) Name: Operation: ----- ---------- Roundrectangle (a,b,x,y,h,v) Draws a hollow rectangle with rounded corners Solidroundrectangle (a,b,x,y,h,v) Draws a solid rectangle with rounded corners Filledroundrectangle (a,b,x,y,h,v) Draws a filled rectangle with rounded corners _____________________________________________________________________________ The following tasks allow the programmer to draw circles. In each case, x and y specify the coordinates of the center of the circle, and r specifies the radius. (All parameters are integers.) Name: Operation: ----- ---------- Circle (x,y,r) Draws a hollow circle Solidcircle (x,y,r) Draws a solid circle Filledcircle (x,y,r) Draws a filled circle _____________________________________________________________________________ The following tasks allow the programmer to draw ellipses. In each case, x and y specify the coordinates of the center of the ellipse, and a and b specify the radii in the x and y directions respectively. (All parameters are integers, unless otherwise specified.) Name: Operation: ----- ---------- Ellipse (x,y,a,b) Draws a hollow ellipse Oval (x,y,a,b) Draws a hollow ellipse Ellipse (x,y,a,b,ang) Draws a rotated hollow ellipse (ang: the floating point rotation angle) Oval (x,y,a,b,ang) Draws a rotated hollow ellipse (ang: the floating point rotation angle) Solidellipse (x,y,a,b) Draws a solid ellipse Solidoval (x,y,a,b) Draws a solid ellipse Solidellipse (x,y,a,b,ang) Draws a rotated solid ellipse (ang: the floating point rotation angle) Solidoval (x,y,a,b,ang) Draws a rotated solid ellipse (ang: the floating point rotation angle) Filledellipse (x,y,a,b) Draws a filled ellipse Filledoval (x,y,a,b) Draws a filled ellipse Filledellipse (x,y,a,b,ang) Draws a rotated filled ellipse (ang: the floating point rotation angle) Filledoval (x,y,a,b,ang) Draws a rotated filled ellipse (ang: the floating point rotation angle) _____________________________________________________________________________ The following tasks allow the programmer to draw polygons. In each case, x and y are arrays that specify the coordinates of the polygon's vertices, and n is the number of vertices. (All parameters are integers.) Name: Operation: ----- ---------- Polygon (x,y,n) Draws a hollow polygon Solidpolygon (x,y,n) Draws a solid polygon Filledpolygon (x,y,n) Draws a filled polygon Example: Int x[5] = {400, 525, 475, 325, 300} Int y[5] = { 50, 75, 190, 270, 100} Call line color (11) Call solid color (4) Call filled polygon (x, y, 5) _____________________________________________________________________________ Name: Arc (Int left, Int top, Int right, Int bottom, \ Int xstart, Int ystart, Int xend, Int yend) Type: Task Operation: Draws an elliptical arc. The arc drawn is a segment of the ellipse defined by the specified bounding rect- angle. The starting point of the arc is the point at which a ray drawn from the center of the bounding rect- angle through the specified starting point intersects the ellipse. The end point of the arc is the point at which a ray drawn from the center of the bounding rect- angle through the specified end point intersects the ellipse. The arc is drawn in a counterclockwise direc- tion. Calling Parameters: left, x-coordinate of upper-left corner of bounding rectangle top, y-coordinate of upper-left corner of bounding rectangle right, x-coordinate of lower-right corner of bounding rectangle bottom, y-coordinate of lower-right corner of bounding rectangle xstart, x-coordinate of arc starting point ystart, y-coordinate of arc starting point xend, x-coordinate of arc ending point yend, y-coordinate of arc ending point _____________________________________________________________________________ Name: Floodfill (Int x, Int y, Int2 c) Floodfill (Int x, Int y, Int c) Type: Task Operation: Fills a specified area of the screen. The fill area is defined by the color that currently exists at "x,y". Filling continues outward in all directions as long as that color is encountered. (This style is useful for filling areas that have multicolored boundaries.) Calling parameters: x: Specifies the x-coordinate at which to begin filling y: Specifies the y-coordinate at which to begin filling c: Specifies the color to be used for filling _____________________________________________________________________________ Name: Floodfill (Int x, Int y, Int2 c, Int2 b) Floodfill (Int x, Int y, Int c, Int b) Type: Task Operation: Fills a bounded area of the screen. Filling begins at the point specified by x and y, and continues in all directions to the color boundary. Calling parameters: x: Specifies the x-coordinate at which to begin filling y: Specifies the y-coordinate at which to begin filling c: Specifies the color to be used for filling b: Specifies the color of the boundary. _____________________________________________________________________________ BITMAP IMAGES _____________________________________________________________________________ The Ultra-SiMPLE system library contains several tasks which allow the user to create, manipulate, and display bitmap image files. Before you can use a file containing a bitmap image you must first "open" the file (much like you would "open" a data file file for reading or writing). Ultra-SiMPLE then assigns to you an identifier called a "handle" (not to be confused with a library "handle" such as @toys). (The handle to an image file is merely a numerical value that uniquely identifies the file so that it can be easily referenced.) After you are finished using an opened image file, you must "close" it (just as you would "close" any opened data file). **[Note: The rbg color values returned by the following tasks/functions (which reference an images color palette) have embedded in them the corresponding palette index. This value can be retrieved by using the "Cvalue" function.] _____________________________________________________________________________ Name: Openimage (Text path) Type: Int function Operation: Opens an image file and loads it into memory. Enter with: path - the path to the image file. Returns: A handle to the image in memory. _____________________________________________________________________________ Name: Createimage (Int xsize, Int ysize) Createimage (Int xsize, Int ysize, Int zbits) Type: Int function Operation: Sets up a block of memory so that the user can create a new bitmap image. (See also: "Putbmppixel" and "Saveimage") Enter with: xsize,ysize - the size of the image to be created. zbits - the number of bits/pixel (1, 4, 8, or 24). (If not specified, 24 is assumed.) Returns: A handle to the "image" in memory. (The initial image is cleared to black.) _____________________________________________________________________________ Name: Getbmpdata (Int handle, Int xsize, Int ysize) Getbmpdata (Int handle, Int xsize, Int ysize, Int zbits) Type: Task Operation: Retrieves information about an opened bitmap image. Enter with: handle - the handle of the image. Returns: xsize - The horizontal size of the image (in pixels). ysize - The vertical size of the image (in pixels). zbits - The number of bits per pixel. _____________________________________________________________________________ Name: Getbmppixel (Int handle, Int x, Int y) Type: Int2 function Operation: Reads a pixel from an opened bitmap image. Enter with: handle - the handle of the image. x,y - the coordinates of the pixel. Returns: The RGB value of the pixel.** _____________________________________________________________________________ Name: Putbmppixel (Int handle, Int x, Int y, Int color) Putbmppixel (Int handle, Int x, Int y, Int2 color) Type: Task Operation: Plots a pixel onto a bitmap image in memory. Enter with: handle - the handle of the image. x,y - the coordinates of the pixel. color - the RGB value (or the 1-byte color value) of the pixel. _____________________________________________________________________________ Name: Getbmppalette (Int handle, Int index) Type: Int2 function Operation: Retrieves a specified palette entry from an opened bitmap image. Enter with: handle - the handle of the image. index - the palette entry to be retrieved. Returns: The RGB value of the palette entry.** _____________________________________________________________________________ Name: Rvalue (Int2 rgb) Type: Int function Operation: Retrieves the red component from an rgb value. Enter with: rgb - the RGB value.** _____________________________________________________________________________ Name: Gvalue (Int2 rgb) Type: Int function Operation: Retrieves the green component from an rgb value. Enter with: rgb - the RGB value.** _____________________________________________________________________________ Name: Bvalue (Int2 rgb) Type: Int function Operation: Retrieves the blue component from an rgb value. Enter with: rgb - the RGB value.** _____________________________________________________________________________ Name: Cvalue (Int2 rgb) Type: Int function Operation: Retrieves the palette index from an rgb value. Enter with: rgb - the RGB value.** _____________________________________________________________________________ Name: Putbmppalette (Int handle, Int index, Int2 rgb) Type: Task Operation: Inserts an rgb color value into a specified location in an opened bitmap's palette. Enter with: handle - the handle of the image. index - the index into the palette. rgb - the RGB value. _____________________________________________________________________________ Name: Getclosestcolor (Int handle, Int2 rgb) Type: Int2 function Operation: Retrieves from an opened bitmap image, the palette entry that most closely matches a specified rgb value. Enter with: handle - the handle of the image. rgb - the RGB value. Returns: The RGB value** of the closest-match palette entry. _____________________________________________________________________________ Name: Closeimage (Int handle) Type: Task Operation: Closes an image. Enter with: handle - the handle of the image to be closed. _____________________________________________________________________________ Name: Saveimage (Int handle, Text path) Type: Task Operation: Closes an image in memory and saves it to a file. Enter with: handle - the handle of the image in memory. path - the path to the file. _____________________________________________________________________________ Name: Savescreen (Int xul, Int yul, Int xlr, Int ylr, Text path) Savescreen (Text path) Type: Task Operation: Saves the specified region of the current screen to a file as a 24-bit BMP image. (If no region is specified, saves the entire screen.) Enter with: xul, yul - the upper-left corner of the region. xlr, ylr - the lower-right corner of the region. path - the path to the output file. NOTE: When saving a large region of the screen, this task may require several seconds to finish executing. _____________________________________________________________________________ Examples: The following program will display a "Forest" bitmap image located in the Windows directory: Int xsize, ysize handle = open image ("c:\\windows\\forest.bmp") get bmp data (handle, xsize, ysize) Do y = 0 To ysize-1 Do x = 0 To xsize-1 z = get bmp pixel (handle, x, y) //Read the pixel from the image put rgb pixel (x, y, z) //Plot the pixel on the screen Loop Loop close image (handle) - - - - - - - - - - - - - - - - - The following program will display the same "Forest" bitmap image as a black and white image, and then save that image onto a file called "monopic" in the root directory of your "C:" drive: Int xsize, ysize, zsize inhandle = open image ("c:\\windows\\forest.bmp") get bmp data (inhandle, xsize, ysize) outhandle = create image (xsize, ysize) Do y = 0 To ysize-1 Do x = 0 To xsize-1 z = get bmp pixel (inhandle, x, y) //Read the pixel z = rgb(gvalue(z),gvalue(z),gvalue(z))//Convert it to gray put bmp pixel (outhandle, x, y, z) //Plot the pixel to memory put rgb pixel (x, y, z) //Plot the pixel to the screen Loop Loop close image (inhandle) save image (outhandle, "c:\\monopic.bmp") _____________________________________________________________________________ KEYBOARD _____________________________________________________________________________ Name: Flushkbd Type: Task Operation: Flushes the input keyboard buffer of any characters waiting to be read. _____________________________________________________________________________ Name: Keyhit ( ) Type: Int function Operation: Tests to see whether or not a key on the keyboard has been pressed. Calling parameter: None Return value: 0 = no key has been pressed 1 = a key has been pressed _____________________________________________________________________________ Name: Readkey ( ) Type: Int function Operation: Reads the keyboard. If a key has been pressed, the numerical value of that key is returned. If no key is pressed, a zero is returned. Calling parameter: None _____________________________________________________________________________ Name: Readkey (Int key) Type: Int function Operation: Reads a key from the keyboard. There are three cases: Case 1: key > 0 If the specified key has been pressed then value of that key is returned. Otherwise a zero is returned. Case 2: key = 0 If any key has been pressed, the value of the pressed key is returned. Otherwise a zero is returned. Case 3: key < 0 If any key has been pressed, the value of the pressed key is returned. If any mouse button is pushed, the negative value of the mouse button is returned (eg., if the right button is pressed, a -2 is returned). If the mouse is moved, a -8 is returned. Otherwise a zero is returned. Calling parameter: key: the specified key _____________________________________________________________________________ Name: Readquitkey Type: Task Operation: Tests to see if any key has been pressed. If so, the program is immediately terminated. _____________________________________________________________________________ Name: Readquitkey (Text key) Type: Task Operation: Tests to see if the specified key has been pressed. If so, the program is immediately terminated. Calling parameter: key: the specified key Example: Readquitkey ("x") //Tests for the "x" key Example: Readquitkey ("End") //Tests for the "End" key _____________________________________________________________________________ Name: Readquitkey (Int key) Type: Int function Operation: Tests to see if the specified key has been pressed. If so, the program is immediately terminated. Calling parameter: key: the specified key - If key > 0, terminates the program if the speci- fied key is pressed. Otherwise, returns which- ever key may have been pressed (zero = no key was pressed). If key = 0, terminates the program if any key is pressed. Returns zero otherwise. If key = -1, terminates the program if any key is pressed, or if the mouse moves, or if a mouse button is pressed. Returns zero otherwise. Example: Readquitkey (335) //Tests for the "End" key _____________________________________________________________________________ Name: Readquitkeyc Type: Task Operation: Tests to see if any key has been pressed. If so, a small window appears and asks the user to verify that the program is to be immediately terminated. Note: (This task uses auxiliary screen #7.) _____________________________________________________________________________ Name: Readquitkeyc (Text key) Type: Task Operation: Tests to see if the specified key has been pressed. If so, a small window appears and asks the user to verify that the program is to be immediately termi- nated. Calling parameter: key: the specified key Note: (This task uses auxiliary screen #7.) _____________________________________________________________________________ Name: Readquitkeyc (Int key) Type: Task Operation: Tests to see if the specified key has been pressed. If so, a small window appears and asks the user to verify that the program is to be immediately termi- nated. Calling parameter: key: the specified key Note: (This task uses auxiliary screen #7.) _____________________________________________________________________________ Name: Waitkey ( ) Type: Int function Operation: Waits until a key is pressed, then returns the numerical value of the key. Calling parameter: None _____________________________________________________________________________ Name: Waitkey (Text key) Type: Task Operation: Waits until the specified key is pressed. Calling parameter: key: the specified key Example: Waitkey (" ") //Waits for the space bar _____________________________________________________________________________ Name: Waitkey (Int key) Type: Int function Operation: Waits until the specified key is pressed, then returns the numerical value of the key. There are three cases: Case 1: key > 0 if the specified key has been pressed then value of that key is returned. Otherwise a zero is returned. Case 2: key = 0 if any key has been pressed, the value of the pressed key is returned. Otherwise a zero is returned. Case 3: key < 0 if any key has been pressed, the value of the pressed key is returned. If any mouse button is pushed, the negative value of the mouse button is returned (eg., if the right button is pressed, a -2 is returned). If the mouse is moved, a -8 is returned. Otherwise a zero is returned. Calling parameter: key: the specified key Example: Waitkey (32) //Waits for the space bar _____________________________________________________________________________ Name: Waitkey (Text key, Int delay) Type: Task Operation: Waits until the specified key is pressed, or until the specified delay time has elapsed. Calling parameters: key: the specified key delay: the specified delay time (in milliseconds) _____________________________________________________________________________ Name: Waitkey (Int key, Int delay) Type: Int function Operation: Waits until the specified key is pressed, or until the specified delay time has elapsed. There are three cases: Case 1: key > 0 If the specified key has been pressed then value of that key is returned. If no key is pressed before the delay time has elapsed, a zero is returned. Case 2: key = 0 If any key has been pressed, the value of the pressed key is returned. If no key is pressed before the delay time has elapsed, a zero is returned. Case 3: key < 0 If any key has been pressed, the value of the pressed key is returned. If any mouse button is pushed, the negative value of the mouse button is returned (eg., if the right button is pressed, a -2 is returned). If the mouse is moved, a -8 is returned. If no key is pressed (and no mouse activity was detected) before the delay time has elapsed, a zero is returned. Calling parameters: key: the specified key delay: the specified delay time (in milliseconds) _____________________________________________________________________________ Name: Waitquitkey Type: Task Operation: Waits until any key is pressed, then terminates the program. __________________________________________________________________________ Name: Waitquitkey (Text key) Type: Task Operation: Waits until the specified key is pressed, then terminates the program. Calling parameter: key: the specified key. Example: Waitquitkey ("Esc") //Waits for the Esc key. __________________________________________________________________________ Name: Waitquitkey (Int key) Type: Task Operation: If key > 0, waits until the specified key is pressed, then terminates the program. If key = 0, waits until any key is pressed, then terminates the program. If key = -1, waits until any key is pressed or until either the mouse moves or until a mouse button is pressed, then terminates the program. Calling parameter: key: the specified key. Example: Waitquitkey (Esc) //Waits for the Esc key. Example: Waitquitkey (27) //Waits for the Esc key. __________________________________________________________________________ Name: Waitquitkey (Text key, Int delay) Type: Task Operation: Waits until the specified key is pressed, or until the specified delay time has elapsed. Then termi- nates the program. Calling parameters: key: the specified key delay: the specified delay time (in milliseconds) _____________________________________________________________________________ Name: Waitquitkey (Int key, Int delay) Type: Task Operation: Waits until the specified key is pressed, or until the specified delay time has elapsed If key > 0, terminates the program if the specified key is pressed. If key = 0, terminates the program if any key is pressed. If key = -1, terminates the program if any key is pressed or if the mouse either moves or if a mouse button is pressed. If the delay time elapses and the specified keyboard/mouse activity is not detected, Waitquitkey returns back to the calling program without quiting. Calling parameters: key: the specified key delay: the specified delay time (in milliseconds) _____________________________________________________________________________ Name: Keyintext (Text mess) Type: Text function Operation: Displays a prompt message on the screen and then waits for user input of a text string, followed by the Enter key. Calling parameter: mess: the prompt message to be displayed Example: Set name = Keyintext ("Please type your name: ") _____________________________________________________________________________ Name: Keyintext (Text question, Int timeout) Type: Text function Operation: Displays a question on the screen and then waits for user input of a text string, followed by the Enter key. If the Enter key is not pressed in the allotted time, the function returns a a text char- acter whose Ascii value is -1. Calling parameters: question: the question to be displayed timeout: the number of seconds allotted for the user to respond Example: question = "Which planet is closest to the sun? " answer = keyin text (question, 5) If (answer = char(-1)) Display "Out of time!" Else If (answer ~ "mercury") Display "Correct!" Else Display "Wrong!" Endelse _____________________________________________________________________________ Name: Keyintext (Int x, Int y, Text mess) Type: Text function Operation: Displays a prompt message on the screen and then waits for user input of a text string, followed by the Enter key. Calling parameter: x, y: the screen coordinates for the prompt message mess: the prompt message to be displayed Example: Set z = Keyintext (75, 95, "Please type your name: ") _____________________________________________________________________________ Name: Keyintext (Int x, Int y, Int size, Text mess) Type: Text function Operation: Displays a prompt message on the screen and then waits for user input of a text string, followed by the Enter key. Calling parameter: x, y: the screen coordinates for the prompt message size: the size (1 - 5) of the prompt characters mess: the prompt message to be displayed Example: Set z = Keyintext (75, 95, 2, "Type your name: ") _____________________________________________________________________________ Name: Keyinint (Text mess) or, Keyinwhole (Text mess) Type: Int function Operation: Displays a prompt message on the screen and then waits for user input of an integer value, followed by the Enter key. Calling parameter: mess: the prompt message to be displayed Example: Set numdog = Keyinint ("How many dogs do you own: ") _____________________________________________________________________________ Name: Keyinfloat (Text mess) or, Keyindecimal (Text mess) Type: Float function Operation: Displays a prompt message on the screen and then waits for user input of a floating point value, followed by the Enter key. Calling parameter: mess: the prompt message to be displayed Example: Set answer = Keyinfloat ("What is 7 divided by 2? ") _____________________________________________________________________________ Name: Keyinint2 (Text mess) or, Keyinwhole2 (Text mess) Type: Int2 function Operation: Displays a prompt message on the screen and then waits for user input of a double precision integer value, followed by the Enter key. Calling parameter: mess: the prompt message to be displayed Example: Set age=Keyinint2("How many hours have you lived? ") _____________________________________________________________________________ Name: Keyinfloat2 (Text mess) or, Keyindecimal2 (Text mess) Type: Float2 function Operation: Displays a prompt message on the screen and then waits for user input of a double precision floating point value, followed by the Enter key. Calling parameter: mess: the prompt message to be displayed Example: Set pi=Keyinfloat2("Please enter the value of Pi: ") _____________________________________________________________________________ Name: Cntrlc (Int flag) Type: Task Operation: Sets a flag that allows/inhibits Control-C from in- terupting any "Keyin" function. Calling parameter: flag: 0, inhibit (default) 1, allow Note: When running in a window, Control-C must remain inhibited. _____________________________________________________________________________ MATH FUNCTIONS _____________________________________________________________________________ Name: Type: Operation: ----- ----- ---------- Acos (x) Float2 Computes the arc cosine of x (in radians). Asin (x) Float2 Computes the arc sine of x (in radians). Atan (x) Float2 Computes the arc tangent of x (in radians). Atan2 (y,x) Float2 Computes the arc tangent of y/x (in radians). Bitand (a,b) Int Returns the result of performing the bit-by- bit operation of: a And b. Bitor (a,b) Int Returns the result of performing the bit-by- bit operation of: a Or b. Bitxor (a,b) Int Returns the result of performing the bit-by- bit operation of: a Exclusive-or b. Bool (logexp) Int If the logical expression is true, returns the value 1. If the logical expression is false, returns the value 0. Cos (x) Float2 Computes the cosine of x. (x is expressed in radians.) Cosh (x) Float2 Computes the hyperbolic cosine of x. Cycle (x,y) Int2 Computes x "cycle" y. The "cycle" opera- tion is merely a "modulo" operation which extends the modulo cycle into the negative number domain. For example, if y=3: x Cycle(x,3) x%3 --- --------- --- 5 2 2 4 1 1 3 0 0 2 2 2 1 1 1 0 0 0 -1 2 -1 -2 1 -2 -3 0 0 -4 2 -1 -5 1 -2 ... ... ... Exp (x) Float2 Computes e to the x. Factor (n) Int2 Computes the smallest prime factor of n. (If n<2, returns a value of 1) (If n is prime, returns a value of 0) Log (x) Float2 Computes the natural logarithm of x. Log10 (x) Float2 Computes the base ten logarithm of x. Pow (x,y) Float2 Computes x to the y power. Random (n) Int Generates a pseudo-random integer number in the range: 0 through n-1. Sgn (x) Int Computes the sign of x. If x >= 0, the value +1 is returned. Otherwise, the value -1 is returned. Sin (x) Float2 Computes the sine of x. (x is expressed in radians.) Sinh (x) Float2 Computes the hyperbolic sine of x. Sqrt (x) Float2 Computes the square root of x. Tan (x) Float2 Computes the tangent of x. (x is expressed in radians.) Tanh (x) Float2 Computes the hyperbolic tangent of x. ______________________________________________________________________________ ABSOLUTE VALUE FUNCTIONS _____________________________________________________________________________ Name: Type: Operation: ----- ----- ---------- Iabs (x) Int Computes the absolute value of integer x. Wabs (x) (Same as Iabs) I2abs (x) Int2 Computes the absolute value of double pre- cision integer x. W2abs (x) (Same as I2abs) Fabs (x) Float Computes the absolute value of floating point x. Dabs (x) (Same as Fabs) F2abs (x) Float2 Computes the absolute value of double pre- cision floating point x. D2abs (x) (Same as F2abs) _____________________________________________________________________________ MIN/MAX FUNCTIONS _____________________________________________________________________________ Name: Type: Operation: ----- ----- ---------- Mini (a, b) Int If Int a < Int b, returns Int a. Otherwise, returns Int b. Maxi (a, b) Int If Int a > Int b, returns Int a. Otherwise, returns Int b. Minf (a, b) Float If Float a < Float b, returns Float a. Otherwise, returns Float b. Maxf (a, b) Float If Float a > Float b, returns Float a. Otherwise, returns Float b. Mini2 (a, b) Int2 If Int2 a < Int2 b, returns Int2 a. Otherwise, returns Int2 b. Maxi2 (a, b) Int2 If Int2 a > Int2 b, returns Int2 a. Otherwise, returns Int2 b. Minf2 (a, b) Float2 If Float2 a < Float2 b, returns Float2 a. Otherwise, returns Float2 b. Maxf2 (a, b) Float2 If Float2 a > Float2 b, returns Float2 a. Otherwise, returns Float2 b. _____________________________________________________________________________ Name: Mandelbrot (Float2 x, Float2 y, Int2 limit) Type: Int2 function Operation: Generates a Mandelbrot number for the specified coordinates. Calling parameters: x: x coordinate y: y coordinate limit: maximum number of iterations to be performed If the specified point (x,y) is contained in the Mandelbrot set, the function will return limit as the calculated value. _____________________________________________________________________________ Name: Randomize Type: Task Operation: Randomizes the random number generator's seed. _____________________________________________________________________________ Name: Seed (Int seed) Type: Task Operation: Allows specification of a specific seed to be used for random number generation. _____________________________________________________________________________ MEMORY _____________________________________________________________________________ Name: Peek (Int2 loc) Type: Int2 function Operation: Returns the 16-bit value at memory location loc . _____________________________________________________________________________ Name: Peek (Int segment, Int offset) Type: Int function Operation: Returns the 16-bit value at the memory location specified by segment and offset . _____________________________________________________________________________ Name: Peekb (Int2 loc) Type: Int2 function Operation: Returns the 8-bit value at memory location loc . _____________________________________________________________________________ Name: Peekb (Int segment, Int offset) Type: Int function Operation: Returns the 8-bit value at the memory location specified by segment and offset . _____________________________________________________________________________ Name: Poke (Int2 loc, Int value) Type: Task Operation: Stores the 16-bit value into memory location loc . _____________________________________________________________________________ Name: Poke (Int segment, Int offset, Int value) Type: Task Operation: Stores the 16-bit value into the memory location specified by segment and offset . _____________________________________________________________________________ Name: Pokeb (Int2 loc, Int value) Type: Task Operation: Stores the 8-bit value into memory location loc . _____________________________________________________________________________ Name: Pokeb (Int segment, Int offset, Int value) Type: Task Operation: Stores the 8-bit value into the memory location specified by segment and offset . _____________________________________________________________________________ Reading/Writing Memory In addition to "peeking" and "poking" bit values, Ultra-SiMPLE also allows the user to store/retrieve information of any type (Int, Float, etc.) direct- ly to/from memory. This means that memory can be partitioned to represent giant dimensioned arrays of any data types. (The region of memory that is used is referred to as "The Global Heap".) To directly use memory as an array you must first "open" a block of memory (much like you would "open" a disk file for input/output). But instead of specifying a path to a file, you would indicate the number of bytes of memory you wish to use for the "array". (For example, to store a million floating point numbers in memory you would need to specify four million bytes, since each floating point number requires four bytes. To store 1000 text strings would require 256000 bytes, since each text string can contain as many as 256 characters.) Ultra-SiMPLE then assigns to you an identifier called a "handle" (not to be confused with a library "handle" such as @toys). (The handle to memory is merely a numerical value that uniquely identifies the block of memory you requested so that it can be used as a "memory array".) Each element of a "memory array" can then accessed by specifying its index, just as you would use a subscript to access the elements of a conventional array. After you are finished using a block of memory, you should "close" it (much as you would "close" an opened disk file). _____________________________________________________________________________ Name: Openmemory (Int2 size) Type: Int function Operation: Opens a block of memory so that it can be used like a dimensioned array. Enter with: size, The number of bytes of memory being requested. Returns: A handle to the block of memory. Example: handle=open memory (25000) _____________________________________________________________________________ Name: Writebyte (Int handle, Int index, Int val) Type: Task Operation: Writes 8 bits of data to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". val, the 8-bit quantity to be written. Example: write byte (handle, 12345, 255) _____________________________________________________________________________ Name: Readbyte (Int handle, Int index) Type: Int function Operation: Reads 8 bits of data from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: value = read byte (handle, 12345) _____________________________________________________________________________ Name: Writeint (Int handle, Int index, Int val) Type: Task Operation: Writes an Int value to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". val, the value to be written. Example: write int (handle, 12345, -3794) _____________________________________________________________________________ Name: Readint (Int handle, Int index) Type: Int function Operation: Reads an Int value from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: value = read int (handle, 12345) _____________________________________________________________________________ Name: Writeint2 (Int handle, Int index, Int2 val) Type: Task Operation: Writes an Int2 value to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". val, the value to be written. Example: write int2 (handle, 12345, 7654321L) _____________________________________________________________________________ Name: Readint2 (Int handle, Int index) Type: Int2 function Operation: Reads an Int2 value from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: value = read int2 (handle, 12345) _____________________________________________________________________________ Name: Writefloat (Int handle, Int index, Float val) Type: Task Operation: Writes an Float value to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". val, the value to be written. Example: write float (handle, 12345, 3.1416) _____________________________________________________________________________ Name: Readfloat (Int handle, Int index) Type: Float function Operation: Reads an Float value from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: value = read int (handle, 12345) _____________________________________________________________________________ Name: Writefloat2 (Int handle, Int index, Float2 val) Type: Task Operation: Writes an Float2 value to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". val, the value to be written. Example: write float (handle, 12345, 6.023e-24) _____________________________________________________________________________ Name: Readfloat2 (Int handle, Int index) Type: Float2 function Operation: Reads an Float2 value from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: value = read float2 (handle, 12345) _____________________________________________________________________________ Name: Writetext (Int handle, Int index, Text string) Type: Task Operation: Writes a Text string to a "memory array". Enter with: handle, the handle of the block of memory repre- senting the "array". index, the "subscript" of the "array". string, the text string to be written. Example: write text (handle, 12345, "How now, brown cow") _____________________________________________________________________________ Name: Readtext (Int handle, Int index) Type: Text function Operation: Reads a Text string from a "memory array". Enter with: handle, the handle of the block of memory repre-. senting the "array". index, the "subscript" of the "array". Example: message = read text (handle, 12345) _____________________________________________________________________________ Name: Closememory (Int handle) Type: Task Operation: Closes a block of memory for further input or output. Calling Parameter: handle, the handle of the block of memory to be closed. _____________________________________________________________________________ Example ------- The following program stores 5 floating point numbers in memory, and then reads them back out again: handle = open memory (20) Do j = 0 To 4 write float (handle, j, sqrt (j+9)) Loop Do k = 0 To 4 data = read float (handle, k) Display data Loop close memory (handle) _____________________________________________________________________________ MOUSE _____________________________________________________________________________ Name: Readmouse (Int x, Int y, Int z) Type: Task Operation: Returns the current x and y position of the mouse along with its button status. Calling parameters: x: the current x coordinate for the mouse y: the current y coordinate for the mouse z: the mouse button status: 1 = left button pushed 2 = right button pushed 3 = both buttons pushed _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Showmouse Type: Task Operation: Makes the mouse cursor visible on the screen. _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Showmouse (Int cursor) Type: Task Operation: Selects a mouse cursor and makes it visible on the screen. Calling parameter: cursor - the type of mouse cursor desired: 0 - "standard" Windows arrow 1 - crosshairs 2 - hourglass 3 - I-beam 4 - up-arrow _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Unshowmouse Type: Task Operation: Replaces the current mouse cursor with the one which had been previously been in effect. _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Hidemouse Type: Task Operation: Makes the mouse cursor invisible on the screen. _____________________________________________________________________________ Name: Seemouse ( ) Type: Int function Operation: Returns zero if the mouse cursor is currently hidden. _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Movemouse (Int x, Int y) Type: Task Operation: Moves the mouse cursor to the specified x and y coordinates on the screen. Calling parameters: x: the x coordinate at which the mouse cursor should appear y: the y coordinate at which the mouse cursor should appear _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Limitmouse (Int a, Int b, Int c, Int d) Type: Task Operation: Confines the mouse cursor to the specified rectangu- lar area of the screen. Calling parameters: a: the x-coordinate of the upper-left corner of the confining rectangle b: the y-coordinate of the upper-left corner of the confining rectangle c: the x-coordinate of the lower-right corner of the confining rectangle d: the y-coordinate of the lower-right corner of the confining rectangle _____________________________________________________________________________ [Note: The following feature is not active when running in a window.] Name: Freemouse Type: Task Operation: Unconfines the mouse cursor. (See: Limitmouse) _____________________________________________________________________________ Name: Waitbutton ( ) Type: Int function Operation: Waits until any button on the mouse is pressed and released. Returns the number (1-3) of the button. _____________________________________________________________________________ Name: Waitbutton (Int id) Type: Int function Operation: Waits until the specified button on the mouse is pressed and released. Returns the number (1-3) of the button. Calling parameter: id: the specified button (1-3) (If id=0, wait for any button) _____________________________________________________________________________ Graphics Buttons _____________________________________________________________________________ Name: Drawbutton (Int id, Text label, Int color, Int mode) Type: Task Operation: Creates and draws a colored push-button on the graph- ics screen at the current text cursor position. Calling parameters: id: the reference ID (1-32) for the button label: the label to be placed on the button color: the color (0-15) of the button mode: =0, return non-zero ID while a button is being pressed >0, return momentary non-zero ID only when a button is released (i.e., "Windows"-style) <0, return momentary non-zero ID only when a button is pressed (See also the Readbuttons function.) _____________________________________________________________________________ Name: Readbuttons ( ) Type: Int function Operation: Returns the reference ID (1-32) of the button (on the graphics screen) being pressed. (If the right-hand mouse button is selecting, returns -ID.) (See also the Drawbutton task.) _____________________________________________________________________________ Name: Readbuttons (Int x, Int y, Int z) Type: Int function Operation: [Same as Readbuttons ( ) except that calling pro- gram must furnish the x , y , and z parameters of the mouse.] Calling parameters: x: the current x coordinate of the mouse y: the current y coordinate of the mouse z: the mouse button status _____________________________________________________________________________ Name: Disablebutton (Int id) Type: Task Operation: Deactivates the specified button. The button can later be reactivated by calling the "Enablebutton" task. Calling parameter: id: the reference ID of the button to be disabled _____________________________________________________________________________ Name: Enablebutton (Int id) Type: Task Operation: Reactivates the specified button. Calling parameter: id: the reference ID of the button to be enabled _____________________________________________________________________________ Name: Killbutton (Int id) Type: Task Operation: Permanenty deactivates the specified button. Calling parameter: id: the reference ID of the button to be disabled _____________________________________________________________________________ MOVIES _____________________________________________________________________________ The Media Control Interface (MCI) allows the user to play movie (.avi) files. To play a movie file you must first "open" the file (much like you would "open" a data file file for reading or writing). Ultra-SiMPLE then assigns to you an identifier called a "handle" (not to be confused with a library "handle" such as @toys). (The handle to a movie file is merely a numerical value that uniquely identifies the file so that it can be easily referenced.) After you are finished playing a movie file, you should "close" it (just as you would "close" any opened data file). _____________________________________________________________________________ Name: Openmovie (Text path) Type: Int function Operation: Opens a movie file so that it can be played. Enter with: path - the path to the movie file. Returns: A handle to the file. Example: handle = open movie ("mymovie.avi") _____________________________________________________________________________ Name: Startmovie (Int handle) Startmovie (Int handle, Int2 from) Startmovie (Int handle, Int2 from, Int2 to) Type: Task Operation: Starts playing the specified movie in full-screen mode. Enter with: handle - the handle of the movie file. from - the starting position (in milliseconds) for playback. (If not specified, starts from the beginning of the movie.) to - the ending position (in milliseconds) for playback. (If not specified, plays to the end of the movie.) Caution: Be sure that the data types of the calling parameters that you pass to a Startmovie task exactly match the types that are expected. Example: Call start movie (handle, 1000L, 5000L) _____________________________________________________________________________ Name: Startmovie (Int handle, Int xul, Int yul) Startmovie (Int handle, Int2 from, Int xul, Int yul) Startmovie (Int handle, Int2 from, Int2 to, \ Int xul, Int yul) Type: Task Operation: Starts playing the specified movie in its normal size at a specified location (xul, yul) on the screen. Enter with: handle - the handle of the movie file. from - the starting position (in milliseconds) for playback. (If not specified, starts from the beginning of the movie.) to - the ending position (in milliseconds) for playback. (If not specified, plays to the end of the movie.) xul,yul - the upper-left coordinates at which the movie is to be played. Caution: Be sure that the data types of the calling parameters that you pass to a Startmovie task exactly match the types that are expected. Example: Call start movie (handle, 1000L, 5000L, 200, 100) _____________________________________________________________________________ Name: Waitmoviedone (Int handle) Type: Task Operation: Waits until the specified movie file is finished playing. Enter with: handle - the handle of the movie file. _____________________________________________________________________________ Name: Moviedone (Int handle) Type: Int function Operation: Returns zero (FALSE) if the specified movie file is still playing. Enter with: handle - the handle of the movie file. Example: If movie done (handle) Call close movie (handle) _____________________________________________________________________________ Name: Closemovie (Int handle) Type: Task Operation: Closes a movie file. Enter with: handle - the handle of the movie file. _____________________________________________________________________________ Example: The following program would play the first 5 seconds of a movie named "myflick.avi" located in the root directory of the "C:" drive: id = open movie ("c:\\myflick.avi") start movie (id, 0L, 5000L) wait movie done (id) close movie (id) _____________________________________________________________________________ SOUNDS _____________________________________________________________________________ The Ultra-SiMPLE system library contains seven pre-defined sound tasks, each of which produces its corresponding sound: Task Cuckoo Task Honk Task Twing Task Drip Task Rattle Task Snip Task Pop Example: Call honk _____________________________________________________________________________ Name: Playsound (Text path) Type: Task Operation: Plays a sound file and waits for it to finish. Enter with: path - the path to the sound file. Example: Playsound ("\\SiMPLE\\SOUNDS\\bugle.mid") _____________________________________________________________________________ The Media Control Interface (MCI) allows the user to play sounds (wave files and midi files) through the computer's sound card. Aside from the Playsound task and the seven pre-defined sounds described above, to play either a wave file or a midi file you must first "open" the file (much like you would "open" a data file file for reading or writing). Ultra-SiMPLE then assigns to you an identifier called a "handle" (not to be confused with a library "handle" such as @toys). (The handle to a sound file is merely a numerical value that uniquely identifies the file so that it can be easily referenced.) After you are finished using a sound file, you should "close" it (just as you would "close" any opened data file). The Playsound task (described above) automatically performs all of these operations for you. _____________________________________________________________________________ Name: Openmci (Text path) Type: Int function Operation: Opens a sound file so that it can be played through the sound card. Enter with: path - the path to the sound file. Returns: A handle to the file. Example: handle = open mci ("mysound.wav") _____________________________________________________________________________ Name: Startmci (Int handle) Startmci (Int handle, Int2 from) Startmci (Int handle, Int2 from, Int2 to) Type: Task Operation: Starts playing the specified sound file. Enter with: handle - the handle of the sound file. from - the starting position (in milliseconds) for playback. (If not specified, starts from the beginning of the file.) to - the ending position (in milliseconds) for playback. (If not specified, plays to the end of the file.) Example: Call start mci (handle, 1000, 5000) _____________________________________________________________________________ Name: Midivolume (Int2 left, Int2 right) Type: Task Operation: Sets the volume level for playing midi files. Enter with: left - the volume setting (0-65535) for the left channel right - the volume setting (0-65535) for the right channel _____________________________________________________________________________ Name: Wavevolume (Int2 left, Int2 right) Type: Task Operation: Sets the volume level for playing wave files. Enter with: left - the volume setting (0-65535) for the left channel right - the volume setting (0-65535) for the right channel _____________________________________________________________________________ Name: Cyclemci (Int handle) Cyclemci (Int handle, Int2 from) Cyclemci (Int handle, Int2 from, Int2 to) Type: Task Operation: Starts playing the specified sound file over and over in a loop. Enter with: handle - the handle of the sound file. from - the starting position (in milliseconds) for each playback. (If not specified, starts from the beginning of the file.) to - the ending position (in milliseconds) for each playback. (If not specified, plays to the end of the file.) _____________________________________________________________________________ Name: Pausemci (Int handle) Type: Task Operation: Stops playing (pauses) the specified sound file. (Call the "Resumemci" task to resume playing.) Enter with: handle - the handle of the sound file. _____________________________________________________________________________ Name: Resumemci (Int handle) Type: Task Operation: Resumes playing the paused sound file. Enter with: handle - the handle of the paused sound file. _____________________________________________________________________________ Name: Stopcyclingmci (Int handle) Type: Task Operation: Stops playing the specified sound file when it reaches the end of its current cycle. Enter with: handle - the handle of the sound file. _____________________________________________________________________________ Name: Stopmci (Int handle) Type: Task Operation: Stops playing the specified sound file immediately. Enter with: handle - the handle of the sound file. _____________________________________________________________________________ Name: Waitmcidone (Int handle) Type: Task Operation: Waits until the specified sound file is finished playing. Enter with: handle - the handle of the sound file. _____________________________________________________________________________ Name: Mcidone (Int handle) Type: Int function Operation: Returns zero (FALSE) if the specified sound file is still playing. Enter with: handle - the handle of the sound file. Example: If mci done (handle) Call close mci (handle) _____________________________________________________________________________ Name: Closemci (Int handle) Type: Task Operation: Closes a sound file. Enter with: handle - the handle of the sound file. _____________________________________________________________________________ Example: The following program will play the "Canyon" midi file in the Windows media directory: id = open mci ("\\windows\\media\\canyon.mid") start mci (id) wait mci done (id) close mci (id) _____________________________________________________________________________ ACCESSING THE MIDI CONTROLER In addition to being able to play midi FILES, it is also possible to play sounds by directly accessing the midi CONTROLER. (A complete list of all the midi "voices" appears at the end of this section.) The following tasks provide direct access to the midi controller: _____________________________________________________________________________ Name: Openmidi Type: Task Operation: Opens the midi controler. _____________________________________________________________________________ Name: Playnote (Int voice, Int note, Int dur) Type: Task Operation: Plays the specified musical note at maximum volume. Enter with: voice - the voice to be used for the note. note - the note to be played. (60 = Middle C, 0 = silence) dur - the duration of the note (in milliseconds). (If the 'note' parameter is greater than 0, the note will stop playing abruptly after the specified duration. If the 'note' para- meter is less than 0, the note will be sus- tained until the next non-silent note is en- countered.) _____________________________________________________________________________ Name: Closemidi Type: Task Operation: Closes the midi controler. _____________________________________________________________________________ Example: The following program will play a "do-re-mi" sequence of notes (in the key of C) on a Harpsichord, with each note lasting for one second: open midi play note (7, 60, 1000) play note (7, 62, 1000) play note (7, 64, 1000) close midi _____________________________________________________________________________ For more "exotic" applications (such as playing chords), the following tasks are also available: _____________________________________________________________________________ Name: Startmidi (Int chan, Int voice, Int note, Int vol) Type: Task Operation: Starts playing the specified musical note. Enter with: chan - the midi channel (0-15) in which the note is to be played. voice - the voice to be used for the note: note - the note to be played. (60 = Middle C, 0 = silence) vol - the volume (0-127) to be used for the note. _____________________________________________________________________________ Name: Stopmidi Type: Task Operation: Stops playing all midi sounds. _____________________________________________________________________________ Example: The following program will use channels 0, 1, and 2 to play a quiet 3-note Grand Piano chord (in the key of C) for two seconds: open midi start midi (0, 1, 60, 32) start midi (1, 1, 64, 32) start midi (2, 1, 67, 32) delay (2000) stop midi close midi _____________________________________________________________________________ *The Midi voices are specified by the numbers in the following table: 1. Acoustic Grand Piano 65. Soprano Sax 2. Bright Acoustic Piano 66. Alto Sax 3. Electric Grand Piano 67. Tenor Sax 4. Honky-tonk Piano 68. Baritone Sax 5. Electric Piano 1 69. Oboe 6. Electric Piano 2 70. English Horn 7. Harpsichord 71. Bassoon 8. Clavi 72. Clarinet 9. Celesta 73. Piccolo 10. Glockenspiel 74. Flute 11. Music Box 75. Recorder 12. Vibraphone 76. Pan Flute 13. Marimba 77. Blown Bottle 14. Xylophone 78. Shakuhachi 15. Tubular Bells 79. Whistle 16. Dulcimer 80. Ocarina 17. Drawbar Organ 81. Lead 1 (square) 18. Percussive Organ 82. Lead 2 (sawtooth) 19. Rock Organ 83. Lead 3 (calliope) 20. Church Organ 84. Lead 4 (chiff) 21. Reed Organ 85. Lead 5 (charang) 22. Accordion 86. Lead 6 (voice) 23. Harmonica 87. Lead 7 (fifths) 24. Tango Accordion 88. Lead 8 (bass + lead) 25. Acoustic Guitar (nylon) 89. Pad 1 (new age) 26. Acoustic Guitar (steel) 90. Pad 2 (warm) 27. Electric Guitar (jazz) 91. Pad 3 (polysynth) 28. Electric Guitar (clean) 92. Pad 4 (choir) 29. Electric Guitar (muted) 93. Pad 5 (bowed) 30. Overdriven Guitar 94. Pad 6 (metallic) 31. Distortion Guitar 95. Pad 7 (halo) 32. Guitar harmonics 96. Pad 8 (sweep) 33. Acoustic Bass 97. FX 1 (rain) 34. Electric Bass (finger) 98. FX 2 (soundtrack) 35. Electric Bass (pick) 99. FX 3 (crystal) 36. Fretless Bass 100. FX 4 (atmosphere) 37. Slap Bass 1 101. FX 5 (brightness) 38. Slap Bass 2 102. FX 6 (goblins) 39. Synth Bass 1 103. FX 7 (echoes) 40. Synth Bass 2 104. FX 8 (sci-fi) 41. Violin 105. Sitar 42. Viola 106. Banjo 43. Cello 107. Shamisen 44. Contrabass 108. Koto 45. Tremolo Strings 109. Kalimba 46. Pizzicato Strings 110. Bag pipe 47. Orchestral Harp 111. Fiddle 48. Timpani 112. Shanai 49. String Ensemble 1 113. Tinkle Bell 50. String Ensemble 2 114. Agogo 51. SynthStrings 1 115. Steel Drums 52. SynthStrings 2 116. Woodblock 53. Choir Aahs 117. Taiko Drum 54. Voice Oohs 118. Melodic Tom 55. Synth Voice 119. Synth Drum 56. Orchestra Hit 120. Reverse Cymbal 57. Trumpet 121. Guitar Fret Noise 58. Trombone 122. Breath Noise 59. Tuba 123. Seashore 60. Muted Trumpet 124. Bird Tweet 61. French Horn 125. Telephone Ring 62. Brass Section 126. Helicopter 63. SynthBrass 1 127. Applause 64. SynthBrass 2 128. Gunshot _____________________________________________________________________________ STICKERS _____________________________________________________________________________ A "Sticker" is a pair of special type image files: A bitmap image (file type: ".stk") A mask image (file type: ".msk") which define an image which can be pasted anywhere on the screen. The Ultra- SiMPLE system library contains several tasks which allow the user to manipu- late Stickers. (The path "\SiMPLE\STICKERS" contains several sample stick- ers for you to play with.) Before you can use a Sticker you must first "open" the Sticker (much like you would "open" an ordinary bitmap image file. Ultra-SiMPLE then assigns to you an identifier called a "handle" (not to be confused with a library "handle" such as @toys). (The handle to a Sticker is merely a numerical value that uniquely identifies the Sticker so that it can be easily referenced.) After you are finished using a Sticker, you must "close" it (just as you would "close" any opened image file). _____________________________________________________________________________ Name: Opensticker (Text path) Type: Int function Operation: Opens a Sticker and loads it into memory. (No more than 32 Stickers may be currently open at any one time.) Enter with: path - the path to the Sticker. [Note: You must NOT specify the .stk (or .msk) extension. They are automatically supplied by the task.] Returns: A handle to the Sticker. (Sticker handles are assigned as consecutive integers: 1, 2, 3, ... 32.) _____________________________________________________________________________ Name: Getstickerdata (Int handle, Int xsize, Int ysize) Getstickerdata (Int handle, Int xsize, Int ysize, Int zbits) Type: Task Operation: Retrieves information about an opened sticker. Enter with: handle - the handle of the sticker. Returns: xsize - The horizontal size of the sticker (in pixels). ysize - The vertical size of the sticker (in pixels). zbits - The number of bits per pixel. _____________________________________________________________________________ Name: Pastesticker (Int handle, Int x, Int y) Type: Task Operation: Pastes a Sticker onto the screen. Enter with: handle - the handle of the Sticker. x,y - the location on the screen at which the center of the Sticker is to be located. _____________________________________________________________________________ Name: Pastenegative (Int handle, Int x, Int y) Type: Task Operation: Pastes the negative image of a Sticker onto the screen. Enter with: handle - the handle of the Sticker. x,y - the location on the screen at which the center of the Sticker is to be located. _____________________________________________________________________________ Name: Pullsticker (Int handle, Int x, Int y) Type: Task Operation: Removes a Sticker from the screen (leaving a hole where the Sticker had been). Enter with: handle - the handle of the Sticker. x,y - the location on the screen at which the center of the Sticker is located. _____________________________________________________________________________ Name: Closesticker (Int handle) Type: Task Operation: Closes a Sticker. Enter with: handle - the handle of the Sticker to be closed. _____________________________________________________________________________ Example: The following program pastes $1000 worth of quarters onto the screen: hand = open sticker ("\\simple\\stickers\\quarter") Do k = 1 To 4000 paste sticker (hand, random(800), random(600)) Loop close sticker (hand) _____________________________________________________________________________ STRINGS _____________________________________________________________________________ Name: Extract (Text t, Int a) Extract (Text t, Int a, Int b) Type: Text function Operation: Extracts a sub-string from a string. Calling parameters: t - The text string from which characters are to be extracted. a - The position of the first character in the sub-string to be extracted. b - The position of the final character to be extracted. (If not specified, extracts all the characters starting from position a .) _____________________________________________________________________________ Name: Length (Text t) Len (Text t) Type: Int function Operation: Returns the length of a string. Calling parameter: t - The string whose length is to be determined. _____________________________________________________________________________ Name: Char (Int charval) Type: Text function Operation: Converts the numerical value of the integer calling parameter into a one character string. Calling parameter: charval - The numerical value to be converted. Example: The following two statements are equivalent: Set x = Char (99) Set x = "c" _____________________________________________________________________________ Name: Ascii (Text t) Type: Int function Operation: Converts the first character of the specified text string into its integer ASCII value Calling parameter: t - The text string to be converted. Example: The following two statements are equivalent: Set x = 99 Set x = Ascii ("c") _____________________________________________________________________________ Name: Parse (Text string, Text tokens[], Int num) Type: Task Operation: Parses a string into individual tokens. Calling parameters: string - The text string to be parsed (Tokens must be separated by spaces) tokens[] - The array of returned tokens num - The number of tokens expected (Returns the actual number of tokens that were found) Example: Text tokens[7] Set string = "SiMPLE for kids!" Set num = 7 Call Parse (string, tokens, num) Display num Do k = 1 To num Display tokens[k-1] Loop k Result: The following would be displayed: 3 SiMPLE for kids! _____________________________________________________________________________ Name: Strstr (Text a, Text b) Type: Text function Operation: Tests to see if text sub-string b is contained anywhere inside text string a . If a match is found, the sub-string b is returned by the Strstr function. If no match is found, a null character is returned. Calling parameters: a - The text string to be searched b - The text sub-string being looked for Example: Set x= Strstr ("abcdefg","def") Display x Result: The text sub-string, def, would be displayed _____________________________________________________________________________ Name: Strind (Text a, Text b) Type: Int function Operation: Tests to see if text sub-string b is contained anywhere inside text string a . If a match is found, the character position (index) of the start of the sub-string is returned by the Strind function. If no match is found, a value of -1 is returned. Calling parameters: a - The text string to be searched b - The text sub-string being looked for Example: Set x = Strind ("abcdefg","def") Display x Result: The value, 3, would be displayed _____________________________________________________________________________ Name: Isalpha (Text t) Type: Int function Operation: Tests the first character of the specified text string to see whether it is an alpha character (a-z) Calling parameter: t - The text string to be tested. Return value: +1, character is uppercase alpha 0, character is not alpha -1, character is lowercase alpha _____________________________________________________________________________ Name: Isdigit (Text t) Type: Int function Operation: Tests the first character of the specified text string to see whether it is a digit character (0-9) Calling parameter: t - The text string to be tested. Return value: 1, character is a digit 0, character is not a digit _____________________________________________________________________________ MISCELLANEOUS _____________________________________________________________________________ Name: Simple Type: Task Operation: Displays the word "SiMPLE" in colored letters. _____________________________________________________________________________ Name: Universe ( ) Type: Text function Operation: Lets the program know which universe it's running in. Returns: Either "Pro" or "Ultra" _____________________________________________________________________________ Name: Getmode ( ) Type: Int function Operation: Lets the program know whether it is running in full-screen mode or in a window. Returns: zero, the program is running in full-screen mode. non-zero, the program is running in a window. _____________________________________________________________________________ Name: Pause Type: Int function [Can also be invoked as a task] Operation: Displays the message: "Press any key..." and waits for a keyboard response. Returns: The key that was pressed _____________________________________________________________________________ Name: Messagebox (Text message) Type: Task Operation: Displays a small window containing a message, along with an "OK" button. It then waits for the user to click the button. Calling parameter: message: the message to be displayed Examples: messagebox ("This is a one-line message.") messagebox ("This is a\ntwo-line message.") Note: (This task uses auxiliary screen #7.) _____________________________________________________________________________ Name: Querybox (Text question) Type: Int function Operation: Displays a small window containing a "yes or no" question, along with a "Yes" button and a "No" button. It then waits for the user to respond. Calling parameter: question: the "yes or no" question beeing asked Returns: 1, if the "Yes" button was clicked (or if the "Y" key was pressed). 0, if the "No" button was clicked (or if the "N" key was pressed). Note: (This function uses auxiliary screen #7.) _____________________________________________________________________________ Name: Confirmquit ( ) Type: Int function Operation: Displays a small window containing the message: "Are you sure you want to quit?" along with a "Yes" button and a "No" button. It then waits for the user to respond. Returns: 1, if the "Yes" button was clicked (or if the "Y" key was pressed. 0, if the "No" button was clicked (or if the "N" key was pressed. Note: (This task uses auxiliary screen #7.) _____________________________________________________________________________ Name: Quit Type: Task Operation: Terminates the program [either by invoking the "Goodbye" task or the user's "myquit()" function, depending on what was specified on the program's "Ultra" compiler directive). _____________________________________________________________________________ Name: Goodbye Type: Task Operation: Exits the program. [Should be used only in the user's "myquit()" function.] _____________________________________________________________________________ Name: System (Text command) Type: Task Operation: Allows a Command Prompt command to be issued. Calling parameter: command: a text string representing the command to be issued. Example: Call System ("md c:\\\"New Directory\"") _____________________________________________________________________________ Name: Winexec (Text name) Type: Task Operation: Executes the program specified by "name". Calling parameter: name: the name of (or the path to) the program which is to be executed _____________________________________________________________________________ Time Operations _____________________________________________________________________________ Name: Delay (Int time) Type: Task Operation: Delays for a specified number of milliseconds. Calling parameter: time: the number of milliseconds _____________________________________________________________________________ Name: Wait (Int ticks) Type: Task Operation: Delays for a specified number of clock ticks. Calling parameter: time: the number of clock ticks _____________________________________________________________________________ Name: Clktck ( ) Type: Int function Operation: Returns the rate (ticks per second) at which the clock is ticking. _____________________________________________________________________________ Name: Starttimer Type: Task Operation: Starts an internal timer for measuring elapsed time. _____________________________________________________________________________ Name: Elapsedtime ( ) Type: Int2 function Operation: Returns the amount of time (in milliseconds) since the timer was started. _____________________________________________________________________________ Name: Time ( ) Type: Text function Operation: Returns the current date and time as a 24 character text string. (E.g., "Mon 1999 May 17 09:49:27") _____________________________________________________________________________ Main Program Calling Parameters _____________________________________________________________________________ Name: Param (Int index) Type: Text function Operation: Retrieves the specified calling parameter to the main program. Calling parameter: index: the calling parameter to be retrieved (1 = the first parameter, 2 = the second parameter, ... 9 = nineth parameter) _____________________________________________________________________________ Name: Numargs ( ) Type: Int function Operation: Retrieves the number of calling parameters that have been passed to the main program. _____________________________________________________________________________ Display Settings _____________________________________________________________________________ Name: Xpixelscreen ( ) Type: Int function Operation: Returns the horizontal resolution (in pixels) of the entire display screen. _____________________________________________________________________________ Name: Ypixelscreen ( ) Type: Int function Operation: Returns the vertical resolution (in pixels) of the entire display screen. _____________________________________________________________________________ Name: Xpixels ( ) Type: Int function Operation: Returns the horizontal resolution (in pixels) of the window. (If running in full-screen mode, the "window" is the entire display screen.) _____________________________________________________________________________ Name: Ypixels ( ) Type: Int function Operation: Returns the current vertical resolution (in pixels) of the window. (If running in full-screen mode, the "window" is the entire display screen.) _____________________________________________________________________________ Name: Zbits ( ) Type: Int function Operation: Returns the current number of bits per pixel of the display screen. _____________________________________________________________________________ System I/O _____________________________________________________________________________ Name: Kickio Type: Task Operation: Briefly returns control back to Windows so that it can attend to any pending I/O operations (such as keeping a wave file playing, etc.). _____________________________________________________________________________ Null Tasks/Functions _____________________________________________________________________________ The Ultra-SiMPLE system library contains several "do nothing" tasks/functions which exist for the sole purpose of allowing at least a minimal amount of compilation compatibility with Pro-SiMPLE: Task Sound Task Nosound Task Graphon Task Graphoff Int Ingrmode ( ) _____________________________________________________________________________ AUXILIARY (or "Virtual") SCREENS Ultra-SiMPLE has a total of eight different "screens" (numbered 0 through 7) onto which information (graphics, text, etc.) can be "displayed". Screen 0 (the primary screen) is the only one that is actually visible. The remaining seven screens (the auxiliary screens) are all virtual (i.e., they are hidden from view). However information that has been "displayed" onto an auxiliary screen can be brought into view by copying the auxiliary screen onto the pri- mary screen. [NOTE: You should try to avoid using screen 7 whenever possible, as it is in- tended for system use. (See the "Messagebox" task and the "Querybox" function.)] [NOTE: Because of the unique way in which the auxiliary screens are imple- mented, they cannot be used in programs that are intended to run di- rectly from Read-only memory (such as a CD).] _____________________________________________________________________________ The following tasks provide access to the auxiliary screens: Task: Operation: ----- ---------- Openscreen (Int id) Opens (i.e, "creates") the specified aux screen. You must open an auxiliary screen* before you can use it. *[However it is not necessary to open the primary screen (id=0). Screen 0 is always available by default.] Selectscreen (Int id) Selects the specified screen as the target screen onto which all subsequent display operations will be directed. (I.e., the specified screen becomes the "active" screen.) Bitbltscreen (Int id) Bitbltscreen (Int id, Int xul, Int yul, Int dx, Int dy) Bitbltscreen (Int id, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top) Bitbltscreen (Int id, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int2 mode) Bitbltscreen (Int id, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys) Bitbltscreen (Int id, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys, Int2 mode) Copies the contents of the specified screen onto the active screen. [The calling parameters are the same as for Bitblt.] Closescreen (Int id) Closes (i.e, "deletes") the specified aux screen. When a program ends, it must always remember to close any auxiliary screens* that it opened. *[However it is not necessary to close the primary screen (id=0). Screen 0 automatic- ly closes by itself.] _____________________________________________________________________________ The following function is also available: Function: Operation: --------- ---------- Int Activescreen() Returns the id number of the active screen. _____________________________________________________________________________ Example ------- The following program opens two auxiliary screens, sets each one to a dif- ferent color, and then alternately displays each screen five times: open screen (1) open screen (2) select screen (1); cls (2) tabxy (20, 10); Display " This is screen ONE ", select screen (2); cls (4) tabxy (20, 10); Display " This is screen TWO ", select screen (0) Do k=1,5 bitblt screen (1) delay (1000) bitblt screen (2) delay (1000) Loop close screen (2) close screen (1) quit _____________________________________________________________________________ THE BITBLT TASK _____________________________________________________________________________ "Bitblt" is a powerful task which can be used to display bitmap images very quickly. It can also be used to magnify bitmap images. Before you can use Bitblt to display an image you must first convert the image's handle into a "Bitblt handle" (by invoking the "Openblt" function). _____________________________________________________________________________ Name: Openblt (Int ihand) Type: Int function Operation: Creates a "Bltblt handle" from an image handle. Enter with: ihand - the handle of the image. Returns: The "Bitblt handle". _____________________________________________________________________________ Name: Bitblt (Int bhand, Int xul, Int yul) Bitblt (Int bhand, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top) Bitblt (Int bhand, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int2 mode) Bitblt (Int bhand, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys) Bitblt (Int bhand, Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys, Int2 mode) Type: Task Operation: Displays a bitmap image onto the screen. Enter with: bhand - the "Bitblt handle". xul,yul - the coordinates of the upper-left corner of the destination rectangle. Other optional parameters: dx,dy - the size of destination rectangle. (Default: the entire screen) left,top - the upper-left corner of the source rectangle. (Default: 0,0) dxs,dys - the size of the source rectangle. (Default: the entire image) mode - the mode of operation: BLACKNESS Turns all output black. DSTINVERT Inverts the destination bitmap. MERGEPAINT Combines the inverted source bitmap with the destination bitmap by using the Boolean OR operator. NOTSRCCOPY Copies the inverted source bitmap to the destination. NOTSRCERASE Inverts the result of combining the destination and source bitmaps by using the Boolean OR operator. SRCAND Combines pixels of the destination and source bitmaps by using the Boolean AND operator. SRCCOPY Copies the source bitmap to the des- tination bitmap. (Default) SRCERASE Inverts the destination bitmap and combines the result with the source bitmap by using the Boolean AND op- erator. SRCINVERT Combines pixels of the destination and source bitmaps by using the Boolean XOR operator. SRCPAINT Combines pixels of the destination and source bitmaps by using the Boolean OR operator. WHITENESS Turns all output white. _____________________________________________________________________________ Name: Closeblt (Int bhand) Type: Task Operation: Closes a "Bitblt handle". Enter with: bhand - the "Bitblt handle" to be closed. _____________________________________________________________________________ Examples: The following program will display (in the upper left-hand corner of the screen) a "Forest" bitmap image located in the Windows directory: ihand = open image ("c:\\windows\\forest.bmp") bhand = open blt (ihand) bitblt (bhand, 0, 0) close blt (bhand) close image (ihand) The following program will display the same "Forest" bitmap image magnified by a factor of two: ihand = open image ("c:\\windows\\forest.bmp") bhand = open blt (ihand) bitblt (bhand, 0, 0, 512, 512, 0, 0, 256, 256) close blt (bhand) close image (ihand) _____________________________________________________________________________ IMAGES OF PLAYING CARDS _____________________________________________________________________________ The Ultra-SiMPLE system library contains several tasks which allow the user to display images of playing cards. (Each card is 71x94 pixels.) Before you can display a card image you must first "open" the deck. And after you are finished using the deck of cards, you must "close" it. _____________________________________________________________________________ Name: Opendeck Type: Task Operation: Opens the deck of playing cards so that they can be displayed. _____________________________________________________________________________ Name: Showcard (Int x, Int y, Int card) Type: Task Operation: Displays a specified card at a specified location on the screen. Parameters: x,y --- The location on the screen at which the upper-left corner of the card is to appear. card -- The card (1-52) which is to be displayed: 1 - Ace of Clubs 2 - Two of Clubs - - - 13 - King of Clubs -------------------- 14 - Ace of Diamonds 15 - Two of Diamonds - - - 26 - King of Diamonds --------------------- 27 - Ace of Hearts 28 - Two of Hearts - - - 39 - King of Hearts --------------------- 40 - Ace of Spades 41 - Two of Spades - - - 52 - King of Spades If card=0, the card is displayed face down. If card<0, the card is displayed as a negative image. _____________________________________________________________________________ Name: Erasecard (Int x, Int y, Int color) Erasecard (Int x, Int y, Int2 color) Type: Task Operation: Erases a card at the specified location on the screen. Parameters: x,y ---- The location at which the card is to be erased. color -- The background color on which the card is currently being displayed. [This task merely calls the "Blankcard" task with a negative "color" value.] _____________________________________________________________________________ Name: Blankcard (Int x, Int y, Int color) Blankcard (Int x, Int y, Int2 color) Type: Task Operation: Displays a blank card at a specified location on the screen. (The user can then add any image to create a customized playing card.) Parameters: x,y ---- The location at which the blank card is to appear. color -- The color in which the card is to be displayed. If color<0, the card's outline is also drawn in the specified color (i.e., the whole card is "erased" to the specified color). _____________________________________________________________________________ Name: Closedeck Type: Task Operation: Closes the deck of playing cards. _____________________________________________________________________________ Example: The following program will keep filling the screen with cards until the "Esc" key is pressed: cls (3) open deck Do show card (random(xpixels()+71)-71, \ random(ypixels()+94)-94, \ random(53)) delay (5) If read key (27) Break Loop close deck quit _____________________________________________________________________________ ACCESSING THE WINDOWS CLIPBOARD By using the Windows clipboard it is possible to pass a bitmap image between your program and Windows. [When using the clipboard to RECEIVE an image from Windows, you MUST first issue a "SFX OFF" command before compiling your program. However it is not necessary to issue the "SFX OFF" command if your program RETURNS an image to Windows.] _____________________________________________________________________________ Name: Loadclipboard Loadclipboard (Int xul, Int yul, Int dx, Int dy) Type: Task Operation: Captures a region of the screen and loads it onto the Windows clipboard. (If no region is specified, the entire screen is captured.) Enter with: xul,yul - the coordinates of the upper-left corner of the rectangular region. dx,dy - the size of the region. [Note: You cannot load the clipboard from an AUXILIARY screen. The image to be loaded must be on the PRIMARY screen.] _____________________________________________________________________________ Name: Clipboard Type: Int function Operation: Tests the Windows clipboard to see whether or not it contains a bitmap image. Returns: 0, no image is present 1, an image is present _____________________________________________________________________________ Name: Bitbltclipboard Bitbltclipboard (Int xul, Int yul) Bitbltclipboard (Int xul, Int yul, Int dx, Int dy, \ Int left, Int top) Bitbltclipboard (Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int2 mode) Bitbltclipboard (Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys) Bitbltclipboard (Int xul, Int yul, Int dx, Int dy, \ Int left, Int top, Int dxs, Int dys, Int2 mode) Type: Task Operation: Displays the clipboard image onto the screen. [The calling parameters are the same as for Bitblt.] _____________________________________________________________________________ WINDOWS (These tasks/functions are available for programs that are intended to run in a window.) _____________________________________________________________________________ Name: Winframe Type: Task Operation: Draws a slightly thicker frame around the edge of the program's window. Calling parameters: (none) _____________________________________________________________________________ Name: Winframe (Int size, Int thick) Type: Task Operation: Draws an extended "3-D" frame around the edge of the program's window. Calling parameters: size: the extent of the frame thick: the "thickness" of the frame _____________________________________________________________________________ Name: Movewindow (Int x, Int y) Type: Task Operation: Moves the program's window to the specified x,y location on the display screen. _____________________________________________________________________________ Name: Windowloc (Int xul, Int yul, Int xlr, Int ylr) Type: Task Operation: Returns the current location of the program's window. Calling parameters: xul - the x-coordinate of the upper-left corner of the window yul - the y-coordinate of the upper-left corner of the window xlr - the y-coordinate of the lower-right corner of the window ylr - the y-coordinate of the lower-right corner of the window _____________________________________________________________________________ Name: Minimized ( ) Type: Int function Operation: Returns a non-zero value if the program's window is currently minimized; returns zero otherwise. _____________________________________________________________________________ Name: Waitifminimized Type: Task Operation: If the program's window is currently minimized, waits until it becomes restored again. _____________________________________________________________________________ Name: Getmode ( ) Type: Int function Returns: zero - if the program is running in full-screen mode one - if the program is running in a window _____________________________________________________________________________