Skip to content

Commit

Permalink
Add docstrings for all the commands
Browse files Browse the repository at this point in the history
  • Loading branch information
mwitmer committed Feb 4, 2014
1 parent 561bfb6 commit b952d40
Show file tree
Hide file tree
Showing 11 changed files with 90 additions and 5 deletions.
21 changes: 18 additions & 3 deletions guile-wm.texi
Original file line number Diff line number Diff line change
Expand Up @@ -1322,6 +1322,21 @@ is canceled, the return value is unspecified.
An X11 font string that specifies the font used to display the minibuffer
@end deffn

@code{minibuffer} also exports some commands that use the minibuffer:

@deffn{Command} prompt-for-eval
Prompt for a Guile scheme expression, evaluate it, and display the
result.
@end deffn

@deffn{Command} prompt-for-command
Prompt for a Guile-WM command and run it.
@end deffn

@deffn{Command} prompt-for-shell-command
Prompt for a shell command and run it.
@end deffn

@node Randr
@section Randr

Expand Down Expand Up @@ -1359,7 +1374,7 @@ Set the resolution of randr output @var{output} to (@var{width}, @var{height}).
@end deffn

@deffn{Command} set-offset! (output #:string) (x #:number) (y #:number)
Set the resolution of randr output @var{output} to (@var{x}, @var{y}).
Set the offset of randr output @var{output} to (@var{x}, @var{y}).
@end deffn

@deffn{Command} disable-screen! (output #:string)
Expand All @@ -1369,7 +1384,7 @@ Disable randr output @var{output}.
@deffn{Command} rotate-screen! (output #:string) (rotation #:symbol)

Set the rotation of randr output @var{output} to @var{rotation}, which
can be any one of the following:
can be any one of the following symbols:

@code{rotate-0}, @code{reflect-x}, @code{reflect-y}, @code{rotate-90},
@code{rotate-270}, or @code{rotate-180}.
Expand Down Expand Up @@ -1630,7 +1645,7 @@ Bring the bottom-most X window to the front and give it the input focus.

@deffn{Command} visible-window-cycle
Bring the bottom-most visible X window to the front and give it the
input focus.
input focus. Requires window reparenting to work properly.
@end deffn

@node Window Menu
Expand Down
9 changes: 9 additions & 0 deletions module/guile-wm/command.scm
Original file line number Diff line number Diff line change
Expand Up @@ -76,20 +76,29 @@
(backtrace))))

