diff options
author | Eli Zaretskii <eliz@gnu.org> | 2016-05-07 12:16:27 +0300 |
---|---|---|
committer | Eli Zaretskii <eliz@gnu.org> | 2016-05-07 12:16:27 +0300 |
commit | 4ffec91aa1fe668609f460cf6377644597c23306 (patch) | |
tree | 4fe9756b816ca269d3fb520b1f3719dad3696673 | |
parent | dc662713e235c9c55c71636168af7e14519f180d (diff) | |
download | emacs-4ffec91aa1fe668609f460cf6377644597c23306.tar.gz |
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.
-rw-r--r-- | doc/lispref/processes.texi | 52 | ||||
-rw-r--r-- | etc/NEWS | 8 | ||||
-rw-r--r-- | src/process.c | 4 |
3 files changed, 63 insertions, 1 deletions
diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index f660b159386..03ae1f04349 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. + +@defun set-process-window-size process height width +Tell @var{process} that its logical window size has dimensions +@var{width} by @var{height}, in character units. If this function +succeeds in communicating this information to the process, it returns +@code{t}; otherwise it returns @code{nil}. +@end 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. + +@defopt 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 @w{@code{(@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 +@code{set-process-window-size} for this process. + +Emacs supplies two predefined values for this variable: +@code{window-adjust-process-window-size-smallest}, 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. +@end 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 +@code{window-adjust-process-window-size-function}. + @node Filter Functions @subsection Process Filter Functions @cindex filter function @@ -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 2c758a4c9a7..14d7b6df1c3 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); |