mirror of
https://github.com/LDDestroier/CC/
synced 2024-11-14 22:04:53 +00:00
114 lines
6.1 KiB
Markdown
114 lines
6.1 KiB
Markdown
# 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`.
|
|
|
|
```lua
|
|
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.
|
|
|
|
```lson
|
|
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.
|
|
```lson
|
|
-- 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.
|