(define-command (quit)
"Quit the window manager and close the connection to the X
server. Replaces the core binding of the same name."
(when (and (current-xcb-connection) (xcb-connected? (current-xcb-connection)))
(log! (format #f "Quitting Guile-WM"))
(xcb-disconnect! (current-xcb-connection))))

(define-command (shell-command commands #:string)
"Concatenate COMMANDS into a single string and execute the result in
a detached process."
(close-port (open-pipe (string-join commands) OPEN_READ)))

(define-command (shell-command-output cmd #:string)
"Concatenate COMMANDS into a single string and execute the result
in a process; wait for the command to terminate and return a string
containing its output."
(let* ((port (open-input-pipe (string-join cmd)))
(str (read-delimited "" port)))
(close-pipe port)
str))

(define-command (wm-eval (exp #:string))
"Evaluate S-expression @var{exp} in the window manager's current
environment."
(catch #t
(lambda ()
(with-input-from-string exp
Expand Down
2 changes: 2 additions & 0 deletions module/guile-wm/module/cursor.scm
Original file line number Diff line number Diff line change
Expand Up @@ -110,4 +110,6 @@
cursor)

(define-command (set-cursor! (cursor #:symbol))
"Set the cursor to the X11 cursor glyph associated with the symbol
CURSOR in `x-cursors'."
(change-window-attributes (current-root) #:cursor (make-cursor cursor)))
2 changes: 2 additions & 0 deletions module/guile-wm/module/fullscreen.scm
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,8 @@
(find-dimens (cdr possible)))))))

(define-command (fullscreen)
"Resize the focused window to take up the whole screen (or output, if
randr is enabled)."
(define (fullscreen-it win)
(with-replies ((geom get-geometry win))
(define border (* 2 (xref geom 'border-width)))
Expand Down
7 changes: 7 additions & 0 deletions module/guile-wm/module/message.scm
Original file line number Diff line number Diff line change
Expand Up @@ -37,18 +37,25 @@
(if hide-message-thread (cancel-thread hide-message-thread)))

(define-command (message msg #:string)
"Display MSG in the upper right hand corner of the screen. It will
disappear after eight seconds."
(message-with-timeout (string-join msg) message-default-timeout))

(define-command (message-with-timeout (msg #:string) (timeout #:number))
"Display MSG in the upper right hand corner of the screen for
TIMEOUT seconds."
(show-message msg)
(set!
hide-message-thread
(make-thread (lambda () (sleep timeout) (hide-message)))))

(define-command (sticky-message msg #:string)
"Display MSG in the upper right hand corner of the screen until the
message window is hidden or a new message is displayed"
(show-message (string-join msg)))

(define-command (hide-message)
"Hide the message window"
(unmap-window message-window)
(if hide-message-thread (cancel-thread hide-message-thread))
(set! hide-message-thread #f))
Expand Down
4 changes: 4 additions & 0 deletions module/guile-wm/module/minibuffer.scm
Original file line number Diff line number Diff line change
Expand Up @@ -123,13 +123,17 @@
(minibuffer (format #f "~a [~a]: " arg-name (keyword->symbol type))))

(define-command (prompt-for-eval)
"Prompt for a Guile scheme expression, evaluate it, and display the
result."
(minibuffer "eval: " (lambda (cmd) (message (format #f "~a" (wm-eval cmd))))))

(define-command (prompt-for-command)
"Prompt for a Guile-WM command and run it."
(define cmd (minibuffer "command: "))
(if (not (unspecified? cmd)) (run-command cmd get-additional-arg)))

(define-command (prompt-for-shell-command)
"Prompt for a shell command and run it."
(minibuffer "/usr/bin/sh -c: " shell-command))

(define-once minibuffer-window #f)
Expand Down
8 changes: 8 additions & 0 deletions module/guile-wm/module/randr.scm
Original file line number Diff line number Diff line change
Expand Up @@ -64,15 +64,23 @@
(define-command (set-resolution! (output #:string)
(width #:number)
(height #:number))
"Set the resolution of randr output OUTPUT to (WIDTH, HEIGHT)."
(resolution output width height))

(define-command (set-offset! (output #:string) (x #:number) (y #:number))
"Set the offset of randr output OUTPUT to (X, Y)."
(offset output x y))

(define-command (disable-screen! (output #:string))
"Disable randr output OUTPUT."
(disable output))

(define-command (rotate-screen! (output #:string) (rotation #:symbol))
"Set the rotation of randr output OUTPUT to ROTATION, which
can be any one of the following symbols:
`rotate-0, `reflect-x', `reflect-y', `rotate-90',
`rotate-270', or `rotate-180'."
(rotate output rotation))

(define (mode-pair mode-info) (cons (xref mode-info 'id) mode-info))
Expand Down
6 changes: 5 additions & 1 deletion module/guile-wm/module/root-keymap.scm
Original file line number Diff line number Diff line change
Expand Up @@ -42,9 +42,11 @@
(define-public root-key (make-procedure-with-setter root-key-ref root-key-set!))

(define-command (bind-root-key! (key #:symbol) (str #:string))
"Bind KEY to command string STR in the root keymap."
(bind-key-command! root-keymap key str))

(define-command (unbind-root-key! (key #:symbol))
"Remove the binding for KEY in the root keymap."
(unbind-key! root-keymap key))

(define (run-keymap get)
Expand Down Expand Up @@ -77,7 +79,9 @@ keymap while minibuffers, menus, and so on are active."
(get-later process-root-key))
(get-later process-root-key))

(define-command (set-root-key! (key #:symbol)) (set! (root-key) key))
(define-command (set-root-key! (key #:symbol))
"Set the root key to KEY."
(set! (root-key) key))

(define-public keymap-cursor
(make-procedure-with-setter
Expand Down
28 changes: 28 additions & 0 deletions module/guile-wm/module/tiling.scm
Original file line number Diff line number Diff line change
Expand Up @@ -519,52 +519,76 @@
;; about their X windows, not the tile abstraction used internally

(define-command (horizontal-split)
"Split the selected tile in half horizontally. The left new tile
will be selected and store the contents of the original tile."
(split-tile-horizontal! selected-tile))

(define-command (vertical-split)
"Split the selected tile in half vertically. The top new tile will
be selected and store the contents of the original tile."
(split-tile-vertical! selected-tile))

(define-command (select-down)
"Select the tile below the currently selected tile, if one exists"
(and=> (tile-below selected-tile) select-tile))

(define-command (select-up)
"Select the tile above the currently selected tile, if one exists"
(and=> (tile-above selected-tile) select-tile))

(define-command (select-left)
"Select the tile to the left of the currently selected tile, if one
exists"
(and=> (tile-to-left selected-tile) select-tile))

(define-command (select-right)
"Select the tile to the right of the currently selected tile, if one
exists"
(and=> (tile-to-right selected-tile) select-tile))

(define-command (move-right)
"Move the contents of the selected tile to the tile to the right, if
one exists, and select it"
(and-let* ((new-tile (tile-to-right selected-tile)))
(move-tile selected-tile new-tile)))

(define-command (move-left)
"Move the contents of the selected tile to the tile to the left, if
one exists, and select it"
(and-let* ((new-tile (tile-to-left selected-tile)))
(move-tile selected-tile new-tile)))

(define-command (move-up)
"Move the contents of the selected tile to the tile above, if one
exists, and select it"
(and-let* ((new-tile (tile-above selected-tile)))
(move-tile selected-tile new-tile)))

(define-command (move-down)
"Move the contents of the selected tile to the tile below, if one
exists, and select it"
(and-let* ((new-tile (tile-below selected-tile)))
(move-tile selected-tile new-tile)))

(define-command (grow-window-vertical)
"Increase the the height of the selected tile"
(resize-tile-in-context! selected-tile 'vertical +))

(define-command (grow-window-horizontal)
"Increase the the width of the selected tile"
(resize-tile-in-context! selected-tile 'horizontal +))

(define-command (shrink-window-vertical)
"Decrease the the height of the selected tile"
(resize-tile-in-context! selected-tile 'vertical -))

(define-command (shrink-window-horizontal)
"Decrease the the width of the selected tile"
(resize-tile-in-context! selected-tile 'horizontal -))

(define-command (clear-frame)
"Delete all the tiles in the current frame and replace them with one
tile holding the window that was in the selected tile"
(let* ((current-frame (frame-of selected-tile))
(new-tile (make-tile
(frame-height current-frame)
Expand All @@ -579,10 +603,12 @@
(select-tile new-tile)))

(define-command (reveal-window)
"Place the next hidden window in the queue into the current tile"
(pop-and-unhide-x-window! selected-tile)
(select-tile selected-tile))

(define-command (restore-window)
"Place the most recently hidden window into the current tile"
(define most-recent (most-recent-x-window))
(cond
(most-recent
Expand All @@ -596,6 +622,8 @@
(select-tile selected-tile))))

(define-command (delete-split)
"Delete the tile that is split with the selected one and replace
them both with one tile containing the selected tile's contents"
(define container (tile-container selected-tile))
(if (frame? container) #f
(let ((new-tile
Expand Down
1 change: 1 addition & 0 deletions module/guile-wm/module/time.scm
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@
(11 . Dec)))

(define-command (show-time)
"Display a message with the current date and time"
(define tm (localtime (current-time)))
(message (format #f "~2,,,'0@a:~2,,,'0@a:~2,,,'0@a ~a ~a ~a"
(tm:hour tm)
Expand Down
7 changes: 6 additions & 1 deletion module/guile-wm/module/window-cycle.scm
Original file line number Diff line number Diff line change
Expand Up @@ -46,8 +46,13 @@
set-focus)
(set-focus (car windows))))))

(define-command (window-cycle) (basic-window-cycle (lambda (win) #t)))
(define-command (window-cycle)
"Bring the bottom-most X window to the front and give it the input
focus."
(basic-window-cycle (lambda (win) #t)))

(define-command (visible-window-cycle)
"Bring the bottom-most visible X window to the front and give it the
input focus. Requires window reparenting to work properly."
(basic-window-cycle
(lambda (win) (not (window-obscured? win)))))

0 comments on commit b952d40

Please sign in to comment.