QX82
About How-To Reference

This is a full list of all the QX82 functions, organized by module (namespace). At the top of your Javascript file, you can declare these imports as:

import * as qx from "./qx82/qx.js";
import * as qxa from "./qx82/qxa.js";
import * as qut from "./qx82/qut.js";

Contents

Module: qx

Module: qx

qx.init(callback)

Initializes the API. This must be called before other functions and it must finish executing before other API functions are called. Once the supplied callback is called, you can start using QX82 functions.

callback function

The callback to call when initialization is done.

qx.render()

Forces the screen to render right now. You only need this if you are doing some kind of animation on your own and you want to redraw the screen immediately to show the current state. Otherwise the screen repaints automatically when waiting for user input.

qx.color(fg, bg)

Sets the foreground and/or the background color.

fg integer

The foreground color.

bg integer (optional)

(optional) The foreground color (a number). If omitted, the current background color will be kept.

qx.getFgColor()

Returns the current foreground color.

qx.getBgColor()

Returns the current background color. Note that -1 means transparent.

qx.cls()

Clears the screen using the current background color.

qx.locate(col, row)

Places the cursor at the given screen column and row.

col

The column where the cursor is to be placed.

row

(optional) The row where the cursor is to be placed. If omitted, remains on the current row.

qx.col()

Returns the cursor's current column.

qx.row()

Returns the cursor's current row.

qx.cursor(visible)

Shows or hides the cursor.

visible boolean

If true, show the cursor. If false, hide the cursor.

qx.print(text)

Prints text at the cursor position, using the current foreground and background colors. This will advance the cursor position.

text string

The text to print. This can contain embedded newlines and they will behave as you expect: printing will continue at the next line. If PRINT_ESCAPE_START and PRINT_ESCAPE_END are defined in CONFIG, then you can also use escape sequences. For example {{c1}} sets the color to 1, so your string can be "I like the color {{c1}}blue" and the word 'blue' would be in blue. The sequence {{b2}} sets the background to 2 (red). The sequence {{z}} resets the color to the default. See example-printing.html for an example.

qx.printCentered(text, width)

Prints text centered horizontally in a field of the given width. If the text is bigger than the width, it will overflow it.

text string

The text to print.

width number

The width of the field, in characters.

qx.drawText(x, y, text, fontId = null)

Draws text at an arbitrary pixel position on the screen, not following the "row and column" system. This won't affect cursor position.

x integer

The X coordinate of the top-left of the text.

y integer

The Y coordinate of the top-left of the text.

text string

The text to print. This can contain embedded newlines and they will behave as you expect: printing will continue at the next line.

fontId string

(optional) If specified, this is a font ID previously obtained with qxa.loadFont(), indicating the custom font to use to print the text. If not specified, then we will use the current font as set with qx.setFont(), or the default font if that was never set.

qx.measure(text)

Measures the size of the given text without printing it.

text string

The text to measure.

Return value

An object with {cols, rows} indicating how wide and how tall the text is, expressed in rows and columns (not pixels).

qx.printChar(charCode, numTimes = 1)

Prints a character at the current cursor position using the current foreground and background colors, advancing the cursor position.

charCode integer | string

The character to print, as an integer (its ASCII code). This can also be a one-character string for convenience, so 65 and "A" mean the same thing.

numTimes integer, optional, default = 1

How many times to print the character. By default 1.

qx.printRect(widthCols, heightRows, charCode = 32)

Prints a rectangle of the given size with the given character, with the current foreground and background colors, starting at the current cursor position. Does not change cursor position.

widthCols integer

Width of the rectangle in screen columns.

heightRows integer

Height of the rectangle in screen rows.

charCode integer | string (default = 32)

The character to print, as an integer (its ASCII code). This can also be a one-character string for convenience, so 65 and "A" mean the same thing. By default this is 32 (space).

qx.printBox(widthCols, heightRows, fill = true, borderChar = 0x80)

Prints a box of the given size starting at the cursor position, using border-drawing characters. Does not change cursor position.

widthCols integer

Width of the box in screen columns, including the border.

heightRows integer

Height of the box in screen rows, including the border.

fill boolean (default = true)

If true, will fill the interior of the box with spaces. Otherwise, the interior of the box won't be printed, only the borders.

borderChar integer (default = 0x80)

The first border-drawing character to use. Border-drawing characters are assumed to start at the given character code and must be arranged in this order: top-left, top-right, bottom-left, bottom-right, vertical bar, horizontal bar. The default font has these characters already in the right positions and order at char code 0x80.

