(JC3-63EE): Map to U+8910 instead of U+FA60.
[chise/xemacs-chise.git.1] / man / new-users-guide / custom1.texi
1 @comment  node-name,  next,  previous,  up
2 @node Customization Basics, Help, Edit, Top
3 @chapter Customize key bindings and menus 
4 @cindex init.el
5 @cindex customize
6 @findex eval-region
7
8 When you start Emacs, it reads the file @file{~/.xemacs/init.el} in the
9 @file{.xemacs/} subdirectory of your home directory. You can use this
10 file to initialize and customize Emacs to your liking. This file should
11 contain lisp-code. You can customize your @file{init.el} file to create
12 new menus, disable menus, change key bindings, enable a minor mode,
13 etc. Any kind of customization affects only a particular Emacs job that
14 you do them in. If you want to save your customizations `permanently'
15 i.e. for future use also, you have to put it in your @samp{init.el}
16 file. After you make changes to your @file{init.el} file and save it, the
17 changes will be effective only after you start Emacs again i.e. for a
18 new Emacs process. To try out some of the examples in this section,
19 highlight that region and evaluate the region by giving the command
20 @kbd{M-x eval-region}. You will be able to see the results of your
21 customizations in that Emacs session only (@pxref{Lisp
22 Eval,,,xemacs,XEmacs User's Manual}).
23
24 @comment  node-name,  next,  previous,  up
25 @menu
26 * Customizing key Bindings::    Changing Key Bindings
27 * Customizing Menus::           Adding, Deleting, Enabling and Disabling Menus
28 @end menu
29
30 @node Customizing key Bindings, Customizing Menus, Customization Basics, Customization Basics
31 @section Customize key bindings 
32 @cindex key bindings
33 @cindex keystrokes
34
35   Most of Emacs commands use key
36 sequences. @xref{Keystrokes,,,xemacs,XEmacs User's Manual}, for more
37 information about Keys and Commands. In Emacs, the keys themselves carry
38 no meaning unless they are bound to a function. For example, @kbd{C-n}
39 moves the cursor to the next line because its bound to the function
40 @b{next-line}. Similarly, @kbd{C-p} moves to the previous line because
41 its bound to the function @b{previous-line}. The functions themselves
42 define a particular behavior. You can customize the key @kbd{C-n} to
43 move to the previous line by binding it to @b{previous-line} and
44 @kbd{C-p} to move to the next line by binding it to @b{next-line}. To
45 bind keys to globally run commands you need to use the following syntax
46 in your @b{init.el} file:
47
48 @cindex binding keys
49 @example
50 @code{(global-set-key @var{keys} @var{cmd})}
51 @end example
52 @noindent
53   Here, @code{global-set-key} is a function which will bind the
54 @dfn{keys} to the specified @dfn{cmd}. For example, if you type the
55 following in your @b{init.el} file:
56
57 @example
58 (global-set-key "\C-p" 'next-line)
59 (global-set-key "\C-n" 'previous-line)
60 @end example
61
62 @noindent
63 then @kbd{C-p} will move to the next line and @kbd{C-n} to the previous
64 line. 
65
66 You can also disable a key binding, by using @samp{nil} as the @var{cmd}
67 in the syntax stated above. Here, @samp{nil} stands for @samp{false}
68 which means disable a command or turn off a feature. If you want to
69 enable a command or turn on a particular feature use @samp{t}
70 which stands for @samp{true}.  For example, if you do not wish @kbd{C-x
71 C-c} to @samp{Exit Emacs} you can type the following expression in your
72 @file{init.el} file:
73
74 @example
75 (global-set-key "\C-x\C-c" nil)
76 @end example
77
78 @noindent
79 You might want to have this statement in your @file{init.el} file because
80 its easy to hit this command by mistake and it could be annoying to exit
81 Emacs unintentionally. There is an @b{Exit Emacs} option in the @b{File
82 menu} which you might want to use instead. To make a particular key
83 undefined you can also use:
84
85 @example
86 (global-unset-key "\C-x\C-c")
87 @end example
88
89 @noindent
90 Now if you use the command @kbd{C-x C-c}, you will get an error saying
91 that the command is undefined.
92
93   Some other customizations you could try are:
94 @itemize @bullet
95
96 @item
97 @example
98 (global-set-key 'button3 'beginning-of-buffer)
99 @end example
100
101 @noindent
102 Now when you press the third button of your mouse, the cursor will be
103 placed at the @code{beginning-of-buffer}.
104
105 @item
106 @example
107 (global-set-key 'f1 'goto-line)
108 @end example
109
110 @noindent
111 If you press the @key{F1} key, you will be prompted for a line
112 number. After you type the line number and hit @key{RET}, the cursor
113 will be placed on that line number.
114
115 @item
116 @example
117 (global-set-key 'f2 'undo)
118 @end example
119
120 Pressing @key{F2} will undo the last command. If you have a @key{undo}
121 key on your keyboard, try binding that key to the undo command.
122 @end itemize
123
124
125   Another syntax for customizing key bindings is:
126 @code{(define-key @var{keymap} @var{keys} @var{def})}
127 It defines @var{keys} to run @var{def} in the keymap @var{keymap}.
128
129 @var{keymap} is a keymap object which records the bindings of keys to
130 the commands that they run.
131
132 @var{keys} is the sequence of keystrokes to bind.
133
134 @var{def} is anything that can be a key's definition:
135
136 Look at the following two examples:
137
138 @example
139 (define-key global-map "\C-xl" 'make-symbolic-link)
140 (define-key c-mode-map "\C-xl" 'make-symbolic-link)
141 @end example
142
143 @findex make-symbolic-link
144 @noindent
145 Both the examples bind the key @kbd{C-xl} to run the function
146 @code{make-symbolic-link} (@pxref{Misc File Ops,,,xemacs,XEmacs User's
147 Manual}). However, the second example will bind the key only for C
148 mode. @xref{Major Modes,,,xemacs,XEmacs User's Manual}, for more
149 information on Major Modes in XEmacs.
150
151
152
153 @comment  node-name,  next,  previous,  up
154 @node Customizing Menus,  , Customizing key Bindings, Customization Basics
155 @section Customizing Menus
156 @cindex customize menus
157 @cindex delete menus
158 @cindex disable menus
159 @findex add-menu-item
160 @cindex add menus
161
162 You can customize any of the  XEmacs Pull-down-Menus. You can create your
163 own menu, delete an existing one, enable a menu or disable a menu. For
164 more information on the default menus available to you, @xref{Pull-down
165 Menus}. 
166
167   Some of the functions which are available to you for customization are:
168 @enumerate
169
170 @item
171 add-menu-item: (@var{menu-name} @var{item-name} @var{function} @var{enabled-p}
172 &optional @var{before})
173
174 This function will add a menu item to a menu, creating the menu first if
175 necessary. If the named item already exists, the menu will remain
176 unchanged. For example, if you add the following example to your
177 @file{init.el} file or evaluate it (@pxref{Customization Basics}),
178
179 @example
180 (add-menu-item '("Edit") "Replace String" replace-string t "Clear")
181 @end example
182
183 @noindent
184 a sub-menu @b{Replace String} will be created under @b{Edit} menu before the
185 sub-menu @b{Clear}. The @b{Edit} menu will now look like:
186
187 @example
188 Undo                    C-x u
189 Cut                     cut
190 Copy                    copy
191 Paste                   paste
192 Replace String
193 Clear
194 Start Macro Recording   C-x(
195 End Macro Recording     C-x)
196 Execute Last Macro      C-xe
197 @end example
198
199 @noindent
200 @b{Replace String} will now execute the function 
201 @code{replace-string}. Select this menu item. Emacs will prompt you for
202 a string name to be replaced. Type a 
203 string and hit @key{RET}. Now type a new string to replace the old
204 string and hit @key{RET}. All occurrences of the old string will be
205 replaced by the new string. In this example,
206
207 @samp{Edit} is the @var{menu-name} which identifies the menu into which
208 the new menu item should be inserted. 
209
210 @samp{Replace String} is the @var{item-name} which names the menu item
211 to be added. 
212
213 @samp{replace-string} is the @var{function} i.e. the command to be
214 invoked when the menu item "Replace String" is selected. 
215
216 @samp{t} is the @var{enabled-p} parameter which controls whether the
217 menu item is selectable or not. This parameter can be either @code{t} (selectable), @code{nil} (not selectable), or a
218 form to evaluate. This form is evaluated just before the menu is
219 displayed, and the menu item will be selectable if the form returns
220 non-@code{nil}. 
221
222 @samp{Clear} is the @var{&optional before} parameter which is the name
223 of the menu before which the new menu or sub-menu should be added. The
224 @var{&optional} string means that this parameter is optional. You do not
225 need to specify this parameter. If you do not specify this parameter in
226 the example above, the @b{Replace String} menu item will be added at the
227 end of the list of sub-menus in the @b{Edit} menu i.e. after @b{Execute
228 Last Macro}.
229
230   If you wish to add a new menu to the menubar, try:
231
232 @example
233 (add-menu-item nil "Bot" 'end-of-buffer t)
234 @end example
235
236 @noindent
237 This will create a new menu @b{Bot} on the menu bar. Selecting this menu
238 will take you to the end of the buffer. Using @code{nil} for the
239 parameter @var{menu-name} will create a new menu. Your menu-bar
240 will now look like: 
241
242 @example
243 File Edit Options Buffers Bot                         Help
244 @end example
245
246   The following example will illustrate how you can add sub-menus to the
247 submenus themselves:
248
249 @example
250 (add-menu-item '("File" "Management") "Copy File" 'copy-file t)
251 (add-menu-item '("File" "Management") "Delete File" 'delete-file t)
252 (add-menu-item '("File" "Management") "Rename File" 'rename-file t)
253 @end example
254 @noindent
255
256 This will create a sub-menu @b{Management} under the @b{File}
257 menu. When you select the submenu @b{Management}, it will contain three
258 submenus: @b{Copy File}, @b{Delete File} and @b{Rename File}. 
259
260 @findex delete-menu-item
261 @cindex deleting menu items
262 @item
263 delete-menu-item: (@var{menu-path})
264 This function will remove the menu item defined by @var{menu-name} from
265 the menu hierarchy. Look at the following examples and the comments just
266 above them which specify what the examples do.
267
268 @example
269 ;; deletes the "Replace String" menu item created earlier
270 (delete-menu-item '("Edit" "Replace String")) 
271
272 ;; deletes the "Bot" menu created earlier
273 (delete-menu-item '("Bot"))
274
275 ;; deletes the sub-menu "Copy File" created earlier
276 (delete-menu-item '("File" "File Management" "Copy File"))
277
278 ;; deletes the sub-menu "Delete File" created earlier
279 (delete-menu-item '("File" "Management" "Delete File")) 
280
281 ;; deletes the sub-menu "Rename File" created earlier
282 (delete-menu-item '("File" "Management" "Rename File"))
283 @end example
284
285
286 @findex disable-menu-item
287 @cindex disabling menu items
288 @item
289 disable-menu-item: (@var{menu-name})
290 Disables the specified menu item. The following example 
291
292 @example
293 (disable-menu-item '("File" "Management" "Copy File"))
294 @end example
295
296 @noindent
297 will make the @b{Copy File} item unselectable. This menu-item would
298 still be there but it will appear faded which would mean that it cannot
299 be selected.
300
301 @findex enable-menu-item
302 @cindex enabling menu items
303 @item
304 enable-menu-item: (@var{menu-name})
305 Enables the specified previously disabled menu item. 
306
307 @example
308 (enable-menu-item '("File" "Management" "Copy File"))
309 @end example
310
311 @noindent
312 This will enable the sub-menu @b{Copy File}, which was disabled by the
313 earlier command.
314
315 @findex relabel-menu-items
316 @cindex relabelling menu items
317 @item
318 relabel-menu-item: (@var{menu-name} @var{new-name})
319 Change the string of the menu item specified by @var{menu-name} to
320 @var{new-name}. 
321
322 @example
323 (relabel-menu-item '("File" "Open...") "Open File")
324 @end example
325
326 This example will rename the @b{Open...} menu item from the @b{File}
327 menu to @b{Open File}. 
328
329 @end enumerate
330