@c This is part of the Emacs manual.
@c Copyright (C) 2000--2021 Free Software Foundation, Inc.
@c See file emacs.texi for copying conditions.
@node Mac OS / GNUstep
@appendix Emacs and macOS / GNUstep
@cindex macOS
@cindex Macintosh
@cindex GNUstep

  This section describes the peculiarities of using Emacs built with
the GNUstep libraries on GNU/Linux or other operating systems, or on
macOS with native window system support.  On macOS, Emacs can be
built either without window system support, with X11, or with the
Cocoa interface; this section only applies to the Cocoa build.  This
does not support versions before macOS 10.6.

  GNUstep is free software; macOS is not.  Because it is a non-free
operating system, macOS denies its users the freedom that every computer
user deserves.  That is an injustice.  For your freedom's sake, we
urge you to switch to a free operating system.

  We support GNU Emacs on proprietary operating systems because
we hope this taste of freedom will inspire users to escape from them.

  For various historical and technical reasons, Emacs uses the term
@samp{Nextstep} internally, instead of ``Cocoa'' or ``macOS''; for
instance, most of the commands and variables described in this section
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 descendant.  Apart from Cocoa, there is
another NeXTstep-style system: GNUstep, which is free software.  As of
this writing, Emacs GNUstep support is in alpha status (@pxref{GNUstep
Support}), but we hope to improve it in the future.

@menu
* Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or macOS.
* Mac / GNUstep Customization:: Customizations under GNUstep or macOS.
* Mac / GNUstep Events::        How window system events are handled.
* GNUstep Support::             Details on status of GNUstep support.
@end menu

@node Mac / GNUstep Basics
@section Basic Emacs usage under macOS and GNUstep

@cindex modifier keys (macOS)
  By default, the @key{Alt} and @key{Option} keys are the same as
@key{Meta}.  The Mac @key{Cmd} key is the same as @key{Super}, and
Emacs provides a set of key bindings using this modifier key that mimic
other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}).  You
can change these bindings in the usual way (@pxref{Key Bindings}).
The modifiers themselves can be customized;
@pxref{Mac / GNUstep Customization}.

  @kbd{S-mouse-1} adjusts the region to the click position,
just like @kbd{mouse-3} (@code{mouse-save-then-kill}); it does not pop
up a menu for changing the default face, as @kbd{S-mouse-1} normally
does (@pxref{Text Scale}).  This change makes Emacs behave more like
other Mac / GNUstep applications.

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

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


@subsection Grabbing environment variables

@c How is this any different to launching from a window manager menu
@c in GNU/Linux?  These are sometimes not login shells either.
@cindex environment variables (macOS)
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.

For the PATH and MANPATH variables, a system-wide method
of setting PATH is recommended on macOS, using the
@file{/etc/paths} files and the @file{/etc/paths.d} directory.

@node Mac / GNUstep Customization
@section Mac / GNUstep Customization

There are a few customization options that are specific to the
Nextstep port.  For example, they affect things such as the modifier
keys and the fullscreen behavior.  To see all such options, use
@kbd{M-x customize-group @key{RET} ns @key{RET}}.

@subsection Modifier keys

The following variables control the behavior of the actual modifier
keys:

@table @code
@vindex ns-alternate-modifier
@vindex ns-right-alternate-modifier
@item ns-alternate-modifier
@itemx ns-right-alternate-modifier
The left and right @key{Option} or @key{Alt} keys.

@vindex ns-command-modifier
@vindex ns-right-command-modifier
@item ns-command-modifier
@itemx ns-right-command-modifier
The left and right @key{Command} keys.

@vindex ns-control-modifier
@vindex ns-right-control-modifier
@item ns-control-modifier
@itemx ns-right-control-modifier
The left and right @key{Control} keys.

@vindex ns-function-modifier
@item ns-function-modifier
The @key{Function} (fn) key.
@end table

The value of each variable is either a symbol, describing the key for
any purpose, or a list of the form
@code{(:ordinary @var{symbol} :function @var{symbol} :mouse @var{symbol})},
which describes the modifier when used with ordinary keys, function keys
(that do not produce a character, such as arrow keys), and mouse clicks.

If the @var{symbol} is one of @code{control}, @code{meta}, @code{alt},
@code{super} or @code{hyper}, this describes the Emacs modifier it
represents.  If @var{symbol} is @code{none}, Emacs does not use the
key, which retains its standard behavior.  For instance, the
@key{Option} key in macOS is then used for composing additional
characters.