qx.drawImage(x, y, image)

Draws an image (previously loaded with qxa.loadImage).

x integer

The x coordinate (in pixels) of the point on the screen where the top-left of the image will be drawn.

y integer

The y coordinate (in pixels) of the point on the screen where the top-left of the image will be drawn.

image Image

The image to draw.

qx.drawImageRect(x, y, image, srcX, srcY, width, height)

Draws a rectangular part of an image (previously loaded with qxa.loadImage).

x integer

The x coordinate (in pixels) of the point on the screen where the top-left of the image will be drawn.

y integer

The y coordinate (in pixels) of the point on the screen where the top-left of the image will be drawn.

image Image

The image to draw.

srcX integer

The x coordinate (in pixels) of the top-left of the rectangle to be drawn.

srcY integer

The y coordinate (in pixels) of the top-left of the rectangle to be drawn.

width integer

The width in pixels of the rectangle to be drawn.

height integer

The height in pixels of the rectangle to be drawn.

qx.drawRect(x, y, width, height)

Draws a rectangle (border only). The rectangle is drawn using the current foreground color.

qx.drawRect(x, y, width, height)

x integer

The x coordinate (in pixels) of the top-left corner of the rectangle.

y integer

The y coordinate (in pixels) of the top-left corner of the rectangle.

width integer

The width in pixels of the rectangle.

height integer

The height in pixels of the rectangle.

qx.fillRect(x, y, width, height)

Draws a filled rectangle. The rectangle is drawn and filled using the current foreground (not background!) color.

qx.fillRect(x, y, width, height)

x integer

The x coordinate (in pixels) of the top-left corner of the rectangle.

y integer

The y coordinate (in pixels) of the top-left corner of the rectangle.

width integer

The width in pixels of the rectangle.

height integer

The height in pixels of the rectangle.

qx.playSound(sfx, volume = 1, loop = false)

Plays a sound (previously loaded with qxa.playSound).

sfx Sound

The sound to play.

volume number (default = 1)

The volume to play the sound at.

loop boolean (default = false)

Plays the sound in a loop (returns to the start after finishing)

qx.spr(ch, x, y)

Draws a sprite on the screen.

ch

The character code of the sprite.

x

The X position at which to draw (top-left).

y

The Y position at which to draw (top-left).

qx.key(keyName)

Checks if the given key is currently pressed or not. This only works if running in a frame handler (see the qx.frame() function).

keyName string

The name of the key like "A", "B", "C", "ArrowUp", etc. This is just the Javascript key name as described here.

qx.keyp(keyName)

Checks if the given key was JUST pressed on this frame. This only works if running in a frame handler (see the frame() function). When a key is pressed, this function will return true for one frame, then will become false afterwards even if the key is held.

keyName string

The name of the key like "A", "B", "C", "ArrowUp", etc. This is just the Javascript key name as described here.

qx.redefineColors(colors)

Redefines the colors, that is, assigns new RGB values to each of the integer colors. This won't change the image on the screen, it only applies to newly drawn elements, so this can't be used for palette animation of something that was already drawn.

WARNING This is reasonably expensive, as all cached glyph images

must be regenerated. Don't call this often.

colors array

An array of RGB values with the new color definitions, in the same format as in the CONFIG object.

qx.setFont(fontId)

Sets the current font for text-based operations like qx.print(). Note that the font passed must have been previously loaded with qxa.loadFont(). For use as a text font, the font's character dimensions must be a multiple of CONFIG.CHR_WIDTH and CONFIG.CHR_HEIGHT, so for example if you specified that your default character size is 8x8, then fonts can be 8x8, 16x8, 16x16, 32x32, etc. But not 9x7 for example.

qx.setFont(fontId)

fontId string

(optional) The font to set. To reset to the default font, pass null, or omit the parameter.

qx.stopSound(sfx)

Stop a sound (previously loaded with qxa.playSound).

sfx Sound

The sound to stop playing.

qx.getContext()

Returns the raw canvas 2D context so you can draw anything you want to it. Note that this is the off-screen 2D context, so you are drawing to a hidden surface and your beautiful artwork will only be visible once the screen renders (either by calling qx.render() explicitly, or by calling a blocking function that causes an implicit render).

qx.getContext()

Return value

The raw HTML 2D canvas context for your enjoyment. If you put the context into an unusual state, please revert that state after you're done, otherwise QX82 might get confused.

qx.saveScreen()

