Sunday, October 02, 2005

Controlling WebKit and Safari through Preferences

Mac OS X has a centralized preferences system (stuff in ~/Library/Preferences) which, for some apps, contains hidden settings. Some of these can be quite useful, interesting, or annoying. This is coverage of such settings for Safari and the underlying WebKit.
First, a warning. None of these settings are in any way guaranteed to work after this is written, nor are they safe from blowing up your keyboard when entered. If you test any of these, be sure to keep track of which, especially when OS/Safari/WebKit updates come from Apple, as otherwise very strange things could happen.
I'm not going to cover how to change defaults (hint, Terminal's defaults or Property List Editor) as that's covered nicely elsewhere. All these should be done only to (at least initially) so you don't break other apps which use the system's WebKit.
Except for CustomUserAgent, the Safari list does not cover items which can be set through the Debug menu (but does include enabling said menu). This also does not cover basic AppKit-level preferences (those beginning with NS, like NSNavLastRootDirectory).

Read on for more detail

WebKit Preferences
WebKit preferences can be set in Safari's preferences to avoid affecting other WebKit-based applications. They can also be set in those apps' preferences if needed, or even in the global domain to affect everything. To be safe, start off just changing Safari's prefs.
If you want the definitive reference for WebKit preferences (and other things WebKit), please check the source.

  • WebKitHistoryItemLimit (number)
    This (which is by default 1000) sets how much history is remembered and is a simple page count.

  • WebKitHistoryAgeInDaysLimit (number)
    The number of days an item on the history list lives, after which it is removed (defaults to 7). This plus WebKitHistoryItemLimit allow you to control the history list either with a simple count, or age. To be safe with the age (if you do lots of browsing), you may want to increase the item limit so it doesn't kick in before the age limit.

  • WebIconDatabaseEnabled (boolean)
    Whether storing web site icons (favicon.ico files) are kept (defaults to YES). When enabled, see WebIconDatabaseDirectoryDefaultsKey for where they go.

  • WebIconDatabaseDirectoryDefaultsKey (string)
    When web site icons are enabled (via WebIconDatabaseEnabled), this specifies where the database is located. WebKit sets this to ~/Library/Icons, but Safari changes it to an app specific ~/Library/Safari/Icons.

  • BufferTextDrawing (boolean)
    Enables some form of text drawing buffering, which may or may not be fully implemented yet (currently defaults to NO).

  • WebKitOmitPDFSupport (boolean)
    Use to disable handling PDF within WebKit (defaults to NO, or support PDF). When PDF is handled by WebKit, it displays the PDF in the view where HTML shows (eg, the normal display area in Safari). When not handled, Safari simply downloads the PDF.

  • WebKitLogLevel (string)
    This is a mask value, and is not enabled in Safari.

  • WebKitPageCacheSizePreferenceKey (number)
    Specifies the size of the page cache; first thing to note is that it is somewhat dependent on the amount of memory on the machine (1G or more of memory, this value is used; between 0.5G and 1G, and one less is used; under 0.5G and two less is used). This is the page cache, not what's stored on disk, so it's quite small (default is 3).

  • WebKitObjectCacheSizePreferenceKey (number)
    Indicates the size of the object cache; like WebKitPageCacheSizePreferenceKey, this is dependent on system memory (1G or more multiplies this by four, 0.5G by two, and less does no multiplication). Default is 8388608, which is 8M.

  • WebKitShouldPrintBackgroundsPreferenceKey (boolean)
    When YES (defaults to NO), for any page which uses a background image, will include that image when printing.

  • WebKitTextAreasAreResizable (boolean)
    Appears to be unused so far (defaults to NO).

  • WebKitAllowAnimatedImagesPreferenceKey (boolean)
    Appears to be unused so far (defaults to YES).

  • WebKitAllowAnimatedImageLoopingPreferenceKey (boolean)
    Appears to be unused so far (defaults to YES).

  • WebKitBackForwardCacheExpirationIntervalKey (number)
    How long a cached page can be used when going back/forward through history (defaults to 1800 seconds).

  • WebKitRespectStandardStyleKeyEquivalents (boolean)
    When YES, allows certain keyboard shortcuts to turn on/off certain styles (like bold and italic). NO is WebKit's default, but Safari sets it to YES.

  • WebKitShowsURLsInToolTips (boolean)
    If set to YES, shows a link's URL in a tooltip; default is NO.

  • WebKitPDFDisplayMode (number)
    Should be the style used for displaying PDFs, but it seems to have no effect.
    This and WebKitPDFScaleFactor can be set (for the current session only) by Ctrl-/right-clicking when viewing a PDF and selecting the appropriate setting.

  • WebKitPDFScaleFactor (number)
    Should set the scaling used when displaying PDFs, but seems ignored.

Safari Preferences
These are for Safari only so will not do much of anything for other WebKit-based applications.

  • IncludeDebugMenu (boolean)
    When YES, includes the Debug menu (to modify some of Safari's behaviour). Default is NO.

  • Log (boolean)
    If set to YES, logs some syndication information to stderr (console log if you run Safari in the normal ways). Default is NO.

  • Log.SPI (boolean)
    Logs more detailed syndication information when YES (also to stderr). Defaults to NO

  • CacheDirectory (string)
    Where Safari places its on-disk cache files. Default is ~/Library/Caches/Safari. Note, in my testing, when changing this, Safari will create both the new location and the default, but not actually write anything in either location.

  • DebugShowBuildNumberInWindowTitles (boolean)
    When YES, adds the current build number (eg, 'v412.5') in window titles.

  • CustomUserAgent (string)
    Allows control over what Safari sends as its user agent string back to web servers; default is "Mozilla/5.0 (Macintosh; U; PPC Mac OS X; en-us) AppleWebKit/412.7 (KHTML, like Gecko) Safari/412.5" as of Safari 2.0.1/412.5. The Debug menu allows you to set some canned values for this, but setting it through preferences lets you use any old string you wish.

  • BackForwardListSizeLimit (number)
    Controls the size of the back/forward history list; defaults to 100. Do not set to anything under 100, or Safari will become confused, except for 0 which disables the back button altogether. Values over 100 are acceptable.


  • Just picked this up thru Mac OSX Hints page. Thanks--I've been trying to muddle thru learning some of this and you have made it easier to learn even if my confidence in actually doing is still minimal.

    By Anonymous Anonymous, at October 5, 2005 at 5:44 PM  

  • Thank you for that PDF display thing I've been looking for this. I don't understand why I would want to view pdf in my browser any way, cheers.

    By Anonymous Anonymous, at October 5, 2005 at 11:49 PM  

  • OnyX allows to disable PDF display, if you prefer a GUI.

    By Anonymous Anonymous, at October 6, 2005 at 3:57 AM  

  • Sometimes it's handy to preview PDF documents directly in Safari. When I want to download one without displaying it first I just option-click its link.

    By Anonymous sjk, at October 7, 2005 at 2:56 PM  

  • Anyone have a clue as to how to turn off the URL auto complete 'feature'? To me and many others, it's pretty annoying.

    By Anonymous Anonymous, at January 3, 2007 at 1:10 PM  

Post a Comment

<< Home