Permalink
Newer
Older
100644 393 lines (267 sloc) 15.8 KB
Oct 28, 2010
1
# Workgroups for Windows (for Emacs)
Nov 11, 2010
3
It's tedious setting Emacs' window layout just the way you like it -- splitting
Nov 11, 2010
4
windows, adjusting their size, switching to the right buffers, etc. And even
Nov 11, 2010
5
when it *is* set, it won't stay that way for long. On top of that, you can't
Nov 11, 2010
6
save your window-configurations to disk, so you have to start over from scratch
Nov 11, 2010
7
every time you restart Emacs.
8
Nov 11, 2010
9
There are solutions out there to parts of the problem -- elscreen, revive.el,
Nov 11, 2010
10
window-configuration-to-register, etc. -- but none provide a complete solution.
11
Workgroups does.
12
Nov 11, 2010
13
With Workgroups, you can:
15
- Store an unlimited number of window configs
Nov 11, 2010
16
17
- Save window configs to disk, and load them from disk
18
19
- Kill and yank window configs
20
21
It also provides:
22
23
- Animated window config morphing
24
25
- Frame reversing and window movement
26
27
- A concept of "base" and "working" configs, for maximum flexibility
28
29
- Lots of other stuff
30
31
32
## Background
33
34
Workgroups is a window configuration management package for GNU Emacs. Here's
35
what the Elisp info docs have to say about window configurations `(info
36
"(Elisp)Window Configurations")`:
37
38
> A "window configuration" records the entire layout of one frame--all windows,
39
> their sizes, which buffers they contain, how those buffers are scrolled, and
40
> their values of point and the mark; also their fringes, margins, and scroll
41
> bar settings. It also includes the value of `minibuffer-scroll-window'. As a
42
> special exception, the window configuration does not record the value of point
43
> in the selected window for the current buffer. Also, the window configuration
44
> does not record the values of window parameters; see *Note Window
45
> Parameters::.
46
47
The problem with Emacs' window configurations is that they're opaque C types:
48
you can't peer inside them. To get at the information in a window
49
configuration, you must restore it in a frame, then access that frame's
50
parameters.
51
52
Here's what the same info node has to say about window configuration opacity:
53
54
> Other primitives to look inside of window configurations would make sense, but
55
> are not implemented because we did not need them.
57
Workgroups solves this problem by implementing an independent window
58
configuration object. Workgroups' window configurations (called "wconfigs")
59
save all the settings listed above, and more. For instance, if a region is
60
highlighted in `transient-mark-mode`, that region will still be highlighted
61
after restarting Emacs and restoring that wconfig. They also save frame
62
position and size. And wconfigs can be constructed and manipulated
63
programatically, without the need to restore them in a live frame, enabling
64
things like frame morphing, window moving, frame reversing and other operations.
Oct 28, 2010
67
## Getting Workgroups
Oct 28, 2010
69
The latest version of Workgroups can always be found
70
[here](http://github.com/tlh/workgroups.el). You can clone the repo by running:
Oct 28, 2010
72
git clone git://github.com/tlh/workgroups.el
74
Workgroups is being actively developed. Later on, when you want to update to
75
the latest:
76
77
git fetch
78
git merge origin
79
Oct 28, 2010
81
## Installation
82
83
- Put `workgroups.el` somewhere on your Emacs load path
84
85
- Byte-compile `workgroups.el`. This isn't required, but it'll speed some
Nov 11, 2010
86
things up:
Oct 28, 2010
87
88
M-x byte-compile-file RET /path/to/workgroups.el RET
89
90
- Add this line to your `.emacs` file:
91
92
(require 'workgroups)
93
94
95
## Configuration
96
97
- Set your prefix key (or not). The prefix key for Workgroups' commands
98
defaults to `C-z`. You could set it to `C-c w` like this:
Oct 28, 2010
99
100
(setq wg-prefix-key (kbd "C-c w"))
101
102
Workgroups saves the prefix key's current definition when it's enabled, and
103
restores it when it's disabled, so you don't have to worry about stomping
104
keydefs if you want to try out different prefixes.
Oct 28, 2010
105
106
Most commands are bound to both `<prefix> <key>` and `<prefix> C-<key>` for
107
convenience. See the definition of `wg-map` in the source for a complete list
108
of bindings.
Nov 4, 2010
109
110
- There are many other customization options. See the customization section in
111
the source for details, or use:
Oct 28, 2010
112
113
M-x customize-group RET workgroups RET
114
115
116
## Usage
117
118
- Turn on `workgroups-mode` either by issuing the command:
119
120
M-x workgroups-mode RET
121
122
or by evaluating this form, which can be added to your `.emacs` file:
Oct 28, 2010
123
124
(workgroups-mode 1)
125
126
You should see "wg" in the minor mode list on the mode-line.
127
128
- To get started right away, hit `<prefix> ?` for a list of commands and their
129
bindings.
Oct 28, 2010
130
131
132
## Tutorial
133
134
### Workgroup Creation
135
136
To start off, add a few workgroups. Hit `<prefix> c` to issue the command
137
`wg-create-workgroup`, give it a name, hit `RET`, and a new workgroup is
138
created. Maybe split the screen a few times with `C-x 2` and `C-x 3`, and
139
switch to different buffers in some of the windows to make it unique. Repeat
140
this process a few times to create some different workgroups.
Oct 28, 2010
141
142
Every workgroup must have a unique name. You can rename workgroups after
143
they've been created with `<prefix> A` (`wg-rename-workgroup`).
Nov 4, 2010
144
Oct 28, 2010
145
146
### Workgroup Switching
147
148
`<prefix> v` issues the command `wg-switch-to-workgroup`. This will do a
149
completing-read (with
150
[ido](http://www.emacswiki.org/emacs/InteractivelyDoThings) if it's enabled) on
151
the available workgroup names, and switch to the workgroup with that name.
152
`<prefix> n` will switch to the workgroup rightward in the workgroups list from
153
the current workgroup, and `<prefix> p` will switch to the one leftward in the
154
list. `<prefix> 0` through `<prefix> 9` switch to the workgroup at that
155
position in the workgroups list. Try switching between your workgroups now.
Oct 28, 2010
156
157
Nov 4, 2010
158
### Morph
159
160
After you've switched between workgroups, you'll notice that Workgroups animates
161
the transition between wconfigs. "Morph" reuses whatever tree structure the two
162
window trees have in common, sliding in or wiping subtrees as necessary to
163
complete the transformation. You can toggle it off and on with `<prefix> w`
164
(`wg-toggle-morph`), or you can set the value of `wg-morph-on` to t or nil to
165
turn it on or off permenently.
166
167
There are a couple variables that determine morph speed. `wg-morph-hsteps` and
168
`wg-morph-vsteps` control the number of columns and lines respectively that
169
window boundaries move for each step of the morph transition. The defaults for
170
these are a little low, so that you can see what morph is doing. You can set
171
them as high as you like, but values less than 1 are invalid.
172
173
There are separate horizontal and vertical step values used in terminal frames
174
(`wg-morph-terminal-hsteps` and `wg-morph-terminal-vsteps`). This is because
175
Emacs' `redisplay` is usually significanly faster on local terminal frames, so
176
morphing can happen too fast to see at values appropriate for GUI frames. If
177
they are set, their values are used in terminal frames. If they are nil, the
178
step values default to `wg-morph-hsteps` and `wg-morph-vsteps`.
179
180
*NOTE on morphing in xterm*
181
182
xterm has some wierd redisplay issues:
183
184
- An unset background color can cause *extremely* slow `redisplay` in xterm. So
185
if:
186
187
(frame-parameter (selected-frame) 'background-color)
188
189
returns:
190
191
=> "unspecified-bg"
192
193
you may run into this.
194
195
- Very large terminal geometries (270x70 or higher) can also cause very slow
196
`redisplay` in xterm. Until I figure out the best way to handle this, you
197
should just see what works, and either set your background color or turn off
198
morphing with:
Nov 4, 2010
201
202
Oct 28, 2010
203
### Base and Working Configs
204
205
Window configs drift through use. Windows get resized; different buffers get
206
selected; point and mark change, and so on. When you switch from one workgroup
207
to another, then back to the first, you want it to be in the same state that you
208
left it in so you don't lose your place. At the same time, it can be tedious
209
getting the window configuration just the way you like it, and it sucks when it
210
gets mangled, so it'd be nice to be able to revert it back to a known-good state
211
at any time.
212
213
For this reason, every workgroup actually consists of two wconfigs: a base
214
config and a working config [1]. The base config is the pristine original
215
wconfig, set exactly the way you like it. And the working config is whatever
216
the frame happens to look like while you're using it [2]. The base config only
217
gets altered explicitly, and you can revert back to it at any time. Use
218
`<prefix> r` (`wg-revert-workgroup`) to revert the working config to the base
219
config. The opposite of reverting is updating. `<prefix> u`
220
(`wg-update-workgroup`) updates the base config with the current working config.
221
222
So the two commands are mirror images of each other: the former sets the working
223
config to the base config (reverting the working config), and the latter sets
224
the base config to the working config (updating the base config). You can
225
revert all workgroups' working configs to their base configs with `<prefix> R`
226
(`wg-revert-all-workgroups`), and you can update all workgroups' base configs to
227
their working configs with `<prefix> U` (`wg-update-all-workgroups`). Update
228
all your workgroups with `<prefix> U` now.
229
230
It's important to understand that you never actually *use* the base config --
231
only the working config. The base config sits in the background, and can only
232
be modified with explicit updates.
233
234
[1] That's not entirely true: working configs are actually properties of frames,
235
so every frame has its own working config for each workgroup. This is because
236
when working with multiple frames, one expects the working config to remain the
237
same in that frame. If you move to another frame and modify a workgroup's
238
working config, then switch back to the first frame, it doesn't feel right when
239
the working config has changed while you were gone. This may seem complicated,
240
but in practice it's very natural. There's only one base config per workgroup,
241
though -- they're the same across all frames.
242
243
[2] Workgroups updates working configs lazily: it doesn't update the working
244
config every time changes are made to the frame -- only when the working config
245
is requested by a function. This produces the same behavior as more tedious
246
perpetual updates, but much simpler code.
Oct 28, 2010
247
248
249
### Saving and Loading
250
251
Saving and loading was the original motivation for writing Workgroups. You can
252
save your workgroups to a file with `<prefix> C-s` (`wg-save`) and you can load
253
workgroups from a file with `<prefix> C-l` (`wg-load`). Save your workgroups
254
now.
Oct 28, 2010
255
256
Once you have a file of saved workgroups, it's convenient to load it on Emacs
257
startup. To do so you can add a line like this to your `.emacs`:
Oct 28, 2010
258
259
(wg-load "/path/to/saved/workgroups")
260
261
So your final `.emacs` setup may look something like this:
262
263
(add-to-list 'load-path "/path/to/workgroups.el")
264
(require 'workgroups)
265
(setq wg-prefix-key (kbd "C-c a"))
266
(workgroups-mode 1)
267
(wg-load "/path/to/saved/workgroups")
Oct 28, 2010
268
269
The customization variable `wg-switch-on-load` controls whether to automatically
270
switch to the first workgroup in a file when the file is loaded. It defaults to
271
`t`, so when you add the above to your `.emacs` file, the first workgroup in the
272
file will automatically be switched to on Emacs startup.
Oct 28, 2010
275
### Killing and Yanking
276
277
You can kill workgroups with `<prefix> k` (`wg-kill-workgroup`). Killing a
278
workgroup deletes it from the list of workgroups, and copies its working config
279
to the kill ring. You can yank killed wconfigs into the current frame with
280
`<prefix> y` (`wg-yank-config`). If the last command was `wg-yank-config`,
281
calling it again will yank the *next* wconfig in the kill ring, and so on, much
282
like Emacs' own kill ring.
Nov 4, 2010
283
284
You can save a wconfig to the kill ring without killing its workgroup with the
285
kill-ring-save commands. `<prefix> M-w` (`wg-kill-ring-save-working-config`)
286
saves the working config to the kill ring, and `<prefix> M-W`
287
(`wg-kill-ring-save-base-config`) saves the base config to the kill ring.
288
289
`<prefix> M-k` (`wg-kill-workgroup-and-buffers`) kills a workgroup, and all the
290
buffers visible in it, and `<prefix> K` (`wg-delete-other-workgroups`) deletes
291
all but the current workgroup.
Oct 28, 2010
292
293
294
### Cloning
295
296
Cloning a workgroup creates a new workgroup under a different name with the a
297
copy of the current workgroup's base and working configs. `<prefix> C`
298
(`wg-clone-workgroup`) will clone the current workgroup.
Oct 28, 2010
299
300
301
### Offsetting and Swapping
302
303
You can move a workgroup leftward or rightward in the workgroups list with
304
`<prefix> ,` (`wg-offset-left`) and `<prefix> .` (`wg-offset-right`)
305
respectively. These commands work cyclically, so when you offset a workgroup
306
leftward or rightward when it's already on the far left or right of the list, it
307
will wrap around to the other side.
Nov 4, 2010
308
309
`<prefix> x` (`wg-swap-workgroups`) will swap the position in the workgroups
310
list of the previously selected workgroup with that of the current workgroup.
Oct 28, 2010
311
312
313
### Switching to Buffers
314
315
You can switch to workgroups based on the buffers that are visible in them with
316
`<prefix> b` (`wg-get-by-buffer`). Workgroups constructs the list of available
317
buffer names from the workgroups list, so it's possible to switch to a workgroup
318
determined from a buffer file-name that hasn't been visited yet, if you haven't
319
switched to that workgroup yet in your current Emacs session.
Oct 28, 2010
320
321
322
### Messaging
323
324
Workgroups has commands to display various bits of information in the echo-area,
325
like the current workgroup name, the list of workgroups, the current time, etc.
326
The help buffer has a complete list (see the Help section below).
Oct 28, 2010
327
328
329
### Help
330
331
To bring up a help buffer listing all the commands and their bindings, hit
332
`<prefix> ?` (`wg-help`).
Oct 28, 2010
333
334
335
## FAQ
336
337
**Q:** Does Workgroups for Windows have anything to do with Microsoft Windows
338
for Workgroups?
339
**A:** Nope.
340
341
**Q:** Why is it called "Workgroups"?
342
**A:** Mostly because it's funny, but it also makes sense. I needed a name that
343
would also work for the collections of wconfigs being manipulated. Elscreen
344
has "screens", which works well. I couldn't call them "window configurations"
345
because it's too long, and Emacs already uses that for something else. It'd
346
be misleading, too, since a workgroup is actually a named set of multiple
347
wconfigs (one base config, and then a working config for each frame).
348
"Workgroup" seemed like a good name for such a collection of window
349
configurations, and, thanks to Microsoft, the word "workgroups" is already
350
associated with the word "windows". So "Workgroups" it is. I'll have to do
351
something special for the 0.3.11 release.
Oct 28, 2010
352
353
**Q:** Why should I use Workgroups instead of Elscreen?
354
**A:** Workgroups provides persistence, base and working configs, morphing,
355
frame-reversing and other chrome, unlimited workgroups per frame and cleaner
358
**Q:** What's the difference between a "window configuration", a "wconfig" and a
359
"workgroup"?
360
**A:** A "window configuration" is Emacs' opaque internal representation of most
361
of the state of one frame. A "wconfig" is Workgroups' independent,
362
translucent window configuration object. And a "workgroup" is a named set of
363
multiple wconfigs (one base config, and then a working config for each frame).
364
365
366
## Feature Requests
367
368
Feature requests, like other parameters you'd like Workgroups to persist, should
369
be added to the [wiki](http://github.com/tlh/workgroups.el/wiki)
370
371
372
## Reporting Bugs
373
374
If you encounter a bug in Workgroups, please file an issue
375
[here](http://github.com/tlh/workgroups.el/issues). If possible, please include
Nov 11, 2010
376
a stack-trace and the value of `wg-list`.
Oct 28, 2010
379
## A Note On Application Buffers
381
Workgroups doesn't currently save the state of applications like ERC or Gnus,
382
though this is on the TODO list. If you save a workgroup that includes
383
application buffers, and then you restore that workgroup in another Emacs
384
session before relaunching those applications and buffers, Workgroups will just
385
default to `*scratch*`. To get back to your saved state, launch those
386
applications and buffers and hit `<prefix> R` to `wg-revert-all-workgroups`.
388
389
## License
390
391
Copyright (C) 2010 tlh Workgroups for Windows (for Emacs) is released under the
392
GPL. See the file `workgroups.el`.