doc/emacs/macos.texi

   1 @c This is part of the Emacs manual.
   2 @c Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
   3 @c   2009, 2010  Free Software Foundation, Inc.
   4 @c See file emacs.texi for copying conditions.
   5 @node Mac OS / GNUstep, Microsoft Windows, Antinews, Top
   6 @appendix Emacs and Mac OS / GNUstep
   7 @cindex Mac OS X
   8 @cindex Macintosh
   9 @cindex GNUstep
  10
  11   This section briefly describes the peculiarities of using Emacs built with
  12 the GNUstep libraries on GNU/Linux or other operating systems, or on Mac OS X
  13 with native window system support.  For Mac OS X, Emacs can be built either
  14 without window system support, with X11, or with the Cocoa interface.  This
  15 section only applies to the Cocoa build.  Emacs 23 does not support Mac OS
  16 Classic.
  17
  18   Emacs, when built on Mac OS X, uses the Cocoa application interface.  For
  19 various historical and technical reasons, Emacs uses the term @samp{Nextstep}
  20 internally, instead of ``Cocoa'' or ``Mac OS X''; for instance, most of the
  21 commands and variables described in the following sections begin with
  22 @samp{ns-}, which is short for @samp{Nextstep}.  NeXTstep was an application
  23 interface released by NeXT Inc during the 1980s, of which Cocoa is a direct
  24 descendant.  Apart from Cocoa, there is another NeXTstep-style system:
  25 GNUstep, which is free software.  As of this writing, the GNUstep support is
  26 alpha status (@pxref{GNUstep Support}), but we hope to improve it in the
  27 future.
  28
  29 @menu
  30 * Mac / GNUstep Basics::        Basic Emacs usage under GNUstep or Mac OS.
  31 * Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS.
  32 * Mac / GNUstep Events::        How window system events are handled.
  33 * GNUstep Support::             Details on status of GNUstep support.
  34 @end menu
  35
  36 @node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep
  37 @section Basic Emacs usage under Mac OS and GNUstep
  38
  39   By default, the @key{alt} and @key{option} keys are the same as
  40 @key{Meta} when running under Mac OS.  The Mac @key{Cmd} key is the
  41 same as @key{Super}, and Emacs provides a set of keybindings using
  42 this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac /
  43 GNUstep Events}).  You can change these bindings in the usual way (@pxref{Key
  44 Bindings}).
  45
  46   The standard Mac / GNUstep font and color panels are accessible via Lisp commands.
  47   To use the color panel, drag from it to an Emacs frame to change the
  48 foreground color of the face at that position (if the @key{shift} key
  49 is held down, it changes the background color instead). To discard the
  50 settings, create a new frame and close the altered one.
  51 @c [unclear if the following holds.]
  52 @c  To finalize the settings for either color or font, choose @samp{Save Options} in the @samp{Options} menu.
  53
  54   @key{S-Mouse-1} (i.e., clicking the left mouse button
  55 while holding down the @key{Shift} key) adjusts the region to the
  56 click position, just like @key{Mouse-3} (@code{mouse-save-then-kill});
  57 it does not pop up a menu for changing the default face, as
  58 @key{S-Mouse-1} normally does (@pxref{Temporary Face Changes}).  This
  59 change makes Emacs behave more like other Mac / GNUstep applications.
  60
  61   When you open or save files using the menus, or using the
  62 @key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file
  63 dialogs to read file names.  However, if you use the regular Emacs key
  64 sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read
  65 file names.
  66
  67   On GNUstep, in an X-windows environment you need to use @key{Cmd-c}
  68 instead of one of the @key{C-w} or @key{M-w} commands to transfer text
  69 to the X primary selection; otherwise, Emacs will use the
  70 ``clipboard'' selection.  Likewise, @key{Cmd-y} (instead of @key{C-y})
  71 yanks from the X primary selection instead of the kill-ring or
  72 clipboard.
  73
  74
  75 @subsection Grabbing environment variables
  76
  77 @c How is this any different to launching from a window manager menu
  78 @c in GNU/Linux?  These are sometimes not login shells either.
  79 Many programs which may run under Emacs, like latex or man, depend on the
  80 settings of environment variables.  If Emacs is launched from the shell, it
  81 will automatically inherit these environment variables and its subprocesses
  82 will inherit them from it.  But if Emacs is launched from the Finder it
  83 is not a descendant of any shell, so its environment variables haven't been
  84 set, which often causes the subprocesses it launches to behave differently than
  85 they would when launched from the shell.
  86
  87 For the PATH and MANPATH variables, a system-wide method
  88 of setting PATH is recommended on Mac OS X 10.5 and later, using the
  89 @file{/etc/paths} files and the @file{/etc/paths.d} directory.
  90
  91 @node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep
  92 @section Mac / GNUstep Customization
  93
  94 Emacs can be customized in several ways in addition to the standard
  95 customization buffers and the Options menu.
  96
  97
  98 @subsection Font and Color Panels
  99
 100 The Font Panel may be accessed with M-x ns-popup-font-panel.  It
 101 will set the default font in the frame most recently used or clicked
 102 on.
 103
 104 @c  To make the setting permanent, use @samp{Save Options} in the
 105 @c Options menu, or run @code{menu-bar-options-save}.
 106
 107 You can bring up a color panel with M-x ns-popup-color-panel. and
 108 drag the color you want over the emacs face you want to change.  Normal
 109 dragging will alter the foreground color.  Shift dragging will alter the
 110 background color.
 111
 112 @c To make the changes permanent select the "Save Options"
 113 @c item in the "Options" menu, or run @code{menu-bar-options-save}.
 114
 115 Useful in this context is the listing of all faces obtained by @key{M-x}
 116 @code{list-faces-display}.
 117
 118 @subsection Open files by dragging to an Emacs window
 119
 120 The default behaviour when a user drags files from another application
 121 into an Emacs frame is to insert the contents of all the dragged files
 122 into the current buffer.  To remap the @code{ns-drag-file} event to
 123 open the dragged files in the current frame use the following line:
 124
 125 @lisp
 126 (define-key global-map [ns-drag-file] 'ns-find-file)
 127 @end lisp
 128
 129
 130 @node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep
 131 @section Windowing System Events under Mac OS / GNUstep
 132
 133   Nextstep applications receive a number of special events which have
 134 no X equivalent.  These are sent as specially defined ``keys'', which
 135 do not correspond to any sequence of keystrokes.  Under Emacs, these
 136 ``key'' events can be bound to functions just like ordinary
 137 keystrokes.  Here is a list of these events.
 138
 139 @table @key
 140 @item ns-open-file
 141 @vindex ns-pop-up-frames
 142 This event occurs when another Nextstep application requests that
 143 Emacs open a file.  A typical reason for this would be a user
 144 double-clicking a file in the Finder application.  By default, Emacs
 145 responds to this event by opening a new frame and visiting the file in
 146 that frame (@code{ns-find-file}).  As an exception, if the selected
 147 buffer is the @samp{*scratch*} buffer, Emacs visits the file in the
 148 selected frame.
 149
 150 You can change how Emacs responds to @key{ns-open-file} by changing
 151 the variable @code{ns-pop-up-frames}.  Its default value,
 152 @code{'fresh}, is what we have just described.  A value of @code{t}
 153 means to always visit the file in a new frame.  A value of @code{nil}
 154 means to always visit the file in an existing frame.
 155
 156 @item ns-open-temp-file
 157 This event occurs when another application requests that Emacs open a
 158 temporary file.  By default, this is handled by just generating a
 159 @code{ns-open-file} event, the results of which are described above.
 160
 161 You can bind @key{ns-pop-up-frames} and @key{ns-open-temp-file} to
 162 other Lisp functions.  When the event is registered, the name of the
 163 file to open is stored in the variable @code{ns-input-file}.
 164
 165 @item ns-open-file-line
 166 Some applications, such as ProjectBuilder and gdb, request not only a
 167 particular file, but also a particular line or sequence of lines in
 168 the file.  Emacs handles this by visiting that file and highlighting
 169 the requested line (@code{ns-open-file-select-line}).
 170
 171 @item ns-drag-file
 172 This event occurs when a user drags files from another application
 173 into an Emacs frame.  The default behavior is to insert the contents
 174 of all the dragged files into the current buffer
 175 (@code{ns-insert-files}).  The list of dragged files is stored in the
 176 variable @code{ns-input-file}.
 177
 178 @item ns-drag-color
 179 This event occurs when a user drags a color from the color well (or
 180 some other source) into an Emacs frame.  The default behavior is to
 181 alter the foreground color of the area the color was dragged onto
 182 (@code{ns-set-foreground-at-mouse}).  If this event is issued with a
 183 @key{Shift} modifier, Emacs changes the background color instead
 184 (@code{ns-set-background-at-mouse}).  The name of the dragged color is
 185 stored in the variable @code{ns-input-color}.
 186
 187 @item ns-change-font
 188 This event occurs when the user selects a font in a Nextstep font
 189 panel (which can be opened with @kbd{Cmd-t}).  The default behavior is
 190 to adjust the font of the selected frame
 191 (@code{ns-respond-to-changefont}).  The name and size of the selected
 192 font are stored in the variables @code{ns-input-font} and
 193 @code{ns-input-fontsize}, respectively.
 194
 195 @item ns-power-off
 196 This event occurs when the user logs out and Emacs is still running, or when
 197 `Quit Emacs' is chosen from the application menu.
 198 The default behavior is to save all file-visiting buffers.
 199 @end table
 200
 201   Emacs also allows users to make use of Nextstep services, via a set
 202 of commands whose names begin with @samp{ns-service-} and end with the
 203 name of the service.  Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} to
 204 see a list of these commands.  These functions either operate on
 205 marked text (replacing it with the result) or take a string argument
 206 and return the result as a string.  You can also use the Lisp function
 207 @code{ns-perform-service} to pass arbitrary strings to arbitrary
 208 services and receive the results back.  Note that you may need to
 209 restart Emacs to access newly-available services.
 210
 211
 212 @node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep
 213 @section GNUstep Support
 214
 215 Emacs can be built and run under GNUstep, however there are still some
 216 issues to be addressed.  Interested developers should contact
 217 @email{emacs-devel@@gnu.org}.
 218
 219 @c Presumably no longer relevant since CANNOT_DUMP removed 2009-05-06:
 220 @ignore
 221 In particular, it may be necessary to run @samp{make bootstrap} with a
 222 plain X configuration, then @samp{make clean} and @samp{./configure
 223 --with-ns} followed by @samp{make install}.
 224
 225 Currently CANNOT_DUMP is automatically enabled in GNUstep configurations,
 226 because the unex file(s) for GNUstep, mainly @samp{unexelf.c}, have not been
 227 updated yet with the ``zone'' code in and related to @samp{unexmacosx.c}.
 228 @end ignore
 229
 230
 231 @ignore
 232    arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6
 233 @end ignore