[RFC] External Windows for "OS"es

This is a simple draft RFC (Request for Comments) for allowing apps that are running under an "OS" (shell) to open new, independent windows
outside the primary program's screen. This draft does not include any fallback for if your shell hasn't implemented the protocol, as that would be unique
to the toolkit your program is using for showing the UI.

The primary goals of this protocol are:

• Self-Contained
• Toolkit/Shell agnostic
• Ease of use

This Spec calls for the addition of two functions to the term API provided by your shell or "OS":

• term.newWindow(title, width, height) – Returns: id, term
• term.activeWindow() – Returns the active window ID, if it's the app is inactive, this should return nil (Though, ideally your app would not be getting events if this is the case.)

The term-capable result returned by term.newWindow() adds the following additional functions.

• setTitle(title) – Changes the window's title.
• setSize(size) – Changes the window's size
• show() – Shows the window from a hidden state.
• hide() – Hides a window from a shown state.
• getFlags() – Returns a table of string flags.
• setFlags(table) – Sets the flags currently applied, as a table of string values.

Events would be passed back to the main window's event pump with a window_ prefix. Examples are:

• window_flag_added id, flag – Fired when a flag is added to the given window.
• window_flag_removed id, flag – Fired when a flag is removed from the given window.
• window_resize id – Fired when a window is resized, given the window ID that was resized.

Flags

Flags are a simple list of string values, which should be one of the following.

• Capabilities
• minimisable
• resizable
• closable
• modal – Means the main window may not get focused unless this window is dismissed.
• State (Read-Only)
• minimised
• maximised
• focused

Additional flags may be defined with a prefix, for instance, for foo-shell you could add foo-shell.bacon-cheese which changes the colours of the window decorations.

---

Additional Notes:

The returned id can take any form, however it should be assumed to be unique on an at-least per-program basis. For the purposes of term.activeWindow() – the normal terminal window that all apps have is defined as 'main-window'.

---

Changes

• 2014-02-05
• Add modal flag, makes the window jump to the top when it's parent window is selected.
• 2014-01-19
• Removal of window_char, window_key, etc.
• Addition of term.activeWindow()
• Additional details on standard flags.
• 2014-01-15
• Initial addition of this section.
• Rename window_resized to window_resize in the spirit of LyqydOS

---

I'm looking for feedback on any part of this draft, as that is the reason I'm publishing it.

With the additions coming up in the next version of ComputerCraft including built-in windowing, it will probably be prudent to wait and see how that works before going too much further down these sorts of roads. I think it would be useful to have a way to maximize or fullscreen a window such that it can be restored to the previous size. It'd be easier to have the windowing system remember this rather than trying to keep track of it yourself, especially if window size changes can be initiated external to the program.

I'm not really a fan of the different event names, but I don't have a better idea as to how to handle them. Perhaps those events would only go to the "active" window, and the program would have a way of determining which of its windows was the "active" one at any given point in time.

We discussed this a short while back here http://www.computercraft.info/forums2/index.php?/topic/16136-computercraft-standards/.

As Lyqyd said, however, there's a native windowing API coming.

The window API that Dan is adding in 1.6 is just a way to cut out sub-sections of a screen from a terminal target, is my understanding. I could be wrong about this, but that's the impression I'm under.

I'll go about adding and updating the main post with some additional ideas momentarily, however, I'm also interested in what all kind of data people would want.

EDIT with some additional comments

oeed – the problem with that post is that it's not putting forth any actual standards, it's merely calling for one. in this post, I'm putting forth a proposed standard, that at least I intend to support in my shell.

Lyqyd – Added a "flag" system which includes maximised and minimised as flags, which I think should also be general-purpose enough for other things that we can't see coming from the future of shells for ComputerCraft.

As always, comments are welcome. :)/>

Hmmm, rather than just having normal events with "window_" prepended, why not make a single event called "window_event" which returns the id and a table, which when unpacked will return the full event i. e. "mouse_click", button, x, y

For reference, LyqydOS throws window_resize events on window size changes, and ComputerCraft already uses monitor_resize for monitor size changes.

Lyqyd, on 15 January 2014 - 05:25 PM said:

For reference, LyqydOS throws window_resize events on window size changes, and ComputerCraft already uses monitor_resize for monitor size changes.

Indeed, that's what I was basing the resize event on. I figure one of a few things could change with that.

• There could be a standard "main-window" id
• the RFC's window_resize could be renamed.
• Apps could check the window_resize event's second parameter for nil.

EDIT Clarify something.

Hmmm, closeable, resizeable, etc doesn't really belong there Imo. Perhaps just an win.isCloseable() method or something?

Symmetryc, on 15 January 2014 - 05:59 PM said:

Hmmm, closeable, resizeable, etc doesn't really belong there Imo. Perhaps just an win.isCloseable() method or something?

These are meant to be flags for the shell, not flags for the program. I'd rather avoid callback systems, as much as possible, as I feel that's not really very ComputerCraft-y. Another thing I'm considering is making the flags be a attribute system instead, so you can do things like set foo-shell.min-size or similar.

New Update!

I've updated the original post with some additions, as well as some removals. Namely, the window_char, window_key… etc events are removed, instead favouring a term.activeWindow() call. Lyqyd suggested this, and I also found it's rather more intiutive for a GUI toolkit's perspective. Also, I've added a few more flags that are possible.

Comments remain welcome, so dig in!