Mirrors/exwm2
2
0
Fork 0
mirror of https://github.com/emacs-exwm/exwm.git synced 2024-11-23 13:07:59 +01:00
Code Issues Projects Releases Packages Wiki Activity

satisfy checkdoc

Browse source 
* exwm-background.el (exwm-background--connected-p): Add docstring.
(exwm-background--connect): Add docstring.
* exwm-core.el (exwm-debug-log-time-function):
(exwm-debug): Rename to exwm-debug-mode; define obsolete alias for old name.
(exwm--debug): Update docstring to reflect above name change.
(exwm--log): condition on exwm-debug-mode
(exwm-mode-map): update exwm-debug-mode binding
* exwm-floating.el (exwm-floating--set-allowed-actions):
Rename TILLING parameter to TILED-P; update docstring.
(exwm-floating--start-moveresize): Add parameters to docstring.
(exwm-floating--do-moveresize): Add parameter to docstring.
* exwm-input.el (exwm-input-prefix-keys): Remove embedded keybinding from docstring.
(exwm-input--on-PropertyNotify): Add parameter to docstring.
(exwm-input--on-EnterNotify): Add parameter to docstring.
(exwm-input--on-keysyms-update): Add docstring.
(exwm-input--set-active-window): Add parameter to docstring.
(exwm-input--on-ButtonPress): Add parameter to docstring.
(exwm-input--on-KeyPress): Add parameter to docstring.
(exwm-input--on-CreateNotify): Add parameter to docstring.
(exwm-input--grab-global-prefix-keys): Add docstring.
(exwm-input--set-key): Add docstring.
(exwm-input-set-key): Add parameter to docstring.
(exwm-input--unread-event): Add docstring.
(exwm-input--translate): Add docstring.
(exwm-input--cache-event): Add parameter to docstring.
(exwm-input--on-KeyPress-line-mode): Rename parameter; add parameter to docstring.
(exwm-input--on-KeyPress-char-mode): Rename parameter; add parameter to docstring.
(exwm-input-grab-keyboard): Add parameter to docstring.
(exwm-input-release-keyboard): Add parameter to docstring.
(exwm-input-toggle-keyboard): Add parameter to docstring.
(exwm-input-send-next-key): Rename parameter; mention limit in docstring.
(exwm-input--set-simulation-keys): Rename parameter; add parameter to docstring.
(exwm-input--read-keys): Add docstring.
(exwm-input-set-simulation-key): Add parameters to docstring.
(exwm-input-send-simulation-key): Rename parameter; add parameter to docstring.
* exwm-randr.el (exwm-randr--on-ScreenChangeNotify): Add parameter to docstring.
(exwm-randr--on-Notify): Add parameter to docstring.
(exwm-randr--on-ConfigureNotify): Add parameter to docstring.
* exwm-xim.el (exwm-xim--on-ClientMessage): Add parameter to docstring.
* exwm.el (exwm-restart): Remove question mark from prompt arg
(exwm-enable): Remove question mark from prompt arg; add parameter to docstring.
(exwm--confirm-kill-terminal): Remove question mark from prompt arg.
(exwm--confirm-kill-emacs): Ensure prompt ends in question mark.
This commit is contained in:
Nicholas Vollmer 2024-06-05 23:34:37 -04:00 committed by Daniel Mendler
parent 588f6ca043
commit 9e965fd2af
7 changed files with 79 additions and 60 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
exwm-background.el
View file

