Commit | Line | Data |
---|---|---|
ebc956ca | 1 | @c This is part of the Emacs manual. |
b65d8176 | 2 | @c Copyright (C) 2000, 2001, 2002, 2003, 2004, |
3f548a7c | 3 | @c 2005, 2006, 2007, 2008 Free Software Foundation, Inc. |
ebc956ca | 4 | @c See file emacs.texi for copying conditions. |
53c1041b | 5 | @node Mac OS, Microsoft Windows, Antinews, Top |
385f3fc8 | 6 | @appendix Emacs and Mac OS |
ebc956ca EZ |
7 | @cindex Mac OS |
8 | @cindex Macintosh | |
9 | ||
385f3fc8 YM |
10 | This section briefly describes the peculiarities of using Emacs |
11 | under Mac OS with native window system support. For Mac OS X, Emacs | |
12 | can be built either without window system support, with X11, or with | |
13 | Carbon API. This section only applies to the Carbon build. For Mac | |
14 | OS Classic, Emacs can be built with or without Carbon API, and this | |
15 | section applies to either of them because they run on the native | |
16 | window system. | |
17 | ||
18 | Emacs built on Mac OS X supports most of its major features except | |
19 | display support of PostScript images. The following features of Emacs | |
20 | are not supported on Mac OS Classic: unexec (@code{dump-emacs}), | |
21 | asynchronous subprocesses (@code{start-process}), and networking | |
22 | (@code{open-network-stream}). As a result, packages such as Gnus, | |
23 | GUD, and Comint do not work. Synchronous subprocesses | |
24 | (@code{call-process}) are supported on non-Carbon build, but | |
25 | specially-crafted external programs are needed. Since external | |
26 | programs to handle commands such as @code{print-buffer} and | |
27 | @code{diff} are not available on Mac OS Classic, they are not | |
28 | supported. Non-Carbon build on Mac OS Classic does not support some | |
29 | features such as file dialogs, drag-and-drop, and Unicode menus. | |
ebc956ca EZ |
30 | |
31 | @menu | |
385f3fc8 YM |
32 | * Input: Mac Input. Keyboard and mouse input on Mac. |
33 | * Intl: Mac International. International character sets on Mac. | |
b08fa67e | 34 | * Env: Mac Environment Variables. Setting environment variables for Emacs. |
385f3fc8 YM |
35 | * Directories: Mac Directories. Volumes and directories on Mac. |
36 | * Font: Mac Font Specs. Specifying fonts on Mac. | |
b08fa67e | 37 | * Functions: Mac Functions. Mac-specific Lisp functions. |
ebc956ca EZ |
38 | @end menu |
39 | ||
ebc956ca | 40 | @node Mac Input |
385f3fc8 | 41 | @section Keyboard and Mouse Input on Mac |
4946337d EZ |
42 | @cindex Meta (Mac OS) |
43 | @cindex keyboard coding (Mac OS) | |
ebc956ca | 44 | |
d0aeb9af YM |
45 | @vindex mac-control-modifier |
46 | @vindex mac-command-modifier | |
47 | @vindex mac-option-modifier | |
f4d07c63 YM |
48 | @vindex mac-function-modifier |
49 | On Mac, Emacs can use @key{control}, @key{command}, @key{option}, and | |
50 | laptop @key{function} keys as any of Emacs modifier keys except | |
51 | @key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and | |
52 | @key{SUPER}). The assignment is controlled by the variables | |
53 | @code{mac-control-modifier}, @code{mac-command-modifier}, | |
23666aa8 YM |
54 | @code{mac-option-modifier}, and @code{mac-function-modifier}. The value |
55 | for each of these variables can be one of the following symbols: | |
56 | @code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and | |
57 | @code{nil} (no particular assignment). By default, the @key{control} | |
58 | key works as @key{CTRL}, and the @key{command} key as @key{META}. | |
d0aeb9af YM |
59 | |
60 | For the @key{option} key, if @code{mac-option-modifier} is set to | |
61 | @code{nil}, which is the default, the key works as the normal | |
62 | @key{option} key, i.e., dead-key processing will work. This is useful | |
63 | for entering non-@acronym{ASCII} Latin characters directly from the | |
64 | Mac keyboard, for example. | |
ebc956ca | 65 | |
385f3fc8 YM |
66 | Emacs recognizes the setting in the Keyboard control panel (Mac OS |
67 | Classic) or the International system preference pane (Mac OS X) and | |
f4d07c63 YM |
68 | supports international and alternative keyboard layouts (e.g., Dvorak). |
69 | Selecting one of the layouts from the keyboard layout pull-down menu | |
70 | will affect how the keys typed on the keyboard are interpreted. | |
385f3fc8 YM |
71 | |
72 | @vindex mac-pass-command-to-system | |
73 | @vindex mac-pass-control-to-system | |
74 | Mac OS intercepts and handles certain key combinations (e.g., | |
ebc956ca | 75 | @key{command}-@key{SPC} for switching input languages). These will not |
385f3fc8 YM |
76 | be passed to Emacs. One can disable this interception by setting |
77 | @code{mac-pass-command-to-system} or @code{mac-pass-control-to-system} | |
78 | to @code{nil}. | |
79 | ||
80 | @vindex mac-emulate-three-button-mouse | |
81 | Especially for one-button mice, the multiple button feature can be | |
82 | emulated by setting @code{mac-emulate-three-button-mouse} to @code{t} | |
83 | or @code{reverse}. If set to @code{t} (@code{reverse}, respectively), | |
84 | pressing the mouse button with the @key{option} key is recognized as | |
85 | the second (third) button, and that with the @key{command} key is | |
86 | recognized as the third (second) button. | |
87 | ||
88 | @vindex mac-wheel-button-is-mouse-2 | |
89 | For multi-button mice, the wheel button and the secondary button are | |
90 | recognized as the second and the third button, respectively. If | |
91 | @code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their roles | |
92 | are exchanged. | |
ebc956ca EZ |
93 | |
94 | @node Mac International | |
385f3fc8 | 95 | @section International Character Set Support on Mac |
ebc956ca | 96 | @cindex Mac Roman coding system |
4946337d | 97 | @cindex clipboard support (Mac OS) |
ebc956ca | 98 | |
385f3fc8 YM |
99 | Mac uses non-standard encodings for the upper 128 single-byte |
100 | characters. They also deviate from the ISO 2022 standard by using | |
101 | character codes in the range 128-159. The coding systems | |
102 | @code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic} | |
103 | are used to represent these Mac encodings. | |
ebc956ca | 104 | |
ebc956ca | 105 | You can use input methods provided either by LEIM (@pxref{Input |
385f3fc8 YM |
106 | Methods}) or Mac OS to enter international characters. To use the |
107 | former, see the International Character Set Support section of the | |
108 | manual (@pxref{International}). | |
ebc956ca | 109 | |
385f3fc8 YM |
110 | Emacs on Mac OS automatically changes the value of |
111 | @code{keyboard-coding-system} according to the current keyboard | |
112 | layout. So users don't need to set it manually, and even if set, it | |
113 | will be changed when the keyboard layout change is detected next time. | |
ebc956ca EZ |
114 | |
115 | The Mac clipboard and the Emacs kill ring (@pxref{Killing}) are | |
385f3fc8 YM |
116 | synchronized by default: you can yank a piece of text and paste it |
117 | into another Mac application, or cut or copy one in another Mac | |
118 | application and yank it into a Emacs buffer. This feature can be | |
119 | disabled by setting @code{x-select-enable-clipboard} to @code{nil}. | |
120 | One can still do copy and paste with another application from the Edit | |
121 | menu. | |
122 | ||
123 | On Mac, the role of the coding system for selection that is set by | |
0024f7e0 | 124 | @code{set-selection-coding-system} (@pxref{Communication Coding}) is |
385f3fc8 YM |
125 | two-fold. First, it is used as a preferred coding system for the |
126 | traditional text flavor that does not specify any particular encodings | |
127 | and is mainly used by applications on Mac OS Classic. Second, it | |
128 | specifies the intermediate encoding for the UTF-16 text flavor that is | |
129 | mainly used by applications on Mac OS X. | |
130 | ||
131 | When pasting UTF-16 text data from the clipboard, it is first | |
132 | converted to the encoding specified by the selection coding system | |
133 | using the converter in the Mac OS system, and then decoded into the | |
134 | Emacs internal encoding using the converter in Emacs. If the first | |
af85a998 YM |
135 | conversion failed, then the UTF-16 data is directly converted to Emacs |
136 | internal encoding using the converter in Emacs. Copying UTF-16 text | |
137 | to the clipboard goes through the inverse path. The reason for this | |
138 | two-pass decoding is to avoid subtle differences in Unicode mappings | |
139 | between the Mac OS system and Emacs such as various kinds of hyphens, | |
140 | and to minimize users' customization. For example, users that mainly | |
141 | use Latin characters would prefer Greek characters to be decoded into | |
142 | the @code{mule-unicode-0100-24ff} charset, but Japanese users would | |
143 | prefer them to be decoded into the @code{japanese-jisx0208} charset. | |
144 | Since the coding system for selection is automatically set according | |
145 | to the system locale setting, users usually don't have to set it | |
146 | manually. | |
385f3fc8 YM |
147 | |
148 | The default language environment (@pxref{Language Environments}) is | |
149 | set according to the locale setting at the startup time. On Mac OS, | |
150 | the locale setting is consulted in the following order: | |
151 | ||
152 | @enumerate | |
153 | @item | |
154 | Environment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} as | |
155 | in other systems. | |
156 | ||
157 | @item | |
158 | Preference @code{AppleLocale} that is set by default on Mac OS X 10.3 | |
159 | and later. | |
160 | ||
161 | @item | |
162 | Preference @code{AppleLanguages} that is set by default on Mac OS X | |
163 | 10.1 and later. | |
164 | ||
165 | @item | |
166 | Variable @code{mac-system-locale} that is derived from the system | |
167 | language and region codes. This variable is available on all | |
168 | supported Mac OS versions including Mac OS Classic. | |
169 | @end enumerate | |
170 | ||
171 | The default values of almost all variables about coding systems are | |
172 | also set according to the language environment. So usually you don't | |
173 | have to customize these variables manually. | |
ebc956ca EZ |
174 | |
175 | @node Mac Environment Variables | |
176 | @section Environment Variables and Command Line Arguments. | |
4946337d | 177 | @cindex environment variables (Mac OS) |
ebc956ca | 178 | |
e0f712ba AC |
179 | On Mac OS X, when Emacs is run in a terminal, it inherits the values |
180 | of environment variables from the shell from which it is invoked. | |
385f3fc8 YM |
181 | However, when it is run from the Finder as a GUI application, it only |
182 | inherits environment variable values defined in the file | |
183 | @file{~/.MacOSX/environment.plist} that affects all the applications | |
184 | invoked from the Finder or the @command{open} command. | |
e0f712ba | 185 | |
385f3fc8 YM |
186 | Command line arguments are specified like |
187 | ||
188 | @example | |
47915f5f | 189 | /Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 & |
385f3fc8 YM |
190 | @end example |
191 | ||
192 | @noindent | |
193 | if Emacs is installed at @file{/Applications/Emacs.app}. If Emacs is | |
194 | invoked like this, then it also inherits the values of environment | |
195 | variables from the shell from which it is invoked. | |
196 | ||
197 | On Mac OS Classic, environment variables and command line arguments | |
e0f712ba AC |
198 | for Emacs can be set by modifying the @samp{STR#} resources 128 and |
199 | 129, respectively. A common environment variable that one may want to | |
200 | set is @samp{HOME}. | |
ebc956ca EZ |
201 | |
202 | The way to set an environment variable is by adding a string of the | |
203 | form | |
204 | ||
205 | @example | |
206 | ENV_VAR=VALUE | |
207 | @end example | |
208 | ||
209 | @noindent | |
210 | to resource @samp{STR#} number 128 using @code{ResEdit}. To set up the | |
211 | program to use unibyte characters exclusively, for example, add the | |
212 | string | |
213 | ||
214 | @example | |
215 | EMACS_UNIBYTE=1 | |
216 | @end example | |
217 | ||
385f3fc8 YM |
218 | @cindex Mac Preferences |
219 | Although Emacs on Mac does not support X resources (@pxref{X | |
220 | Resources}) directly, one can use the Preferences system in place of X | |
221 | resources. For example, adding the line | |
222 | ||
223 | @example | |
224 | Emacs.cursorType: bar | |
225 | @end example | |
226 | ||
227 | @noindent | |
228 | to @file{~/.Xresources} in X11 corresponds to the execution of | |
229 | ||
230 | @example | |
231 | defaults write org.gnu.Emacs Emacs.cursorType bar | |
232 | @end example | |
233 | ||
234 | @noindent | |
235 | on Mac OS X. One can use boolean or numeric values as well as string | |
236 | values as follows: | |
237 | ||
238 | @example | |
239 | defaults write org.gnu.Emacs Emacs.toolBar -bool false | |
240 | defaults write org.gnu.Emacs Emacs.lineSpacing -int 3 | |
241 | @end example | |
242 | ||
243 | @noindent | |
244 | Try @kbd{M-x man RET defaults RET} for the usage of the | |
245 | @command{defaults} command. Alternatively, if you have Developer | |
246 | Tools installed on Mac OS X, you can use Property List Editor to edit | |
247 | the file @file{~/Library/Preferences/org.gnu.Emacs.plist}. | |
248 | ||
ebc956ca EZ |
249 | |
250 | @node Mac Directories | |
385f3fc8 | 251 | @section Volumes and Directories on Mac |
4946337d | 252 | @cindex file names (Mac OS) |
ebc956ca | 253 | |
385f3fc8 YM |
254 | This node applies to Mac OS Classic only. |
255 | ||
256 | The directory structure in Mac OS Classic is seen by Emacs as | |
ebc956ca EZ |
257 | |
258 | @example | |
b08fa67e | 259 | /@var{volumename}/@var{filename} |
ebc956ca EZ |
260 | @end example |
261 | ||
b08fa67e | 262 | So when Emacs requests a file name, doing file name completion on |
892c6176 RS |
263 | @file{/} will display all volumes on the system. You can use @file{..} |
264 | to go up a directory level. | |
ebc956ca | 265 | |
385f3fc8 | 266 | On Mac OS Classic, to access files and folders on the desktop, look |
e0f712ba AC |
267 | in the folder @file{Desktop Folder} in your boot volume (this folder |
268 | is usually invisible in the Mac @code{Finder}). | |
269 | ||
385f3fc8 | 270 | On Mac OS Classic, Emacs creates the Mac folder |
e0f712ba AC |
271 | @file{:Preferences:Emacs:} in the @file{System Folder} and uses it as |
272 | the temporary directory. Emacs maps the directory name @file{/tmp/} | |
273 | to that. Therefore it is best to avoid naming a volume @file{tmp}. | |
274 | If everything works correctly, the program should leave no files in it | |
275 | when it exits. You should be able to set the environment variable | |
276 | @code{TMPDIR} to use another directory but this folder will still be | |
277 | created. | |
ebc956ca EZ |
278 | |
279 | ||
280 | @node Mac Font Specs | |
385f3fc8 | 281 | @section Specifying Fonts on Mac |
4946337d | 282 | @cindex font names (Mac OS) |
ebc956ca | 283 | |
305f719a | 284 | It is rare that you need to specify a font name in Emacs; usually |
d0aeb9af YM |
285 | you specify face attributes instead. For example, you can use 14pt |
286 | Courier by customizing the default face attributes for all frames: | |
287 | ||
288 | @lisp | |
47915f5f YM |
289 | (set-face-attribute 'default nil |
290 | :family "courier" :height 140) | |
d0aeb9af YM |
291 | @end lisp |
292 | ||
293 | @noindent | |
294 | Alternatively, an interactive one is also available | |
295 | (@pxref{Face Customization}). | |
296 | ||
297 | But when you do need to specify a font name in Emacs on Mac, use a | |
298 | standard X font name: | |
ebc956ca | 299 | |
b08fa67e | 300 | @smallexample |
f8ca728a AC |
301 | -@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{} |
302 | @dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset} | |
b08fa67e | 303 | @end smallexample |
ebc956ca | 304 | |
b08fa67e | 305 | @noindent |
305f719a | 306 | @xref{Font X}. Wildcards are supported as they are on X. |
ebc956ca | 307 | |
47915f5f YM |
308 | Emacs on Mac OS Classic uses QuickDraw Text routines for drawing texts |
309 | by default. Emacs on Mac OS X uses @acronym{ATSUI, Apple Type Services | |
310 | for Unicode Imaging} as well as QuickDraw Text, and most of the | |
311 | characters other than Chinese, Japanese, and Korean ones are drawn using | |
312 | the former by default. | |
313 | ||
314 | @acronym{ATSUI}-compatible fonts have maker name @code{apple} and | |
444246ca KB |
315 | charset @code{iso10646-1}. For example, 12-point Monaco can be specified |
316 | by the name: | |
317 | ||
318 | @example | |
319 | -apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1 | |
320 | @end example | |
321 | ||
df7593dd KB |
322 | Note that these names must be specified using a format containing all |
323 | 14 @samp{-}s (not by | |
324 | @samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance), | |
444246ca | 325 | because every @acronym{ATSUI}-compatible font is a scalable one. |
47915f5f YM |
326 | |
327 | QuickDraw Text fonts have maker name @code{apple} and various charset | |
328 | names other than @code{iso10646-1}. Native Apple fonts in Mac Roman | |
329 | encoding has charset @code{mac-roman}. You can specify a | |
330 | @code{mac-roman} font for @acronym{ASCII} characters like | |
331 | ||
332 | @smalllisp | |
385f3fc8 YM |
333 | (add-to-list |
334 | 'default-frame-alist | |
335 | '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman")) | |
47915f5f | 336 | @end smalllisp |
385f3fc8 YM |
337 | |
338 | @noindent | |
339 | but that does not extend to ISO-8859-1: specifying a @code{mac-roman} | |
340 | font for Latin-1 characters introduces wrong glyphs. | |
341 | ||
342 | Native Apple Traditional Chinese, Simplified Chinese, Japanese, | |
343 | Korean, Central European, Cyrillic, Symbol, and Dingbats fonts have | |
df7593dd | 344 | the charsets @samp{big5-0}, @samp{gb2312.1980-0}, |
385f3fc8 YM |
345 | @samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0}, |
346 | @samp{ksc5601.1989-0}, @samp{mac-centraleurroman}, | |
347 | @samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats}, | |
348 | respectively. | |
349 | ||
385f3fc8 | 350 | The use of @code{create-fontset-from-fontset-spec} (@pxref{Defining |
47915f5f YM |
351 | Fontsets}) for defining fontsets often results in wrong ones especially |
352 | when using only OS-bundled QuickDraw Text fonts. The recommended way to | |
353 | use them is to create a fontset using | |
354 | @code{create-fontset-from-mac-roman-font}: | |
385f3fc8 YM |
355 | |
356 | @lisp | |
357 | (create-fontset-from-mac-roman-font | |
358 | "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman" | |
359 | nil "foo") | |
360 | @end lisp | |
361 | ||
362 | @noindent | |
363 | and then optionally specifying Chinese, Japanese, or Korean font | |
364 | families using @code{set-fontset-font}: | |
365 | ||
366 | @lisp | |
367 | (set-fontset-font "fontset-foo" | |
368 | 'chinese-gb2312 '("song" . "gb2312.1980-0")) | |
369 | @end lisp | |
ebc956ca EZ |
370 | |
371 | Single-byte fonts converted from GNU fonts in BDF format, which are not | |
372 | in the Mac Roman encoding, have foundry, family, and character sets | |
373 | encoded in the names of their font suitcases. E.g., the font suitcase | |
374 | @samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to by | |
375 | the name @samp{-ETL-fixed-*-iso8859-1}. | |
376 | ||
385f3fc8 | 377 | @vindex mac-allow-anti-aliasing |
47915f5f YM |
378 | Mac OS X 10.2 or later can use two types of text renderings: Quartz 2D |
379 | (aka Core Graphics) and QuickDraw. By default, Emacs uses the former on | |
380 | such versions. It can be changed by setting | |
381 | @code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil} | |
382 | (QuickDraw). Both @acronym{ATSUI} and QuickDraw Text drawings are | |
383 | affected by the value of this variable. | |
384 | ||
e43c7935 YM |
385 | Appearance of text in small sizes will also be affected by the ``Turn |
386 | off text smoothing for font sizes @var{n} and smaller'' setting in the | |
387 | General pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 or | |
388 | later) of the System Preferences. This threshold can alternatively be | |
389 | set just for Emacs (i.e., not as the system-wide setting) using the | |
390 | @command{defaults} command: | |
391 | ||
392 | @example | |
393 | defaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n} | |
394 | @end example | |
395 | ||
ebc956ca EZ |
396 | |
397 | @node Mac Functions | |
c44461ef | 398 | @section Mac-Specific Lisp Functions |
4946337d | 399 | @cindex Lisp functions specific to Mac OS |
ebc956ca EZ |
400 | |
401 | @findex do-applescript | |
402 | The function @code{do-applescript} takes a string argument, | |
403 | executes it as an AppleScript command, and returns the result as a | |
404 | string. | |
405 | ||
51c2603b AC |
406 | @findex mac-file-name-to-posix |
407 | @findex posix-file-name-to-mac | |
408 | The function @code{mac-file-name-to-posix} takes a Mac file name and | |
7b67d693 | 409 | returns the GNU or Unix equivalent. The function |
51c2603b AC |
410 | @code{posix-file-name-to-mac} performs the opposite conversion. They |
411 | are useful for constructing AppleScript commands to be passed to | |
412 | @code{do-applescript}. | |
ab5796a9 | 413 | |
385f3fc8 YM |
414 | @findex mac-set-file-creator |
415 | @findex mac-get-file-creator | |
416 | @findex mac-set-file-type | |
417 | @findex mac-get-file-type | |
418 | The functions @code{mac-set-file-creator}, | |
419 | @code{mac-get-file-creator}, @code{mac-set-file-type}, and | |
420 | @code{mac-get-file-type} can be used to set and get creator and file | |
421 | codes. | |
422 | ||
423 | @findex mac-get-preference | |
424 | The function @code{mac-get-preference} returns the preferences value | |
425 | converted to a Lisp object for a specified key and application. | |
426 | ||
ab5796a9 MB |
427 | @ignore |
428 | arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6 | |
429 | @end ignore |