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
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
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
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
37 @node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep
38 @section Basic Emacs usage under Mac OS and GNUstep
40 Redundancy in the menus can be reduced and more shortcuts shown by
41 invoking @code{ns-extended-platform-support-mode}.
43 By default, the @key{alt} and @key{option} keys are the same as
44 @key{Meta} when running under Mac OS. The Mac @key{Cmd} key is the
45 same as @key{Super}, and Emacs provides a set of keybindings using
46 this modifier key that mimic other Mac / GNUstep applications (@pxref{Mac /
47 GNUstep Events}). You can change these bindings in the usual way (@pxref{Key
50 The standard Mac / GNUstep font and color panels are accessible via the
51 @samp{Windows} menu, or via the standard @key{Cmd-t} and @key{Cmd-C}
52 keybindings. To use the color panel, drag from it to an Emacs frame
53 to change the foreground color of the face at that position (if the
54 @key{shift} key is held down, it changes the background color
55 instead). To finalize the settings for either color or font, choose
56 @samp{Save Options} in the @samp{Options} menu. To discard the
57 settings, create a new frame and close the altered one.
59 @key{S-Mouse-1} (i.e., clicking the left mouse button
60 while holding down the @key{Shift} key) adjusts the region to the
61 click position, just like @key{Mouse-3} (@code{mouse-save-then-kill});
62 it does not pop up a menu for changing the default face, as
63 @key{S-Mouse-1} normally does (@pxref{Temporary Face Changes}). This
64 change makes Emacs behave more like other Mac / GNUstep applications.
66 When you open or save files using the menus, or using the standard
67 @key{Cmd-o} and @key{Cmd-S} bindings, Emacs uses graphical file
68 dialogs to read file names. However, if you use the regular Emacs key
69 sequences, such as @key{C-x C-f}, Emacs uses the minibuffer to read
72 On GNUstep, in an X-windows environment you need to use @key{Cmd-c}
73 instead of one of the @key{C-w} or @key{M-w} commands to transfer text
74 to the X primary selection; otherwise, Emacs will use the
75 ``clipboard'' selection. Likewise, @key{Cmd-y} (instead of @key{C-y})
76 yanks from the X primary selection instead of the kill-ring or
80 @subsection Grabbing environment variables
82 Many programs which may run under Emacs like latex or man depend on the
83 settings of environment variables. If Emacs is launched from the shell, it
84 will automatically inherit these environment variables and its subprocesses
85 will inherit them from it. But if Emacs is launched from the Finder it
86 is not a descendant of any shell, so its environment variables haven't been
87 set which often causes the subprocesses it launches to behave differently than
88 they would when launched from the shell.
90 To solve this problem for Emacs, there are two solutions. First is to
91 run, from the command line:
94 .../Emacs.app/Contents/MacOS/bin/mac-fix-env
97 This will pick up your environment settings and save them into a special file
98 @file{~/.MacOSX/environment.plist}, which the desktop environment will use to
99 set the environment for all launched applications. The drawback of this
100 method is it needs to be run again whenever something changes.
102 The other approach is to use the @code{ns-grabenv} command inside Emacs. This
103 function will run a subshell and copy its environment variables into Emacs.
105 Adding this line to your @file{~/.emacs} will grab the csh environment
106 whenever emacs runs under a window system.
109 (if window-system (ns-grabenv))
112 If you have a different shell you will have to give @code{ns-grabenv} some
113 arguments. For zsh you would do this.
116 (if window-system (ns-grabenv "/usr/bin/zsh"
121 The reason that @code{ns-grabenv} is not done by default is that it adds up
122 to a second or two to the Emacs startup time.
125 @node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep
126 @section Mac / GNUstep Customization
128 Emacs can be customized in several ways in addition to the standard
129 customization buffers and the Options menu.
131 In addition, redundancy in the menus can be reduced and more shortcuts
132 shown by invoking @code{ns-extended-platform-support-mode}.
135 @subsection Font and Color Panels
137 The Font Panel may be accessed from the Windows menu or by @kbd{Cmd-t}. It
138 will set the default font in the frame most recently used or clicked on. To
139 make the setting permanent, use @samp{Save Options} in the Options menu, or
140 run @code{menu-bar-options-save}.
142 You can bring up a color panel (with @key{Cmd-C} or from the Windows menu) and
143 drag the color you want over the emacs face you want to change. Normal
144 dragging will alter the foreground color. Shift dragging will alter the
145 background color. To make the changes permanent select the "Save Options"
146 item in the "Options" menu, or run @code{menu-bar-options-save}. Useful in this
147 context is the listing of all faces obtained by @key{M-x}
148 @code{list-faces-display}.
150 @subsection Open files by dragging to an Emacs window
152 The default behaviour when a user drags files from another application
153 into an Emacs frame is to insert the contents of all the dragged files
154 into the current buffer. To remap the @code{ns-drag-file} event to
155 open the dragged files in the current frame use the following line:
158 (define-key global-map [ns-drag-file] 'ns-find-file)
162 @node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep
163 @section Windowing System Events under Mac OS / GNUstep
165 Nextstep applications receive a number of special events which have
166 no X equivalent. These are sent as specially defined ``keys'', which
167 do not correspond to any sequence of keystrokes. Under Emacs, these
168 ``key'' events can be bound to functions just like ordinary
169 keystrokes. Here is a list of these events.
173 @vindex ns-pop-up-frames
174 This event occurs when another Nextstep application requests that
175 Emacs open a file. A typical reason for this would be a user
176 double-clicking a file in the Finder application. By default, Emacs
177 responds to this event by opening a new frame and visiting the file in
178 that frame (@code{ns-find-file}), As an exception, if the selected
179 buffer is the @samp{*scratch*} buffer, Emacs visits the file in the
182 You can change how Emacs responds to @key{ns-open-file} by changing
183 the variable @code{ns-pop-up-frames}. Its default value,
184 @code{'fresh}, is what we have just described. A value of @code{t}
185 means to always visit the file in a new frame. A value of @code{nil}
186 means to always visit the file in an existing frame.
188 @item ns-open-temp-file
189 This event occurs when another application requests that Emacs open a
190 temporary file. By default, this is handled by just generating a
191 @code{ns-open-file} event, the results of which are described above.
193 You can bind @key{ns-pop-up-frames} and @key{ns-open-temp-file} to
194 other Lisp functions. When the event is registered, the name of the
195 file to open is stored in the variable @code{ns-input-file}.
197 @item ns-open-file-line
198 Some applications, such as ProjectBuilder and gdb, request not only a
199 particular file, but also a particular line or sequence of lines in
200 the file. Emacs handles this by visiting that file and highlighting
201 the requested line (@code{ns-open-file-select-line}).
204 This event occurs when a user drags files from another application
205 into an Emacs frame. The default behavior is to insert the contents
206 of all the dragged files into the current buffer
207 (@code{ns-insert-files}). The list of dragged files is stored in the
208 variable @code{ns-input-file}.
211 This event occurs when a user drags a color from the color well (or
212 some other source) into an Emacs frame. The default behavior is to
213 alter the foreground color of the area the color was dragged onto
214 (@code{ns-set-foreground-at-mouse}). If this event is issued with a
215 @key{Shift} modifier, Emacs changes the background color instead
216 (@code{ns-set-background-at-mouse}). The name of the dragged color is
217 stored in the variable @code{ns-input-color}.
220 This event occurs when the user selects a font in a Nextstep font
221 panel (which can be opened with @kbd{Cmd-t}). The default behavior is
222 to adjust the font of the selected frame
223 (@code{ns-respond-to-changefont}). The name and size of the selected
224 font are stored in the variables @code{ns-input-font} and
225 @code{ns-input-fontsize} respectively.
228 This event occurs when the user logs out and Emacs is still running, or when
229 `Quit Emacs' is chosen from the application menu.
230 The default behavior is to save all file-visiting buffers.
233 Emacs also allows users to make use of Nextstep services, via a set
234 of commands whose names begin with @samp{ns-service-} and end with the
235 name of the service. Type @kbd{M-x ns-service-@key{TAB}@key{TAB}} to
236 see a list of these commands. These functions either operate on
237 marked text (replacing it with the result) or take a string argument
238 and return the result as a string. You can also use the Lisp function
239 @code{ns-perform-service} to pass arbitrary strings to arbitrary
240 services and receive the results back. Note that you may need to
241 restart Emacs to access newly-available services.
244 @node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep
245 @section GNUstep Support
247 Emacs can be built and run under GNUstep however building is difficult and
248 there are some limitations to functionality. In particular, it may be
249 necessary to run @samp{make bootstrap} with a plain X configuration, then
250 @samp{make clean} and @samp{./configure --with-ns} followed by @samp{make
253 Currently CANNOT_DUMP is automatically enabled in GNUstep configurations,
254 because the unex file(s) for GNUstep, mainly @samp{unexelf.c}, have not been
255 updated yet with the ``zone'' code in and related to @samp{unexmacosx.c}.
258 arch-tag: a822c2ab-4273-4997-927e-c153bb71dcf6