mirror of https://github.com/20kdc/OC-KittenOS.git
236 lines
6.1 KiB
Plaintext
236 lines
6.1 KiB
Plaintext
The "neoux" (aka NeoUX) library is a
|
|
UI framework for KittenOS NEO, meant
|
|
to provide a consistent set of
|
|
controls and a consistent way to
|
|
navigate the UI in any given case.
|
|
|
|
Thus, it's not used by text editing
|
|
programs such as Neolithic.
|
|
|
|
To get ahold of NeoUX in your app,
|
|
use code similar to:
|
|
|
|
local event, neoux
|
|
event = require("event")(neo)
|
|
neoux = require("neoux")(event, neo)
|
|
|
|
The neo table is used for retrieving
|
|
the required accesses for APIs.
|
|
|
|
The NeoUX API is divided into three
|
|
parts - the part that connects it to
|
|
Everest & utility functions, the UI
|
|
framework's "tcwindow" root, and the
|
|
basic set of controls.
|
|
|
|
The most reliable reference on the
|
|
API a control implements is given
|
|
at the top of libs/neoux.lua, and
|
|
for updatability reasons will not
|
|
be repeated here, except with the
|
|
note that "xI"/"yI" is within-char
|
|
position from 0 to 1.
|
|
|
|
Main functions:
|
|
|
|
fileDialog(mode[, callback]):
|
|
Creates a file dialog, returning a
|
|
file wrapper (see ul-fwrap) on
|
|
success, or nil on failure.
|
|
If a callback is given, then nil is
|
|
always returned immediately, and
|
|
the callback is called when the
|
|
dialog has shown.
|
|
mode is the mode used for the file,
|
|
so see ul-fwrap for values.
|
|
|
|
neoux.create(w, h, title, callback):
|
|
Creates a window,
|
|
including a NeoUX window wrapper.
|
|
NOTE: The width can never be smaller
|
|
than 8, under any circumstances.
|
|
Trying to will cause the width to be
|
|
forced to 8.
|
|
The parameter list is compatible
|
|
with the window "reset" function,
|
|
and it is intended that you use
|
|
this to simplify your code where
|
|
possible.
|
|
The callback is of the kind:
|
|
function(window, evt, ...)
|
|
Where window is the window wrapper,
|
|
and everything else is the Everest
|
|
event with API and Window ID gone.
|
|
It is recommended that you use this
|
|
in the form shown:
|
|
|
|
local stopping = false
|
|
local function genWindow()
|
|
return 8, 8, "mainwin",
|
|
neoux.tcwindow(8, 8, {
|
|
-- you can have as many
|
|
-- controls as you want,
|
|
-- but don't be deliberately
|
|
-- wasteful
|
|
neoux.tcrawview(1, 1, {
|
|
"Each day",
|
|
"shall en",
|
|
"d as it ",
|
|
"begins, ",
|
|
"and thou",
|
|
"gh you'r",
|
|
"e far aw",
|
|
"ay from "
|
|
})
|
|
}, function (w)
|
|
w.close()
|
|
stopping = true
|
|
end, 0xFFFFFF, 0)
|
|
end
|
|
local w = neoux.create(genWindow())
|
|
while not stopping do
|
|
event.pull()
|
|
end
|
|
|
|
pad: See ul-fmttx, but loaded on
|
|
demand and unloaded after use.
|
|
|
|
fmtText: See ul-fmttx, but loaded on
|
|
demand and unloaded after use.
|
|
|
|
neoux.tcwindow(w, h, controls,
|
|
closing, bg, fg[, selIndex], [kf]):
|
|
Creates a neoux.create-compatible
|
|
callback for a NeoUX GUI framework
|
|
window.
|
|
W/H is the width/height of the
|
|
window, for background drawing.
|
|
controls is an ipairsable table
|
|
containing UI framework controls.
|
|
(The definition of a UI framework
|
|
control is noted at the top of the
|
|
neoux.lua library file, so that it
|
|
does not become out of date.)
|
|
closing is a function (window) used
|
|
when a close request occurs.
|
|
bg/fg sets the application's colour
|
|
scheme for controls that care.
|
|
selIndex, if provided, is the index
|
|
of the control that should start
|
|
out selected.
|
|
kf, if provided, is a table that
|
|
is used for extended information:
|
|
ctrl: True when left Ctrl key
|
|
is down, nil or false when it's
|
|
up.
|
|
rctrl: True when right Ctrl key
|
|
is down, nil or false when it's
|
|
up.
|
|
shift: True when left Shift key
|
|
is down, nil or false when it's
|
|
up.
|
|
rshift: True when right Shift key
|
|
is down, nil or false when it's
|
|
up.
|
|
|
|
startDialog(fmt, title, wait):
|
|
Shows a text dialog.
|
|
fmt is some un-safeTextFormat'd
|
|
text for the dialog.
|
|
title can be nil, or more un-STF'd
|
|
text for the dialog title.
|
|
wait can be nil/false to not wait,
|
|
and otherwise.
|
|
|
|
UI framework window API (TODO):
|
|
reset(...): For parameters, see the
|
|
neoux.create function. Resets the
|
|
window without closing/reopening,
|
|
essentially reusing the window yet
|
|
changing its contents. Choose over
|
|
destroying and then creating a
|
|
window - it acts better with
|
|
shutdown, for example.
|
|
Implicitly performs a setSize,
|
|
so a refresh will occur.
|
|
|
|
getSize(): Returns width, height.
|
|
|
|
setSize(w, h): Changes the width and
|
|
height. Like in the API this wraps,
|
|
this is guaranteed to refresh all
|
|
the lines of your window.
|
|
NOTE: The width can never be smaller
|
|
than 8, under any circumstances.
|
|
Trying to will cause the width to be
|
|
forced to 8.
|
|
|
|
getDepth(...): Read the note
|
|
in us-evrst for details.
|
|
span(...): Read the relevant note in
|
|
us-evrst for details.
|
|
recommendPalette(...): Read the note
|
|
in us-evrst for details.
|
|
|
|
close(): Closes the window, freeing
|
|
both Everest and NeoUX resources
|
|
associated with it.
|
|
|
|
UI framework controls (TODO):
|
|
|
|
(X/Y positions are 1-based, as usual
|
|
in OpenComputers)
|
|
|
|
neoux.tcrawview(x, y, lines)
|
|
Creates a UI element that displays
|
|
some raw lines, in the format from
|
|
the fmtText function.
|
|
This format is essentially raw span
|
|
text, pre-STF'd, immediately
|
|
ready to submit to Everest.
|
|
|
|
neoux.tchdivider(x, y, w)
|
|
Creates a UI element that displays
|
|
a 1-high horizontal divider.
|
|
The used characters are a detail of
|
|
the implementation.
|
|
|
|
neoux.tcvdivider(x, y, h)
|
|
Creates a UI element that displays
|
|
a 1-wide vertical divider.
|
|
The used characters are a detail of
|
|
the implementation.
|
|
|
|
neoux.tcbutton(x, y, text, callback)
|
|
Creates a UI element for a button.
|
|
The text is not run through
|
|
safeTextFormat automatically, so
|
|
you must do it yourself if wide
|
|
characters are expected.
|
|
The width is thus always equal to:
|
|
unicode.len(text) + 2
|
|
The height is always 1.
|
|
The callback is a function (window)
|
|
where window is the NeoUX wrapped
|
|
window.
|
|
|
|
neoux.tcfield(x, y, w, textprop)
|
|
Creates a UI element for a text
|
|
field.
|
|
textprop is a function, which
|
|
can be called in two ways:
|
|
textprop(newval) -> nil
|
|
Writes a string.
|
|
textprop() -> val
|
|
Reads a string. The string must
|
|
NOT be safeTextFormatted, as this
|
|
is done internally (in contrast to
|
|
tcbutton) only for display, as the
|
|
textfield has to edit the string.
|
|
|
|
-- This is released into
|
|
the public domain.
|
|
-- No warranty is provided,
|
|
implied or otherwise.
|
|
|