Saves the contents of the screen into an ImageData object and returns it. You can later restore the screen's contents with qx.restoreScreen. An ImageData object is somewhat large, as it contains all the pixels on the screen. This is no longer 1985, so you can keep several of these in memory, but you shouldn't create them indiscriminately.

qx.saveScreen()

Return value

An ImageData object with the screen's contents.

qx.restoreScreen(screenData)

Restores the contents of the screen using an ImageData object obtained from a previous call to qx.saveScreen().

qx.restoreScreen(screenData)

screenData ImageData

The ImageData object obtained from a previous call to qx.saveScreen().

qx.key()

Waits until the user presses a key and returns it.

Return value

The name of the key that was pressed, like "A", "B", "ArrowUp", etc. This is just the Javascript key name as described here.

qx.readLine(initString = "", maxLen = -1, maxWidth = -1)

Waits until the user inputs a line of text, then returns it.

initString string (default = "")

The initial string presented for the user to edit.

maxLen integer (default -1)

The maximum length of the string the user can type. If this is -1, this means there is no limit.

maxWidth integer (default = -1)

The maximum width of the input line, in characters. When the user types more, the text will wrap to the next line. If this is -1, this means it won't wrap at all.

qx.menu(choices, options = {})

Shows a menu of choices and waits for the user to pick an option.

choices array

An array of choices, for example ["Foo", "Bar", "Qux"]

options Object (default = {})

Additional options, as a dictionary. These are the available options:

  • title: the title to show on the window
  • prompt: the prompt to show. Can be multiple lines (use \n)
  • selFgColor: foreground color of selected item
  • selBgColor: background color of selected item
  • bgChar: character to use for the background of the window
  • borderChar: border character to use for the window
  • centerH: if true, center the menu horizontally on the screen
  • centerV: if true, center the menu vertically on the screen
  • center: if true, equivalent to centerH and centerV
  • padding: padding between window borders and contents, default 1.
  • selIndex: initially selected index, default 0.
  • cancelable: if true, the user can cancel the menu with ESC, in which case the return value will be -1.

Return value

Returns the index of the item selected by the user, or -1 if the menu was cancelable and the user cancelled it.

qx.dialog(prompt, choices = ["OK"])

Displays a dialog with the given prompt and choices. This is a syntactical convenience to menu().

prompt string

The text to show like "Error reticulating splines."

choices array (default = ["OK"])

The choices to present to the user. If omitted, this will just show "OK". You can use for example ["No","Yes"] if you want the user to be able to choose one of those options to confirm something.

qx.wait(seconds)

Waits for a given number of seconds.

seconds number

How long to wait for, in seconds.

qx.typewriter(text, delay = 0.05)

Shows text slowly, character by character, as in a typewriter.

text string

The text to print.

delay number (default = 0.05)

How long to wait between characters, in seconds. Spaces don't have delay.

qx.loadImage(url)

Loads an image from the given URL.

url string

The URL from which to load the image. This can be a relative path if the image is located on the same site. Can be a PNG or a JPG.

Return value

An Image object that you can use with qx.drawImage().

qx.loadSound(url)

Loads a sound file from the given URL.

url string

The URL from which to load the sound. This can be a relative path if the image is located on the same site. Can be a WAV or MP3.

Return value

A Sound object that you can use with qx.playSound().

qx.loadFont(fontImageFile)

Loads a font for later use in drawing text.

fontImageFile string

The URL to an image file containing the font. This image file should be a grid of the font's character laid out in a 16x16 grid. The character width and height will be deduced from the image size by dividing the width and height by 16, respectively. Therefore, the image's dimensions must both be a multiple of 16.

Return value

A font ID that you can later use in functions that take a font like qx.setFont() and qx.drawText().

qx.fatal(error)

Shows a fatal error and throws an exception.

error string

The error to show.

qx.assert(cond, msg)

Asserts that the given condition is true, else shows a fatal error.

cond boolean

The condition that you fervently hope will be true.

msg string

The error message to show if the condition is false.

Return value

For convenience, this function returns the 'cond' parameter.

qx.assertDebug(cond, msg)

Same as qut.assert() but only asserts if CONFIG.DEBUG is true.

cond boolean

The condition that you fervently hope will be true.

msg string

The error message to show if the condition is false.

qx.assertEquals(expected, actual, what)

Asserts that two values are equal.

expected any

What you expect the value to be.

actual any

What the value actually is.

what string

A description of what the value is, like "dragon's position", "magician's spell state" or something like that.

qx.checkType(varName, varValue, varType)

