doc/emacs/macos.texi

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