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