MsWindowsRegistry

This page deals with GNU Emacs and the Windows Registry, especially using the Registry to customize Emacs. It is set up as a FAQ. You may want to jump straight to an example of setting the registry

What can I do with the Windows Registry for Emacs customization?

Why does GNU Emacs use the Windows Registry?

Emacs is originally a Unix and X application. Users expect the same interfaces for customization even from the Windows ports. One of these interfaces is the X resource customization. It seems it was decided instead of depending on an Xrdb (X resource database) or attempt to read a %HOME%\.Xresources file directly, to just to use the Windows Registry, because it is also a resource database.

What Registry keys does Emacs use?

According to the official documentation (info “(emacs)Resources”) , the keys are:
Below we use the common abbreviations HKCU for HKEY_CURRENT_USER and HKLM for HKEY_LOCAL_MACHINE; but in registry parameter files you must use the full names. See the example below.
What keys are used may differ on different ports. For example, Meadow 3.00 DOES NOT search the above keys, but instead uses these keys:

Which Registry key should I use?

Use HKCU for personal customization and HKLM for system-wide customization. Prefer HKCU for single-user systems.

How are the X resources searched for in the Registry?

Emacs checks the environment for whether a particular setting is bound and set. In particular, for the registry keys above, Emacs searches for string values with those names.
For example, before opening the first frame it tries to open the HKCU\…\Emacs key to search for the string value named “Emacs.Background”, and if it finds that, sets its background color to the value given there (e.g., “black”).

What X resources does Emacs search for in the Registry?

Although the official documentation has a list (info “(emacs)Table of Resources”), it may not be correct for an Emacs Windows port.
Here is a sample list of string values. It is incomplete, with alternate executable names culled. (This list needs verification) Remember each string value may be set under the HKCU or HKLM key, depending on whether the value should be for a single user or for all users. If a string value appears in both HKCU and HKLM, the value set under HKCU is the one used.
        Emacs.Alpha
        Emacs.AutoRaiseLower
        Emacs.Background
        Emacs.BackgroundMode
        Emacs.BitmapIcon
        Emacs.BorderColor
        Emacs.BorderWidth
        Emacs.BufferPredicate
        Emacs.CursorBlink
        Emacs.CursorHeight
        Emacs.CursorType
        Emacs.Face.AttributeBackground
        Emacs.Face.AttributeBackgroundPixmap
        Emacs.Face.AttributeBold
        Emacs.Face.AttributeBox
        Emacs.Face.AttributeFamily
        Emacs.Face.AttributeFont
        Emacs.Face.AttributeForeground
        Emacs.Face.AttributeHeight
        Emacs.Face.AttributeInherit
        Emacs.Face.AttributeInverse
        Emacs.Face.AttributeItalic
        Emacs.Face.AttributeOverline
        Emacs.Face.AttributeSlant
        Emacs.Face.AttributeStipple
        Emacs.Face.AttributeStrikeThrough
        Emacs.Face.AttributeUnderline
        Emacs.Face.AttributeWeight
        Emacs.Face.AttributeWidth
        Emacs.Font
        Emacs.Foreground
        Emacs.Fullscreen
        Emacs.Geometry
        Emacs.LineSpacing
        Emacs.MenuBar
        Emacs.Minibuffer
        Emacs.Name
        Emacs.ReverseVideo
        Emacs.ScreenGamma
        Emacs.ScrollBarWidth
        Emacs.Title
        Emacs.ToolBar
        Emacs.internalBorder
        Emacs.internalBorderWidth
Here is a list of string values for Meadow. It is an incomplete list with alternate executable names culled. (It has many more: Meadow-exe.* and Meadow_exe.*, for a total of 1590 entries.)
        MEADOW.Alpha
        MEADOW.AutoRaiseLower
        MEADOW.Background
        MEADOW.BackgroundMode
        MEADOW.BitmapIcon
        MEADOW.BorderColor
        MEADOW.BorderWidth
        MEADOW.BufferPredicate
        MEADOW.CursorBlink
        MEADOW.CursorHeight
        MEADOW.CursorType
        MEADOW.Face.AttributeBackground
        MEADOW.Face.AttributeBackgroundPixmap
        MEADOW.Face.AttributeBold
        MEADOW.Face.AttributeBox
        MEADOW.Face.AttributeFamily
        MEADOW.Face.AttributeFont
        MEADOW.Face.AttributeForeground
        MEADOW.Face.AttributeHeight
        MEADOW.Face.AttributeInherit
        MEADOW.Face.AttributeInverse
        MEADOW.Face.AttributeItalic
        MEADOW.Face.AttributeOverline
        MEADOW.Face.AttributeSlant
        MEADOW.Face.AttributeStipple
        MEADOW.Face.AttributeStrikeThrough
        MEADOW.Face.AttributeUnderline
        MEADOW.Face.AttributeWeight
        MEADOW.Face.AttributeWidth
        MEADOW.Font
        MEADOW.Foreground
        MEADOW.Fullscreen
        MEADOW.Geometry
        MEADOW.IME-Font
        MEADOW.LineSpacing
        MEADOW.MenuBar
        MEADOW.Minibuffer
        MEADOW.Name
        MEADOW.ReverseVideo
        MEADOW.ScreenGamma
        MEADOW.ScrollBarWidth
        MEADOW.Title
        MEADOW.ToolBar
        MEADOW.internalBorder
        MEADOW.internalBorderWidth

How can find all the X resources searched for in the Registry?

