Emacs and Mac OS / GNUstep
**************************

This section briefly describes the peculiarities of using Emacs built with the GNUstep libraries on GNU/Linux or other operating systems, or on 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 alpha status (see GNUstep Support), but we hope to improve it in the future.

Basic Emacs usage under Mac OS and GNUstep
==========================================

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 / GNUstep applications (see Mac / GNUstep Events).  You can change these bindings in the usual way (see Key Bindings), or by using the Preferences panel (see Mac / GNUstep Customization).

The standard Mac / GNUstep 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.

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 / GNUstep 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.

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.

Grabbing environment variables
------------------------------

Many programs which may run under Emacs like latex or man depend on the settings of environment variables.  If Emacs is launched from the shell, it will automatically inherit these environment variables and its subprocesses will inherit them from it.  But if Emacs is launched from the Finder it is not a descendant of any shell, so its environment variables haven't been set which often causes the subprocesses it launches to behave differently than they would when launched from the shell.

To solve this problem for Emacs, there are two solutions.  First is to run, from the command line:

     .../Emacs.app/Contents/MacOS/bin/mac-fix-env

This will pick up your environment settings and save them into a special file ~/.MacOSX/environment.plist, which the desktop environment will use to set the environment for all launched applications.  The drawback of this method is it needs to be run again whenever something changes.

The other approach is to use the ns-grabenv command inside Emacs.  This function will run a subshell and copy its environment variables into Emacs.

Adding this line to your ~/.emacs will grab the csh environment whenever emacs runs under a window system.

     (if window-system (ns-grabenv))

If you have a different shell you will have to give ns-grabenv some arguments.  For zsh you would do this.

     (if window-system (ns-grabenv "/usr/bin/zsh"
                                "source /etc/zshenv"
                                "source ~/.zshenv"))

The reason that ns-grabenv is not done by default is that it adds up to a second or two to the Emacs startup time.

Mac / GNUstep Customization
===========================

Emacs can be customized in several ways in addition to the standard customization buffers and the Options menu.

Preferences Panel
-----------------

The Preferences panel, much like the Options menu, is designed to allow quick and convenient setting of commonly used options.

The Preferences panel is available for setting commonly used GUI-related options for Emacs.  Access it under the Emacs menu (Mac) or Info menu (GNUstep), or using Cmd-,.

Settings made here are saved when OK is hit, or Save Options is selected from the Options menu.  These settings are stored into the NeXTstep ``defaults'' system under keys described below.

  * To set the default font used by Emacs click the Default Font... button to being up the Font Panel, then click on a frame.  The font of this frame will then be changed when you make a selection in the Font Panel, and this will be used as the default for future frames.  If you do not select a frame first, the Font Panel will not work.

  * The Color panel, brought up by the Colors... button, allows setting of foreground or background of any face.  Drag from the color bar to over the emacs face you want to change.  This will change the foreground of that face, or holding shift when dragging will change the background.

  * Smooth Fonts and Use Quickdraw control text antialiasing. Quickdraw is an older Mac technology still supported under OS X.

  * The Expand Line Spacing slider controls vertical spacing of text.  The 0.0 setting corresponds to the same height as other applications.  Settings less than 0 compress the spacing, and greater than 0 expand it.  Emacs must be restarted for the new setting to take effect.

  * The Cursor Type radio buttons select the cursor shape: cursor:

       * Filled Box - the cursor is displayed as a box (default)

       * Vertical Bar - the cursor is displayed as a vertical line

       * Underscore - the cursor is displayed as a horizontal line

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

  * The Cursor Blink Rate slider to sets the frequency at which the cursor blinks (CURRENTLY INOPERATIVE -- use customize group cursor instead.)

  * The Use System Highlight Color option controls whether selected text is highlighted with the system default or the local emacs setting.

The behavior of Modifier keys inside emacs can be controlled by the drop-down menus in the Modifiers section.  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.

Font and Color Panels
---------------------

The Font Panel may be accessed from the Windows menu or by Cmd-t.  It will set the default font in the frame most recently used or clicked on.  To make the setting permanent, use Save Options in the Options menu, or run ns-save-preferences.

You can bring up a color panel (with Cmd-C or from the Windows menu) and drag the color you want over the emacs face you want to change.  Normal dragging will alter the foreground color.  Shift dragging will alter the background color.  To make the changes permanent select the "Save Options" item in the "Options" menu, or run ns-save-preferences.  Useful in this context is the listing of all faces obtained by M-x list-faces-display.

Defaults
--------

Under X, resources are used to customize the behavior of Emacs to the needs of the user.  Nextstep defaults fulfill a similar function.  From the command line, the command defaults read org.gnu.Emacs shows 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.  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

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 blue

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.

Open files by dragging to an Emacs window
-----------------------------------------

The default behaviour when a user drags files from another application into an Emacs frame is to insert the contents of all the dragged files into the current buffer.  To remap the ns-drag-file event to open the dragged files in the current frame use the following line:

     (define-key global-map [ns-drag-file] 'ns-find-file)

Windowing System Events under Mac OS / GNUstep
==============================================

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.

GNUstep Support
===============

Emacs can be built and run under GNUstep however building is difficult and there are some limitations to functionality.  In particular, it may be necessary to run make bootstrap with a plain X configuration, then make clean and ./configure --with-ns followed by make install.

Currently CANNOT_DUMP is automatically enabled in GNUstep configurations, because the unex file(s) for GNUstep, mainly unexelf.c, have not been updated yet with the ``zone'' code in and related to unexmacosx.c.