From 771bfcee077dba206b8a6c9ddc60c69e331fbb16 Mon Sep 17 00:00:00 2001 From: Rui Guo Date: Sun, 23 Aug 2009 01:02:41 +0800 Subject: [PATCH] Fill in design document. --- src/drafts/scripting | 221 +++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 172 insertions(+), 49 deletions(-) diff --git a/src/drafts/scripting b/src/drafts/scripting index bc9625a..cfeeee1 100644 --- a/src/drafts/scripting +++ b/src/drafts/scripting @@ -10,6 +10,11 @@ Screen: 3. The hook on interesting events in Screen. 4. The ability to do run asynchronously to Screen itself. +[Note: asynchronous scripting support is not supported yet, due to the fact +that screen is highly thread-unsafe. One possible solution is to implement an +implicit locking through the asynchronous IO mechanism (similar to the one +used by attacher <=> back end) that is currently in use.] + A. Query & control interface Currently, screen provides a way to control a running session through the -X @@ -77,9 +82,10 @@ III. The scripting interface There are several kinds of objects that may be interested to scripts. +========== A. Display -Stands for a user interface. +Stands for a user view that presented by an attacher. ---------- Properties: @@ -128,32 +134,36 @@ layout: idle_timeout: mode: write only. type: Int. - description: Set the idle timeout for this display, and actives the idle - event. It differs from the idle command, which uses a global - value for all attached displays. - + description: Set the idle timeout of the next activation for this display, + and actives the idle event. It differs from the idle command, + which uses a global value for all attached displays. ---------- Methods: ---------- -get_canvases: Get a list of canvases on this display. +table get_canvases(); + Returns a list/table of canvases on this display. -top_canvas: Get the top (or top-left) canvas on the display. +Canvas top_canvas(); + Returns the top (or top-left) canvas on the display. -bottom_canvas: Get the bottom canvas on the display. +Canvas bottom_canvas(); + Returns the bottom canvas on the display. ---------- Events: ---------- -on_idle: (Display) - Triggerred whenever the idle timeout is reached. The handler will be +onidle: (Display) + Triggered whenever the idle timeout is reached. The handler will be called with a reference to the idling display. If the handler returns - non-zero, the internal idle processing will be overriden. Please note + non-zero, the internal idle processing will be overridden. Please note that the The idle timeout is not reseted on such a situation, remember to - setup idle timout in the handler if multiple activation is needed.. + setup idle timeout in the handler if multiple activation is needed.. + +========= B. Window Stands for the sub-terminal(PTY, telnet etc) that processes runs on. @@ -213,13 +223,23 @@ void set_monitor_status(bool activity, int status); Set the status of activity/silence monitor. The number of status for the silence monitor is the seconds of threshold. +char ** get_lines(); + Return the content on the window as an array of string. Each string represent + a single line. + +char ** get_history(); + Return the history buffer of the window as an array of string. Each string + represent a single line. + void stuff(string buf); - put the string into the input buffer. + put the string into the input buffer. This can be used to interactive with + the application within the window void activate(); Show the window in current focused canvas. int waitfor(string pattern); + NOT IMPLEMENTED YET Waiting for a specified output pattern. The pattern is limited to plain text. NOTICE: This is an asynchronous method call and can only be called in asynchronous mode. @@ -231,7 +251,7 @@ hook([obj], event, handler, [priv]) Events ---------- -on_activity (display, window) +onactivity (display, window) triggered when the activity monitor got fired. This will be triggered for each display on which the window is hidden. Return non-zero in the handler will override the default activity message. @@ -241,31 +261,37 @@ onsilent (display, window) each display on which the window is hidden. Return non-zero in the handler will override the default silent message. -on_focus (display, window) +onfocus (display, window) Triggered when the window gets input focus on a display. Differs from the global event forechange, it's associated with a specific window. -on_leave (display, window) +onleave (display, window) Triggered after the window lost input focus on a display. Differs from the global event forechange, it's associated with a specific window. -on_show (display, window) +onshow (display, window) Triggered after the first view of this window show up on a display. Differs from on_focus when there are many regions on a display. -on_hide (display, window) +onhide (display, window) Triggered after the last view of this window disappeared from a display. Differs from on_leave when there are many regions on a display. -on_close (window) +onclose (window) Triggered before the window close. Can be used to free any references to the window. -can_resize -on_resize +onresize (window) + Triggered after the window is resized. + +onoutput (window, string) + Triggered when the window has new output. This output is not cooked to on + line basis. Please be careful when using this hook. The system speed can be + significantly slowed down due to ill use of this. +======= C. User -------- @@ -293,15 +319,47 @@ umask: type: String. description: The access for the window created by this user to other users. The result will be in a form of 'rwx'. + NOTE: NOT IMPLEMENTED YET. + +========= +D. Canvas -D. Display +-------- +Property: +-------- +next: + mode: read only + type: Canvas + description: The next canvas on display. ----------- -Methods: ----------- +xoff: +yoff: + mode: read only + type: int + description: The x/y offset of canvas on the display. + +xe/ye: + mode: read only + description: The bottom right coordinate of the canvas. + +window: + mode: read write + description: The window currently showing on the canvas. + Can be used to select a new window to show. + The new window can also be NULL, so that the + canvas shows nothing. + +display: + mode: read only + description: The display that this canvas belongs to. + +caption: + mode: write only + description: The caption string for this canvas. The string set to caption + can contain screen escapes and will be expended before show + up on the display. -E. Canvas ---------- Methods: @@ -310,23 +368,79 @@ Methods: select() Get input focus for this canvas. -showwin(win) - Show window 'win' on this canvas. +split(horizontal) + Split the canvas into two part. If the horizontal flag is not set, the split + is done in vertical. + +========= +E. Layout + + The layout of canvases on a display. Can be used to emulate the tab feature + of VIM. + +---------- +Properties: +---------- + +title + mode: read write + type: string + description: The title of a layout. + + +number + mode: read write + type: int + description: The number of the layout in the layout list. + +autosave + mode: read write + type: int + description: Specify whether the layout will be automatically updated on + switch. + +-------- +Methods: +-------- + +select(); + Use this layout on current display. Does nothing whenever the current display + is NULL. +========= F. Screen This is a pseudo object standing for the whole screen object. All other - objects can be obtained starting from this one. + objects can be obtained starting from this one. Since this is not a real + object, there's no property for it. -------- Methods: -------- -windows -displays -command -windowbyname +Table windows(); + Returns a list/table of windows in screen. The table/list is not necessary + indexed by the window number. But the order of the windows should keep the + same. -hook([obj], event, handler, [priv]) +Table displays(); + Returns a list/table of attached displays in screen. + +Table layouts(); + Returns a list/table of defined layouts. + +command(string); + Invoke a screen command specified as a string. + +Display display(); + The display that currently has internal events happening. Can be null. + +append_msg(string msg); + Show a message on the status/caption line. + +schedule(int timeout, handler); + Schedule an handler to be triggered in 'timeout' seconds later. + +hook([obj], event, handler, [priv]); or obj:hook(event, handler,[priv]) listen to the event notification. The event is associated with the specified @@ -337,7 +451,7 @@ or obj:hook(event, handler,[priv]) This method returns a ticket (or handle) of the registration. This is used to unregister the notification, using the syntax: ticket:unhook(). -input(prompt, callback, [prefill]) +input(prompt, callback, [prefill]); get input from user asynchronously with a callback. This call returns immediately, with a input line poped up. The input prompt is set to the first parameter and the buffer can be pre-filled with the third @@ -346,19 +460,35 @@ input(prompt, callback, [prefill]) The input happens at the active canvas of the current display. If there is no current display input line appears in all canvas that shows the current - layer. FIXME!!! + layer. -------- Events: -------- -cmdexecuted +cmdexecuted(command, args) + An SCREEN command is executed with a list of arguments (args). This has + nothing to do with the shell command in user window. + detached (display, is_remote) -For detach-events, it's not enough to just listen to 'cmdexecuted' -command, since this command is not used for remote detaches. So -scripts looking to do something on a detach event need to hook to -this event, instead of hooking to 'cmdexecuted' event and looking -for 'detach' command. + For detach-events, it's not enough to just listen to 'cmdexecuted' + command, since this command is not used for remote detaches. So + scripts looking to do something on a detach event need to hook to + this event, instead of hooking to 'cmdexecuted' event and looking + for 'detach' command. + +forechanged(display, window) + Triggered when a new window has been set on the display. + +onattach(display) + Triggered after a new display is attached. + +oncreatewindow(window) + Triggered after a new window is created. Can be used to hook other events on + that window. + +processcaption(canvas) + Triggered whenever the caption for the canvas needs to be updated. =================== The Implementation @@ -369,10 +499,3 @@ language bindings at the same time, with each registered at the compiling time and loaded (initialized) dynamically at runtime. It's an bridge between scripts and screen itself. ---------------- -Binding related. ---------------- - ---------------- -Binding independent ---------------- -- 2.11.4.GIT