@c This is part of the Emacs manual.@c Copyright (C) 2000, 2001, 2002, 2003, 2004,@c 2005, 2006, 2007 Free Software Foundation, Inc.@c See file emacs.texi for copying conditions.@node Mac OS, Microsoft Windows, Antinews, Top@appendix Emacs and Mac OS@cindex Mac OS@cindex Macintosh This section briefly describes the peculiarities of using Emacsunder Mac OS with native window system support. For Mac OS X, Emacscan be built either without window system support, with X11, or withCarbon API. This section only applies to the Carbon build. For MacOS Classic, Emacs can be built with or without Carbon API, and thissection applies to either of them because they run on the nativewindow system. Emacs built on Mac OS X supports most of its major features exceptdisplay support of PostScript images. The following features of Emacsare not supported on Mac OS Classic: unexec (@code{dump-emacs}),asynchronous subprocesses (@code{start-process}), and networking(@code{open-network-stream}). As a result, packages such as Gnus,GUD, and Comint do not work. Synchronous subprocesses(@code{call-process}) are supported on non-Carbon build, butspecially-crafted external programs are needed. Since externalprograms to handle commands such as @code{print-buffer} and@code{diff} are not available on Mac OS Classic, they are notsupported. Non-Carbon build on Mac OS Classic does not support somefeatures such as file dialogs, drag-and-drop, and Unicode menus.@menu* Input: Mac Input. Keyboard and mouse input on Mac.* Intl: Mac International. International character sets on Mac.* Env: Mac Environment Variables. Setting environment variables for Emacs.* Directories: Mac Directories. Volumes and directories on Mac.* Font: Mac Font Specs. Specifying fonts on Mac.* Functions: Mac Functions. Mac-specific Lisp functions.@end menu@node Mac Input@section Keyboard and Mouse Input on Mac@cindex Meta (Mac OS)@cindex keyboard coding (Mac OS)@vindex mac-control-modifier@vindex mac-command-modifier@vindex mac-option-modifier@vindex mac-function-modifier On Mac, Emacs can use @key{control}, @key{command}, @key{option}, andlaptop @key{function} keys as any of Emacs modifier keys except@key{SHIFT} (i.e., @key{ALT}, @key{CTRL}, @key{HYPER}, @key{META}, and@key{SUPER}). The assignment is controlled by the variables@code{mac-control-modifier}, @code{mac-command-modifier},@code{mac-option-modifier}, and @code{mac-function-modifier}. The valuefor each of these variables can be one of the following symbols:@code{alt}, @code{control}, @code{hyper}, @code{meta}, @code{super}, and@code{nil} (no particular assignment). By default, the @key{control}key works as @key{CTRL}, and the @key{command} key as @key{META}. For the @key{option} key, if @code{mac-option-modifier} is set to@code{nil}, which is the default, the key works as the normal@key{option} key, i.e., dead-key processing will work. This is usefulfor entering non-@acronym{ASCII} Latin characters directly from theMac keyboard, for example. Emacs recognizes the setting in the Keyboard control panel (Mac OSClassic) or the International system preference pane (Mac OS X) andsupports international and alternative keyboard layouts (e.g., Dvorak).Selecting one of the layouts from the keyboard layout pull-down menuwill affect how the keys typed on the keyboard are interpreted.@vindex mac-pass-command-to-system@vindex mac-pass-control-to-system Mac OS intercepts and handles certain key combinations (e.g.,@key{command}-@key{SPC} for switching input languages). These will notbe passed to Emacs. One can disable this interception by setting@code{mac-pass-command-to-system} or @code{mac-pass-control-to-system}to @code{nil}.@vindex mac-emulate-three-button-mouse Especially for one-button mice, the multiple button feature can beemulated by setting @code{mac-emulate-three-button-mouse} to @code{t}or @code{reverse}. If set to @code{t} (@code{reverse}, respectively),pressing the mouse button with the @key{option} key is recognized asthe second (third) button, and that with the @key{command} key isrecognized as the third (second) button.@vindex mac-wheel-button-is-mouse-2 For multi-button mice, the wheel button and the secondary button arerecognized as the second and the third button, respectively. If@code{mac-wheel-button-is-mouse-2} is set to @code{nil}, their rolesare exchanged.@node Mac International@section International Character Set Support on Mac@cindex Mac Roman coding system@cindex clipboard support (Mac OS) Mac uses non-standard encodings for the upper 128 single-bytecharacters. They also deviate from the ISO 2022 standard by usingcharacter codes in the range 128-159. The coding systems@code{mac-roman}, @code{mac-centraleurroman}, and @code{mac-cyrillic}are used to represent these Mac encodings. You can use input methods provided either by LEIM (@pxref{InputMethods}) or Mac OS to enter international characters. To use theformer, see the International Character Set Support section of themanual (@pxref{International}). Emacs on Mac OS automatically changes the value of@code{keyboard-coding-system} according to the current keyboardlayout. So users don't need to set it manually, and even if set, itwill be changed when the keyboard layout change is detected next time. The Mac clipboard and the Emacs kill ring (@pxref{Killing}) aresynchronized by default: you can yank a piece of text and paste itinto another Mac application, or cut or copy one in another Macapplication and yank it into a Emacs buffer. This feature can bedisabled by setting @code{x-select-enable-clipboard} to @code{nil}.One can still do copy and paste with another application from the Editmenu. On Mac, the role of the coding system for selection that is set by@code{set-selection-coding-system} (@pxref{Communication Coding}) istwo-fold. First, it is used as a preferred coding system for thetraditional text flavor that does not specify any particular encodingsand is mainly used by applications on Mac OS Classic. Second, itspecifies the intermediate encoding for the UTF-16 text flavor that ismainly used by applications on Mac OS X. When pasting UTF-16 text data from the clipboard, it is firstconverted to the encoding specified by the selection coding systemusing the converter in the Mac OS system, and then decoded into theEmacs internal encoding using the converter in Emacs. If the firstconversion failed, then the UTF-16 data is directly converted to Emacsinternal encoding using the converter in Emacs. Copying UTF-16 textto the clipboard goes through the inverse path. The reason for thistwo-pass decoding is to avoid subtle differences in Unicode mappingsbetween the Mac OS system and Emacs such as various kinds of hyphens,and to minimize users' customization. For example, users that mainlyuse Latin characters would prefer Greek characters to be decoded intothe @code{mule-unicode-0100-24ff} charset, but Japanese users wouldprefer them to be decoded into the @code{japanese-jisx0208} charset.Since the coding system for selection is automatically set accordingto the system locale setting, users usually don't have to set itmanually. The default language environment (@pxref{Language Environments}) isset according to the locale setting at the startup time. On Mac OS,the locale setting is consulted in the following order:@enumerate@itemEnvironment variables @env{LC_ALL}, @env{LC_CTYPE} and @env{LANG} asin other systems.@itemPreference @code{AppleLocale} that is set by default on Mac OS X 10.3and later.@itemPreference @code{AppleLanguages} that is set by default on Mac OS X10.1 and later.@itemVariable @code{mac-system-locale} that is derived from the systemlanguage and region codes. This variable is available on allsupported Mac OS versions including Mac OS Classic.@end enumerate The default values of almost all variables about coding systems arealso set according to the language environment. So usually you don'thave to customize these variables manually.@node Mac Environment Variables@section Environment Variables and Command Line Arguments.@cindex environment variables (Mac OS) On Mac OS X, when Emacs is run in a terminal, it inherits the valuesof environment variables from the shell from which it is invoked.However, when it is run from the Finder as a GUI application, it onlyinherits environment variable values defined in the file@file{~/.MacOSX/environment.plist} that affects all the applicationsinvoked from the Finder or the @command{open} command. Command line arguments are specified like@example/Applications/Emacs.app/Contents/MacOS/Emacs -g 80x25 &@end example@noindentif Emacs is installed at @file{/Applications/Emacs.app}. If Emacs isinvoked like this, then it also inherits the values of environmentvariables from the shell from which it is invoked. On Mac OS Classic, environment variables and command line argumentsfor Emacs can be set by modifying the @samp{STR#} resources 128 and129, respectively. A common environment variable that one may want toset is @samp{HOME}. The way to set an environment variable is by adding a string of theform@exampleENV_VAR=VALUE@end example@noindentto resource @samp{STR#} number 128 using @code{ResEdit}. To set up theprogram to use unibyte characters exclusively, for example, add thestring@exampleEMACS_UNIBYTE=1@end example@cindex Mac Preferences Although Emacs on Mac does not support X resources (@pxref{XResources}) directly, one can use the Preferences system in place of Xresources. For example, adding the line@exampleEmacs.cursorType: bar@end example@noindentto @file{~/.Xresources} in X11 corresponds to the execution of@exampledefaults write org.gnu.Emacs Emacs.cursorType bar@end example@noindenton Mac OS X. One can use boolean or numeric values as well as stringvalues as follows:@exampledefaults write org.gnu.Emacs Emacs.toolBar -bool falsedefaults write org.gnu.Emacs Emacs.lineSpacing -int 3@end example@noindentTry @kbd{M-x man RET defaults RET} for the usage of the@command{defaults} command. Alternatively, if you have DeveloperTools installed on Mac OS X, you can use Property List Editor to editthe file @file{~/Library/Preferences/org.gnu.Emacs.plist}.@node Mac Directories@section Volumes and Directories on Mac@cindex file names (Mac OS) This node applies to Mac OS Classic only. The directory structure in Mac OS Classic is seen by Emacs as@example/@var{volumename}/@var{filename}@end exampleSo when Emacs requests a file name, doing file name completion on@file{/} will display all volumes on the system. You can use @file{..}to go up a directory level. On Mac OS Classic, to access files and folders on the desktop, lookin the folder @file{Desktop Folder} in your boot volume (this folderis usually invisible in the Mac @code{Finder}). On Mac OS Classic, Emacs creates the Mac folder@file{:Preferences:Emacs:} in the @file{System Folder} and uses it asthe temporary directory. Emacs maps the directory name @file{/tmp/}to that. Therefore it is best to avoid naming a volume @file{tmp}.If everything works correctly, the program should leave no files in itwhen it exits. You should be able to set the environment variable@code{TMPDIR} to use another directory but this folder will still becreated.@node Mac Font Specs@section Specifying Fonts on Mac@cindex font names (Mac OS) It is rare that you need to specify a font name in Emacs; usuallyyou specify face attributes instead. For example, you can use 14ptCourier by customizing the default face attributes for all frames:@lisp(set-face-attribute 'default nil :family "courier" :height 140)@end lisp@noindentAlternatively, an interactive one is also available(@pxref{Face Customization}).But when you do need to specify a font name in Emacs on Mac, use astandard X font name:@smallexample-@var{maker}-@var{family}-@var{weight}-@var{slant}-@var{widthtype}-@var{style}@dots{}@dots{}-@var{pixels}-@var{height}-@var{horiz}-@var{vert}-@var{spacing}-@var{width}-@var{charset}@end smallexample@noindent@xref{Font X}. Wildcards are supported as they are on X. Emacs on Mac OS Classic uses QuickDraw Text routines for drawing textsby default. Emacs on Mac OS X uses @acronym{ATSUI, Apple Type Servicesfor Unicode Imaging} as well as QuickDraw Text, and most of thecharacters other than Chinese, Japanese, and Korean ones are drawn usingthe former by default. @acronym{ATSUI}-compatible fonts have maker name @code{apple} andcharset @code{iso10646-1}. For example, 12-point Monaco can be specifiedby the name:@example-apple-monaco-medium-r-normal--12-*-*-*-*-*-iso10646-1@end exampleNote that these names must be specified using a format containing all14 @samp{-}s (not by@samp{-apple-monaco-medium-r-normal--12-*-iso10646-1}, for instance),because every @acronym{ATSUI}-compatible font is a scalable one. QuickDraw Text fonts have maker name @code{apple} and various charsetnames other than @code{iso10646-1}. Native Apple fonts in Mac Romanencoding has charset @code{mac-roman}. You can specify a@code{mac-roman} font for @acronym{ASCII} characters like@smalllisp(add-to-list 'default-frame-alist '(font . "-apple-monaco-medium-r-normal--13-*-*-*-*-*-mac-roman"))@end smalllisp@noindentbut that does not extend to ISO-8859-1: specifying a @code{mac-roman}font for Latin-1 characters introduces wrong glyphs. Native Apple Traditional Chinese, Simplified Chinese, Japanese,Korean, Central European, Cyrillic, Symbol, and Dingbats fonts havethe charsets @samp{big5-0}, @samp{gb2312.1980-0},@samp{jisx0208.1983-sjis} and @samp{jisx0201.1976-0},@samp{ksc5601.1989-0}, @samp{mac-centraleurroman},@samp{mac-cyrillic}, @samp{mac-symbol}, and @samp{mac-dingbats},respectively. The use of @code{create-fontset-from-fontset-spec} (@pxref{DefiningFontsets}) for defining fontsets often results in wrong ones especiallywhen using only OS-bundled QuickDraw Text fonts. The recommended way touse them is to create a fontset using@code{create-fontset-from-mac-roman-font}:@lisp(create-fontset-from-mac-roman-font "-apple-courier-medium-r-normal--13-*-*-*-*-*-mac-roman" nil "foo")@end lisp@noindentand then optionally specifying Chinese, Japanese, or Korean fontfamilies using @code{set-fontset-font}:@lisp(set-fontset-font "fontset-foo" 'chinese-gb2312 '("song" . "gb2312.1980-0"))@end lisp Single-byte fonts converted from GNU fonts in BDF format, which are notin the Mac Roman encoding, have foundry, family, and character setsencoded in the names of their font suitcases. E.g., the font suitcase@samp{ETL-Fixed-ISO8859-1} contains fonts which can be referred to bythe name @samp{-ETL-fixed-*-iso8859-1}.@vindex mac-allow-anti-aliasing Mac OS X 10.2 or later can use two types of text renderings: Quartz 2D(aka Core Graphics) and QuickDraw. By default, Emacs uses the former onsuch versions. It can be changed by setting@code{mac-allow-anti-aliasing} to @code{t} (Quartz 2D) or @code{nil}(QuickDraw). Both @acronym{ATSUI} and QuickDraw Text drawings areaffected by the value of this variable. Appearance of text in small sizes will also be affected by the ``Turnoff text smoothing for font sizes @var{n} and smaller'' setting in theGeneral pane (Mac OS X 10.1 or 10.2) or in the Appearance pane (10.3 orlater) of the System Preferences. This threshold can alternatively beset just for Emacs (i.e., not as the system-wide setting) using the@command{defaults} command:@exampledefaults write org.gnu.Emacs AppleAntiAliasingThreshold @var{n}@end example@node Mac Functions@section Mac-Specific Lisp Functions@cindex Lisp functions specific to Mac OS@findex do-applescript The function @code{do-applescript} takes a string argument,executes it as an AppleScript command, and returns the result as astring.@findex mac-file-name-to-posix@findex posix-file-name-to-mac The function @code{mac-file-name-to-posix} takes a Mac file name andreturns the GNU or Unix equivalent. The function@code{posix-file-name-to-mac} performs the opposite conversion. Theyare useful for constructing AppleScript commands to be passed to@code{do-applescript}.@findex mac-set-file-creator@findex mac-get-file-creator@findex mac-set-file-type@findex mac-get-file-type The functions @code{mac-set-file-creator},@code{mac-get-file-creator}, @code{mac-set-file-type}, and@code{mac-get-file-type} can be used to set and get creator and filecodes.@findex mac-get-preference The function @code{mac-get-preference} returns the preferences valueconverted to a Lisp object for a specified key and application.@ignore arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6@end ignore