@ -156,10 +156,12 @@ may kill this connection when they replace it.")
(xcb:flush exwm-background--connection))
(defun exwm-background--connected-p ()
"Return t if a live background connection process exists and is connected."
(and exwm-background--connection
(process-live-p (slot-value exwm-background--connection 'process))))
(defun exwm-background--connect ()
"Establish background Pixmap connection."
(unless (exwm-background--connected-p)
(setq exwm-background--connection (xcb:connect))
;;prevent query message on exit

15
exwm-core.el
View file

@ -38,12 +38,12 @@
:group 'exwm)
(defcustom exwm-debug-log-time-function #'exwm-debug-log-uptime
"Function used for generating timestamps in `exwm-debug' logs.
"Function used for generating timestamps in debug log.
Here are some predefined candidates:
`exwm-debug-log-uptime': Display the uptime of this Emacs instance.
`exwm-debug-log-time': Display time of day.
`nil': Disable timestamp."
nil: Disable timestamp."
:type `(choice (const :tag "Emacs uptime" ,#'exwm-debug-log-uptime)
(const :tag "Time of day" ,#'exwm-debug-log-time)
(const :tag "Off" nil)
@ -98,14 +98,15 @@ Here are some predefined candidates:
(declare-function exwm-workspace-switch "exwm-workspace.el"
(frame-or-index &optional force))
(define-minor-mode exwm-debug
(define-minor-mode exwm-debug-mode
"Debug-logging enabled if non-nil."
:global t
:group 'exwm-debug)
(define-obsolete-function-alias 'exwm-debug 'exwm-debug-mode "0.30")
(defmacro exwm--debug (&rest forms)
"Evaluate FORMS if mode `exwm-debug' is active."
(when exwm-debug `(progn ,@forms)))
"Evaluate FORMS if `exwm-debug-mode' is active."
(when exwm-debug-mode `(progn ,@forms)))
(defmacro exwm--log (&optional format-string &rest objects)
"Emit a message prepending the name of the function being executed.
@ -113,7 +114,7 @@ Here are some predefined candidates:
FORMAT-STRING is a string specifying the message to output, as in
`format'. The OBJECTS arguments specify the substitutions."
(unless format-string (setq format-string ""))
`(when exwm-debug
`(when exwm-debug-mode
(xcb-debug:message ,(concat "%s%s:\t" format-string "\n")
(if exwm-debug-log-time-function
(funcall exwm-debug-log-time-function)
@ -285,7 +286,7 @@ One of `line-mode' or `char-mode'.")
(let ((map (make-sparse-keymap)))
(define-key map "\C-c\C-d\C-l" #'xcb-debug:clear)
(define-key map "\C-c\C-d\C-m" #'xcb-debug:mark)
(define-key map "\C-c\C-d\C-t" #'exwm-debug)
(define-key map "\C-c\C-d\C-t" #'exwm-debug-mode)
(define-key map "\C-c\C-f" #'exwm-layout-set-fullscreen)
(define-key map "\C-c\C-h" #'exwm-floating-hide)
(define-key map "\C-c\C-k" #'exwm-input-release-keyboard)

13
exwm-floating.el
View file

@ -125,13 +125,14 @@ This hook runs in the context of the corresponding buffer."
(declare-function exwm-workspace--update-offsets "exwm-workspace.el" ())
(declare-function exwm-workspace--workarea "exwm-workspace.el" (frame))
(defun exwm-floating--set-allowed-actions (id tilling)
"Set _NET_WM_ALLOWED_ACTIONS."
(defun exwm-floating--set-allowed-actions (id tiled-p)
"Set _NET_WM_ALLOWED_ACTIONS for window with ID.
If TILED-P is non-nil, set actions for tiled window."
(exwm--log "#x%x" id)
(xcb:+request exwm--connection
(make-instance 'xcb:ewmh:set-_NET_WM_ALLOWED_ACTIONS
:window id
:data (if tilling
:data (if tiled-p
(vector xcb:Atom:_NET_WM_ACTION_MINIMIZE
xcb:Atom:_NET_WM_ACTION_FULLSCREEN
xcb:Atom:_NET_WM_ACTION_CHANGE_DESKTOP
@ -466,7 +467,9 @@ This hook runs in the context of the corresponding buffer."
(select-frame-set-input-focus exwm-workspace--current)))
(defun exwm-floating--start-moveresize (id &optional type)
"Start move/resize."
"Start move/resize for window with ID.
When non-nil, TYPE indicates the type of move/resize.
Float resizing is stopped when TYPE is nil."
(exwm--log "#x%x" id)
(let ((buffer-or-id (or (exwm--id->buffer id) id))
frame container-or-id x y width height cursor)
@ -672,7 +675,7 @@ This hook runs in the context of the corresponding buffer."
(setq exwm-floating--moveresize-calculate nil)))
(defun exwm-floating--do-moveresize (data _synthetic)
"Perform move/resize."
"Perform move/resize on floating window with DATA."
(when exwm-floating--moveresize-calculate
(let* ((obj (make-instance 'xcb:MotionNotify))
result value-mask x y width height buffer-or-id container-or-id)

88
exwm-input.el
View file

@ -46,7 +46,6 @@
'(?\C-x ?\C-u ?\C-h ?\M-x ?\M-` ?\M-& ?\M-:)
"List of prefix keys EXWM should forward to Emacs when in `line-mode'.
The point is to make keys like `C-x C-f' forwarded to Emacs in `line-mode'.
There is no need to add prefix keys for global/simulation keys or those
defined in `exwm-mode-map' here."
:type '(repeat key-sequence)
@ -231,7 +230,7 @@ ARGS are additional arguments to CALLBACK."
(xcb:flush exwm--connection))
(defun exwm-input--on-PropertyNotify (data _synthetic)
"Handle PropertyNotify events."
"Handle PropertyNotify events with DATA."
(exwm--log)
(when exwm-input--timestamp-callback
(let ((obj (make-instance 'xcb:PropertyNotify)))
@ -246,7 +245,7 @@ ARGS are additional arguments to CALLBACK."
(defvar exwm-input--last-enter-notify-position nil)
(defun exwm-input--on-EnterNotify (data _synthetic)
"Handle EnterNotify events."
"Handle EnterNotify events with DATA."
(let ((evt (make-instance 'xcb:EnterNotify))
buffer window frame frame-xid edges fake-evt)
(xcb:unmarshal evt data)
@ -292,6 +291,7 @@ ARGS are additional arguments to CALLBACK."
(setq exwm-input--last-enter-notify-position (vector root-x root-y)))))
(defun exwm-input--on-keysyms-update ()
"Update global prefix keys."
(exwm--log)
(let ((exwm-input--global-prefix-keys nil))
(exwm-input--update-global-prefix-keys)))
@ -386,7 +386,8 @@ attempt later."
(xcb:flush exwm--connection)))))))
(defun exwm-input--set-active-window (&optional id)
"Set _NET_ACTIVE_WINDOW."
"Set _NET_ACTIVE_WINDOW.
When non-nil, ID is passed as the window data."
(exwm--log)
(xcb:+request exwm--connection
(make-instance 'xcb:ewmh:set-_NET_ACTIVE_WINDOW
@ -394,7 +395,7 @@ attempt later."
:data (or id xcb:Window:None))))
(defun exwm-input--on-ButtonPress (data _synthetic)
"Handle ButtonPress event."
"Handle ButtonPress event with DATA."
(let ((obj (make-instance 'xcb:ButtonPress))
(mode xcb:Allow:SyncPointer)
button-event window buffer frame fake-last-command)
@ -466,7 +467,7 @@ attempt later."
(run-hooks 'exwm-input--event-hook))
(defun exwm-input--on-KeyPress (data _synthetic)
"Handle KeyPress event."
"Handle KeyPress event with DATA."
(with-current-buffer (window-buffer (selected-window))
(let ((obj (make-instance 'xcb:KeyPress)))
(xcb:unmarshal obj data)
@ -482,7 +483,7 @@ attempt later."
(run-hooks 'exwm-input--event-hook)))
(defun exwm-input--on-CreateNotify (data _synthetic)
"Handle CreateNotify events."
"Handle CreateNotify events with DATA."
(exwm--log)
(let ((evt (make-instance 'xcb:CreateNotify)))
(xcb:unmarshal evt data)
@ -505,6 +506,7 @@ attempt later."
'children))))))
(defun exwm-input--grab-global-prefix-keys (&rest xwins)
"Grab global prefix keys in XWINS."
(exwm--log)
(let ((req (make-instance 'xcb:GrabKey
:owner-events 0
@ -539,6 +541,7 @@ attempt later."
(xcb:flush exwm--connection)))
(defun exwm-input--set-key (key command)
"Set KEY to COMMAND."
(exwm--log "key: %s, command: %s" key command)
(global-set-key key command)
(cl-pushnew key exwm-input--global-keys))
@ -566,9 +569,9 @@ Notes:
;;;###autoload
(defun exwm-input-set-key (key command)
"Set a global key binding.
"Set a global KEY binding to COMMAND.
The new key binding only takes effect in real time when this command is
The new binding only takes effect in real time when this command is
called interactively, and is lost when this session ends unless it's
specifically saved in the Customize interface for `exwm-input-global-keys'.
@ -583,6 +586,7 @@ instead."
(exwm-input--update-global-prefix-keys)))
(defsubst exwm-input--unread-event (event)
"Append EVENT to `unread-command-events'."
(declare (indent defun))
(setq unread-command-events
(append unread-command-events `((t . ,event)))))
@ -602,6 +606,7 @@ instead."
event)
(cl-defun exwm-input--translate (key)
"Translate KEY."
(let (translation)
(dolist (map (list input-decode-map
local-function-key-map
@ -614,7 +619,8 @@ instead."
key)
(defun exwm-input--cache-event (event &optional temp-line-mode)
"Cache EVENT."
"Cache EVENT.
When non-nil, TEMP-LINE-MODE temporarily puts the window in line mode."
(exwm--log "%s" event)
(setq exwm-input--line-mode-cache
(vconcat exwm-input--line-mode-cache (vector event)))
@ -681,9 +687,9 @@ Current buffer must be an `exwm-mode' buffer."
(error-message-string err))
(xcb-debug:backtrace))))
(defun exwm-input--on-KeyPress-line-mode (key-press raw-data)
"Parse X KeyPress event to Emacs key event and then feed the command loop."
(with-slots (detail state) key-press
(defun exwm-input--on-KeyPress-line-mode (keypress raw-data)
"Feed parsed X KEYPRESS event with RAW-DATA to Emacs command loop."
(with-slots (detail state) keypress
(let ((keysym (xcb:keysyms:keycode->keysym exwm--connection detail state))
event raw-event mode)
(exwm--log "%s" keysym)
@ -707,7 +713,7 @@ Current buffer must be an `exwm-mode' buffer."
(xcb:+request exwm--connection
(make-instance 'xcb:SendEvent
:propagate 0
:destination (slot-value key-press 'event)
:destination (slot-value keypress 'event)
:event-mask xcb:EventMask:NoEvent
:event raw-data)))
(when event
@ -722,9 +728,9 @@ Current buffer must be an `exwm-mode' buffer."
:time xcb:Time:CurrentTime))
(xcb:flush exwm--connection))))
(defun exwm-input--on-KeyPress-char-mode (key-press &optional _raw-data)
"Handle KeyPress event in `char-mode'."
(with-slots (detail state) key-press
(defun exwm-input--on-KeyPress-char-mode (keypress &optional _raw-data)
"Handle `char-mode' KEYPRESS event."
(with-slots (detail state) keypress
(let ((keysym (xcb:keysyms:keycode->keysym exwm--connection detail state))
event raw-event)
(exwm--log "%s" keysym)
@ -840,7 +846,8 @@ button event."
;;;###autoload
(defun exwm-input-grab-keyboard (&optional id)
"Switch to `line-mode'."
"Switch to `line-mode`.
When ID is non-nil, grab key events on its corresponding window."
(interactive (list (when (derived-mode-p 'exwm-mode)
(exwm--buffer->id (window-buffer)))))
(when id
@ -851,7 +858,8 @@ button event."
;;;###autoload
(defun exwm-input-release-keyboard (&optional id)
"Switch to `char-mode`."
"Switch to `char-mode`.
When ID is non-nil, release keyboard events on its corresponding window."
(interactive (list (when (derived-mode-p 'exwm-mode)
(exwm--buffer->id (window-buffer)))))
(when id
@ -862,7 +870,8 @@ button event."
;;;###autoload
(defun exwm-input-toggle-keyboard (&optional id)
"Toggle between `line-mode' and `char-mode'."
"Toggle between `line-mode' and `char-mode'.
When ID is non-nil, toggle in its correpsonding window."
(interactive (list (when (derived-mode-p 'exwm-mode)
(exwm--buffer->id (window-buffer)))))
(when id
@ -904,25 +913,24 @@ button event."
(xcb:flush exwm--connection)))
;;;###autoload
(cl-defun exwm-input-send-next-key (times &optional end-key)
"Send next key to client window.
EXWM will prompt for the key to send. This command can be prefixed to send
multiple keys. If END-KEY is non-nil, stop sending keys if it's pressed."
(cl-defun exwm-input-send-next-key (n &optional end-key)
"Send next N keys to client window.
N is currently capped at 12.
EXWM will prompt for the key to send.
If END-KEY is non-nil, stop sending keys if it's pressed."
(interactive "p")
(exwm--log)
(unless (derived-mode-p 'exwm-mode)
(cl-return-from exwm-input-send-next-key))
(when (> times 12) (setq times 12))
(unless (derived-mode-p 'exwm-mode) (cl-return-from exwm-input-send-next-key))
(setq n (min n 12))
(let (key keys)
(dotimes (i times)
(dotimes (i n)
;; Skip events not from keyboard
(let ((exwm-input-line-mode-passthrough t))
(catch 'break
(while t
(setq key (read-key (format "Send key: %s (%d/%d) %s"
(key-description keys)
(1+ i) times
(1+ i) n
(if end-key
(concat "To exit, press: "
(key-description
@ -933,10 +941,11 @@ multiple keys. If END-KEY is non-nil, stop sending keys if it's pressed."
(when (eq key end-key) (cl-return-from exwm-input-send-next-key))
(exwm-input--fake-key key))))
(defun exwm-input--set-simulation-keys (simulation-keys &optional no-refresh)
"Set simulation keys."
(exwm--log "%s" simulation-keys)
(unless no-refresh
(defun exwm-input--set-simulation-keys (keys &optional cache)
"Set simulation KEYS.
If CACHE is non-nil reuse `exwm-input--simulation-keys' cache."
(exwm--log "%s" keys)
(unless cache
;; Unbind simulation keys.
(let ((hash (buffer-local-value 'exwm-input--simulation-keys
(current-buffer))))
@ -949,7 +958,7 @@ multiple keys. If END-KEY is non-nil, stop sending keys if it's pressed."
hash)))
;; Abandon the old hash table.
(setq exwm-input--simulation-keys (make-hash-table :test #'equal)))
(dolist (i simulation-keys)
(dolist (i keys)
(let ((original (vconcat (car i)))
(simulated (cdr i)))
(setq simulated (if (sequencep simulated)
@ -1013,6 +1022,7 @@ Notes:
:type '(repeat function))
(cl-defun exwm-input--read-keys (prompt stop-key)
"Read keys with PROMPT until STOP-KEY pressed."
(let ((cursor-in-echo-area t)
keys key)
(while (not (eq key stop-key))
@ -1026,7 +1036,7 @@ Notes:
;;;###autoload
(defun exwm-input-set-simulation-key (original-key simulated-key)
"Set a simulation key.
"Set ORIGINAL-KEY to SIMULATED-KEY.
The simulation key takes effect in real time, but is lost when this session
ends unless it's specifically saved in the Customize interface for
@ -1069,15 +1079,15 @@ where both ORIGINAL-KEY and SIMULATED-KEY are key sequences."
(exwm-input--set-simulation-keys simulation-keys)))
;;;###autoload
(cl-defun exwm-input-send-simulation-key (times)
"Fake a key event according to the last input key sequence."
(cl-defun exwm-input-send-simulation-key (n)
"Fake N key events according to the last input key sequence."
(interactive "p")
(exwm--log)
(unless (derived-mode-p 'exwm-mode)
(cl-return-from exwm-input-send-simulation-key))
(let ((keys (gethash (this-single-command-keys)
exwm-input--simulation-keys)))
(dotimes (_ times)
(dotimes (_ n)
(dolist (key keys)
(exwm-input--fake-key key)))))

6
exwm-randr.el
View file

@ -264,7 +264,7 @@ In a mirroring setup some monitors overlap and should be treated as one."
(run-hooks 'exwm-randr-refresh-hook))))
(defun exwm-randr--on-ScreenChangeNotify (data _synthetic)
"Handle `ScreenChangeNotify' event.
"Handle `ScreenChangeNotify' event with DATA.
Run `exwm-randr-screen-change-hook' (usually user scripts to configure RandR)."
(exwm--log)
@ -276,7 +276,7 @@ Run `exwm-randr-screen-change-hook' (usually user scripts to configure RandR)."
(run-hooks 'exwm-randr-screen-change-hook)))))
(defun exwm-randr--on-Notify (data _synthetic)
"Handle `CrtcChangeNotify' and `OutputChangeNotify' events.
"Handle `CrtcChangeNotify' and `OutputChangeNotify' events with DATA.
Refresh when any CRTC/output changes."
(exwm--log)
@ -296,7 +296,7 @@ Refresh when any CRTC/output changes."
(setq exwm-randr--last-timestamp timestamp)))))))
(defun exwm-randr--on-ConfigureNotify (data _synthetic)
"Handle `ConfigureNotify' event.
"Handle `ConfigureNotify' event with DATA.
Refresh when any RandR 1.5 monitor changes."
(exwm--log)

2
exwm-xim.el
View file

@ -269,7 +269,7 @@ this client."
(xcb:flush exwm-xim--conn))))
(cl-defun exwm-xim--on-ClientMessage (data _synthetic)
"Handle ClientMessage event on IMS communication window (request).
"Handle ClientMessage event DATA on IMS communication window (request).
Such events would be received when clients request for _XIM_PROTOCOL.
The actual XIM request is in client message data or a property."

11
exwm.el
View file

@ -139,7 +139,7 @@ After this time, the server will be killed.")
"Restart EXWM."
(interactive)
(exwm--log)
(when (exwm--confirm-kill-emacs "Restart?" 'no-check)
(when (exwm--confirm-kill-emacs "Restart" 'no-check)
(let* ((attr (process-attributes (emacs-pid)))
(args (cdr (assq 'args attr)))
(ppid (cdr (assq 'ppid attr)))
@ -976,7 +976,10 @@ FRAME, if given, indicates the X display EXWM should manage."
;;;###autoload
(defun exwm-enable (&optional undo)
"Enable/Disable EXWM."
"Enable/Disable EXWM.
Optional argument UNDO may be either of the following symbols:
- `undo' prevents reinitialization.
- `undo-all' attempts to revert all hooks and advice."
(exwm--log "%s" undo)
(pcase undo
(`undo ;prevent reinitialization
@ -1062,7 +1065,7 @@ FUNCTION is the function to be evaluated, ARGS are the arguments."
;; This is invoked instead of `save-buffers-kill-emacs' (C-x C-c) on client
;; frames.
(if (exwm--terminal-p)
(exwm--confirm-kill-emacs "Kill terminal?")
(exwm--confirm-kill-emacs "Kill terminal")
t))
(defun exwm--confirm-kill-emacs (prompt &optional force)
@ -1087,7 +1090,7 @@ If FORCE is any other non-nil value, force killing of Emacs."
(`break (y-or-n-p prompt))
(x x)))
(t
(yes-or-no-p (format "[EXWM] %d X window(s) will be destroyed. %s"
(yes-or-no-p (format "[EXWM] %d X window(s) will be destroyed. %s?"
(length exwm--id-buffer-alist) prompt))))
;; Run `kill-emacs-hook' (`server-force-stop' excluded) before Emacs
;; frames are unmapped so that errors (if any) can be visible.