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.

Notes on UI design:

The UI design is heavily monochrome.

 core (neoux supported):
"[textheretext]": This means a text
 field. It should preferably right-
  align text if too much is inside,
  ensuring that what is being written
  can be read.
 The enter button should do nothing,
  and the backspace/delete buttons
  should both remove the last Unicode
  character.
"<texthere>": This means a button.
 Space or enter should activate it.

 additional:
"◢": Resize widget. Drag-dropping
      should cause a resize. This
      need not occur until the drop
      is completed.
     Standardized by Izaya.
     The non-GUI way to do this is
      for ctrl-arrows to resize
      the window.

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