[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/hyperbole 1ce15b4995 4/5: hycontrol.el: Shorten docs st
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/hyperbole 1ce15b4995 4/5: hycontrol.el: Shorten docs strings to be within 80 char limit. (#263) |
|
Date: |
Mon, 3 Oct 2022 14:57:52 -0400 (EDT) |
branch: externals/hyperbole
commit 1ce15b49956de8a3836b329d953d5cc04173b3a5
Author: Mats Lidell <mats.lidell@lidells.se>
Commit: GitHub <noreply@github.com>
hycontrol.el: Shorten docs strings to be within 80 char limit. (#263)
---
ChangeLog | 1 +
hycontrol.el | 274 ++++++++++++++++++++++++++++++++++++-----------------------
2 files changed, 168 insertions(+), 107 deletions(-)
diff --git a/ChangeLog b/ChangeLog
index 6bcf19d821..8316d67d9a 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,6 @@
2022-10-03 Mats Lidell <matsl@gnu.org>
+* hycontrol.el:
* hui-select.el:
* hpath.el:
* hibtypes.el:
diff --git a/hycontrol.el b/hycontrol.el
index d817c8f17e..196ffab90a 100644
--- a/hycontrol.el
+++ b/hycontrol.el
@@ -3,9 +3,9 @@
;; Author: Bob Weiner
;;
;; Orig-Date: 1-Jun-16 at 15:35:36
-;; Last-Mod: 16-May-22 at 00:12:56 by Bob Weiner
+;; Last-Mod: 6-Aug-22 at 17:25:25 by Mats Lidell
;;
-;; Copyright (C) 2016-2021 Free Software Foundation, Inc.
+;; Copyright (C) 2016-2022 Free Software Foundation, Inc.
;; See the "HY-COPY" file for license information.
;;
;; This file is part of GNU Hyperbole.
@@ -134,7 +134,7 @@
;;; ************************************************************************
(defvar hycontrol-debug nil
- "When set non-nil by a user, some HyControl functions log debugging messages
to the *Messages* buffer.")
+ "Whether some HyControl functions log debugging messages to *Messages*.")
(defvar hycontrol-display-buffer-predicate-list
;; Display only buffers attached to files.
@@ -149,30 +149,31 @@ evaluated with the buffer argument as the current buffer,
e.g. (eq
major-mode 'c-mode).")
(defcustom hycontrol-help-flag t
- "*When t (the default), display key binding help in the minibuffer when in a
HyControl mode."
+ "*Non-nil means show key binding help in the minibuffer when in a HyControl
mode."
:type 'boolean
:group 'hyperbole-screen)
(defcustom hycontrol-invert-mode-line-flag t
- "*When t (default) and in a HyControl mode, invert mode-line to emphasize
the special key bindings in effect."
+ "*Non-nil means invert mode-line to emphasize the special key bindings in
effect."
:type 'boolean
:group 'hyperbole-screen)
(defcustom hycontrol-keep-window-flag nil
- "*When non-nil (default is nil), leave original window when tear off window
to another frame."
+ "*Non-nil means leave original window when tear off window to another frame."
:type 'boolean
:group 'hyperbole-screen)
(defcustom hycontrol-maximum-units 1000
"*Maximum units setting allowed for hycontrol commands.
-The unit counter resets to the last digit entered whenever this value is
exceeded."
+The unit counter resets to the last digit entered whenever this
+value is exceeded."
:type '(integer :match (lambda (_widget value)
(and (integerp value) (> value 0)
(<= value (max 1000 (display-pixel-width))))))
:group 'hyperbole-screen)
(defcustom hycontrol-frame-offset '(13 . 23)
- "*Increase in pixel offset for new hycontrol frames relative to the selected
frame.
+ "*Increase in offset for new hycontrol frames relative to the selected frame.
Its value is an (x-offset . y-offset) pair in pixels."
:type '(cons integer integer)
:group 'hyperbole-screen)
@@ -181,7 +182,9 @@ Its value is an (x-offset . y-offset) pair in pixels."
'(((1920 . 1080) . (0 10 0 68)) ; 24" iMac HD display
((2560 . 1440) . (0 15 0 93)) ; 27" iMac HD display
(t . (0 0 0 0)))
- "*Alist of (screen-predicate . (top-offset right-offset bottom-offset
left-offset) pairs.
+ "*Alist of screen predicate offset pairs.
+The format is (screen-predicate . (top-offset right-offset
+bottom-offset left-offset).
Offsets are integers given in pixels. The offsets associated with the first
matching screen-predicate are used in HyControl screen edge frame placement
commands; this is set when HyControl is first loaded/used.
@@ -219,12 +222,12 @@ The final predicate should always be t, for default
values, typically of zero.")
(defvar hycontrol-frame-widths
'(1.0 0.75 0.666 0.5 0.333 0.25)
- "List of frame width percentages that HyControl cycles through when
adjusting a frame's width.
+ "List of width percentages to cycle through when adjusting a frame's width.
0.75 and 75 are treated as the same percentage.")
(defvar hycontrol-frame-heights
'(1.0 0.75 0.666 0.5 0.333 0.25)
- "List of frame height percentages that HyControl cycles through when
adjusting a frame's height.
+ "List of height percentages to cycle through when adjusting a frame's height.
0.75 and 75 are treated as the same percentage.")
(defvar hycontrol-arg nil
@@ -480,11 +483,13 @@ associated key: quit {q}, abort {C-g}, or toggle {t}.")
(defvar hycontrol--quit-function nil
- "Stores function auto-generated by a call to `set-transient-map' to remove
the transient-map later.")
+ "Stores function to remove the transient-map later.
+The function is auto-generated by a call to `set-transient-map'")
(defvar hycontrol--screen-edge-position 0
- "Cycles between 0-7 representing corner and center edge positions in
clockwise order from the upper left corner.")
+ "Cycles between 0-7 representing corner and center edge positions.
+The cycle is in clockwise order from the upper left corner.")
(defvar hycontrol--frame-widths-pointer nil)
(defvar hycontrol--frame-heights-pointer nil)
@@ -492,7 +497,8 @@ associated key: quit {q}, abort {C-g}, or toggle {t}.")
(defvar hycontrol--buffer-list-pointer nil)
(defvar hycontrol--initial-which-key-inhibit nil
- "Stores value of `which-key-inhibit' flag from \"which-key\" package upon
entry to HyControl, if any.")
+ "Store value of `which-key-inhibit' flag from \"which-key\" package, if any.
+Used on entry to HyControl.")
;;; ************************************************************************
;;; Private functions
@@ -551,7 +557,7 @@ If the argument is 0, set it to -1."
hycontrol-arg (if (zerop hycontrol-arg) -1 (- hycontrol-arg))))
(defun hycontrol-minus-key ()
- "Conditional command to execute when the minus key is pressed in a HyControl
mode."
+ "Conditional command to execute when the minus key is pressed."
(interactive)
(cond ((and (symbolp last-command)
(string-match-p
"\\`\\(hui:menu-enter\\|hycontrol.*-\\(frames\\|windows\\|prefix\\|universal\\)-\\(mode\\|arg\\)\\)"
(symbol-name last-command)))
@@ -562,7 +568,7 @@ If the argument is 0, set it to -1."
(hycontrol-window-minimize-lines))))
(defun hycontrol-multiply-universal-arg ()
- "Return the new prefix argument based on existing `hycontrol-arg' and one
press of the universal arg, C-u."
+ "Return prefix arg based on `hycontrol-arg' and one press of the universal
arg."
(interactive)
(setq this-command 'hycontrol-multiply-universal-arg
hycontrol-arg (* hycontrol-arg 4))
@@ -675,36 +681,48 @@ relative to Left and Top which are both zero."
(frame-edges frame 'outer-edges))
(defsubst hycontrol-frame-x-origin (&optional frame)
- "Return the X origin coordinate (upper left point) of optional FRAME or the
selected frame. This includes all graphical window manager decorations.
-Under a graphical window system, this is in pixels; otherwise, it is in
characters."
+ "Return the X origin coordinate of optional FRAME or the selected frame.
+This includes all graphical window manager decorations. The X
+origin coordinate is the upper left point. Under a graphical
+window system, this is in pixels; otherwise, it is in characters."
(nth 0 (hycontrol-frame-edges frame)))
(defsubst hycontrol-frame-y-origin (&optional frame)
- "Return the Y origin coordinate (upper left point) of optional FRAME or the
selected frame. This includes all graphical window manager decorations.
-Under a graphical window system, this is in pixels; otherwise, it is in
characters."
+ "Return the Y origin coordinate of optional FRAME or the selected frame.
+This includes all graphical window manager decorations. The Y
+origin coordinate is the upper left point. Under a graphical
+window system, this is in pixels; otherwise, it is in characters."
(nth 1 (hycontrol-frame-edges frame)))
(defun hycontrol-frame-height (&optional frame)
- "Return the height of optional FRAME or the selected frame. This includes
all graphical window manager decorations.
-Under a graphical window system, this is in pixels; otherwise, it is in
characters."
+ "Return the height of optional FRAME or the selected frame.
+This includes all graphical window manager decorations. Under a
+graphical window system, this is in pixels; otherwise, it is in
+characters."
(frame-pixel-height frame))
(defun hycontrol-frame-width (&optional frame)
- "Return the width of optional FRAME or the selected frame. This includes
all graphical window manager decorations.
-Under a graphical window system, this is in pixels; otherwise, it is in
characters."
+ "Return the width of optional FRAME or the selected frame.
+This includes all graphical window manager decorations. Under a
+graphical window system, this is in pixels; otherwise, it is in
+characters."
(frame-pixel-width frame))
;; Frame Resizing Support
(defconst hycontrol-screen-offset-sensitivity 12
- "Number of pixels a frame dimension can be off from its screen-offset and
still be considered at the screen edge.")
+ "Screen edge sensitivity in pixels.
+Number of pixels a frame dimension can be off from its
+screen-offset and still be considered at the screen edge.")
(defun hycontrol-frame-at-left-p ()
- "Return non-nil if selected frame's left edge is at the left edge of the
screen sans `hycontrol-screen-left-offset'."
+ "Non-nil if selected frame's left edge is at the left edge of the screen.
+Screen left edge is adjusted based on `hycontrol-screen-left-offset'."
(<= (- (nth 0 (hycontrol-frame-edges)) hycontrol-screen-left-offset)
hycontrol-screen-offset-sensitivity))
(defun hycontrol-frame-at-top-p ()
- "Return non-nil if selected frame's bottom is at the top of the screen sans
`hycontrol-screen-top-offset'."
+ "Non-nil if selected frame's bottom is at the top of the screen.
+Screen top is adjusted based on `hycontrol-screen-top-offset'."
(<= (- (nth 1 (hycontrol-frame-edges)) hycontrol-screen-top-offset
;; Under macOS, frames are automatically offset vertically by
;; the height of the global menubar, so account for that.
@@ -712,12 +730,14 @@ Under a graphical window system, this is in pixels;
otherwise, it is in characte
hycontrol-screen-offset-sensitivity))
(defun hycontrol-frame-at-right-p ()
- "Return non-nil if selected frame's right edge is at the right edge of the
screen sans `hycontrol-screen-right-offset'."
+ "Non-nil if selected frame's right edge is at the right edge of the screen.
+Screen right edge is adjusted based on `hycontrol-screen-right-offset'."
(<= (- (display-pixel-width) (nth 2 (hycontrol-frame-edges))
hycontrol-screen-right-offset)
hycontrol-screen-offset-sensitivity))
(defun hycontrol-frame-at-bottom-p ()
- "Return non-nil if selected frame's bottom is at the bottom of the screen
sans `hycontrol-screen-bottom-offset'."
+ "Non-nil if selected frame's bottom is at the bottom of the screen.
+Screen bottom edge is adjusted based on `hycontrol-screen-bottom-offset'."
(<= (- (display-pixel-height) (nth 3 (hycontrol-frame-edges))
hycontrol-screen-bottom-offset
;; Under macOS, frames are automatically offset vertically by
;; the height of the global menubar, so account for that.
@@ -727,7 +747,8 @@ Under a graphical window system, this is in pixels;
otherwise, it is in characte
;; Frame Zoom Support
(defun hycontrol-frame-zoom (zoom-func arg max-msgs)
"Zoom default frame face using ZOOM-FUNC and amount ARG (must be 1-9).
-MAX-MSGS is a number used only if ZOOM-FUNC is undefined and an error message
is logged."
+MAX-MSGS is a number used only if ZOOM-FUNC is undefined and an
+error message is logged."
(if (fboundp zoom-func)
(let ((frame-zoom-font-difference arg))
(funcall zoom-func))
@@ -735,8 +756,9 @@ MAX-MSGS is a number used only if ZOOM-FUNC is undefined
and an error message is
(defun hycontrol-make-frame ()
- "Create and select a new frame with the same size and selected buffer as the
selected frame.
-It is offset from the selected frame by `hycontrol-frame-offset' (x . y)
pixels."
+ "Create a new frame with the same size and selected buffer as the selected
frame.
+The new frame is selected. It is offset from the selected frame
+by `hycontrol-frame-offset' (x . y) pixels."
(interactive)
(select-frame (make-frame (list (cons 'width (frame-width)) (cons 'height
(frame-height))
(cons 'left (+ (car hycontrol-frame-offset)
(car (frame-position))))
@@ -752,7 +774,7 @@ It is offset from the selected frame by
`hycontrol-frame-offset' (x . y) pixels.
('right (set-frame-position nil (+ x pixels) y)))))
(defun hycontrol-numeric-keypad (e _arg)
- "Move the selected frame to a screen location based on the location of the
last pressed numeric keypad key."
+ "Move frame to screen location based on the last pressed numeric keypad key."
(let ((num (if (integerp e)
e
;; kp-<num> symbol
@@ -831,15 +853,19 @@ multiple of the default frame font width."
(error "(HyDebug): Invalid expression in
`hycontrol-display-buffer-predicate-list' - %s" err)))
(defvar hycontrol--blank-buffer (get-buffer-create "BLANK")
- "Blank buffer to display in extra window grid windows after selected
buffer list is exhausted.")
+ "Blank buffer to display in extra window grid windows.
+Used after selected buffer list is exhausted.")
(defun hycontrol-window-display-buffer (window)
- "Given a WINDOW, choose the next appropriate buffer to display from
`hycontrol--buffer-list'.
+ "Given a WINDOW, choose the next appropriate buffer to display.
+Uses `hycontrol--buffer-list'.
-When `hycontrol--invert-display-buffer-predicates' is non-nil and not 'ignore,
-the list of buffers used is further filtered using the functions and
sexpressions
-in `hycontrol-display-buffer-predicate-list', which by default filters
-a frame's buffer-list to just those buffers with attached files.
+When `hycontrol--invert-display-buffer-predicates' is non-nil and
+not 'ignore, the list of buffers used is further filtered using
+the functions and sexpressions in
+`hycontrol-display-buffer-predicate-list', which by default
+filters a frame's buffer-list to just those buffers with attached
+files.
Filtering is disabled if a specific list of buffers is sent to the
`hycontrol-make-windows-grid' function that calls this."
@@ -862,9 +888,10 @@ Filtering is disabled if a specific list of buffers is
sent to the
(defun hycontrol-window-display-buffer-with-repeats (window)
"This is no longer used since Hyperbole V8. Left here for reference.
-Given a WINDOW, choose the next appropriate buffer to display therein using
`hycontrol-display-buffer-predicate-list'.
-Also uses the value of`hycontrol--buffer-list' as the list of
-buffers to distribute among the windows."
+Given a WINDOW, choose the next appropriate buffer to display
+therein using `hycontrol-display-buffer-predicate-list'. Also
+uses the value of`hycontrol--buffer-list' as the list of buffers
+to distribute among the windows."
(let ((buf (car hycontrol--buffer-list-pointer)))
(setq hycontrol--buffer-list-pointer (cdr hycontrol--buffer-list-pointer))
(unless buf
@@ -898,7 +925,7 @@ buffers to distribute among the windows."
(apply #'message msg-args)))
(defun hycontrol-user-error (max-msgs &rest err)
- "Log MAX-MSGS, adding ERR to the *Messages* buffer log; display ERR for 2
seconds."
+ "Log MAX-MSGS, adding ERR to *Messages* buffer; display ERR for 2 seconds."
(let ((message-log-max max-msgs))
(beep)
(apply #'message err)
@@ -950,7 +977,8 @@ is set to 1. If it is > `hycontrol-maximum-units', it is
set to
(keyboard-quit))
(defun hycontrol-quit ()
- "Globally quit HyControl Frames mode, typically on a press of {q}, always on
a press of {Q}.
+ "Globally quit HyControl Frames mode.
+Typically on a press of {q}, always on a press of {Q}.
If in a help buffer where {q} is bound to `quit-window', run that
instead of quitting HyControl."
(interactive)
@@ -1017,9 +1045,10 @@ instead of quitting HyControl."
(delete-other-frames)))
(defun hycontrol-frame-swap-buffers ()
- "Swap the buffers displayed by each of two visible, most recently used
frames and return t.
-The selected window in each frame is used. If there are not at least
-two visible frames, do nothing and return nil."
+ "Swap the buffers displayed by each of two visible, most recently used
frames.
+Return t on success. The selected window in each frame is used.
+If there are not at least two visible frames, do nothing and
+return nil."
(interactive)
(let ((frames (filtered-frame-list #'frame-visible-p))
frame2
@@ -1043,7 +1072,7 @@ two visible frames, do nothing and return nil."
"(Virtual 7 8 9 Enter a digit to
Numeric 4 5 6 move the frame
Keypad) 1 2 3 to that quadrant"
- "HyControl prompt string for virtual numeric keypad (emulate keypad when not
available)")
+ "Prompt string for virtual numeric keypad (emulate keypad when not
available).")
(defun hycontrol-virtual-numeric-keypad (arg)
(catch 'quit
@@ -1055,7 +1084,8 @@ two visible frames, do nothing and return nil."
(hycontrol-numeric-keypad (- e ?0) arg))))
(defun hycontrol-frame-to-screen-edges (&optional arg)
- "Cycle the selected frame's position clockwise through the middle of edges
and corners of the screen; once per call.
+ "Cycle the selected frame's position clockwise; once per call.
+Cycle through the middle of edges and corners of the screen.
With an optional ARG of 0, just reset the cycle position to 0."
(interactive)
(if (and arg (zerop arg))
@@ -1071,7 +1101,8 @@ With an optional ARG of 0, just reset the cycle position
to 0."
(setq hycontrol--screen-edge-position 0))))
(defun hycontrol-frame-to-bottom ()
- "Move the selected frame to the bottom of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the bottom of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil (car (frame-position))
@@ -1079,12 +1110,14 @@ With an optional ARG of 0, just reset the cycle
position to 0."
hycontrol-screen-bottom-offset)))
(defun hycontrol-frame-to-left ()
- "Move the selected frame to the left of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the left of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position nil hycontrol-screen-left-offset (cdr
(frame-position))))
(defun hycontrol-frame-to-right ()
- "Move the selected frame to the right of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the right of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil (- (display-pixel-width) (hycontrol-frame-width)
@@ -1092,8 +1125,10 @@ With an optional ARG of 0, just reset the cycle position
to 0."
(cdr (frame-position))))
(defun hycontrol-frame-fit-to-screen (&optional frame x-origin y-origin)
- "Ensure the selected frame fits within the screen, allowing for
hycontrol-screen-*-offsets.
-Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use
when resizing FRAME (defaults to selected frame)."
+ "Ensure the selected frame fits within the screen.
+Allow for hycontrol-screen-*-offsets. Accepts optional arguments
+FRAME, X-ORIGIN, and Y-ORIGIN (in pixels) to use when resizing
+FRAME (defaults to selected frame)."
(let ((max-width (- (display-pixel-width) hycontrol-screen-left-offset
hycontrol-screen-right-offset 2))
(max-height (- (display-pixel-height) hycontrol-screen-top-offset
hycontrol-screen-bottom-offset 2))
(frame-resize-pixelwise t))
@@ -1121,12 +1156,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and
Y-ORIGIN (in pixels) to use when
(defun hycontrol-frame-to-top ()
- "Move the selected frame to the top of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the top of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position nil (car (frame-position))
hycontrol-screen-top-offset))
(defun hycontrol-frame-to-bottom-center ()
- "Move the selected frame to the center of the bottom of the screen, allowing
for hycontrol-screen-*-offsets."
+ "Move the selected frame to the center of the bottom of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil (round (/ (- (display-pixel-width) (hycontrol-frame-width)) 2))
@@ -1143,13 +1180,15 @@ Accepts optional arguments FRAME, X-ORIGIN, and
Y-ORIGIN (in pixels) to use when
(defun hycontrol-frame-to-left-center ()
- "Move the selected frame to the center of the left of the screen, allowing
for hycontrol-screen-*-offsets."
+ "Move the selected frame to the center of the left of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil hycontrol-screen-left-offset (round (/ (- (display-pixel-height)
(hycontrol-frame-height)) 2))))
(defun hycontrol-frame-to-right-center ()
- "Move the selected frame to the center of the right of the screen, allowing
for hycontrol-screen-*-offsets."
+ "Move the selected frame to the center of the right of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil (- (display-pixel-width) (hycontrol-frame-width)
@@ -1157,12 +1196,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and
Y-ORIGIN (in pixels) to use when
(round (/ (- (display-pixel-height) (hycontrol-frame-height)) 2))))
(defun hycontrol-frame-to-top-center ()
- "Move the selected frame to the center of the top of the screen, allowing
for hycontrol-screen-*-offsets."
+ "Move the selected frame to the center of the top of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position nil (round (/ (- (display-pixel-width)
(hycontrol-frame-width)) 2)) hycontrol-screen-top-offset))
(defun hycontrol-frame-to-bottom-left ()
- "Move the selected frame to the bottom left of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the bottom left of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position nil
hycontrol-screen-left-offset
@@ -1170,7 +1211,8 @@ Accepts optional arguments FRAME, X-ORIGIN, and Y-ORIGIN
(in pixels) to use when
hycontrol-screen-bottom-offset)))
(defun hycontrol-frame-to-bottom-right ()
- "Move the selected frame to the bottom right of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the bottom right of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil
@@ -1180,12 +1222,14 @@ Accepts optional arguments FRAME, X-ORIGIN, and
Y-ORIGIN (in pixels) to use when
;; Frame Resizing
(defun hycontrol-frame-to-top-left ()
- "Move the selected frame to the top left of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the top left of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position nil hycontrol-screen-left-offset
hycontrol-screen-top-offset))
(defun hycontrol-frame-to-top-right ()
- "Move the selected frame to the top right of the screen, allowing for
hycontrol-screen-*-offsets."
+ "Move the selected frame to the top right of the screen.
+Allow for hycontrol-screen-*-offsets."
(interactive)
(hycontrol-set-frame-position
nil (- (display-pixel-width) (hycontrol-frame-width)
@@ -1210,7 +1254,8 @@ non-integer arguments are ignored and the default value
is used."
(t (hycontrol-frame-resize-percentage 1))))
(defun hycontrol-frame-resize-arg (arg)
- "Inverse result of `hycontrol-frame-resize-percentage' to provide feedback
on any argument value adjustment."
+ "Inverse result of `hycontrol-frame-resize-percentage'.
+This is to provide feedback on any argument value adjustment."
(pcase arg
(0 0)
(1 1)
@@ -1220,9 +1265,10 @@ non-integer arguments are ignored and the default value
is used."
(_ 1)))
(defun hycontrol-frame-resize-to-bottom (&optional arg)
- "Expand the selected frame to the bottom of the screen, allowing for
hycontrol-screen-*-offsets.
-If already at the bottom, adjust its height to ARG percent of the screen (50%
by default
-if ARG is 1 or nil) but keep it at the bottom of the screen."
+ "Expand the selected frame to the bottom of the screen.
+Allow for hycontrol-screen-*-offsets. If already at the bottom,
+adjust its height to ARG percent of the screen (50% by default if
+ARG is 1 or nil) but keep it at the bottom of the screen."
(interactive "p")
(setq arg (hycontrol-frame-resize-percentage arg))
(let ((frame-resize-pixelwise t))
@@ -1238,9 +1284,10 @@ if ARG is 1 or nil) but keep it at the bottom of the
screen."
(hycontrol-frame-resize-arg arg))
(defun hycontrol-frame-resize-to-left (&optional arg)
- "Expand the selected frame to the left of the screen, allowing for
hycontrol-screen-*-offsets.
-If already at the left, adjust its width to ARG percent of the screen (50% by
default
-if ARG is 1 or nil) but keep it at the left of the screen."
+ "Expand the selected frame to the left of the screen.
+Allow for hycontrol-screen-*-offsets. If already at the left,
+adjust its width to ARG percent of the screen (50% by default if
+ARG is 1 or nil) but keep it at the left of the screen."
(interactive "p")
(setq arg (hycontrol-frame-resize-percentage arg))
(let ((frame-resize-pixelwise t))
@@ -1256,9 +1303,11 @@ if ARG is 1 or nil) but keep it at the left of the
screen."
(hycontrol-frame-resize-arg arg))
(defun hycontrol-frame-resize-to-right (&optional arg)
- "Expand the selected frame to the right of the screen, allowing for
hycontrol-screen-*-offsets.
-If already at the right, adjust its width to ARG percent of the screen (50% by
default
-if ARG is 1 or nil) but keep it at the right of the screen."
+ "Expand the selected frame to the right of the screen.
+Allowing for hycontrol-screen-*-offsets. If already at the
+right, adjust its width to ARG percent of the screen (50% by
+default if ARG is 1 or nil) but keep it at the right of the
+screen."
(interactive "p")
(setq arg (hycontrol-frame-resize-percentage arg))
(let ((frame-resize-pixelwise t))
@@ -1274,9 +1323,10 @@ if ARG is 1 or nil) but keep it at the right of the
screen."
(hycontrol-frame-resize-arg arg))
(defun hycontrol-frame-resize-to-top (&optional arg)
- "Expand the selected frame to the top of the screen, allowing for
hycontrol-screen-*-offsets.
-If already at the top, adjust its height to ARG percent of the screen (50% by
default
-if ARG is 1 or nil) but keep it at the top of the screen."
+ "Expand the selected frame to the top of the screen.
+Allow for hycontrol-screen-*-offsets. If already at the top,
+adjust its height to ARG percent of the screen (50% by default if
+ARG is 1 or nil) but keep it at the top of the screen."
(interactive "p")
(setq arg (hycontrol-frame-resize-percentage arg))
(let ((frame-resize-pixelwise t))
@@ -1291,7 +1341,8 @@ if ARG is 1 or nil) but keep it at the top of the screen."
(defun hycontrol-frame-minimize-lines ()
- "Shrink the frame to its approximate smallest number of lines to display all
existing windows."
+ "Shrink frame to its smallest number of lines to display all existing
windows.
+The smallest noumber is an approximation."
(interactive)
(let ((l 0))
(save-window-excursion
@@ -1393,7 +1444,7 @@ Widths are given in screen percentages by the list
;;;###autoload
(defun hycontrol-frame-adjust-widths-full-height ()
- "Cycle through different common widths adjustments of a frame after fixing
its height full-screen.
+ "Cycle through frame width adjustments after fixing its height full-screen.
Widths are given in screen percentages by the list
`hycontrol-frame-widths' and typically go from widest to narrowest."
(interactive)
@@ -1426,7 +1477,7 @@ Heights are given in screen percentages by the list
;;;###autoload
(defun hycontrol-frame-adjust-heights-full-width ()
- "Cycle through different common height adjustments of a frame after fixing
its width full-screen.
+ "Cycle through height adjustments of a frame after fixing its width
full-screen.
Heights are given in screen percentages by the list
`hycontrol-frame-heights' and typically go from tallest to shortest."
(interactive)
@@ -1462,7 +1513,8 @@ Heights are given in screen percentages by the list
;;; Window Commands
(defun hycontrol-invert-mode-line ()
- "If `hycontrol-invert-mode-line-flag' is non-nil, invert the background and
foreground faces of the selected window mode-line."
+ "Invert the background and foreground faces of the selected window mode-line.
+Enabled if `hycontrol-invert-mode-line-flag' is non-nil."
(when hycontrol-invert-mode-line-flag
(let* ((bg (face-background 'mode-line))
(fg (face-foreground 'mode-line)))
@@ -1488,8 +1540,10 @@ Heights are given in screen percentages by the list
items))
(defun hycontrol-windows-grid-buffer-list ()
- "Return either any marked items in Dired, Buffer Menu or IBuffer mode or the
existing frame's buffer list.
-If selecting buffers by major-mode, then ignore any marked items."
+ "Return buffer list for grid.
+Buffers are either any marked items in Dired, Buffer Menu or
+IBuffer mode or the existing frame's buffer list. If selecting
+buffers by major-mode, then ignore any marked items."
(if (and (boundp 'mode) (symbolp mode))
(buffer-list (selected-frame))
;; Get the list of marked items if in an item list buffer and
@@ -1562,9 +1616,10 @@ argument."
(hhist:add hist-elt)))))) ;; Save prior frame configuration for
easy return
(defun hycontrol-windows-grid-minimum-size (num-buffers)
- "Return the minimum integer window grid size to display NUM-BUFFERS.
Minimize number of rows rather than columns.
-Size is a 2 digit whole number with the first digit number of rows and
-the second, number of columns of windows."
+ "Return the minimum integer window grid size to display NUM-BUFFERS.
+Minimize number of rows rather than columns. Size is a 2 digit
+whole number with the first digit number of rows and the second,
+number of columns of windows."
(let* ((num-cols (ceiling (sqrt num-buffers)))
(num-rows (1- num-cols))
(grid-size (+ (* num-rows 10) num-cols)))
@@ -1590,7 +1645,7 @@ the second, number of columns of windows."
;;;###autoload
(defun hycontrol-windows-grid-by-file-pattern (pattern &optional full)
- "Display an automatically sized window grid showing files found from glob
PATTERN.
+ "Display an automatically sized window grid with files found from glob
PATTERN.
Use absolute file paths if called interactively or optional FULL is non-nil."
(interactive
(list (read-string "Pattern of files to display in windows grid: ")
@@ -1601,9 +1656,10 @@ Use absolute file paths if called interactively or
optional FULL is non-nil."
;;;###autoload
(defun hycontrol-windows-grid-by-major-mode (arg mode)
- "Display a grid of windows in the selected frame, sized according to prefix
ARG, with buffers of major MODE.
-Left digit of ARG is the number of grid rows and the right digit is
-the number of grid columns.
+ "Display a grid of windows in the selected frame with buffers of major MODE.
+The grid is sized according to prefix ARG. Left digit of ARG is
+the number of grid rows and the right digit is the number of grid
+columns.
See documentation of `hycontrol-windows-grid' for further details."
(interactive
@@ -1618,9 +1674,9 @@ See documentation of `hycontrol-windows-grid' for further
details."
;;;###autoload
(defun hycontrol-windows-grid-repeatedly (&optional arg)
- "Repeatedly display different window grid layouts according to prefix ARG
prompted for each time.
-Left digit of ARG is the number of grid rows and the right digit is
-the number of grid columns.
+ "Repeatedly display different window grid layouts according to prefix ARG.
+ARG is prompted for each time. Left digit of ARG is the number
+of grid rows and the right digit is the number of grid columns.
See documentation of `hycontrol-windows-grid' for further details."
(interactive "p")
@@ -1736,14 +1792,14 @@ See documentation of `hycontrol-windows-grid' for
further details."
(delete-other-windows)))
(defun hycontrol-window-maximize-lines ()
- "Grow window to its maximum possible number of lines without removing any
windows."
+ "Grow window to its maximum possible number of lines without removing
windows."
(interactive)
(maximize-window))
(defun hycontrol-window-minimize-lines ()
- "Shrink window to its smallest possible number of lines to display entire
buffer, if possible.
-Otherwise or if the window is already displaying all of its lines, shrink it
to about one line,
-if possible."
+ "Shrink window to its smallest number of lines to show whole buffer, if
possible.
+Otherwise or if the window is already displaying all of its
+lines, shrink it to about one line, if possible."
(interactive)
(let ((neg-shrink-amount (- (1+ (count-lines (point-min) (point-max)))))
(window-min-height 1))
@@ -1755,9 +1811,10 @@ if possible."
(shrink-window (1- (window-height))))))
(defun hycontrol-window-swap-buffers ()
- "Swap the buffers displayed by each of two windows within the selected frame
and return t.
-Swap which window is selected so that the current buffer remains the same.
-Do nothing and return nil if there are not precisely two windows."
+ "Swap the buffers displayed in two windows in the selected frame and return
t.
+Swap which window is selected so that the current buffer remains
+the same. Do nothing and return nil if there are not precisely
+two windows."
(interactive)
(let ((windows (window-list nil 'no-mini))
buf1 buf2)
@@ -1773,9 +1830,10 @@ Do nothing and return nil if there are not precisely two
windows."
;;;###autoload
(defun hycontrol-window-to-new-frame ()
"Create a new frame sized to match the selected window with the same buffer.
-If there is only one window in the source frame or if
`hycontrol-keep-window-flag'
-is non-nil, leave the original window and just clone it into the new frame;
-otherwise, delete the original window."
+If there is only one window in the source frame or if
+`hycontrol-keep-window-flag' is non-nil, leave the original
+window and just clone it into the new frame; otherwise, delete
+the original window."
(interactive)
(let ((w (selected-window))
(frame-resize-pixelwise t)
@@ -1818,7 +1876,7 @@ otherwise, delete the original window."
;;; Screen Offsets - Set once when this file is loaded;
`hycontrol-set-screen-offsets' resets them.
(defun hycontrol-display-screen-offsets ()
- "Display a user minibuffer message listing HyControl's screen edge offsets
in pixels."
+ "Display a minibuffer message listing HyControl's screen edge offsets in
pixels."
(interactive)
(message "Screen pixel offsets are: Left: %d; Top: %d; Right: %d; Bot: %d"
hycontrol-screen-left-offset
@@ -1827,8 +1885,9 @@ otherwise, delete the original window."
hycontrol-screen-bottom-offset))
(defun hycontrol-get-screen-offsets ()
- "Return the first matching list of screen edge .50%%%offsets from
`hycontrol-screen-offset-alist'.
-See its documentation for more information."
+ "Return the first matching list of screen edge .50%%%offsets.
+The offsets are from `hycontrol-screen-offset-alist'. See its
+documentation for more information."
(interactive)
(prog1 (catch 'result
(let (predicate offsets width height)
@@ -1859,8 +1918,9 @@ See its documentation for more information."
(if (called-interactively-p 'interactive)
(hycontrol-display-screen-offsets))))
(defun hycontrol-set-screen-offsets ()
- "Set screen edge offsets to the first matching list of offsets from
`hycontrol-screen-offset-alist'.
-See its documentation for more information."
+ "Set screen edge offsets to the first matching list of offsets.
+Offsets are from `hycontrol-screen-offset-alist'. See its
+documentation for more information."
(interactive)
(let ((offsets (hycontrol-get-screen-offsets)))
(setq hycontrol-screen-left-offset (nth 0 offsets)