Fill in design document.screen-scripting-soc
authorRui Guo <firemeteor.guo@gmail.com>
Sat, 22 Aug 2009 17:02:41 +0000 (23 01:02 +0800)
committerRui Guo <firemeteor.guo@gmail.com>
Sat, 22 Aug 2009 17:02:41 +0000 (23 01:02 +0800)
src/drafts/scripting

index bc9625a..cfeeee1 100644 (file)
@@ -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
----------------