File: readme.md

package info (click to toggle)
emacs-window-layout 1.4-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 104 kB
  • sloc: lisp: 663; sh: 36; makefile: 2
file content (135 lines) | stat: -rw-r--r-- 3,900 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
# window-layout management library

Split a frame or window into some windows according to a layout recipe.

## Example

```el
;; Layout function
; -> three pane layout.
(setq wm ; <-- window management object
      (wlf:layout 
       '(| (:left-size-ratio 0.3) 
           folder 
           (- (:upper-max-size 15) 
              summary 
              message))
       '((:name folder 
          :buffer "folder buffer")
         (:name summary
          :buffer "summary buffer")
         (:name message
          :buffer "message buffer")
        )))

;; Window controlling
(wlf:show    wm 'summary)
(wlf:hide    wm 'summary)
(wlf:toggle  wm 'summary)
(wlf:select  wm 'summary)
(wlf:toggle-maximize  wm 'summary)

;; Window updating
(wlf:refresh wm)
(wlf:reset-window-sizes wm)
(wlf:reset-init wm)

;; Accessing a buffer
(wlf:get-buffer wm 'summary) ; -> <#buffer object or buffer name>
(wlf:set-buffer wm 'summary "*scratch*")

;; Accessing a window
(wlf:get-window wm 'summary) ; -> <#window object>

;; Layout hook
(defun wlf:test-hook (wset) (message "HOOK : %s" wset))
(wlf:layout-hook-add wm 'wlf:test-hook)
(wlf:layout-hook-remove wm 'wlf:test-hook)
```

## API Document

### Layout function

- `wlf:layout`
    - Lay out windows and return a management object.
    - Arguments: (see the following sections)
        - recipe : layout recipe list
        - window-params : window options
        - subwindow-p : optional flag
    - Return
        - a wset object, the window management object
- `wlf:no-layout`
    - Just return a management object, does not change window layout.
    - The arguments and return value are the same as `wlf:layout` ones.

#### Layout recipe:

```
( (split type) (split option) 
               (left window name or recipe)
               (right window name or recipe) )
```

- **split type**
    - `-` : split vertically
    - `|` : split horizontally
- **split option** (the prefix 'left' can be replaced by 'right', 'upper' and 'lower'.)
    - `:left-size`  (column or row number) window size
    - `:left-max-size`  (column or row number) if window size is larger than this value, the window is shrunken.
    - `:left-size-ratio`  (0.0 - 1.0) window size ratio. the size of the other side is the rest.

Note: 
- The split option can be omitted.
- The size parameters, `:size`, `:max-size` and `:size-ratio`, are mutually exclusive.
- The size of a window is related with one of the other side window. So, if both side windows set conflict size parameters, the window size may not be adjusted as you write.

#### Window options:

- `:name`  the window name.
- `:buffer` a buffer name or a buffer object to show the window. If nil or omitted, the current buffer remains.
- `:default-hide`  (t/nil) if t, the window is hided initially. (default: nil)
- `:fix-size`  (t/nil) if t, when the windows are laid out again, the window size is remained. (default: nil)

#### subwindow-p option:

If this option is not nil, this function splits the windows within
the current window. If this option is nil or omitted, this function
uses the entire space of the current frame. Because some user
actions and complicated window layouts may cause unexpected split
behaviors, it is easy to use the entire space of a frame.

#### Return value (Window management object):

You should not access the management object directly, because it is not 
intended direct access.
You can make some management objects to switch the window layout.

### Access functions

- `wlf:get-buffer`
- `wlf:set-buffer`
- `wlf:wset-live-p`

### Control functions

- `wlf:refresh`
- `wlf:reset-window-sizes`
- `wlf:reset-init`
- `wlf:show`
- `wlf:hide`
- `wlf:toggle`
- `wlf:toggle-maximize`
- `wlf:select`

### Layout hook

After splitting windows, registered hook are called with one
argument, the window management object.

- `wlf:layout-hook-add`
- `wlf:layout-hook-remove`

## License

GPLv3