Emacs and Mac OS
****************

This section briefly describes the peculiarities of using Emacs under Mac OS X with native window system support.  For Mac OS X, Emacs can be built either without window system support, with X11, or with the Cocoa interface.  This section only applies to the Cocoa build. Emacs 23 does not support Mac OS Classic.

Emacs, when built on Mac OS X, uses the Cocoa application interface. For various historical and technical reasons, Emacs uses the term Nextstep internally, instead of ``Cocoa'' or ``Mac OS X''; for instance, most of the commands and variables described in the following sections begin with ns-, which is short for Nextstep.  NeXTstep was an application interface released by NeXT Inc during the 1980s, of which Cocoa is a direct descendent. Apart from Cocoa, there is another NeXTstep-style system: GNUstep, which is free software.  As of this writing, the GNUstep support is not fully functional, but we hope to improve it in the future.

Basic Emacs usage in Mac OS
===========================

By default, the alt and option keys are the same as Meta when running under Mac OS.  The Mac Cmd key is the same as Super, and Emacs provides a set of keybindings using this modifier key that mimic other Mac applications (see Mac Events).  You can change these bindings in the usual way (see Key Bindings), or by using the Mac preferences panel (see Mac Preferences).

The standard Mac font and color panels are accessible via the Windows menu, or via the standard Cmd-t and Cmd-C keybindings.  To use the color panel, drag from it to an Emacs frame to change the foreground color of the face at that position (if the shift key is held down, it changes the background color instead).  To finalize the settings for either color or font, choose Save Options in the Options menu.  To discard the settings, create a new frame and close the altered one.

In Mac OS, S-Mouse-1 (i.e., clicking the left mouse button while holding down the Shift key) adjusts the region to the click position, just like Mouse-3 (mouse-save-then-kill); it does not pop up a menu for changing the default face, as S-Mouse-1 normally does (see Temporary Face Changes).  This change makes Emacs behave more like other Mac applications.

When you open or save files using the menus, or using the standard Cmd-o and Cmd-S bindings, Emacs uses graphical file dialogs to read file names.  However, if you use the regular Emacs key sequences, such as C-x C-f, Emacs uses the minibuffer to read file names.

When Emacs is called by a name which ends in -nw, it will always start in terminal mode.  For example, if you need a terminal-only Emacs, create a symbolic link from emacs to emacs-nw and launch emacs-nw.

On GNUstep, in an X-windows environment you need to use Cmd-c instead of one of the C-w or M-w commands to transfer text to the X primary selection; otherwise, Emacs will use the ``clipboard'' selection.  Likewise, Cmd-y (instead of C-y) yanks from the X primary selection instead of the kill-ring or clipboard.

Windowing System Events in Mac OS X
===================================

Nextstep applications receive a number of special events which have no X equivalent.  These are sent as specially defined ``keys'', which do not correspond to any sequence of keystrokes.  Under Emacs, these ``key'' events can be bound to functions just like ordinary keystrokes.  Here is a list of these events.

ns-open-file
     This event occurs when another Nextstep application requests that Emacs open a file.  A typical reason for this would be a user double-clicking a file in the Finder application.  By default, Emacs responds to this event by opening a new frame and visiting the file in that frame (ns-find-file), As an exception, if the selected buffer is the *scratch* buffer, Emacs visits the file in the the selected frame.

     You can change how Emacs responds to ns-open-file by changing the variable ns-pop-up-frames.  Its default value, 'fresh, is what we have just described.  A value of t means to always visit the file in a new frame.  A value of nil means to always visit the file in an existing frame.

ns-open-temp-file
     This event occurs when another application requests that Emacs open a temporary file.  By default, this is handled by just generating a ns-open-file event, the results of which are described above.

     You can bind ns-pop-up-frames and ns-open-temp-file to other Lisp functions.  When the event is registered, the name of the file to open is stored in the variable ns-input-file.

ns-open-file-line
     Some applications, such as ProjectBuilder and gdb, request not only a particular file, but also a particular line or sequence of lines in the file.  Emacs handles this by visiting that file and highlighting the requested line (ns-open-file-select-line).

ns-drag-file
     This event occurs when a user drags files from another application into an Emacs frame.  The default behavior is to insert the contents of all the dragged files into the current buffer (ns-insert-files).  The list of dragged files is stored in the variable ns-input-file.

ns-drag-color
     This event occurs when a user drags a color from the color well (or some other source) into an Emacs frame.  The default behavior is to alter the foreground color of the area the color was dragged onto (ns-set-foreground-at-mouse).  If this event is issued with a Shift modifier, Emacs changes the background color instead (ns-set-background-at-mouse).  The name of the dragged color is stored in the variable ns-input-color.

