1 @c This is part of the Emacs manual.
2 @c Copyright (C) 2000-2012 Free Software Foundation, Inc.
3 @c See file emacs.texi for copying conditions.
4 @node Mac OS / GNUstep, Microsoft Windows, Antinews, Top
5 @appendix Emacs and Mac OS / GNUstep
10 This section describes the peculiarities of using Emacs built with
11 the GNUstep libraries on GNU/Linux or other operating systems, or on
12 Mac OS X with native window system support. On Mac OS X, Emacs can be
13 built either without window system support, with X11, or with the
14 Cocoa interface; this section only applies to the Cocoa build. This
15 does not support versions of Mac OS X earlier than 10.4.
17 For various historical and technical reasons, Emacs uses the term
18 @samp{Nextstep} internally, instead of ``Cocoa'' or ``Mac OS X''; for
19 instance, most of the commands and variables described in this section
20 begin with @samp{ns-}, which is short for @samp{Nextstep}. NeXTstep
21 was an application interface released by NeXT Inc during the 1980s, of
22 which Cocoa is a direct descendant. Apart from Cocoa, there is
23 another NeXTstep-style system: GNUstep, which is free software. As of
24 this writing, Emacs GNUstep support is alpha status (@pxref{GNUstep
25 Support}), but we hope to improve it in the future.
28 * Mac / GNUstep Basics:: Basic Emacs usage under GNUstep or Mac OS.
29 * Mac / GNUstep Customization:: Customizations under GNUstep or Mac OS.
30 * Mac / GNUstep Events:: How window system events are handled.
31 * GNUstep Support:: Details on status of GNUstep support.
34 @node Mac / GNUstep Basics, Mac / GNUstep Customization, , Mac OS / GNUstep
35 @section Basic Emacs usage under Mac OS and GNUstep
37 By default, the @key{alt} and @key{option} keys are the same as
38 @key{Meta}. The Mac @key{Cmd} key is the same as @key{Super}, and
39 Emacs provides a set of key bindings using this modifier key that mimic
40 other Mac / GNUstep applications (@pxref{Mac / GNUstep Events}). You
41 can change these bindings in the usual way (@pxref{Key Bindings}).
43 @c FIXME mention ns-alternate-modifier?
44 The variable @code{ns-right-alternate-modifier} controls the
45 behavior of the right @key{alt} and @key{option} keys. These keys
46 behave like the left-hand keys if the value is @code{left} (the
47 default). A value of @code{control}, @code{meta}, @code{alt},
48 @code{super}, or @code{hyper} makes them behave like the corresponding
49 modifier keys; a value of @code{none} tells Emacs to ignore them.
51 @kbd{S-Mouse-1} adjusts the region to the click position,
52 just like @kbd{Mouse-3} (@code{mouse-save-then-kill}); it does not pop
53 up a menu for changing the default face, as @kbd{S-Mouse-1} normally
54 does (@pxref{Text Scale}). This change makes Emacs behave more like
55 other Mac / GNUstep applications.
57 When you open or save files using the menus, or using the
58 @kbd{Cmd-o} and @kbd{Cmd-S} bindings, Emacs uses graphical file
59 dialogs to read file names. However, if you use the regular Emacs key
60 sequences, such as @kbd{C-x C-f}, Emacs uses the minibuffer to read
63 On GNUstep, in an X-windows environment you need to use @kbd{Cmd-c}
64 instead of one of the @kbd{C-w} or @kbd{M-w} commands to transfer text
65 to the X primary selection; otherwise, Emacs will use the
66 ``clipboard'' selection. Likewise, @kbd{Cmd-y} (instead of @kbd{C-y})
67 yanks from the X primary selection instead of the kill-ring or
71 @subsection Grabbing environment variables
73 @c How is this any different to launching from a window manager menu
74 @c in GNU/Linux? These are sometimes not login shells either.
75 Many programs which may run under Emacs, like latex or man, depend on the
76 settings of environment variables. If Emacs is launched from the shell, it
77 will automatically inherit these environment variables and its subprocesses
78 will inherit them from it. But if Emacs is launched from the Finder it
79 is not a descendant of any shell, so its environment variables haven't been
80 set, which often causes the subprocesses it launches to behave differently than
81 they would when launched from the shell.
83 For the PATH and MANPATH variables, a system-wide method
84 of setting PATH is recommended on Mac OS X 10.5 and later, using the
85 @file{/etc/paths} files and the @file{/etc/paths.d} directory.
87 @node Mac / GNUstep Customization, Mac / GNUstep Events, Mac / GNUstep Basics, Mac OS / GNUstep
88 @section Mac / GNUstep Customization
90 Emacs can be customized in several ways in addition to the standard
91 customization buffers and the Options menu.
94 @subsection Font and Color Panels
96 The standard Mac / GNUstep font and color panels are accessible via
97 Lisp commands. The Font Panel may be accessed with @kbd{M-x
98 ns-popup-font-panel}. It will set the default font in the frame most
99 recently used or clicked on.
101 @c To make the setting permanent, use @samp{Save Options} in the
102 @c Options menu, or run @code{menu-bar-options-save}.
104 You can bring up a color panel with @kbd{M-x ns-popup-color-panel} and
105 drag the color you want over the Emacs face you want to change. Normal
106 dragging will alter the foreground color. Shift dragging will alter the
107 background color. To discard the settings, create a new frame and
108 close the altered one.
110 @c To make the changes permanent select the "Save Options"
111 @c item in the "Options" menu, or run @code{menu-bar-options-save}.
113 Useful in this context is the listing of all faces obtained by
114 @kbd{M-x list-faces-display}.
116 @subsection Open files by dragging to an Emacs window
118 The default behavior when a user drags files from another application
119 into an Emacs frame is to insert the contents of all the dragged files
120 into the current buffer. To remap the @code{ns-drag-file} event to
121 open the dragged files in the current frame use the following line:
124 (define-key global-map [ns-drag-file] 'ns-find-file)
128 @subsection Customization options specific to Mac OS / GNUstep
130 The following customization options are specific to the Nextstep port.
133 @item ns-auto-hide-menu-bar
134 Non-nil means the menu-bar is hidden by default, but appears if you
135 move the mouse pointer over it. (Requires Mac OS X 10.6 or later.)
140 @node Mac / GNUstep Events, GNUstep Support, Mac / GNUstep Customization, Mac OS / GNUstep
141 @section Windowing System Events under Mac OS / GNUstep
143 Nextstep applications receive a number of special events which have
144 no X equivalent. These are sent as specially defined ``keys'', which
145 do not correspond to any sequence of keystrokes. Under Emacs, these
146 ``key'' events can be bound to functions just like ordinary
147 keystrokes. Here is a list of these events.
151 @vindex ns-pop-up-frames
152 This event occurs when another Nextstep application requests that
153 Emacs open a file. A typical reason for this would be a user
154 double-clicking a file in the Finder application. By default, Emacs
155 responds to this event by opening a new frame and visiting the file in
156 that frame (@code{ns-find-file}). As an exception, if the selected
157 buffer is the @samp{*scratch*} buffer, Emacs visits the file in the
160 You can change how Emacs responds to a @code{ns-open-file} event by
161 changing the variable @code{ns-pop-up-frames}. Its default value,
162 @samp{fresh}, is what we have just described. A value of @code{t}
163 means to always visit the file in a new frame. A value of @code{nil}
164 means to always visit the file in an existing frame.
166 @item ns-open-temp-file
167 This event occurs when another application requests that Emacs open a
168 temporary file. By default, this is handled by just generating a
169 @code{ns-open-file} event, the results of which are described above.
171 @item ns-open-file-line
172 Some applications, such as ProjectBuilder and gdb, request not only a
173 particular file, but also a particular line or sequence of lines in
174 the file. Emacs handles this by visiting that file and highlighting
175 the requested line (@code{ns-open-file-select-line}).
178 This event occurs when a user drags files from another application
179 into an Emacs frame. The default behavior is to insert the contents
180 of all the dragged files into the current buffer
181 (@code{ns-insert-files}). The list of dragged files is stored in the
182 variable @code{ns-input-file}.
185 This event occurs when a user drags a color from the color well (or
186 some other source) into an Emacs frame. The default behavior is to
187 alter the foreground color of the area the color was dragged onto
188 (@code{ns-set-foreground-at-mouse}). If this event is issued with a
189 @key{Shift} modifier, Emacs changes the background color instead
190 (@code{ns-set-background-at-mouse}). The name of the dragged color is
191 stored in the variable @code{ns-input-color}.
194 This event occurs when the user selects a font in a Nextstep font
195 panel (which can be opened with @kbd{Cmd-t}). The default behavior is
196 to adjust the font of the selected frame
197 (@code{ns-respond-to-changefont}). The name and size of the selected
198 font are stored in the variables @code{ns-input-font} and
199 @code{ns-input-fontsize}, respectively.
202 This event occurs when the user logs out and Emacs is still running, or when
203 `Quit Emacs' is chosen from the application menu.
204 The default behavior is to save all file-visiting buffers.
207 Emacs also allows users to make use of Nextstep services, via a set
208 of commands whose names begin with @samp{ns-service-} and end with the
209 name of the service. Type @kbd{M-x ns-service-@key{TAB}} to
210 see a list of these commands. These functions either operate on
211 marked text (replacing it with the result) or take a string argument
212 and return the result as a string. You can also use the Lisp function
213 @code{ns-perform-service} to pass arbitrary strings to arbitrary
214 services and receive the results back. Note that you may need to
215 restart Emacs to access newly-available services.
217 @node GNUstep Support, , Mac / GNUstep Events, Mac OS / GNUstep
218 @section GNUstep Support
220 Emacs can be built and run under GNUstep, but there are still
221 issues to be addressed. Interested developers should contact
222 @email{emacs-devel@@gnu.org}.