| 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 |
| 5 | @appendix Emacs and Mac OS / GNUstep |
| 6 | @cindex Mac OS X |
| 7 | @cindex Macintosh |
| 8 | @cindex GNUstep |
| 9 | |
| 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. |
| 16 | |
| 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. |
| 26 | |
| 27 | @menu |
| 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. |
| 32 | @end menu |
| 33 | |
| 34 | @node Mac / GNUstep Basics |
| 35 | @section Basic Emacs usage under Mac OS and GNUstep |
| 36 | |
| 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}). |
| 42 | |
| 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. |
| 50 | |
| 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. |
| 56 | |
| 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 |
| 61 | file names. |
| 62 | |
| 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 |
| 68 | clipboard. |
| 69 | |
| 70 | |
| 71 | @subsection Grabbing environment variables |
| 72 | |
| 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. |
| 82 | |
| 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. |
| 86 | |
| 87 | @node Mac / GNUstep Customization |
| 88 | @section Mac / GNUstep Customization |
| 89 | |
| 90 | Emacs can be customized in several ways in addition to the standard |
| 91 | customization buffers and the Options menu. |
| 92 | |
| 93 | |
| 94 | @subsection Font and Color Panels |
| 95 | |
| 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. |
| 100 | |
| 101 | @c To make the setting permanent, use @samp{Save Options} in the |
| 102 | @c Options menu, or run @code{menu-bar-options-save}. |
| 103 | |
| 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. |
| 109 | |
| 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}. |
| 112 | |
| 113 | Useful in this context is the listing of all faces obtained by |
| 114 | @kbd{M-x list-faces-display}. |
| 115 | |
| 116 | @subsection Customization options specific to Mac OS / GNUstep |
| 117 | |
| 118 | The following customization options are specific to the Nextstep port. |
| 119 | |
| 120 | @table @code |
| 121 | @item ns-auto-hide-menu-bar |
| 122 | Non-nil means the menu-bar is hidden by default, but appears if you |
| 123 | move the mouse pointer over it. (Requires Mac OS X 10.6 or later.) |
| 124 | |
| 125 | @end table |
| 126 | |
| 127 | |
| 128 | @node Mac / GNUstep Events |
| 129 | @section Windowing System Events under Mac OS / GNUstep |
| 130 | |
| 131 | Nextstep applications receive a number of special events which have |
| 132 | no X equivalent. These are sent as specially defined ``keys'', which |
| 133 | do not correspond to any sequence of keystrokes. Under Emacs, these |
| 134 | ``key'' events can be bound to functions just like ordinary |
| 135 | keystrokes. Here is a list of these events. |
| 136 | |
| 137 | @table @key |
| 138 | @item ns-open-file |
| 139 | @vindex ns-pop-up-frames |
| 140 | This event occurs when another Nextstep application requests that |
| 141 | Emacs open a file. A typical reason for this would be a user |
| 142 | double-clicking a file in the Finder application. By default, Emacs |
| 143 | responds to this event by opening a new frame and visiting the file in |
| 144 | that frame (@code{ns-find-file}). As an exception, if the selected |
| 145 | buffer is the @file{*scratch*} buffer, Emacs visits the file in the |
| 146 | selected frame. |
| 147 | |
| 148 | You can change how Emacs responds to a @code{ns-open-file} event by |
| 149 | changing the variable @code{ns-pop-up-frames}. Its default value, |
| 150 | @samp{fresh}, is what we have just described. A value of @code{t} |
| 151 | means to always visit the file in a new frame. A value of @code{nil} |
| 152 | means to always visit the file in an existing frame. |
| 153 | |
| 154 | @item ns-open-temp-file |
| 155 | This event occurs when another application requests that Emacs open a |
| 156 | temporary file. By default, this is handled by just generating a |
| 157 | @code{ns-open-file} event, the results of which are described above. |
| 158 | |
| 159 | @item ns-open-file-line |
| 160 | Some applications, such as ProjectBuilder and gdb, request not only a |
| 161 | particular file, but also a particular line or sequence of lines in |
| 162 | the file. Emacs handles this by visiting that file and highlighting |
| 163 | the requested line (@code{ns-open-file-select-line}). |
| 164 | |
| 165 | @item ns-drag-file |
| 166 | This event occurs when a user drags files from another application |
| 167 | into an Emacs frame. The default behavior is to insert the contents |
| 168 | of all the dragged files into the current buffer |
| 169 | (@code{ns-insert-files}). The list of dragged files is stored in the |
| 170 | variable @code{ns-input-file}. |
| 171 | |
| 172 | @item ns-drag-color |
| 173 | This event occurs when a user drags a color from the color well (or |
| 174 | some other source) into an Emacs frame. The default behavior is to |
| 175 | alter the foreground color of the area the color was dragged onto |
| 176 | (@code{ns-set-foreground-at-mouse}). If this event is issued with a |
| 177 | @key{Shift} modifier, Emacs changes the background color instead |
| 178 | (@code{ns-set-background-at-mouse}). The name of the dragged color is |
| 179 | stored in the variable @code{ns-input-color}. |
| 180 | |
| 181 | @item ns-change-font |
| 182 | This event occurs when the user selects a font in a Nextstep font |
| 183 | panel (which can be opened with @kbd{Cmd-t}). The default behavior is |
| 184 | to adjust the font of the selected frame |
| 185 | (@code{ns-respond-to-changefont}). The name and size of the selected |
| 186 | font are stored in the variables @code{ns-input-font} and |
| 187 | @code{ns-input-fontsize}, respectively. |
| 188 | |
| 189 | @item ns-power-off |
| 190 | This event occurs when the user logs out and Emacs is still running, or when |
| 191 | `Quit Emacs' is chosen from the application menu. |
| 192 | The default behavior is to save all file-visiting buffers. |
| 193 | @end table |
| 194 | |
| 195 | Emacs also allows users to make use of Nextstep services, via a set |
| 196 | of commands whose names begin with @samp{ns-service-} and end with the |
| 197 | name of the service. Type @kbd{M-x ns-service-@key{TAB}} to |
| 198 | see a list of these commands. These functions either operate on |
| 199 | marked text (replacing it with the result) or take a string argument |
| 200 | and return the result as a string. You can also use the Lisp function |
| 201 | @code{ns-perform-service} to pass arbitrary strings to arbitrary |
| 202 | services and receive the results back. Note that you may need to |
| 203 | restart Emacs to access newly-available services. |
| 204 | |
| 205 | @node GNUstep Support |
| 206 | @section GNUstep Support |
| 207 | |
| 208 | Emacs can be built and run under GNUstep, but there are still |
| 209 | issues to be addressed. Interested developers should contact |
| 210 | @email{emacs-devel@@gnu.org}. |