The variables for right-hand keys, like @code{ns-right-alternate-modifier},
may also be set to @code{left}, which means to use the same behavior as
the corresponding left-hand key.

@subsection Frame Variables

@table @code
@vindex ns-use-proxy-icon
@item ns-use-proxy-icon
This variable specifies whether to display the proxy icon in the
titlebar.

@vindex ns-confirm-quit
@item ns-confirm-quit
This variable specifies whether to display a graphical confirmation
dialogue on quitting.

@vindex ns-auto-hide-menu-bar
@item ns-auto-hide-menu-bar
This variable specifies whether the macOS menu bar is hidden when an
Emacs frame is selected.  If non-nil the menu bar is not shown unless
the mouse pointer is moved near to the top of the screen.

@vindex ns-use-native-fullscreen
@item ns-use-native-fullscreen
This variable controls whether to use native, or non-native
fullscreen.  Native fullscreen is only available on macOS 10.7 and
above.
@end table

@subsection macOS Trackpad/Mousewheel Variables

These variables only apply to macOS 10.7 (Lion) and above.

@table @code
@vindex ns-use-mwheel-acceleration
@item ns-use-mwheel-acceleration
This variable controls whether Emacs ignores the system mousewheel
acceleration.  When nil each `click' of the mousewheel will correspond
exactly with one mousewheel event.  When non-nil, the default, each
`click' may correspond with more than one mousewheel event, depending
on the user's input.

@vindex ns-use-mwheel-momentum
@item ns-use-mwheel-momentum
This variable controls whether Emacs ignores the system `momentum'
when scrolling using a trackpad.  When non-nil, the default, scrolling
rapidly may result in the buffer continuing to scroll for a short
while after the user has lifted their fingers off the trackpad.

@vindex ns-mwheel-line-height
@item ns-mwheel-line-height
This variable controls the sensitivity of scrolling with the trackpad.
Apple trackpads scroll by pixels, not lines, so Emacs converts the
system's pixel values into lines.  When set to a number, this variable
sets the number of pixels Emacs will consider as one line.  When nil
or a non-number the default line height is used.

Setting a lower number makes the trackpad more sensitive, and a higher
number makes the trackpad less sensitive.
@end table

@subsection Fonts

@findex ns-popup-font-panel
The standard Mac / GNUstep font panel is accessible with @kbd{M-x
ns-popup-font-panel} and will set the default font in the frame most
recently used or clicked on.

@c  To make the setting permanent, use @samp{Save Options} in the
@c Options menu, or run @code{menu-bar-options-save}.

Synthetic bold looks thinner if the background is darker than the
foreground and the LCD font smoothing is turned on.  In such cases,
you can turn off synthetic bold for particular fonts and use
overstriking instead by customizing the variable
@code{face-ignored-fonts}:

@lisp
(push "\\`-[^-]*-monaco-bold-" face-ignored-fonts)
@end lsip

@node Mac / GNUstep Events
@section Windowing System Events under macOS / GNUstep
@cindex events on macOS

  Nextstep applications receive a number of special events which have
no X equivalent.  These are sent as specially defined key events, 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 @file{*scratch*} buffer, Emacs visits the file in the
selected frame.

You can change how Emacs responds to a @code{ns-open-file} event by
changing the variable @code{ns-pop-up-frames}.  Its default value,
@samp{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 the selected 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.

@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-n-drop
This event occurs when a user drags an object from another application
into an Emacs frame.  The default behavior is to open a file in the
window under the mouse, or to insert text at point of the window under
the mouse.

The sending application has some limited ability to decide how Emacs
handles the sent object, but the user may override the default
behavior by holding one or more modifier key.

@table @kbd
@item control
Insert as text in the current buffer.  If the object is a file, this
will insert the filename.
@item alt/option
Attempt to open the object as though it is a file or URL.
@item super/command
Perform the default action for the type.  This can be useful when an
application is overriding the default behavior.
@end table

The modifier keys listed above are defined by macOS and are unaffected
by user changes to the modifiers in Emacs.

@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, or when
``Quit Emacs'' is chosen from the application menu.
The default behavior is to save all file-visiting buffers.
@end table

@cindex using Nextstep services (macOS)
  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}} 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 GNUstep Support
@section GNUstep Support

Emacs can be built and run under GNUstep, but there are still
issues to be addressed.  Interested developers should contact
@ifnothtml
@email{emacs-devel@@gnu.org}.
@end ifnothtml
@ifhtml
@url{https://lists.gnu.org/mailman/listinfo/emacs-devel, the
emacs-devel mailing list}.
@end ifhtml