* macos.texi (Mac Customization): Fix typos.

[bpt/emacs.git] / doc / emacs / macos.texi

@c This is part of the Emacs manual.
@c Copyright (C) 2000, 2001, 2002, 2003, 2004,
@c   2005, 2006, 2007, 2008 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 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
@samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for
instance, most of the commands and variables described in the
following sections begin with @samp{ns-}, which is short for
@samp{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.

@menu
* Mac Basics::          Basic Emacs usage in Mac OS.
* Mac Events::          How window system events are handled.
* Mac Preferences::     Using the Preferences Panel to customize Emacs.
* Mac Customization::   Customizations in Mac OS
@end menu

@node Mac Basics
@section Basic Emacs usage in Mac OS

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

  The standard Mac font and color panels are accessible via the
@samp{Windows} menu, or via the standard @key{Cmd-t} and @key{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
@key{shift} key is held down, it changes the background color
instead).  To finalize the settings for either color or font, choose
@samp{Save Options} in the @samp{Options} menu.  To discard the
settings, create a new frame and close the altered one.

  In Mac OS, @key{S-Mouse-1} (i.e., clicking the left mouse button
while holding down the @key{Shift} key) adjusts the region to the
click position, just like @key{Mouse-3} (@code{mouse-save-then-kill});
it does not pop up a menu for changing the default face, as
@key{S-Mouse-1} normally does (@pxref{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
@key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file
dialogs to read file names.  However, if you use the regular Emacs key
sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read
file names.

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

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

@node Mac Events
@section 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.

@table @key
@item ns-open-file
@vindex ns-pop-up-frames
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 (@code{ns-find-file}), As an exception, if the selected
buffer is the @samp{*scratch*} buffer, Emacs visits the file in the
the selected frame.

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

@item 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
@code{ns-open-file} event, the results of which are described above.

You can bind @key{ns-pop-up-frames} and @key{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 @code{ns-input-file}.

@item 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 (@code{ns-open-file-select-line}).

@item 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
(@code{ns-insert-files}).  The list of dragged files is stored in the
variable @code{ns-input-file}.

@item 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
(@code{ns-set-foreground-at-mouse}).  If this event is issued with a
@key{Shift} modifier, Emacs changes the background color instead
(@code{ns-set-background-at-mouse}).  The name of the dragged color is
stored in the variable @code{ns-input-color}.

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

@item 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.
@end table

  Emacs also allows users to make use of Nextstep services, via a set
of commands whose names begin with @samp{ns-service-} and end with the
name of the service.  Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} 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
@code{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.

@node Mac Preferences
@section 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
@samp{OK}; this has the same effect as if you had explicitly chosen
@samp{Help / Save Preferences}.

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

  Additional preferences may be set from the command line using the
@command{defaults} command.  @xref{Mac Customization}.

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

@itemize @bullet
@item
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.

@item
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.

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

@item
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.

@end itemize

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

@itemize @bullet
@item
The Cursor Type radio buttons can be used to select the style used for the cursor:

@itemize
@item
Box - the cursor is displayed as a box
@item
Underscore - the cursor is displayed as a horizontal bar
@item
Bar - the cursor is displayed as a vertical bar
@item
Hollow - the cursor is displayed as a box with an outline but no fill
@end itemize

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

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

@end itemize

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.

@itemize @bullet
@item
To re-bind the Alt or Opt key select a keybinding from the Alt/Opt Key
combo box.
@item
To re-bind the Command key select a keybinding from the Command Key
combo box.
@end itemize

@node Mac Customization
@section 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 @samp{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 @samp{defaults read Emacs Foo}
and @samp{defaults write Emacs Foo barvalue}.

  Calling the function @code{ns-save-preferences} in lisp, or
selecting the @samp{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 @code{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 (@pxref{Mac Preferences}).  It is
important to note that when you hit @samp{OK} on this panel,
@emph{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 @samp{Emacs}.  Emacs also accepts
color specifications of the form @samp{ARGBaarrggbb} where @var{aa},
@var{rr}, @var{gg}, and @var{bb} are two hexadecimal digits describing
the alpha, red, green, and blue content of the color respectively.
@samp{HSBhhssbb}, @samp{CMYKccmmyykk} and @samp{GRAYgg} are the
equivalents in @samp{HSB}, @samp{CMYK} and gray scales.  (For HSB,
@samp{AHSBaahhssbb} is also accepted.)

@table @samp
@item 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.

@example
defaults write Emacs InternalBorderWidth 2
@end example

@item VerticalScrollBars
@samp{YES} or @samp{NO} to enable or disable scroll bars, @samp{left} or
@samp{right} to explicitly set the side.

@example
defaults write Emacs VerticalScrollBars YES
@end example

@item 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 @samp{Monaco} which doesn't have any bold or italic
versions.  (Italic will be synthesized.)

@item 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.

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

@example
defaults write Emacs Foreground "Black"
@end example

@item Background
The default background color for new frames.

@example
defaults write Emacs Background "White"
@end example

@item Height
Height in rows of the default window.

@example
defaults write Emacs Height 48
@end example

@item Width
Width in columns of the default window.

@example
defaults write Emacs Width 80
@end example

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

@example
defaults write Emacs CursorType box
@end example

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

@example
defaults write Emacs CursorBlinkRate NO
@end example

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

@example
defaults write Emacs CursorColor Highlight
@end example

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

@example
defaults write Emacs Top 100
@end example

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

@example
defaults write Emacs Left 100
@end example

@item HideOnAutoLaunch
@samp{YES} or @samp{NO} to determine whether Emacs will hide itself when
autolaunched from the dock.

@example
defaults write Emacs HideOnAutoLaunch NO
@end example

@item 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 @code{"defaults write"}, you can either set a floating
point value, or @samp{YES}, which is equivalent 0.5, or @samp{NO}, which is
equivalent to 0.0.

@example
defaults write Emacs ExpandSpace -0.125
@end example

@item 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.

@example
defaults write Emacs GSFontAntiAlias NO
@end example

@item 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.

@example
defaults write Emacs UseQuickdrawSmoothing YES
@end example

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

@example
defaults write Emacs AlternateModifier "none"
@end example

@item CommandModifier
This allows you to set the effect of the Command key.  The default is
@samp{super}, which is used in a set of keybindings such as @code{s-o} for
``open file'' and @code{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 @samp{meta} so they still have easy access to
Emacs functionality bound to meta keys.  You can also set this, like Alt/Opt,
to @samp{hyper} or @samp{alt}, though there are no bindings to combinations
using these keys by default.  The @samp{none} option is not available for the
Command key.

@example
defaults write Emacs CommandModifier "meta"
@end example

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

@example
defaults write Emacs TestFrame "100 200 30 70"
@end example

Another default previouly used by many Emacs users is this.

@example
defaults write Workspace DefaultOpenApp Emacs
@end example

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
@file{~/Applications} and @file{~/Applications}).  If anyone knows the current
way to do this under OS X please contact the authors.

@end table

@ignore
   arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
@end ignore