You could either hope for documentation (where is it?), read the source code to Emacs, or use a registry sniffer like the freeware SysInternals RegMon. If you try the latter I suggest adding a filter for “GNU”, because without a filter RegMon produces unusable huge amounts of logging output.

What do the X Resources mean?

Check the official documentation for details.

Is capitalization important?

I think it means something, but I’m not sure.

An example of setting the registry

Say I have the .Xresource file with the following settings.
        Emacs.Background: black
        Emacs.Foreground: white
        Emacs.Font: -*-Lucida Console-normal-r-*-*-11-82-96-96-c-*-iso8859-1
        Emacs.Geometry: 90x60
Then I can prepare the equivalent Registry text file like the following:
        REGEDIT4
        [HKEY_CURRENT_USER\SOFTWARE\GNU\Emacs]
        "Emacs.Background"="black"
        "Emacs.Foreground"="white"
        "Emacs.Font"="-*-Lucida Console-normal-r-*-*-11-82-96-96-c-*-iso8859-1"
        "Emacs.Geometry"="90x60+20-20"
Save the above as a *.reg file, and the double-click it to merge it into the Registry. (aside: “REGEDIT4” is for ANSI text files, and “Windows Registry Editor Version 5.00” is for Unicode (utf-16-le) text files.)

Read the Windows Registry

This fn reads a registry key - retrieves all the values and the names of all the subkeys.

    (defun string/starts-with (s begins)
          "Return non-nil if string S starts with BEGINS."
          (cond ((>= (length s) (length begins))
                 (string-equal (substring s 0 (length begins)) begins))
                (t nil)))
    
    (defun w32reg-read-key (key)
      "Read all values and subkeys for a key path in the Windows registry.
    The return value is a list (KEYNAME VALUES SUBKEYS).  KEYNAME is
    the name of the key. VALUES is a list of values, each one
    following this form: (NAME TYPE VALUE) where each are strings,
    and the TYPE is like \"REG_DWORD\" and so on.
    
    SUBKEYS is a simple list of strings.
    
    If the path does not exist, it returns nil.
    "
      (let ((reg.exe (concat (getenv "windir") "\\system32\\reg.exe"))
            keyname values subkeys (state 0))
    
        (with-temp-buffer
          (insert (shell-command-to-string
                   (concat reg.exe " query " "\"" key "\"")))
    
          (while (not (= (point-min) (point-max)))
            (goto-char (point-min))
            (let ((start (point))
                  (end (line-end-position))
                  line this-value)
              (setq line (buffer-substring-no-properties start end))
              (delete-region start end)
              (delete-char 1) ;; NL
    
              (cond
               ((string/starts-with line "ERROR:")
                nil)
    
               ((string= "" line)
                (setq state (1+ state)))
    
               ((not keyname)
                (setq keyname line
                      state 1))
    
               ((eq state 1)
                (let ((parts (split-string line nil t)))
                  (setq this-value (mapconcat 'identity (cddr parts) " "))
    
                  ;; convert to integer, maybe
                  (if (string= (nth 1 parts) "REG_DWORD")
                      (setq this-value
                            (string-to-number (substring this-value 2))))
    
                  (setq values (cons (list (nth 0 parts)
                                         (nth 1 parts)
                                         this-value) values))))
               ((eq state 2)
                (setq subkeys (cons
                               (if (string/starts-with line keyname)
                                   (substring line (1+ (length keyname)))
                                 line)
                               subkeys)))
               (t nil)))))
    
        (and keyname
             (list keyname values subkeys))))

Read one Registry Value

This fn depends on the previous one, shown above.

    (defun w32reg-read-value (key value)
      "Read a value from a key location in the registry. The result
    is a list like (NAME TYPE VALUE), where the first two items are
    strings.  TYPE is like \"REG_DWORD\", \"REG_SZ\", \"REG_BINARY\",
    and so on.  If TYPE is \"REG_DWORD\", then the VALUE is a number.
    
    If the key value does not exist, it returns nil.
    "
      (let ((all (w32reg-read-key key))
            (c 0) L n r values)
        (and all
             (setq values (nth 1 all)
                   L (length values))
        (while (and (not r) (< c L))
          (setq n (nth c values)
                c (1+ c))
          (if (string= value (car n))
              (setq r n))))
        r))

Read IE Proxy Configuration

This fn depends on the prior fn that allows reading a specific value from the Windows registry.

    (defun w32reg-get-ie-proxy-config ()
      "Return the Proxy Server settings configured for IE, if enabled.
    The result is a list of cons cells; like this:
    
      ((\"http\" . \"127.0.0.1:8888\")
       (\"https\" .  \"127.0.0.1:8888\"))
    
    ...which is suitable for use with (setq url-proxy-services ...)
    
    "
      (let* ((rpath "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings")
             (enabled (w32reg-read-value rpath "ProxyEnable"))
             r)
        (if (and enabled
                 (numberp (nth 2 enabled))
                 (>  (nth 2 enabled) 0))
            (let ((proxy (w32reg-read-value rpath "ProxyServer")))
              (mapcar `(lambda (elt)
                         (let ((x (split-string elt "=" t)))
                           (cons (car x) (cadr x))))
                      (split-string (nth 2 proxy) ";" t))))))

Can I edit the Registry from Emacs?

References

Verified

All (initial) information tested on Meadow 3.00 (Emacs CVS HEAD 22.0 2006/09/08) on Windows XP SP1 and SP2. Some initialization values tested on Windows 10.

Discussion

Any comments?

CategoryWThirtyTwo CategoryPorts CategoryCustomize