ns-change-font
     This event occurs when the user selects a font in a Nextstep font panel (which can be opened with Cmd-t).  The default behavior is to adjust the font of the selected frame (ns-respond-to-changefont).  The name and size of the selected font are stored in the variables ns-input-font and ns-input-fontsize respectively.

ns-power-off
     This event occurs when the user logs out and Emacs is still running. The default behavior is to save all file-visiting buffers without confirmation, and exit.

Emacs also allows users to make use of Nextstep services, via a set of commands whose names begin with ns-service- and end with the name of the service.  Type M-x ns-service-TABTAB to see a list of these commands.  These functions either operate on marked text (replacing it with the result) or take a string argument and return the result as a string.  You can also use the Lisp function ns-perform-service to pass arbitrary strings to arbitrary services and receive the results back.  Note that you may need to restart Emacs to access newly-available services.

Mac Preferences
===============

The Preferences panel can be used to set or change some of the settings for Emacs such as the text appearance, cursor settings, and key bindings.

To save any settings changed through the Preferences panel, click on OK; this has the same effect as if you had explicitly chosen Help / Save Preferences.

To restore Emacs to use its default settings click Reset to Defaults from the Preferences Panel.

Additional preferences may be set from the command line using the defaults command.  See Mac Customization.

Font and color settings can be set using the standard NeXTstep font and color panels.

  * To set the default font used by Emacs click the Default Font... button to launch the Font Panel.  Click on a frame before selecting the font family, typeface, and size of the default font from the Font Panel.

     Note that the default font will not be changed if a frame hasn't been selected first.

  * To set the default foreground or background color click the Colors... button to launch the Color Panel.  Choose the color you want using any of the color models (color wheel, sliders, palette, image, or crayons) available from the Colors toolbar.  To apply the color drag a swatch from the color bar at the top of the panel to text on an Emacs frame.  Holding down shift will change the background color instead of the foreground.

  * To use antialiased text check the Smooth Fonts option.  Lighter font smoothing can be achieved by checking the Use Quickdraw (lighter) smoothing option.

  * To change the line height that text is displayed at drag the Expand Line Spacing slider.  When the slider is set to 0.0 Emacs will use the same line height as other Mac OS X applications.  To increase the line height (and decrease the number of lines that can be displayed on the screen) drag the slider towards 1.0.  To decrease the line height (increases the number of lines that can be displayed) drag the slider towards -1.0.

     After the line spacing setting has been changed Emacs must be restarted to take account of the change.

The Display Preferences can be used to change the appearance of the default cursor used by Emacs.

  * The Cursor Type radio buttons can be used to select the style used for the cursor:

       * Box - the cursor is displayed as a box

       * Underscore - the cursor is displayed as a horizontal bar

       * Bar - the cursor is displayed as a vertical bar

       * Hollow - the cursor is displayed as a box with an outline but no fill

  * Use the Cursor Blink Rate slider to set the frequency at which the cursor blinks.

  * Check the Use System Highlight Color option to use the system default color for highlighted text.

The Modifier Preferences can be used to change the behaviour of the Alt/Opt and Command keys.  By default the Alt or Opt key is bound to the Emacs 'Meta' key, and the Command key is bound to 'super' which allows the Command key to function in a way similar to other NeXTstep/OS X applications.

  * To re-bind the Alt or Opt key select a keybinding from the Alt/Opt Key combo box.

  * To re-bind the Command key select a keybinding from the Command Key combo box.

Mac Customization
=================

Under X, resources are used to customize the behavior of Emacs to the needs of the user.  Nexstep defaults fulfill a similar function.  From the command line, the command defaults read org.gnu.Emacs show these resources as of the last Emacs exited, and individual resources can be read or written by commands like defaults read Emacs Foo and defaults write Emacs Foo barvalue.

Calling the function ns-save-preferences in lisp, or selecting the Option / Save Options menu item, automatically writes out the defaults corresponding to the selected window.

In addition, you can set many of the following customizations by setting default-frame-alist in your initialization file.

Many of the preferences relating specifically to the Nextstep windowing system (such as font rendering and the cursor type) can be set using the Preferences panel (see Mac Preferences).  It is important to note that when you hit OK on this panel, all Nextstep settings are saved (including font and colors).

This is a listing of some of the more useful defaults (and their default values).  Several of these defaults accept the names of colors as values.  For a list of all available colors pull up the color panel and look at the color list called Emacs.  Emacs also accepts color specifications of the form ARGBaarrggbb where AA, RR, GG, and BB are two hexadecimal digits describing the alpha, red, green, and blue content of the color respectively. HSBhhssbb, CMYKccmmyykk and GRAYgg are the equivalents in HSB, CMYK and gray scales.  (For HSB, AHSBaahhssbb is also accepted.)

