ldd-CC/windont/README.md

Windon't

A replacement for the Window API, created by someone who can't think of better names

To load Windon't, simply use require or dofile.

local windont = dofile("path/to/windont.lua")

Windon't contains two functions: one to make a new window object, and another to render them. Beyond that, Windon't stores various default values that are used when creating new windows.

windont.default = {
	baseTerm = term.current(),	-- default base terminal for all windows
	textColor = "0",		-- default text color (what " " corresponds to in term.blit's second argument)
	backColor = "f",		-- default background color (what " " corresponds to in term.blit's third argument)
	blink = true,			-- default getCursorBlink
	visible = true,			-- default whether or not new windows are visible
	alwaysRender = true,		-- if true, new windows will always render if they are written to
}

windont.newWindow

windont.newWindow(number x, number y, number width, number height, table miscData)

Creates a new window located at (x, y), with the specified width and height. By default, the base terminal used will be windont.default.baseTerm, which is normally set to term.current(). "Windon'ts" naturally can be used with term.redirect, but they also come with a meta value which contains all the information of the object, including cursor X and Y, width and height, the whole framebuffer, the cursor blinking, and more.

Windon't windows behave very similarly to regular ol' Window API windows, with a few differences. For one, Windon't windows support transparency when drawing over one another. Secondly, Windon'ts support the use of individual transformation functions for characters, text colors, background colors, and the whole meta function. Transformation functions are, if given, called every time the window is rendered. More on that later.

Additional values can be given to the newly created window through the miscData argument, including the base terminal and visibility. Here are all the values that you can set by default with miscData:

buffer			
renderBuddies		-- table, a list of other windon't objects that will render beneath this one every time this redraws
baseTerm		-- window, the terminal that this windon't object will render onto
isColor

charTransformation	-- function, ran on every X and Y on the window's base temrinal, I'll explain in a bit
textTransformation	-- function, in a bit
backTransformation	-- function, in a bit
metaTransformation	-- function, takes in the 'meta' value of a windon't object so it can be modified

cursorX			-- number, starting cursor X
cursorY			-- number, starting cursor Y

textColor		-- string, starting text color ("0" through "f", or "-"" for transparency)
backColor		-- string, starting background color (same range as textColor)

blink			-- boolean, cursor blinking
alwaysRender		-- boolean, if true, then all term.write or term.blit calls will immediately render to the base temrinal
visible			-- boolean, if false, then the window just like, won't render, man

The normal transformation function (transformation, not metaTransformation) are called on every (x, y) position on the screen per window, and each one takes in six arguments: 1. X position on the screen relative to the window's X position 2. Y position on the screen relative to the window's Y position 3. Character on the window's (X, Y) (if outside the buffer, is nil) 4. Text color on the window's (X, Y) (if outside the buffer, is nil) 5. Background color on the window's (X, Y) (if outside the buffer, is nil) 6. meta value of the window and return the following information: 1. Table containing {new character X position, new character Y position, new character} (all optional values) 2. Table containing {new text X position, new text Y position, new text color} (all optional values) 3. Table containing {new background X position, new background Y position, new background color} (all optional values)

For instance, it could take in:

win.transformation(2, 6, "r", "2", "f", win.meta)`

... and return:

{2, 6, "R"}, {2, 6, "3"}, {"2, 6, "-"}

...with a light blue "R" with a transparent background being placed at (2, 6) to replace the lowercase "r".

metaTransformation is different in that it takes one value, being the window's meta value, and returns nothing. The metaTransformation function just modifies the meta value and that's it.

All transformation functions (besides metaTransformation) will not change the contents of the buffer, only alter how they are drawn to the screen.

windont.render

windont.render(table options, window_1, window_2, ...)

Renders one or more Windon't objects onto their base terminals. If two or more windows share a base terminal, they will render layered atop each other from top to bottom, meaning that window_1 will draw on top of window_2. If windows contain any transparent regions (designated by the color "-" usable with term.blit), then the next window down the list will peek through. Transparency is applied individually for text colors and background colors. If you have a window with a solid BG color but a transparent text color, then the background color of the underlying window will now be the text color of the above window, kinda like a text-shaped stencil.

The argument options is a table, and comes before any windows.

-- Potential options:
local options = {
	onlyX1 = 3,
	onlyX2 = 25,
	onlyY = 7,
	force = false,
	baseTerm = term.current()
}

The number values onlyX1, onlyX2, and onlyY limit where windont.render() draws on the screen. Specifically, it limits rendering to: (onlyX1 >= x <= onlyX2, y == onlyY). The boolean force option disables the optimization where windont.render() would compare the buffer it is about to draw to the last buffer it drew to reduce blit calls. The terminal baseTerm option basically ensures that every window being passed through windont.render() will draw on the specified terminal.

If a window's meta has alwaysRender = true, then windont.render is called with that window, as well as the positions of the write/blit call.