Checks the type of something and throws an exception if it's in the incorrect type. You can also use the convenience functions qut.checkNumber(), qut.checkString() etc as those are more practical to use.

varName string

The name of the variable, like "levelName" or something.

varValue any

The value of the variable.

varType

The expected type of the variable like "string".

qx.checkNumber(varName, varValue, optMin, optMax)

Checks that something you expect to be a number actually is a number, and throws an exception otherwise. This also considers it an error if the value is NaN.

varName string

The name of the variable.

varValue any

The value of the variable.

optMin integer (optional)

If present, this is the minimum acceptable value for the variable.

optMax integer (optional)

If present, this is the maximum acceptable value for the variable.

qx.checkString(varName, varValue)

Checks that a variable is a string, throwing an exception otherwise.

varName string

The name of the variable.

varValue any

The value of the variable.

qx.checkBoolean(varName, varValue)

Checks that a variable is a boolean, throwing an exception otherwise.

varName string

The name of the variable.

varValue any

The value of the variable.

qx.checkFunction(varName, varValue)

Checks that a variable is a function, throwing an exception otherwise.

varName string

The name of the variable.

varValue any

The value of the variable.

qx.checkObject(varName, varValue)

Checks that a variable is an object, throwing an exception otherwise. Also throws an error if the value is null.

varName string

The name of the variable.

varValue any

The value of the variable.

qx.checkInstanceOf(varName, varValue, expectedClass)

Checks that a variable is an instance of a given class, throwing an exception otherwise.

varName string

The name of the variable.

varValue any

The value of the variable.

expectedClass type

The expected class. This is the actual class, not a string with the class name.

qx.checkArray(varName, varValue)

Checks that a variable is an array, throwing an exception otherwise.

varName string

The name of the variable.

varValue any

The value of the variable.

qx.log(msg)

Prints a log to the Javascript console if CONFIG.DEBUG is true.

msg

The message to print.

qx.warn(msg)

Prints a warning to the Javascript console.

msg

The message to print.

qx.error(msg)

Prints an error to the Javascript console.

msg

The message to print.

qx.clamp(x, lo, hi)

Clamps a number, ensuring it's between a minimum and a maximum.

x number

The number to clamp.

lo number

The minimum.

hi number

The maximum.

Return value

The clamped number.

qx.randomInt(lowInclusive, highInclusive)

Returns a random integer in the given closed interval.

lowInclusive integer

The minimum (inclusive).

highInclusive integer

The maximum (inclusive).

qx.randomPick(array)

Returns a randomly picked element of the given array.

array array

The array to pick from.

Return value

A randomly picked element of the given array, or null if the array is empty.

qx.shuffleArray(array)

Shuffles an array, that is, randomly reorder the elements. Does not modify the original array. Returns the shuffled array.

array array

The array to shuffle.

Return value

The shuffled array.

qx.dist2d(x0, y0, x1, y1)

Calculates a 2D distance between points (x0, y0) and (x1, y1).

qx.intersectIntervals(as, ae, bs, be, result = null)

Calculates the intersection between two integer number intervals [as, ae] and [bs, be], both endpoints are inclusive.

as number

The start of the first interval, inclusive.

ae number

The end of the first interval, inclusive.

bs number

The start of the second interval, inclusive.

be number

The end of the second interval, inclusive.

result Object (default = null)

If provided, this is used to return the intersection (see below).

Return value

If there is an intersection, returns true. If there is no intersection (the segments don't overlap), returns false. If this returns true and a 'result' object was provided, then result.start is set to the interval's start, and result.end is set to the interval's end.

qx.intersectRects(r1, r2, dx1 = 0, dy1 = 0, dx2 = 0, dy2 = 0, result = null)

Calculates the intersection of two rectangles.

r1 Rectangle

A rectangle, an object with {x,y,w,h}.

r2 Rectangle

The other rectangle, an object with {x,y,w,h}.

dx1 number (default = 0)

The delta X to add to the first rectangle for the purposes of the calculation.

dy1 number (default = 0)

The delta Y to add to the first rectangle for the purposes of the calculation.

dx2 number (default = 0)

The delta X to add to the second rectangle for the purposes of the calculation.

dy2 number (default = 0)

The delta Y to add to the second rectangle for the purposes of the calculation.

result object (default = null)

If provided, this is used to return the intersection information (see below).

Return value

Returns true if there is a non-empty intersection, false if there isn't. If this returns true and the 'result' object was provided, then sets result.x, result.y, result.w, result.h to represent the intersection rectangle.