InternalBorderWidth
     Width in pixels of the internal border of the Nextstep frame.  This acts to separate the text area of the window from the fringes, scrollbars, and/or edges.

          defaults write Emacs InternalBorderWidth 2

VerticalScrollBars
     YES or NO to enable or disable scroll bars, left or right to explicitly set the side.

          defaults write Emacs VerticalScrollBars YES

Font
     Name of the default font to be used for new frames (which can be overridden by various faces).  If this font is not set, Emacs will use the system wide fixed pitch font.  For most users the system fixed pitch font will be Monaco which doesn't have any bold or italic versions.  (Italic will be synthesized.)

FontSize
     Size of the font to be used for new frames.  If not set, Emacs will use the default size of the system wide fixed pitch font.

Foreground
     The default foreground (text) color for new frames.

          defaults write Emacs Foreground "Black"

Background
     The default background color for new frames.

          defaults write Emacs Background "White"

Height
     Height in rows of the default window.

          defaults write Emacs Height 48

Width
     Width in columns of the default window.

          defaults write Emacs Width 80

CursorType
     Name of the default cursor type for Emacs.  Allowed values are box, hollow, underscore, bar, line and no.

          defaults write Emacs CursorType box

CursorBlinkRate
     Users who want their cursor to blink can set the rate (in seconds) with this defaults write.  Setting it to NO disables cursor blinking.

          defaults write Emacs CursorBlinkRate NO

CursorColor
     Name of the default cursor color for Emacs.  Of a particular use for this setting is the Highlight color.  When it is the cursor color, Emacs will draw the cursor using the standard Nextstep highlighting operator.

          defaults write Emacs CursorColor Highlight

Top
     Distance in pixels from the top of the screen of the upper left corner of the default window.

          defaults write Emacs Top 100

Left
     Distance in pixels from the left edge of the screen to the upper left corner of the default window.

          defaults write Emacs Left 100

HideOnAutoLaunch
     YES or NO to determine whether Emacs will hide itself when autolaunched from the dock.

          defaults write Emacs HideOnAutoLaunch NO

ExpandSpace
     This lets you expand or shrink the line height used for displaying text.  When this is set to 0.0, display should look like other Nextstep applications.  If you set it higher than 0, Emacs will spread the text lines apart, less than 0, compress them together.  (With settings below zero parts of characters may be chopped off in certain fonts.)  When using the Preferences panel, this is controlled by a slider.  You must OK the panel and then restart Emacs for this default to take effect.

     When setting this using "defaults write", you can either set a floating point value, or YES, which is equivalent 0.5, or NO, which is equivalent to 0.0.

          defaults write Emacs ExpandSpace -0.125

GSFontAntiAlias
     This turns antialiasing on and off on.  Note that, on OS X, even if antialiasing is on, Emacs will not antialias text of a size below the system preference setting.

          defaults write Emacs GSFontAntiAlias NO

UseQuickdrawSmoothing
     On OS X 10.3 and higher, this will render fonts using Quickdraw antialiasing, which is less heavy than the Quartz antialiasing used by default.  Whether this is on or off, the system font size threshold for antialiasing (see above) is respected.

          defaults write Emacs UseQuickdrawSmoothing YES

AlternateModifier
     This allows you to set the effect of the Alt or Opt key.  The default is meta, meaning to use as the Emacs 'meta' key.  You can also set this to command, hyper, alt, or none.  The last is useful for Continental users who normally use this key to enter accented and other special characters.

          defaults write Emacs AlternateModifier "none"

CommandModifier
     This allows you to set the effect of the Command key.  The default is super, which is used in a set of keybindings such as s-o for ``open file'' and s-z for ``undo'' that are similar to other NeXTstep applications.  On the other hand, some people who use the Alt/Opt key for accent entry like to set this to meta so they still have easy access to Emacs functionality bound to meta keys.  You can also set this, like Alt/Opt, to hyper or alt, though there are no bindings to combinations using these keys by default.  The none option is not available for the Command key.

          defaults write Emacs CommandModifier "meta"

fooFrame
     Position and size to use for the frame named FOO when it is created.  The position and size have to be specified as a space separated list: top, left, height and width.  top and left are expressed in pixels, height is given in rows and width is given in columns. Named frames can be created by e.g. (make-frame '((name . "FOO"))).

          defaults write Emacs TestFrame "100 200 30 70"

     Another default previouly used by many Emacs users is this.

          defaults write Workspace DefaultOpenApp Emacs

     It caused the NeXTstep Workspace to open files without a registered extension in Emacs instead of as usual Edit.  For this default to work, Emacs needed to be in the application search path of the Workspace (which usually includes ~/Applications and ~/Applications).  If anyone knows the current way to do this under OS X please contact the authors.