emacs-diffs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Emacs-diffs] emacs-25 4ffec91: Document automatic adjustment of process


From: Eli Zaretskii
Subject: [Emacs-diffs] emacs-25 4ffec91: Document automatic adjustment of process' logical window dimensions
Date: Sat, 7 May 2016 09:17:39 +0000 (UTC)

branch: emacs-25
commit 4ffec91aa1fe668609f460cf6377644597c23306
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document automatic adjustment of process' logical window dimensions
    
    * doc/lispref/processes.texi (Process Buffers): Document
    'set-process-window-size' and
    'window-adjust-process-window-size-function'.
    
    * etc/NEWS: Mention the new functionality and variable.
    
    * src/process.c (Fset_process_window_size): Improve the doc string.
---
 doc/lispref/processes.texi |   52 ++++++++++++++++++++++++++++++++++++++++++++
 etc/NEWS                   |    8 +++++++
 src/process.c              |    4 +++-
 3 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi
index f660b15..03ae1f0 100644
--- a/doc/lispref/processes.texi
+++ b/doc/lispref/processes.texi
@@ -1381,6 +1381,58 @@ Killing the process's buffer deletes the process, which 
kills the
 subprocess with a @code{SIGHUP} signal (@pxref{Signals to Processes}).
 @end defun
 
+If the process's buffer is displayed in a window, your Lisp program
+may wish telling the process the dimensions of that window, so that
+the process could adapt its output to those dimensions, much as it
+adapts to the screen dimensions.  The following functions allow to
+communicate this kind of information to processes; however, not all
+systems support the underlying functionality, so it is best to provide
+fallbacks, e.g., via command-line arguments or environment variables.
+
address@hidden set-process-window-size process height width
+Tell @var{process} that its logical window size has dimensions
address@hidden by @var{height}, in character units.  If this function
+succeeds in communicating this information to the process, it returns
address@hidden; otherwise it returns @code{nil}.
address@hidden defun
+
+When windows that display buffers associated with process change their
+dimensions, the affected processes should be told about these changes.
+By default, when the window configuration changes, Emacs will
+automatically call @code{set-process-window-size} on behalf of every
+process whose buffer is displayed in a window, passing it the smallest
+dimensions of all the windows displaying the process's buffer.  This
+works via @code{window-configuration-change-hook} (@pxref{Window
+Hooks}), which is told to invoke the function that is the value of
+the variable @code{window-adjust-process-window-size-function} for
+each process whose buffer is displayed in at least one window.  You
+can customize this behavior by setting the value of that variable.
+
address@hidden window-adjust-process-window-size-function
+The value of this variable should be a function of two arguments: a
+process and the list of windows displaying the process's buffer.  When
+the function is called, the process's buffer is the current buffer.
+The function should return a cons cell @address@hidden(@var{width}
+. @var{height})}} that describes the dimensions of the logical process
+window to be passed via a call to @code{set-process-window-size}.  The
+function can also return @code{nil}, in which case Emacs will not call
address@hidden for this process.
+
+Emacs supplies two predefined values for this variable:
address@hidden, which returns the
+smallest of all the dimensions of the windows that display a process's
+buffer; and @code{window-adjust-process-window-size-largest}, which
+returns the largest dimensions.  For more complex strategies, write
+your own function.
+
+This variable can be buffer-local.
address@hidden defopt
+
+If the process has the @code{adjust-window-size-function} property
+(@pxref{Process Information}), its value overrides the global and
+buffer-local values of
address@hidden
+
 @node Filter Functions
 @subsection Process Filter Functions
 @cindex filter function
diff --git a/etc/NEWS b/etc/NEWS
index cfda333..785d14b 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1588,6 +1588,14 @@ process filter, sentinel, etc., through keyword 
arguments (similar to
 'make-network-process').
 
 +++
+** Subprocesses are automatically told about changes in window dimensions
+The new option 'window-adjust-process-window-size-function' controls
+how subprocesses are told to adapt their logical window sizes to
+changes in the Emacs window configuration.  Its default value calls
+'set-process-window-size' with the smallest dimensions of all the
+windows that display the subprocess's buffer.
+
++++
 ** A new function 'directory-files-recursively' returns all matching
 files (recursively) under a directory.
 
diff --git a/src/process.c b/src/process.c
index 2c758a4..14d7b6d 100644
--- a/src/process.c
+++ b/src/process.c
@@ -1108,7 +1108,9 @@ See `set-process-sentinel' for more info on sentinels.  
*/)
 
 DEFUN ("set-process-window-size", Fset_process_window_size,
        Sset_process_window_size, 3, 3, 0,
-       doc: /* Tell PROCESS that it has logical window size HEIGHT and WIDTH.  
*/)
+       doc: /* Tell PROCESS that it has logical window size WIDTH by HEIGHT.
+Value is t if PROCESS was successfully told about the window size,
+nil otherwise.  */)
   (Lisp_Object process, Lisp_Object height, Lisp_Object width)
 {
   CHECK_PROCESS (process);



reply via email to

[Prev in Thread] Current Thread [Next in Thread]