OC-KittenOS/repository/docs/us-evrst

-- x.neo.pub.window @ sys-everest --

This API is the reference definition
 of how the windowing system works in
 KittenOS NEO.

Implementing this API, by definition,
 makes your process the controller of
 windowing on the system, which means
 you control Icecap security dialogs.

...and that's why r.neo.* access is
 heavily restricted unless the user
 uses the Advanced Settings panel.

The API gives you a function:
 (w, h, title) -> window

This function creates a window.

Window fields:

 id: Window ID.
 setSize(w, h): Changes the size of
  the window, and sends the line
  events (even if the size doesn't
  change)
 getDepth(): Returns the depth of the
  screen the window is on.
 span(x, y, text, bg, fg): Draws a
  span onto the screen.
  This function will error if the
   Everest instance is dead.
  (Others won't.)
 recommendPalette(pal): If the window
  is focused, sets the first #pal
  palette entries to the given RGB
  values.
  This is meant only as a hint to
  Everest, and may be ignored.
  Returns the amount of entries set.
  NOTE: Up to 4 colours may be used
   by the implementation as "base"
   colours, and thus cannot be set as
   past of a palette to prevent any
   use of the application-controlled
   indexes in the major UI.
  This is because the palette-setting
   interface leads to graphics issues
   with multi-tasking, even in those
   programs not using the interface,
   so a set of reliable colours is
   required to keep a multitasking
   system usable in these edge cases.

 close(): Close the window.

Events:

 api, id, "key", ka, kc, down
 api, id, "touch"/"drag"/"drop",
  lx, ly, ix, iy, button
 api, id, "scroll",
  lx, ly, ix, iy, amount
 api, id, "clipboard", text
 api, id, "close"
 api, id, "focus", hasFocus
 api, id, "line", lineIndex

Palette advice for artists:
 *Use 16-colour images*, and ensure
 the viewer software uses the palette
 functions. Always use a 2x4 grid to
 check cell colour limits. If your
 palette contains any reserved
 colour, make it last in the palette,
 so that they are not wasted if not
 used.

-- This is released into
 the public domain.
-- No warranty is provided,
 implied or otherwise.