-
Notifications
You must be signed in to change notification settings - Fork 3
/
customize-keys.html
393 lines (303 loc) · 12.2 KB
/
customize-keys.html
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
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8"/>
<title>Customizing your keys</title>
<link rel="stylesheet" type="text/less" href="./style/less/o-blog.less"/>
<link rel="stylesheet" type="text/css" href="./style/keys.css"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<meta name="generator" content="o-blog version 1.2-137-gea23db7"/>
<link rel="stylesheet" href="./style/keys.css" type="text/css" />
<script src="./style/js/less-1.3.0.min.js" type="text/javascript"></script>
<script src="./style/js/jquery-1.7.1.min.js" type="text/javascript"></script>
<script src="./style/bootstrap/js/bootstrap-modal.js" type="text/javascript"></script>
<script src="./style/bootstrap/js/bootstrap-transition.js" type="text/javascript"></script>
<script src="./style/bootstrap/js/bootstrap-dropdown.js" type="text/javascript"></script>
<script src="./style/bootstrap/js/bootstrap-collapse.js" type="text/javascript"></script>
<script src="./style/js/prettify.js" type="text/javascript"></script>
<script src="./style/js/o-blog.linenumber.js" type="text/javascript"></script>
<script src="./style/js/o-blog-fix.js" type="text/javascript"></script>
</head>
<body>
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a class="btn btn-navbar" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</a>
<a class="brand" href="./index.html">ergoemacs-mode</a>
<div class="nav-collapse collapse">
<ul>
<li><a href="./features.html"><i>icon-cog icon-white</i> Features</a>
</li>
<li><a href="#"><i>icon-book icon-white</i> Documentation</a>
<ul>
<li><a href="./key-setup.html">Included Key Themes and Keyboard Layouts</a>
</li>
<li><a href="./cua-conflict.html">Preserving Emacs Commands while maintaining familiar shortcuts</a>
</li>
<li>
</li>
<li><a href="./key-themes.html">Key Themes</a>
</li>
<li><a href="./keyboard-layouts.html">Keyboard Layouts</a>
</li>
<li><a href="./minor-modes.html">Changes to Modes</a>
</li>
<li>
</li>
<li><a href="design-basis.html">Design Basis</a>
</li>
<li>
</li>
<li><a href="./faq.html">FAQ</a>
</li>
<li>
</li>
<li><a href="./bug-report.html">Bug report</a>
</li>
</ul>
</li>
<li><a href="#"><i>icon-file icon-white</i> Tips</a>
<ul>
<li><a href="./gradual-adoption.html">Gradual Adoption</a>
</li>
<li><a href="./system-wide.html">System Wide Keys</a>
</li>
<li><a href="./customize-keys.html">Customizing your keys</a>
</li>
<li>
</li>
<li><a href="./aliases.html">Making Commands Easier to Type</a>
</li>
<li><a href="./smart-commands.html">Smart Commands</a>
</li>
</ul>
</li>
<li><a href="./testimonials.html"><i>icon-comments-alt icon-white</i> Testimonials</a>
</li>
<li><a href="./changelog.html"><i>icon-pencil icon-white</i> Changelog</a>
</li>
<li><a href="./roadmap.html"><i>icon-tasks icon-white</i> Roadmap</a>
</li>
</ul>
</div>
</div>
</div>
</div>
<div class="subnav subnav-fixed visible-desktop">
<div class="container">
<ul class="breadcrumb">
<li><a href="./index.html">Home</a> <span class="divider">/</span></li>
<li>Customizing your keys</li>
</ul>
</div>
</div>
<div id="page" class="container">
<article>
<div class="article-content">
<p>
You may want to customize your ergoemacs-mode bindings to fit your
particular workflow. This can be accomplished in many ways,
</p>
<div id="outline-container-1" class="outline-3">
<h3 id="sec-1">Ergoemacs defined keys</h3>
<div class="outline-text-3" id="text-1">
<p>These keys are defined in the <code>ergoemacs-keymap</code>. When the layout
changes by changing options, these keys are lost. However, you may
create your own theme to allow these keys to be saved.
</p>
</div>
<div id="outline-container-1-1" class="outline-4">
<h4 id="sec-1-1">Adding a ergonomic key</h4>
<div class="outline-text-4" id="text-1-1">
<p>Ergonomic keys can be added by:
</p>
<pre class="src src-emacs-lisp">(ergoemacs-key <span style="font-style: italic;">"M-a"</span> 'execute-extended-command <span style="font-style: italic;">"Execute"</span>)
</pre>
<p>
This adds the Alt-a command to all keyboards based on the QWERTY
layout. This only applies to the currently selected keyboard theme.
</p>
<p>
Note the last parameter is optional and allows Ergoemacs to document
that this is an "Execute" command when generating keyboard layout diagrams.
</p></div>
</div>
<div id="outline-container-1-2" class="outline-4">
<h4 id="sec-1-2">Adding a fixed key</h4>
<div class="outline-text-4" id="text-1-2">
<p>Fixed keys can be added by:
</p>
<pre class="src src-emacs-lisp">(ergoemacs-fixed-key <span style="font-style: italic;">"C-o"</span> 'ido-find-file <span style="font-style: italic;">"Open File"</span>)
</pre>
<p>
This adds the fixed key to the currently selected emacs theme
</p>
<p>
Note the last parameter is optional and allows Ergoemacs to document
that this is an "Open" command when generating keyboard layout diagrams.
</p>
</div>
</div>
<div id="outline-container-1-3" class="outline-4">
<h4 id="sec-1-3">Adding an ergonomic key map with fixed mappings</h4>
<div class="outline-text-4" id="text-1-3">
<p>When you want to add an ergonomic keymap with fixed mappings such as
the ergoprog theme you can add them as follows:
</p>
<pre class="src src-emacs-lisp">(ergoemacs-key <span style="font-style: italic;">"M-m s"</span> 'save-buffer <span style="font-style: italic;">""</span> t)
</pre>
<p>
This converts the QWERTY M-m keybinding and the fixed keybinding s to
save buffer
</p></div>
</div>
</div>
<div id="outline-container-2" class="outline-3">
<h3 id="sec-2">Using standard emacs functions</h3>
<div class="outline-text-3" id="text-2">
</div>
<div id="outline-container-2-1" class="outline-4">
<h4 id="sec-2-1">Defining keys globally</h4>
<div class="outline-text-4" id="text-2-1">
<p>Ergoemacs respects emacs globally defined keys. To define a global
key, you can use:
</p>
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"M-a"</span>) 'backward-char)
(global-set-key (kbd <span style="font-style: italic;">"C-a"</span>) 'backward-char)
</pre>
<p>
This uses <a href="http://www.emacswiki.org/emacs/EmacsKeyNotation">emacs key notation</a>. In short <code>M-a</code> represents Alt+a, <code>C-a</code>
represents Ctl+a. For these two examples the key is bound to emacs function
<code>backward-char</code>.
</p>
<p>
When you define a global key that conflicts with ergoemacs-mode
keybindings (after loading ergoemacs-mode) the binding will no longer
active in ergoemacs-mode. Therefore, the binding should be active in
most places in emacs.
</p>
<p>
There is still a possibility that another major or minor mode will
bind the key. If that occurs, you can locally override the bindings.
Assuming this occurs in <code>silly-mode</code>, you can usually override the
settings by setting the keys locally in the major-mode:
</p>
<pre class="src src-emacs-lisp">(add-hook 'silly-mode-hook
(<span style="font-weight: bold;">lambda</span>()
(local-set-key (kbd <span style="font-style: italic;">"C-a"</span>) 'backward-char)))
</pre>
<p>
Also note that the order that you define the global-keys matter when
using <code>ergoemacs-mode</code>. For example, if you decide to change the
global binding before <code>ergoemacs-mode</code> loads, the key definition is
typically ignored when <code>ergoemacs-mode</code> is enabled. For example:
</p>
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"M-a"</span>) 'backward-char)
(<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">ergoemacs-mode</span>)
(ergoemacs-mode 1)
</pre>
<p>
The keyboard definition for <code>backward-char</code> is ignored when
<code>ergoemacs-mode</code> is enabled. However, if you use:
</p>
<pre class="src src-emacs-lisp">(<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">ergoemacs-mode</span>)
(global-set-key (kbd <span style="font-style: italic;">"M-a"</span>) 'backward-char)
(ergoemacs-mode 1)
</pre>
<p>
then ergoemacs-mode will respect the Alt+a backward character
assignment.
</p>
<p>
This behavior allows ergoemacs keybindings to override the keys in an
emacs configuration like prelude, emacs-live, etc. If you do not like
this behavior, you can turn it off by:
</p>
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"M-a"</span>) 'backward-char)
(setq ergoemacs-ignore-prev-global nil) <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Will not ignore any globally</span>
<span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">defined keybinding</span>
(<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">ergoemacs-mode</span>)
(ergoemacs-mode 1)
</pre>
<p>
In this example Alt+a will be bound to <code>backward-char</code> for
ergoemacs-mode as well as globally.
</p>
<p>
If you are loading <code>ergoemacs-mode</code> before loading one of these emacs
settings and you want to <i>ignore</i> the keybindings of the settings,
you can also ignore them by using the following code
</p>
<pre class="src src-emacs-lisp">(global-set-key (kbd <span style="font-style: italic;">"M-a"</span>) 'backward-char)
(<span style="font-weight: bold;">require</span> '<span style="font-weight: bold; text-decoration: underline;">ergoemacs-mode</span>)
(ergoemacs-mode 1)
<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Load starter kit here</span>
<span style="font-weight: bold; font-style: italic;">;; </span><span style="font-weight: bold; font-style: italic;">Ignore starter-kit keys in ergoemacs-mode</span>
(ergoemacs-ignore-prev-global) <span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">Globally defined keys defined</span>
<span style="font-weight: bold; font-style: italic;">; </span><span style="font-weight: bold; font-style: italic;">before this point are ignored</span>
</pre>
<p>
One of the disadvantages of using globally defined keys it they will
be bound globally even if <code>ergoemacs-mode</code> is not active.
Additionally, they are not Layout independent. For example, defining
Alt+j on QWERTY will not change to Alt+n for colemak.
</p></div>
</div>
</div>
</div>
</article>
</div>
<div id="footer">
<div class="container">
<div class="row">
<nav class="span3">
<h1>About</h1>
<p>
This page explains how ergoemacs-mode works. It was written in emacs
org-mode and exported to HTML using <a href="https://github.com/renard/o-blog">o-blog</a>.
</p>
</nav>
<nav id="links" class="span3">
<h1>Links</h1>
<ul>
<ul>
<li><a href="./index.html"><i>icon-home icon-white</i> Home</a>
</li>
</ul>
<ul>
<li><a href="./testimonials.html"><i>icon-comments-alt icon-white</i> Testimonials</a>
</li>
<li><a href="./changelog.html"><i>icon-pencil icon-white</i> Changelog</a>
</li>
<li><a href="./roadmap.html"><i>icon-tasks icon-white</i> Roadmap</a>
</li>
</ul>
</ul>
</nav>
<nav id="archives" class="span3">
<h1><a href="./archives.html">Archives</a></h1>
<ul>
</ul>
</nav>
<nav class="tags span3">
<h1><a href="./tags/index.html">Tags</a></h1>
<ul>
</ul>
</nav>
</div>
</div>
<div class="copyright" style="text-align: center;">
<p>
Documentation Copyright © 2007-2013 Matthew Fidler, Xah Lee and David
Capello. Published under the therm of the <a href="http://creativecommons.org/licenses/by-nc-sa/2.0/fr/">Creative Commons Attribution-Noncommercial-Share Alike 2.0 France License</a>. Code
published under <a href="http://www.gnu.org/licenses/gpl-2.0.html">GPL v2</a>.
</p>
<p>Powered by <a href="https://github.com/renard/o-blog">o-blog</a>.</p>
</div>
</div>
</body>
</html>