Fix typo.
[emacs.git] / doc / emacs / msdog.texi
blob4787f98c7ede81b9de1fb86f43ff9c3c2e0b889b
1 @c This is part of the Emacs manual.
2 @c Copyright (C) 1985-1987, 1993-1995, 1997, 2000-2014 Free Software
3 @c Foundation, Inc.
4 @c See file emacs.texi for copying conditions.
5 @node Microsoft Windows
6 @appendix Emacs and Microsoft Windows/MS-DOS
7 @cindex Microsoft Windows
8 @cindex MS-Windows, Emacs peculiarities
10   This section describes peculiarities of using Emacs on Microsoft
11 Windows.  Some of these peculiarities are also relevant to Microsoft's
12 older MS-DOS ``operating system'' (also known as ``MS-DOG'').
13 However, Emacs features that are relevant @emph{only} to MS-DOS are
14 described in a separate
15 @iftex
16 manual (@pxref{MS-DOS,,, emacs-xtra, Specialized Emacs Features}).
17 @end iftex
18 @ifnottex
19 section (@pxref{MS-DOS}).
20 @end ifnottex
23   The behavior of Emacs on MS-Windows is reasonably similar to what is
24 documented in the rest of the manual, including support for long file
25 names, multiple frames, scroll bars, mouse menus, and subprocesses.
26 However, a few special considerations apply, and they are described
27 here.
29 @menu
30 * Windows Startup::     How to start Emacs on Windows.
31 * Text and Binary::     Text files use CRLF to terminate lines.
32 * Windows Files::       File-name conventions on Windows.
33 * ls in Lisp::          Emulation of @code{ls} for Dired.
34 * Windows HOME::        Where Emacs looks for your @file{.emacs} and
35                           where it starts up.
36 * Windows Keyboard::    Windows-specific keyboard features.
37 * Windows Mouse::       Windows-specific mouse features.
38 * Windows Processes::   Running subprocesses on Windows.
39 * Windows Printing::    How to specify the printer on MS-Windows.
40 * Windows Fonts::       Specifying fonts on MS-Windows.
41 * Windows Misc::        Miscellaneous Windows features.
42 @ifnottex
43 * MS-DOS::              Using Emacs on MS-DOS.
44 @end ifnottex
45 @end menu
47 @node Windows Startup
48 @section How to Start Emacs on MS-Windows
49 @cindex starting Emacs on MS-Windows
51   There are several ways of starting Emacs on MS-Windows:
53 @enumerate
54 @item
55 @pindex runemacs.exe
56 @cindex desktop shortcut, MS-Windows
57 @cindex start directory, MS-Windows
58 @cindex directory where Emacs starts on MS-Windows
59 From the desktop shortcut icon: either double-click the left mouse
60 button on the icon, or click once, then press @key{RET}.  The desktop
61 shortcut should specify as its ``Target'' (in the ``Properties'' of
62 the shortcut) the full absolute file name of @file{runemacs.exe},
63 @emph{not} of @file{emacs.exe}.  This is because @file{runemacs.exe}
64 hides the console window that would have been created if the target of
65 the shortcut were @file{emacs.exe} (which is a console program, as far
66 as Windows is concerned).  If you use this method, Emacs starts in the
67 directory specified by the shortcut.  To control where that is,
68 right-click on the shortcut, select ``Properties'', and in the
69 ``Shortcut'' tab modify the ``Start in'' field to your liking.
71 @item
72 From the Command Prompt window, by typing @kbd{emacs @key{RET}} at the
73 prompt.  The Command Prompt window where you did that will not be
74 available for invoking other commands until Emacs exits.  In this
75 case, Emacs will start in the current directory of the Windows shell.
77 @item
78 From the Command Prompt window, by typing @kbd{runemacs @key{RET}} at
79 the prompt.  The Command Prompt window where you did that will be
80 immediately available for invoking other commands.  In this case,
81 Emacs will start in the current directory of the Windows shell.
83 @item
84 @cindex invoking Emacs from Windows Explorer
85 @pindex emacsclient.exe
86 @pindex emacsclientw.exe
87 Via @file{emacsclient.exe} or @file{emacsclientw.exe}, which allow you
88 to invoke Emacs from other programs, and to reuse a running Emacs
89 process for serving editing jobs required by other programs.
90 @xref{Emacs Server}.  The difference between @file{emacsclient.exe}
91 and @file{emacsclientw.exe} is that the former is a console program,
92 while the latter is a Windows GUI program.  Both programs wait for
93 Emacs to signal that the editing job is finished, before they exit and
94 return control to the program that invoked them.  Which one of them to
95 use in each case depends on the expectations of the program that needs
96 editing services.  If that program is itself a console (text-mode)
97 program, you should use @file{emacsclient.exe}, so that any of its
98 messages and prompts appear in the same command window as those of the
99 invoking program.  By contrast, if the invoking program is a GUI
100 program, you will be better off using @file{emacsclientw.exe}, because
101 @file{emacsclient.exe} will pop up a command window if it is invoked
102 from a GUI program.  A notable situation where you would want
103 @file{emacsclientw.exe} is when you right-click on a file in the
104 Windows Explorer and select ``Open With'' from the pop-up menu.  Use
105 the @samp{--alternate-editor=} or @samp{-a} options if Emacs might not
106 be running (or not running as a server) when @command{emacsclient} is
107 invoked---that will always give you an editor.  When invoked via
108 @command{emacsclient}, Emacs will start in the current directory of
109 the program that invoked @command{emacsclient}.
110 @end enumerate
112 @cindex emacsclient, on MS-Windows
113 Note that, due to limitations of MS-Windows, Emacs cannot have both
114 GUI and text-mode frames in the same session.  It also cannot open
115 text-mode frames on more than a single @dfn{Command Prompt} window,
116 because each Windows program can have only one console at any given
117 time.  For these reasons, if you invoke @command{emacsclient} with the
118 @option{-c} option, and the Emacs server runs in a text-mode session,
119 Emacs will always create a new text-mode frame in the same
120 @dfn{Command Prompt} window where it was started; a GUI frame will be
121 created only if the server runs in a GUI session.  Similarly, if you
122 invoke @command{emacsclient} with the @option{-t} option, Emacs will
123 create a GUI frame if the server runs in a GUI session, or a text-mode
124 frame when the session runs in text mode in a @dfn{Command Prompt}
125 window.  @xref{emacsclient Options}.
127 @node Text and Binary
128 @section Text Files and Binary Files
129 @cindex text and binary files on MS-DOS/MS-Windows
131   GNU Emacs uses newline characters to separate text lines.  This is the
132 convention used on GNU, Unix, and other Posix-compliant systems.
134 @cindex end-of-line conversion on MS-DOS/MS-Windows
135   By contrast, MS-DOS and MS-Windows normally use carriage-return linefeed,
136 a two-character sequence, to separate text lines.  (Linefeed is the same
137 character as newline.)  Therefore, convenient editing of typical files
138 with Emacs requires conversion of these end-of-line (EOL) sequences.
139 And that is what Emacs normally does: it converts carriage-return
140 linefeed into newline when reading files, and converts newline into
141 carriage-return linefeed when writing files.  The same mechanism that
142 handles conversion of international character codes does this conversion
143 also (@pxref{Coding Systems}).
145 @cindex cursor location, on MS-DOS
146 @cindex point location, on MS-DOS
147   One consequence of this special format-conversion of most files is
148 that character positions as reported by Emacs (@pxref{Position Info}) do
149 not agree with the file size information known to the operating system.
151   In addition, if Emacs recognizes from a file's contents that it uses
152 newline rather than carriage-return linefeed as its line separator, it
153 does not perform EOL conversion when reading or writing that file.
154 Thus, you can read and edit files from GNU and Unix systems on MS-DOS
155 with no special effort, and they will retain their Unix-style
156 end-of-line convention after you edit them.
158   The mode line indicates whether end-of-line translation was used for
159 the current buffer.  If MS-DOS end-of-line translation is in use for the
160 buffer, the MS-Windows build of Emacs displays a backslash @samp{\} after
161 the coding system mnemonic near the beginning of the mode line
162 (@pxref{Mode Line}).  If no EOL translation was performed, the string
163 @samp{(Unix)} is displayed instead of the backslash, to alert you that the
164 file's EOL format is not the usual carriage-return linefeed.
166 @cindex DOS-to-Unix conversion of files
167   To visit a file and specify whether it uses DOS-style or Unix-style
168 end-of-line, specify a coding system (@pxref{Text Coding}).  For
169 example, @kbd{C-x @key{RET} c unix @key{RET} C-x C-f foobar.txt}
170 visits the file @file{foobar.txt} without converting the EOLs; if some
171 line ends with a carriage-return linefeed pair, Emacs will display
172 @samp{^M} at the end of that line.  Similarly, you can direct Emacs to
173 save a buffer in a specified EOL format with the @kbd{C-x @key{RET} f}
174 command.  For example, to save a buffer with Unix EOL format, type
175 @kbd{C-x @key{RET} f unix @key{RET} C-x C-s}.  If you visit a file
176 with DOS EOL conversion, then save it with Unix EOL format, that
177 effectively converts the file to Unix EOL style, like the
178 @code{dos2unix} program.
180 @cindex untranslated file system
181 @findex add-untranslated-filesystem
182   When you use NFS, Samba, or some other similar method to access file
183 systems that reside on computers using GNU or Unix systems, Emacs
184 should not perform end-of-line translation on any files in these file
185 systems---not even when you create a new file.  To request this,
186 designate these file systems as @dfn{untranslated} file systems by
187 calling the function @code{add-untranslated-filesystem}.  It takes one
188 argument: the file system name, including a drive letter and
189 optionally a directory.  For example,
191 @example
192 (add-untranslated-filesystem "Z:")
193 @end example
195 @noindent
196 designates drive Z as an untranslated file system, and
198 @example
199 (add-untranslated-filesystem "Z:\\foo")
200 @end example
202 @noindent
203 designates directory @file{\foo} on drive Z as an untranslated file
204 system.
206   Most often you would use @code{add-untranslated-filesystem} in your
207 @file{.emacs} file, or in @file{site-start.el} so that all the users at
208 your site get the benefit of it.
210 @findex remove-untranslated-filesystem
211   To countermand the effect of @code{add-untranslated-filesystem}, use
212 the function @code{remove-untranslated-filesystem}.  This function takes
213 one argument, which should be a string just like the one that was used
214 previously with @code{add-untranslated-filesystem}.
216   Designating a file system as untranslated does not affect character
217 set conversion, only end-of-line conversion.  Essentially, it directs
218 Emacs to create new files with the Unix-style convention of using
219 newline at the end of a line.  @xref{Coding Systems}.
221 @node Windows Files
222 @section File Names on MS-Windows
223 @cindex file names on MS-Windows
225   MS-Windows and MS-DOS normally use a backslash, @samp{\}, to
226 separate name units within a file name, instead of the slash used on
227 other systems.  Emacs on MS-DOS/MS-Windows permits use of either slash or
228 backslash, and also knows about drive letters in file names.
230 @cindex file-name completion, on MS-Windows
231   On MS-DOS/MS-Windows, file names are case-insensitive, so Emacs by
232 default ignores letter-case in file names during completion.
234 @vindex w32-get-true-file-attributes
235   The variable @code{w32-get-true-file-attributes} controls whether
236 Emacs should issue additional system calls to determine more
237 accurately file attributes in primitives like @code{file-attributes}
238 and @code{directory-files-and-attributes}.  These additional calls are
239 needed to report correct file ownership, link counts and file types
240 for special files such as pipes.  Without these system calls, file
241 ownership will be attributed to the current user, link counts will be
242 always reported as 1, and special files will be reported as regular
243 files.
245   If the value of this variable is @code{local} (the default), Emacs
246 will issue these additional system calls only for files on local fixed
247 drives.  Any other non-@code{nil} value means do this even for
248 removable and remote volumes, where this could potentially slow down
249 Dired and other related features.  The value of @code{nil} means never
250 issue those system calls.  Non-@code{nil} values are more useful on
251 NTFS volumes, which support hard links and file security, than on FAT,
252 FAT32, and XFAT volumes.
254 @node ls in Lisp
255 @section Emulation of @code{ls} on MS-Windows
256 @cindex Dired, and MS-Windows/MS-DOS
257 @cindex @code{ls} emulation
259   Dired normally uses the external program @code{ls}
260 to produce the directory listing displayed in Dired
261 buffers (@pxref{Dired}).  However, MS-Windows and MS-DOS systems don't
262 come with such a program, although several ports of @sc{gnu} @code{ls}
263 are available.  Therefore, Emacs on those systems @emph{emulates}
264 @code{ls} in Lisp, by using the @file{ls-lisp.el} package.  While
265 @file{ls-lisp.el} provides a reasonably full emulation of @code{ls},
266 there are some options and features peculiar to that emulation;
267 @iftex
268 for more details, see the documentation of the variables whose names
269 begin with @code{ls-lisp}.
270 @end iftex
271 @ifnottex
272 they are described in this section.
274   The @code{ls} emulation supports many of the @code{ls} switches, but
275 it doesn't support all of them.  Here's the list of the switches it
276 does support: @option{-A}, @option{-a}, @option{-B}, @option{-C},
277 @option{-c}, @option{-G}, @option{-g}, @option{-h}, @option{-i}, @option{-n},
278 @option{-R}, @option{-r}, @option{-S}, @option{-s}, @option{-t}, @option{-U},
279 @option{-u}, and @option{-X}.  The @option{-F} switch is partially
280 supported (it appends the character that classifies the file, but does
281 not prevent symlink following).
283 @vindex ls-lisp-use-insert-directory-program
284   On MS-Windows and MS-DOS, @file{ls-lisp.el} is preloaded when Emacs
285 is built, so the Lisp emulation of @code{ls} is always used on those
286 platforms.  If you have a ported @code{ls}, setting
287 @code{ls-lisp-use-insert-directory-program} to a non-@code{nil} value
288 will revert to using an external program named by the variable
289 @code{insert-directory-program}.
291 @vindex ls-lisp-ignore-case
292   By default, @file{ls-lisp.el} uses a case-sensitive sort order for
293 the directory listing it produces; this is so the listing looks the
294 same as on other platforms.  If you wish that the files be sorted in
295 case-insensitive order, set the variable @code{ls-lisp-ignore-case} to
296 a non-@code{nil} value.
298 @vindex ls-lisp-dirs-first
299   By default, files and subdirectories are sorted together, to emulate
300 the behavior of @code{ls}.  However, native MS-Windows/MS-DOS file
301 managers list the directories before the files; if you want that
302 behavior, customize the option @code{ls-lisp-dirs-first} to a
303 non-@code{nil} value.
305 @vindex ls-lisp-verbosity
306   The variable @code{ls-lisp-verbosity} controls the file attributes
307 that @file{ls-lisp.el} displays.  The value should be a list that
308 contains one or more of the symbols @code{links}, @code{uid}, and
309 @code{gid}.  @code{links} means display the count of different file
310 names that are associated with (a.k.a.@: @dfn{links to}) the file's
311 data; this is only useful on NTFS volumes.  @code{uid} means display
312 the numerical identifier of the user who owns the file.  @code{gid}
313 means display the numerical identifier of the file owner's group.  The
314 default value is @code{(links uid gid)} i.e., all the 3 optional
315 attributes are displayed.
317 @vindex ls-lisp-emulation
318   The variable @code{ls-lisp-emulation} controls the flavor of the
319 @code{ls} emulation by setting the defaults for the 3 options
320 described above: @code{ls-lisp-ignore-case},
321 @code{ls-lisp-dirs-first}, and @code{ls-lisp-verbosity}.  The value of
322 this option can be one of the following symbols:
324 @table @code
325 @item GNU
326 @itemx nil
327 Emulate @sc{gnu} systems; this is the default.  This sets
328 @code{ls-lisp-ignore-case} and @code{ls-lisp-dirs-first} to
329 @code{nil}, and @code{ls-lisp-verbosity} to @code{(links uid gid)}.
330 @item UNIX
331 Emulate Unix systems.  Like @code{GNU}, but sets
332 @code{ls-lisp-verbosity} to @code{(links uid)}.
333 @item MacOS
334 Emulate MacOS@.  Sets @code{ls-lisp-ignore-case} to @code{t}, and
335 @code{ls-lisp-dirs-first} and @code{ls-lisp-verbosity} to @code{nil}.
336 @item MS-Windows
337 Emulate MS-Windows.  Sets @code{ls-lisp-ignore-case} and
338 @code{ls-lisp-dirs-first} to @code{t}, and @code{ls-lisp-verbosity} to
339 @code{(links)} on Windows NT/2K/XP/2K3 and to @code{nil} on Windows 9X@.
340 Note that the default emulation is @emph{not} @code{MS-Windows}, even
341 on Windows, since many users of Emacs on those platforms prefer the
342 @sc{gnu} defaults.
343 @end table
345 @noindent
346 Any other value of @code{ls-lisp-emulation} means the same as @code{GNU}.
347 Customizing this option calls the function @code{ls-lisp-set-options} to
348 update the 3 dependent options as needed.  If you change the value of
349 this variable without using customize after @file{ls-lisp.el} is loaded
350 (note that it is preloaded on MS-Windows and MS-DOS), you can call that
351 function manually for the same result.
353 @vindex ls-lisp-support-shell-wildcards
354   The variable @code{ls-lisp-support-shell-wildcards} controls how
355 file-name patterns are supported: if it is non-@code{nil} (the
356 default), they are treated as shell-style wildcards; otherwise they
357 are treated as Emacs regular expressions.
359 @vindex ls-lisp-format-time-list
360   The variable @code{ls-lisp-format-time-list} defines how to format
361 the date and time of files.  @emph{The value of this variable is
362 ignored}, unless Emacs cannot determine the current locale.  (However,
363 if the value of @code{ls-lisp-use-localized-time-format} is
364 non-@code{nil}, Emacs obeys @code{ls-lisp-format-time-list} even if
365 the current locale is available; see below.)
367 The value of @code{ls-lisp-format-time-list} is a list of 2 strings.
368 The first string is used if the file was modified within the current
369 year, while the second string is used for older files.  In each of
370 these two strings you can use @samp{%}-sequences to substitute parts
371 of the time.  For example:
372 @lisp
373 ("%b %e %H:%M" "%b %e  %Y")
374 @end lisp
376 @noindent
377 Note that the strings substituted for these @samp{%}-sequences depend
378 on the current locale.  @xref{Time Parsing,,, elisp, The Emacs Lisp
379 Reference Manual}, for more about format time specs.
381 @vindex ls-lisp-use-localized-time-format
382   Normally, Emacs formats the file time stamps in either traditional
383 or ISO-style time format.  However, if the value of the variable
384 @code{ls-lisp-use-localized-time-format} is non-@code{nil}, Emacs
385 formats file time stamps according to what
386 @code{ls-lisp-format-time-list} specifies.  The @samp{%}-sequences in
387 @code{ls-lisp-format-time-list} produce locale-dependent month and day
388 names, which might cause misalignment of columns in Dired display.
389 @end ifnottex
391 @node Windows HOME
392 @section HOME and Startup Directories on MS-Windows
393 @cindex @code{HOME} directory on MS-Windows
395   The Windows equivalent of @code{HOME} is the @dfn{user-specific
396 application data directory}.  The actual location depends on the
397 Windows version; typical values are @file{C:\Documents and
398 Settings\@var{username}\Application Data} on Windows 2000/XP/2K3,
399 @file{C:\Users\@var{username}\AppData\Roaming} on Windows
400 Vista/7/2008, and either @file{C:\WINDOWS\Application Data} or
401 @file{C:\WINDOWS\Profiles\@var{username}\Application Data} on Windows
402 9X/ME@.  If this directory does not exist or cannot be accessed, Emacs
403 falls back to @file{C:\} as the default value of @code{HOME}.
405   You can override this default value of @code{HOME} by explicitly
406 setting the environment variable @env{HOME} to point to any directory
407 on your system.  @env{HOME} can be set either from the command shell
408 prompt or from @samp{Properties} dialog of @samp{My Computer}.
409 @code{HOME} can also be set in the system registry,
410 @pxref{MS-Windows Registry}.
412   For compatibility with older versions of Emacs@footnote{
413 Older versions of Emacs didn't check the application data directory.
414 }, if there is a file named @file{.emacs} in @file{C:\}, the root
415 directory of drive @file{C:}, and @env{HOME} is set neither in the
416 environment nor in the Registry, Emacs will treat @file{C:\} as the
417 default @code{HOME} location, and will not look in the application
418 data directory, even if it exists.  Note that only @file{.emacs} is
419 looked for in @file{C:\}; the older name @file{_emacs} (see below) is
420 not.  This use of @file{C:\.emacs} to define @code{HOME} is
421 deprecated.
423   Whatever the final place is, Emacs sets the internal value of the
424 @env{HOME} environment variable to point to it, and it will use that
425 location for other files and directories it normally looks for or
426 creates in your home directory.
428   You can always find out what Emacs thinks is your home directory's
429 location by typing @kbd{C-x d ~/ @key{RET}}.  This should present the
430 list of files in the home directory, and show its full name on the
431 first line.  Likewise, to visit your init file, type @kbd{C-x C-f
432 ~/.emacs @key{RET}} (assuming the file's name is @file{.emacs}).
434 @cindex init file @file{.emacs} on MS-Windows
435   The home directory is where your init file is stored.  It can have
436 any name mentioned in @ref{Init File}.
438 @cindex @file{_emacs} init file, MS-Windows
439   Because MS-DOS does not allow file names with leading dots, and
440 older Windows systems made it hard to create files with such names,
441 the Windows port of Emacs supports an init file name @file{_emacs}, if
442 such a file exists in the home directory and @file{.emacs} does not.
443 This name is considered obsolete.
445 @node Windows Keyboard
446 @section Keyboard Usage on MS-Windows
447 @cindex keyboard, MS-Windows
449   This section describes the Windows-specific features related to
450 keyboard input in Emacs.
452 @cindex MS-Windows keyboard shortcuts
453   Many key combinations (known as ``keyboard shortcuts'') that have
454 conventional uses in MS-Windows programs conflict with traditional
455 Emacs key bindings.  (These Emacs key bindings were established years
456 before Microsoft was founded.)  Examples of conflicts include
457 @kbd{C-c}, @kbd{C-x}, @kbd{C-z}, @kbd{C-a}, and @kbd{W-@key{SPC}}.
458 You can redefine some of them with meanings more like the MS-Windows
459 meanings by enabling CUA Mode (@pxref{CUA Bindings}).
461 @kindex F10 @r{(MS-Windows)}
462 @cindex menu bar access using keyboard @r{(MS-Windows)}
463   The @key{F10} key on Windows activates the menu bar in a way that
464 makes it possible to use the menus without a mouse.  In this mode, the
465 arrow keys traverse the menus, @key{RET} selects a highlighted menu
466 item, and @key{ESC} closes the menu.
468 @iftex
469 @inforef{Windows Keyboard, , emacs}, for information about additional
470 Windows-specific variables in this category.
471 @end iftex
472 @ifnottex
473 @vindex w32-alt-is-meta
474 @cindex @code{Alt} key (MS-Windows)
475   By default, the key labeled @key{Alt} is mapped as the @key{META}
476 key.  If you wish it to produce the @code{Alt} modifier instead, set
477 the variable @code{w32-alt-is-meta} to a @code{nil} value.
479 @findex w32-register-hot-key
480 @findex w32-unregister-hot-key
481   MS-Windows reserves certain key combinations, such as
482 @kbd{@key{Alt}-@key{TAB}}, for its own use.  These key combinations are
483 intercepted by the system before Emacs can see them.  You can use the
484 @code{w32-register-hot-key} function to allow a key sequence to be
485 seen by Emacs instead of being grabbed by Windows.  This function
486 registers a key sequence as a @dfn{hot key}, overriding the special
487 meaning of that key sequence for Windows.  (MS-Windows is told that
488 the key sequence is a hot key only when one of the Emacs windows has
489 focus, so that the special keys still have their usual meaning for
490 other Windows applications.)
492   The argument to @code{w32-register-hot-key} must be a single key,
493 with or without modifiers, in vector form that would be acceptable to
494 @code{define-key}.  The meta modifier is interpreted as the @key{Alt}
495 key if @code{w32-alt-is-meta} is @code{t} (the default), and the hyper
496 modifier is always interpreted as the Windows key (usually labeled
497 with @key{start} and the Windows logo).  If the function succeeds in
498 registering the key sequence, it returns the hotkey ID, a number;
499 otherwise it returns @code{nil}.
501 @kindex M-TAB@r{, (MS-Windows)}
502 @cindex @kbd{M-@key{TAB}} vs @kbd{@key{Alt}-@key{TAB}} (MS-Windows)
503 @cindex @kbd{@key{Alt}-@key{TAB}} vs @kbd{M-@key{TAB}} (MS-Windows)
504   For example, @code{(w32-register-hot-key [M-tab])} lets you use
505 @kbd{M-@key{TAB}} normally in Emacs; for instance, to complete the word or
506 symbol at point at top level, or to complete the current search string
507 against previously sought strings during incremental search.
509   The function @code{w32-unregister-hot-key} reverses the effect of
510 @code{w32-register-hot-key} for its argument key sequence.
512 @vindex w32-capslock-is-shiftlock
513   By default, the @key{CapsLock} key only affects normal character
514 keys (it converts lower-case characters to their upper-case
515 variants).  However, if you set the variable
516 @code{w32-capslock-is-shiftlock} to a non-@code{nil} value, the
517 @key{CapsLock} key will affect non-character keys as well, as if you
518 pressed the @key{Shift} key while typing the non-character key.
520 @vindex w32-enable-caps-lock
521   If the variable @code{w32-enable-caps-lock} is set to a @code{nil}
522 value, the @key{CapsLock} key produces the symbol @code{capslock}
523 instead of the shifted version of they keys.  The default value is
524 @code{t}.
526 @vindex w32-enable-num-lock
527 @cindex keypad keys (MS-Windows)
528   Similarly, if @code{w32-enable-num-lock} is @code{nil}, the
529 @key{NumLock} key will produce the symbol @code{kp-numlock}.  The
530 default is @code{t}, which causes @key{NumLock} to work as expected:
531 toggle the meaning of the keys on the numeric keypad.
532 @end ifnottex
534 @vindex w32-apps-modifier
535   The variable @code{w32-apps-modifier} controls the effect of the
536 @key{Apps} key (usually located between the right @key{Alt} and the
537 right @key{Ctrl} keys).  Its value can be one of the symbols
538 @code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
539 or @code{shift} for the respective modifier, or @code{nil} to appear
540 as the key @code{apps}.  The default is @code{nil}.
542 @vindex w32-lwindow-modifier
543 @vindex w32-rwindow-modifier
544 @vindex w32-scroll-lock-modifier
545   The variable @code{w32-lwindow-modifier} determines the effect of
546 the left Windows key (usually labeled with @key{start} and the Windows
547 logo).  If its value is @code{nil} (the default), the key will produce
548 the symbol @code{lwindow}.  Setting it to one of the symbols
549 @code{hyper}, @code{super}, @code{meta}, @code{alt}, @code{control},
550 or @code{shift} will produce the respective modifier.  A similar
551 variable @code{w32-rwindow-modifier} controls the effect of the right
552 Windows key, and @code{w32-scroll-lock-modifier} does the same for the
553 @key{ScrLock} key.  If these variables are set to @code{nil}, the
554 right Windows key produces the symbol @code{rwindow} and @key{ScrLock}
555 produces the symbol @code{scroll}.
557 @vindex w32-pass-alt-to-system
558 @cindex Windows system menu
559 @cindex @code{Alt} key invokes menu (Windows)
560   Emacs compiled as a native Windows application normally turns off
561 the Windows feature that tapping the @key{Alt} key invokes the Windows
562 menu.  The reason is that the @key{Alt} serves as @key{META} in Emacs.
563 When using Emacs, users often press the @key{META} key temporarily and
564 then change their minds; if this has the effect of bringing up the
565 Windows menu, it alters the meaning of subsequent commands.  Many
566 users find this frustrating.
568   You can re-enable Windows's default handling of tapping the @key{Alt}
569 key by setting @code{w32-pass-alt-to-system} to a non-@code{nil}
570 value.
572 @ifnottex
573 @vindex w32-pass-lwindow-to-system
574 @vindex w32-pass-rwindow-to-system
575   The variables @code{w32-pass-lwindow-to-system} and
576 @code{w32-pass-rwindow-to-system} determine whether the respective
577 keys are passed to Windows or swallowed by Emacs.  If the value is
578 @code{nil}, the respective key is silently swallowed by Emacs,
579 otherwise it is passed to Windows.  The default is @code{t} for both
580 of these variables.  Passing each of these keys to Windows produces
581 its normal effect: for example, @kbd{@key{Lwindow}} opens the
582 @code{Start} menu, etc.@footnote{
583 Some combinations of the ``Windows'' keys with other keys are caught
584 by Windows at a low level in a way that Emacs currently cannot prevent.
585 For example, @kbd{@key{Lwindow} r} always pops up the Windows
586 @samp{Run} dialog.  Customizing the value of
587 @code{w32-phantom-key-code} might help in some cases, though.}
589 @vindex w32-recognize-altgr
590 @kindex AltGr @r{(MS-Windows)}
591 @cindex AltGr key (MS-Windows)
592   The variable @code{w32-recognize-altgr} controls whether the
593 @key{AltGr} key (if it exists on your keyboard), or its equivalent,
594 the combination of the right @key{Alt} and left @key{Ctrl} keys
595 pressed together, is recognized as the @key{AltGr} key.  The default
596 is @code{t}, which means these keys produce @code{AltGr}; setting it
597 to @code{nil} causes @key{AltGr} or the equivalent key combination to
598 be interpreted as the combination of @key{Ctrl} and @key{META}
599 modifiers.
600 @end ifnottex
602 @node Windows Mouse
603 @section Mouse Usage on MS-Windows
604 @cindex mouse, and MS-Windows
606   This section describes the Windows-specific variables related to
607 the mouse.
609 @vindex w32-mouse-button-tolerance
610 @cindex simulation of middle mouse button
611   The variable @code{w32-mouse-button-tolerance} specifies the
612 time interval, in milliseconds, for faking middle mouse button press
613 on 2-button mice.  If both mouse buttons are depressed within this
614 time interval, Emacs generates a middle mouse button click event
615 instead of a double click on one of the buttons.
617 @vindex w32-pass-extra-mouse-buttons-to-system
618   If the variable @code{w32-pass-extra-mouse-buttons-to-system} is
619 non-@code{nil}, Emacs passes the fourth and fifth mouse buttons to
620 Windows.
622 @vindex w32-swap-mouse-buttons
623   The variable @code{w32-swap-mouse-buttons} controls which of the 3
624 mouse buttons generates the @kbd{mouse-2} events.  When it is
625 @code{nil} (the default), the middle button generates @kbd{mouse-2}
626 and the right button generates @kbd{mouse-3} events.  If this variable
627 is non-@code{nil}, the roles of these two buttons are reversed.
629 @node Windows Processes
630 @section Subprocesses on Windows 9X/ME and Windows NT/2K/XP
631 @cindex subprocesses on MS-Windows
633 @cindex DOS applications, running from Emacs
634   Emacs compiled as a native Windows application (as opposed to the DOS
635 version) includes full support for asynchronous subprocesses.
636 In the Windows version, synchronous and asynchronous subprocesses work
637 fine on both
638 Windows 9X/ME and Windows NT/2K/XP as long as you run only 32-bit Windows
639 applications.  However, when you run a DOS application in a subprocess,
640 you may encounter problems or be unable to run the application at all;
641 and if you run two DOS applications at the same time in two
642 subprocesses, you may have to reboot your system.
644 Since the standard command interpreter (and most command line utilities)
645 on Windows 9X are DOS applications, these problems are significant when
646 using that system.  But there's nothing we can do about them; only
647 Microsoft can fix them.
649 If you run just one DOS application subprocess, the subprocess should
650 work as expected as long as it is ``well-behaved'' and does not perform
651 direct screen access or other unusual actions.  If you have a CPU
652 monitor application, your machine will appear to be 100% busy even when
653 the DOS application is idle, but this is only an artifact of the way CPU
654 monitors measure processor load.
656 You must terminate the DOS application before you start any other DOS
657 application in a different subprocess.  Emacs is unable to interrupt or
658 terminate a DOS subprocess.  The only way you can terminate such a
659 subprocess is by giving it a command that tells its program to exit.
661 If you attempt to run two DOS applications at the same time in separate
662 subprocesses, the second one that is started will be suspended until the
663 first one finishes, even if either or both of them are asynchronous.
665 @cindex kill DOS application
666 If you can go to the first subprocess, and tell it to exit, the second
667 subprocess should continue normally.  However, if the second subprocess
668 is synchronous, Emacs itself will be hung until the first subprocess
669 finishes.  If it will not finish without user input, then you have no
670 choice but to reboot if you are running on Windows 9X@.  If you are
671 running on Windows NT/2K/XP, you can use a process viewer application to kill
672 the appropriate instance of NTVDM instead (this will terminate both DOS
673 subprocesses).
675 If you have to reboot Windows 9X in this situation, do not use the
676 @code{Shutdown} command on the @code{Start} menu; that usually hangs the
677 system.  Instead, type @kbd{@key{Ctrl}-@key{Alt}-@key{DEL}} and then choose
678 @code{Shutdown}.  That usually works, although it may take a few minutes
679 to do its job.
681 @vindex w32-quote-process-args
682   The variable @code{w32-quote-process-args} controls how Emacs quotes
683 the process arguments.  Non-@code{nil} means quote with the @code{"}
684 character.  If the value is a character, Emacs uses that character to escape
685 any quote characters that appear; otherwise it chooses a suitable escape
686 character based on the type of the program.
688 @ifnottex
689 @findex w32-shell-execute
690   The function @code{w32-shell-execute} can be useful for writing
691 customized commands that run MS-Windows applications registered to
692 handle a certain standard Windows operation for a specific type of
693 document or file.  This function is a wrapper around the Windows
694 @code{ShellExecute} API@.  See the MS-Windows API documentation for
695 more details.
696 @end ifnottex
698 @node Windows Printing
699 @section Printing and MS-Windows
701   Printing commands, such as @code{lpr-buffer} (@pxref{Printing}) and
702 @code{ps-print-buffer} (@pxref{PostScript}) work in MS-DOS and
703 MS-Windows by sending the output to one of the printer ports, if a
704 Posix-style @code{lpr} program is unavailable.  The same Emacs
705 variables control printing on all systems, but in some cases they have
706 different default values on MS-DOS and MS-Windows.
708   Emacs on MS Windows attempts to determine your default printer
709 automatically (using the function @code{default-printer-name}).
710 But in some rare cases this can fail, or you may wish to use a different
711 printer from within Emacs.  The rest of this section explains how to
712 tell Emacs which printer to use.
714 @vindex printer-name@r{, (MS-DOS/MS-Windows)}
715   If you want to use your local printer, then set the Lisp variable
716 @code{lpr-command} to @code{""} (its default value on Windows) and
717 @code{printer-name} to the name of the printer port---for example,
718 @code{"PRN"}, the usual local printer port, or @code{"LPT2"}, or
719 @code{"COM1"} for a serial printer.  You can also set
720 @code{printer-name} to a file name, in which case ``printed'' output
721 is actually appended to that file.  If you set @code{printer-name} to
722 @code{"NUL"}, printed output is silently discarded (sent to the system
723 null device).
725   You can also use a printer shared by another machine by setting
726 @code{printer-name} to the UNC share name for that printer---for
727 example, @code{"//joes_pc/hp4si"}.  (It doesn't matter whether you use
728 forward slashes or backslashes here.)  To find out the names of shared
729 printers, run the command @samp{net view} from the command prompt to
730 obtain a list of servers, and @samp{net view @var{server-name}} to see
731 the names of printers (and directories) shared by that server.
732 Alternatively, click the @samp{Network Neighborhood} icon on your
733 desktop, and look for machines that share their printers via the
734 network.
736 @cindex @samp{net use}, and printing on MS-Windows
737 @cindex networked printers (MS-Windows)
738   If the printer doesn't appear in the output of @samp{net view}, or
739 if setting @code{printer-name} to the UNC share name doesn't produce a
740 hardcopy on that printer, you can use the @samp{net use} command to
741 connect a local print port such as @code{"LPT2"} to the networked
742 printer.  For example, typing @kbd{net use LPT2: \\joes_pc\hp4si}@footnote{
743 Note that the @samp{net use} command requires the UNC share name to be
744 typed with the Windows-style backslashes, while the value of
745 @code{printer-name} can be set with either forward- or backslashes.}
746 causes Windows to @dfn{capture} the @code{LPT2} port and redirect the
747 printed material to the printer connected to the machine @code{joes_pc}.
748 After this command, setting @code{printer-name} to @code{"LPT2"}
749 should produce the hardcopy on the networked printer.
751   With some varieties of Windows network software, you can instruct
752 Windows to capture a specific printer port such as @code{"LPT2"}, and
753 redirect it to a networked printer via the @w{@code{Control
754 Panel->Printers}} applet instead of @samp{net use}.
756   If you set @code{printer-name} to a file name, it's best to use an
757 absolute file name.  Emacs changes the working directory according to
758 the default directory of the current buffer, so if the file name in
759 @code{printer-name} is relative, you will end up with several such
760 files, each one in the directory of the buffer from which the printing
761 was done.
763   If the value of @code{printer-name} is correct, but printing does
764 not produce the hardcopy on your printer, it is possible that your
765 printer does not support printing plain text (some cheap printers omit
766 this functionality).  In that case, try the PostScript print commands,
767 described below.
769 @findex print-buffer @r{(MS-DOS)}
770 @findex print-region @r{(MS-DOS)}
771 @vindex lpr-headers-switches @r{(MS-DOS)}
772   The commands @code{print-buffer} and @code{print-region} call the
773 @code{pr} program, or use special switches to the @code{lpr} program, to
774 produce headers on each printed page.  MS-DOS and MS-Windows don't
775 normally have these programs, so by default, the variable
776 @code{lpr-headers-switches} is set so that the requests to print page
777 headers are silently ignored.  Thus, @code{print-buffer} and
778 @code{print-region} produce the same output as @code{lpr-buffer} and
779 @code{lpr-region}, respectively.  If you do have a suitable @code{pr}
780 program (for example, from GNU Coreutils), set
781 @code{lpr-headers-switches} to @code{nil}; Emacs will then call
782 @code{pr} to produce the page headers, and print the resulting output as
783 specified by @code{printer-name}.
785 @vindex print-region-function @r{(MS-DOS)}
786 @cindex lpr usage under MS-DOS
787 @vindex lpr-command @r{(MS-DOS)}
788 @vindex lpr-switches @r{(MS-DOS)}
789   Finally, if you do have an @code{lpr} work-alike, you can set the
790 variable @code{lpr-command} to @code{"lpr"}.  Then Emacs will use
791 @code{lpr} for printing, as on other systems.  (If the name of the
792 program isn't @code{lpr}, set @code{lpr-command} to the appropriate value.)
793 The variable @code{lpr-switches} has its standard meaning
794 when @code{lpr-command} is not @code{""}.  If the variable
795 @code{printer-name} has a string value, it is used as the value for the
796 @code{-P} option to @code{lpr}, as on Unix.
798 @findex ps-print-buffer @r{(MS-DOS)}
799 @findex ps-spool-buffer @r{(MS-DOS)}
800 @vindex ps-printer-name @r{(MS-DOS)}
801 @vindex ps-lpr-command @r{(MS-DOS)}
802 @vindex ps-lpr-switches @r{(MS-DOS)}
803   A parallel set of variables, @code{ps-lpr-command},
804 @code{ps-lpr-switches}, and @code{ps-printer-name} (@pxref{PostScript
805 Variables}), defines how PostScript files should be printed.  These
806 variables are used in the same way as the corresponding variables
807 described above for non-PostScript printing.  Thus, the value of
808 @code{ps-printer-name} is used as the name of the device (or file) to
809 which PostScript output is sent, just as @code{printer-name} is used
810 for non-PostScript printing.  (There are two distinct sets of
811 variables in case you have two printers attached to two different
812 ports, and only one of them is a PostScript printer.)
814 @cindex Ghostscript, use for PostScript printing
815   The default value of the variable @code{ps-lpr-command} is @code{""},
816 which causes PostScript output to be sent to the printer port specified
817 by @code{ps-printer-name}; but @code{ps-lpr-command} can also be set to
818 the name of a program which will accept PostScript files.  Thus, if you
819 have a non-PostScript printer, you can set this variable to the name of
820 a PostScript interpreter program (such as Ghostscript).  Any switches
821 that need to be passed to the interpreter program are specified using
822 @code{ps-lpr-switches}.  (If the value of @code{ps-printer-name} is a
823 string, it will be added to the list of switches as the value for the
824 @code{-P} option.  This is probably only useful if you are using
825 @code{lpr}, so when using an interpreter typically you would set
826 @code{ps-printer-name} to something other than a string so it is
827 ignored.)
829   For example, to use Ghostscript for printing on the system's default
830 printer, put this in your @file{.emacs} file:
832 @example
833 (setq ps-printer-name t)
834 (setq ps-lpr-command "D:/gs6.01/bin/gswin32c.exe")
835 (setq ps-lpr-switches '("-q" "-dNOPAUSE" "-dBATCH"
836                         "-sDEVICE=mswinpr2"
837                         "-sPAPERSIZE=a4"))
838 @end example
840 @noindent
841 (This assumes that Ghostscript is installed in the
842 @file{D:/gs6.01} directory.)
844 @node Windows Fonts
845 @section Specifying Fonts on MS-Windows
846 @cindex font specification (MS Windows)
848   Starting with Emacs 23, fonts are specified by their name, size
849 and optional properties.  The format for specifying fonts comes from the
850 fontconfig library used in modern Free desktops:
852 @example
853   [Family[-PointSize]][:Option1=Value1[:Option2=Value2[...]]]
854 @end example
856   The old XLFD based format is also supported for backwards compatibility.
858 @cindex font backend selection (MS-Windows)
859   Emacs 23 and later supports a number of font backends.  Currently,
860 the @code{gdi} and @code{uniscribe} backends are supported on Windows.
861 The @code{gdi} font backend is available on all versions of Windows,
862 and supports all fonts that are natively supported by Windows.  The
863 @code{uniscribe} font backend is available on Windows 2000 and later,
864 and supports TrueType and OpenType fonts.  Some languages requiring
865 complex layout can only be properly supported by the Uniscribe
866 backend.  By default, both backends are enabled if supported, with
867 @code{uniscribe} taking priority over @code{gdi}.  To override that
868 and use the GDI backend even if Uniscribe is available, invoke Emacs
869 with the @kbd{-xrm Emacs.fontBackend:gdi} command-line argument, or
870 add a @code{Emacs.fontBackend} resource with the value @code{gdi} in
871 the Registry under either the
872 @samp{HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs} or the
873 @samp{HKEY_LOCAL_MACHINE\SOFTWARE\GNU\Emacs} key (@pxref{Resources}).
875 @cindex font properties (MS Windows)
876 @noindent
877 Optional properties common to all font backends on MS-Windows are:
879 @table @code
881 @vindex font-weight-table @r{(MS-Windows)}
882 @item weight
883 Specifies the weight of the font.  Special values @code{light},
884 @code{medium}, @code{demibold}, @code{bold}, and @code{black} can be specified
885 without @code{weight=} (e.g., @kbd{Courier New-12:bold}).  Otherwise,
886 the weight should be a numeric value between 100 and 900, or one of the
887 named weights in @code{font-weight-table}.  If unspecified, a regular font
888 is assumed.
890 @vindex font-slant-table @r{(MS-Windows)}
891 @item slant
892 Specifies whether the font is italic.  Special values
893 @code{roman}, @code{italic} and @code{oblique} can be specified
894 without @code{slant=} (e.g., @kbd{Courier New-12:italic}).
895 Otherwise, the slant should be a numeric value, or one of the named
896 slants in @code{font-slant-table}.  On Windows, any slant above 150 is
897 treated as italics, and anything below as roman.
899 @item family
900 Specifies the font family, but normally this will be specified
901 at the start of the font name.
903 @item pixelsize
904 Specifies the font size in pixels.  This can be used instead
905 of the point size specified after the family name.
907 @item adstyle
908 Specifies additional style information for the font.
909 On MS-Windows, the values @code{mono}, @code{sans}, @code{serif},
910 @code{script} and @code{decorative} are recognized.  These are most useful
911 as a fallback with the font family left unspecified.
913 @vindex w32-charset-info-alist
914 @item registry
915 Specifies the character set registry that the font is
916 expected to cover.  Most TrueType and OpenType fonts will be Unicode fonts
917 that cover several national character sets, but you can narrow down the
918 selection of fonts to those that support a particular character set by
919 using a specific registry from @code{w32-charset-info-alist} here.
921 @item spacing
922 Specifies how the font is spaced.  The @code{p} spacing specifies
923 a proportional font, and @code{m} or @code{c} specify a monospaced font.
925 @item foundry
926 Not used on Windows, but for informational purposes and to
927 prevent problems with code that expects it to be set, is set internally to
928 @code{raster} for bitmapped fonts, @code{outline} for scalable fonts,
929 or @code{unknown} if the type cannot be determined as one of those.
930 @end table
932 @cindex font properties (MS Windows gdi backend)
933 Options specific to @code{GDI} fonts:
935 @table @code
937 @cindex font scripts (MS Windows)
938 @cindex font Unicode subranges (MS Windows)
939 @item script
940 Specifies a Unicode subrange the font should support.
942 The following scripts are recognized on Windows: @code{latin}, @code{greek},
943 @code{coptic}, @code{cyrillic}, @code{armenian}, @code{hebrew}, @code{arabic},
944 @code{syriac}, @code{nko}, @code{thaana}, @code{devanagari}, @code{bengali},
945 @code{gurmukhi}, @code{gujarati}, @code{oriya}, @code{tamil}, @code{telugu},
946 @code{kannada}, @code{malayam}, @code{sinhala}, @code{thai}, @code{lao},
947 @code{tibetan}, @code{myanmar}, @code{georgian}, @code{hangul},
948 @code{ethiopic}, @code{cherokee}, @code{canadian-aboriginal}, @code{ogham},
949 @code{runic}, @code{khmer}, @code{mongolian}, @code{symbol}, @code{braille},
950 @code{han}, @code{ideographic-description}, @code{cjk-misc}, @code{kana},
951 @code{bopomofo}, @code{kanbun}, @code{yi}, @code{byzantine-musical-symbol},
952 @code{musical-symbol}, and @code{mathematical}.
954 @cindex font antialiasing (MS Windows)
955 @item antialias
956 Specifies the antialiasing method.  The value @code{none} means no
957 antialiasing, @code{standard} means use standard antialiasing,
958 @code{subpixel} means use subpixel antialiasing (known as Cleartype on
959 Windows), and @code{natural} means use subpixel antialiasing with
960 adjusted spacing between letters.  If unspecified, the font will use
961 the system default antialiasing.
962 @end table
964 @node Windows Misc
965 @section Miscellaneous Windows-specific features
967   This section describes miscellaneous Windows-specific features.
969 @vindex w32-use-visible-system-caret
970 @cindex screen reader software, MS-Windows
971   The variable @code{w32-use-visible-system-caret} is a flag that
972 determines whether to make the system caret visible.  The default when
973 no screen reader software is in use is @code{nil}, which means Emacs
974 draws its own cursor to indicate the position of point.  A
975 non-@code{nil} value means Emacs will indicate point location with the
976 system caret; this facilitates use of screen reader software, and is
977 the default when such software is detected when running Emacs.
978 When this variable is non-@code{nil}, other variables affecting the
979 cursor display have no effect.
981 @iftex
982 @inforef{Windows Misc, , emacs}, for information about additional
983 Windows-specific variables in this category.
984 @end iftex
986 @ifnottex
987 @vindex w32-grab-focus-on-raise
988 @cindex frame focus policy, MS-Windows
989   The variable @code{w32-grab-focus-on-raise}, if set to a
990 non-@code{nil} value causes a frame to grab focus when it is raised.
991 The default is @code{t}, which fits well with the Windows default
992 click-to-focus policy.
993 @end ifnottex
995 @ifnottex
996 @include msdog-xtra.texi
997 @end ifnottex