undocumented features

[macubergeek]

I've seen posts where submitters tell the reader how to modify an application's plist file in Preferences to turn on hidden or undocumented features. I wonder if a kind knowlegeable person might tell us how to find these undocumented features and how to figure out how to set the parameter=value pairs in the application's plist file?

[sao]

macubergeek,

A lot of settings are not so obvious even when you use the defaults read command from Terminal.app, and you can search for strings in the plist files to find these "hidden" settings but it's actually quite boring work.

[macubergeek]

sounds sufficiently nerdy for me ;-)

I'll have to man the read command!!

thanks

jim

[sao]

Just for fun, I run a 'google' search and came up with the following:

Note: some of these modifications can be done with apps like 'Tinker Tool', some may not even work in Panther or they might already be included in the Application Preferences (haven't tested all). The following examples use the 'defaults' command from Terminal.app. If you run them, please let me know if you discover mistakes or the command doesn't work. Try them at your own risk.

*You should avoid changing values using the 'defaults' tool while the target application is running.

---
To get the Safari Debug menu:
defaults write com.apple.Safari IncludeDebugMenu 1
to disable it:
defaults write com.apple.Safari IncludeDebugMenu 0
---
To enable the Debug menu in Sherlock:
defaults write com.apple.Sherlock SherlockDebug 1
When set to 1, Sherlock displays the Debug menu; when set to 0, Sherlock hides it.
---
To input commands in the Terminal without even making it the frontmost application:
defaults write com.apple.Terminal FocusFollowsMouse -string YES
To delete the change:
defaults delete com.apple.Terminal FocusFollowsMouse
---
To hit command-shift-Q to quit Terminal, run from an xterm when Terminal is not running:
defaults write NSGlobalDomain NSUserKeyEquivalents '{"Quit Terminal" = "@$Q";}'
---
After you select some text in a terminal window to open it as a URL with 'command-shift-U'
and to close a window if you hit 'command-shift-W' :
defaults write com.apple.Terminal NSUserKeyEquivalents '{"Open URL" = "@$U";"Close" = "@$W";}'
(you can't issue this keyboard tweaks one at a time)
---
To swap the commands using 'command + shift + N' (to create a new folder) with 'command + N' (open a new window):
defaults write com.apple.finder NSUserKeyEquivalents -dict 'New Finder Window' '@$N' 'New Folder' '@N'
Restart the Finder.
---
Disable Command-Q for quitting applications:
defaults write NSGlobalDomain NSUserKeyEquivalents '{"Quit Safari" = "@Q"; "Quit Mail" = "@Q";}'
---
To make iPhoto ask if it should open automatically when media is inserted:
defaults write com.apple.iPhoto AskHotPlugAction true
---
To Keep drives mounted after logout and before login:
defaults write /Library/Preferences/SystemConfiguration/autodiskmount AutomountDisksWithoutUserLogin true
---
To turn crash reporting on:
defaults write com.apple.CrashReporter DialogType crashreport
To turn it off:
defaults delete com.apple.CrashReporter DialogType
To suppress the "The application <application> has unexpectedly quit" alert:
defaults write com.apple.CrashReporter DialogType <setting>
The currently available settings are:
"none" = don't show any dialog at all (crash reports are still silently written to disk)
"prompt" = show the unexpectedly quit dialog and prompt to see if the user wants to submit/view the crashreport.
"crashreport" = don't show the unexpectedly quit dialog - instead immediately show the crashreport/submission screen.
---
To get PBX and Xcode to play a sound upon finishing a build:
defaults write com.apple.Xcode PBXBuildSuccessSound FILE.wav
defaults write com.apple.Xcode PBXBuildFailureSound FILE.wav
(ex /Users/username/Library/Sounds/great.wav )
defaults write com.apple.ProjectBuilder PBXBuildSuccessSound FILE.wav
defaults write com.apple.ProjectBuilder PBXBuildFailureSound FILE.wav
---
To turn on EOAdaptorDebuggingEnabled:
defaults write NSGlobalDomain EOAdaptorDebugEnabled YES
To stop it:
defaults write NSGlobalDomain EOAdaptorDebugEnabled NO
---
To set WOSMTPHost for all applications:
defaults write NSGlobalDomain WOSMTPHost "postoffice.acme.com"
(Assuming your SMTP host is called "postoffice.acme.com")
---
To see all the hidden files and directories:
defaults write com.apple.finder ShowAllFiles TRUE
---
Scroll arrows at both ends of scroll bars:
defaults write -g AppleScrollBarVariant <DoubleBoth or Single or DoubleMax>
---
Remove font anti-aliasing:
defaults write -g AppleAntiAliasingThreshold 128
---
To add custom X-Headers to Mail.app.
This will display any user configured custom headers:
defaults read com.apple.mail UserHeaders
To Add a user configured custom header:
defaults write com.apple.mail UserHeaders '{"X-Custom-Header" = "Your custom header here";}'
To Delete all user configured custom headers:
defaults delete com.apple.mail UserHeaders
---
To change the Dock location:
defaults write com.apple.dock orientation left
defaults write com.apple.dock orientation right
defaults write com.apple.dock orientation top
defaults write com.apple.dock orientation bottom
defaults write com.apple.dock pinning start
defaults write com.apple.dock pinning center
defaults write com.apple.dock pinning end
Restart the Dock.
---
If you want a cool blue dot to activate expose instead of key commands:
defaults write com.apple.dock wvous-floater -bool true; killall Dock
To make the blob go away replace "true" with "false".
---
Remapping the Caps Lock to Control:
1- Edit:
/System/Library/Extensions/IOUSBFamily.kext/Contents/PlugIns/IOUSBHIDDriver.kext/Contents/Info.plist
and add:
<key>Swap control and capslock</key>
<integer>1</integer>
under IOKitPersonalities/Generic_Keyboard.
2- % touch /System/Library/Extensions
3- Reboot.
The above won't work on PowerBooks because they have an ADB keyboard.
---
Apple's X11 can be customized using the 'defaults' command:
Read the available options in 'man Xquartz' and 'man quartz-wm'.
---

[nkuvu]

Very helpful, sao. Thanks.

[sao]

Quote: I'll have to man the read command!!

It's the 'defaults' read command and the 'man defaults' pages.
Some 'defaults' commands:

'defaults domains' --->Prints the names of all Applications/domains in the user's defaults system.

'defaults read' --->Prints all of the user's defaults, for every domain, to standard output.

'defaults read domain' --->Prints all of the user's defaults for the especified application/domain to standard output.

Example: defaults read com.apple.iPhoto

'defaults read domain key' --->Prints the value for the default of domain identified by key.

'defaults read-type domain key' --->Prints the plist type for the given domain identified by key.

'defaults write domain key 'value' --->Writes 'value' as the value for 'key' in 'domain'.

[sao]

Thanks, nkuvu. Maybe, it could be useful if whoever knows or find new plists modifications that work in Panther keep posting them to this thread.

[hayne]

sao,
I think your compilation of undocumented defaults settings would make a good "hint" submission for the main macosxhints site. There have been several of these published there already but it is much better to have them all in one place.
And such a "hint" could also summarize how to use the defaults commands (as you have written above) and talk about how to browse the plist files to discover new tweaks.

[mervTormel]

a couple of caveats here:

a. it is unknown if one could cause system failures by indiscriminately frobbing plist settings to unsane values.

adding speculative random name/value pairs to plists should probably be regarded as folly for the novice

b. undocumented tweaks may be undiscoverable by browsing; e.g., a fresh sherlock plist makes no mention of SherlockDebug, so one can't discover what isn't mentioned in the first place.

it appears that some undocumented tweaks are publicized by people somehow involved in the app code and can attest that there is a query for a name/value pair that doesn't necessarily need to exist as it has a default value in the code.

c. setting valid, undocumented name/value pairs may execute untested/buggy code paths that may render your rig unstable or worse.

one can assume that future-feature code stubs are embedded in apps and are possibly untested, and could be executed by enabling some name/value pair, but may be hazardous to pursue.

[sao]

I agree with mervTormel on the subject, one has to exercise extreme care when dealing with the unknown. The potential to create a mess of your system is there. (like for example, let's say, trying to implement one of the "hidden" features of the 'loginwindow' process like its ability to execute shell scripts when a user logs in or logs out)

The first thing when editing a plist file is to check the syntax very carefully, as there is a very specific format to follow. Open the file in PropertyListEditor (available on the Developer CD) to make sure it’s a legal plist file. You can also use the command line tool 'plutil' to check the syntax of a property list (the command 'plutil -lint filename' will check the plist file for syntax errors).

Plists are XML files which use Apple’s plist DTD, they are text based and human readable and they typically hold 'lists of properties'. They contain useful information, but the problem is that the preference format in Applications is subject to change with each minor version and if you change preferences to illegal values, you may cause the Application to misbehave or crash. Besides there is a need to realize that the property list format must be perfectly structured, and a little error in the file may make the file unparsable, which makes the exercise a bit dangerous.


btw, I found about Sherlock's Debug menu at the Sherlock Release Notes - Changes for 10.3 :
http://developer.apple.com/documenta.../Sherlock.html
and in:
ADC Documentation --> Sherlock Channels -->Creating a New Channel.
http://developer.apple.com/documenta...gChannels.html

[sao]

Generally defaults are organized by domain, are user specific, and are machine-independent. Each application has its own 'unique' domain where its preferences are stored (ex: com.apple.finder, com.apple.x11, org.openknights.neveredit, etc.). All applications, system services, and other programs have their own domains, they also share a domain named NSGlobalDomain. Most applications on MacOS X store their preferences in the User Defaults database in each user's Library/Preferences folder as .plist files.

There are several tools you can use to edit the defaults database:

1- Use your favorite text editor, but this way is a bit risky as a small error may make the file unparsable.

2- You can use the PropertyListEditor.app if you have the Developer Tools installed. It's a good tool to view 'large' prefs files, it will give you a view like that of the NetInfo Manager and will maintain the XML structure for you, but it only allows you to edit one domain at a time.

3- Use the 'defaults' tool supplied by Apple from Terminal.app, it will let you browse and manipulate property lists. You will have to learn some basic commands to use it. Using the terminal has the advantage that you can write preferences that are specific to a particular protocol, server or user. You can use "defaults domains" to find the domain you want to edit. "defaults read" displays a Domain in an old-style plist format. With the 'defaults' command you can read/write just about any xml file, for example:

[pm @ Sao: ~] % defaults read /System/Library/CoreServices/SystemVersion
{
    ProductBuildVersion = 7D24; 
    ProductCopyright = "Apple Computer, Inc. 1983-2003"; 
    ProductName = "Mac OS X"; 
    ProductUserVisibleVersion = "10.3.2"; 
    ProductVersion = "10.3.2"; 
}

For more information, read the man page for 'defaults' or run the command with the usage argument (% defaults usage).

4- Use the 'Defaults Manager' application to view, edit, delete, and backup preferences. "It is useful for developers that want to make sure their preferences are being stored and changed correctly, and can be used to unlock features that previously required the use of Terminal". For example, to reveal the Debug menu in Safari using Defaults Manager, here's what you would do. Quit Safari if it's running. Open Defaults Manager and navigate to the "com.apple.Safari" domain. Click on the "+ Add Sibling" button. Put "IncludeDebugMenu" for the Property Name, "Boolean" for the type, and "1" for the Value. The next time you run Safari there will be a Debug menu that will let you access a lot of hidden features, mainly used for debugging.

The value that Defaults Manager adds over tools such as Property List Editor, Finder, and others is that it allows you to:

- View the defaults of all applications quickly.
- View the NSGlobalDomain.
- Easily backup and restore all or selected domains.
- Easily search the entire database for any domain, property, or value.
- Quickly synchronize with the database.

http://freshmeat.net/projects/defaultsmanager/
(the latest version is 1.08 Beta - you can try it for free during the beta period)

5- To obtain a list of possible 'preference keywords' you can use the 'strings' command in Terminal.app. For example:

% strings /System/Library/CoreServices/Finder.app/Contents/MacOS/Finder
...............
DesktopViewOptions
ShowMountedServersOnDesktop
ShowRemovableMediaOnDesktop
ShowHardDrivesOnDesktop
FileViewer.LastWindowLocation
TargetID
Target
SingleWindowMode
DisableAllAnimations
AnimateWindowZoom
ShowToolbar
WindowBounds
ViewHeight
ViewStyle
AlwaysOpenWindowsInColumnView
NewWindowTarget
NewWindowTargetIsHome
NewWindowTargetPath
FinderSpawnWindow
ScrollPosition
EntryPoint
FileViewer.Statusbar
Binding Override
ZoomRects
..........
(etc...etc...)

[sao]

Property lists are constructed from the basic Core Foundation types CFString, CFNumber, CFBoolean, CFDate, and CFData. To build a complex data structure out of these basic types, you put them inside a CFDictionary or CFArray.

From 'man plist':
Core Foundation Types with XML Equivalents
         CF type         XML tag
         CFString        <string>
         CFNumber        <real> or <integer>
         CFDate          <date>
         CFBoolean       <true/> or <false/>
         CFData          <data>
         CFArray         <array>
         CFDictionary    <dict>

     When encoding the contents of a CFDictionary, each member is encoded by
     placing the dictionary key in a <key> tag and immediately following it
     with the corresponding value in the appropriate tag from the table above.
     See EXAMPLES below for an example XML data generated from a property
     list.

     The XML data format is documented here strictly for help in understanding
     property lists and as a debugging aid. These tags may change in future
     releases so you shouldn't rely on them directly. You should not edit the
     XML data by hand unless you are very familiar with XML syntax and the
     format of property lists. If you want to modify the contents of a prop-
     erty list saved on disk as XML data, use the Property List Editor appli-
     cation.

Each element of a property list has a name, or key, a Class type (for example, String, Number, Dictionary, and so forth), and a value.
A plist file starts with an XML header:
<?xml version="1.0" encoding="UTF-8"?>
Then follows a property list tag <plist>:
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
and the dictionary tag:
<dict>

<dict></dict> - It contains a sequence of key/value pairs. A key-value pair within a dictionary is called an entry. Each entry consists of one object that represents the key and second object that is that key’s value. Within a dictionary, the keys are unique. That is, no two keys in a single dictionary are equal (as determined by the equal callback). Each key is written within the following tags: <key></key> and each value can be any plist type. For example:

<dict>
	    <key>Documents</key>
    <array>
		         <dict>
		              <key>Frame</key>
		              <string>25 89 1217 891 0 0 1280 1002 </string>
		              <key>Magnify</key> 
		              <integer>150</integer>
		              <key>Selection</key>
		              <string>Cocoa (Objective-C)/Application Kit - Classes/NSView/Method Types</string>
		              <key>Toolbar Small</key>
		              <false/>
		              <key>Toolbar Visible</key>
		              <true/>
		         </dict>
	     </array>
     <key>dv  com.apple.soundmgr._DV Sound Output Settings</key>
	     <data>
	     fQAAAA==
	     </data>
</dict>

<string></string> - String values contains any UTF-8 sequence of characters.
<real></real><integer></integer> - are used to wrap numerical values.
<date></date> - store dates and times that can be compared to other dates and times.
<true/> and <false/> - used to wrap boolean values.
<data></data> - are typically used for raw data storage.
<array></array> - An array contains a sequence of plist types.

plist files end by closing the <dict> tag, and then finally the enclosing <plist> tag:
</dict>
</plist>

[sao]

Preferences that are not accessible through an application's Preference panel are usually called "hidden" preferences. The reason why many of these defaults cannot be accessed is probably because they are only meant to be used by the developer, they are for features that may not be complete, or management decided not to include the feature.

Some applications have documented online their "hidden" preferences or ways on how to solve same problems with the 'deafults' tool:

---
PStill Preferences: Hidden
http://www.stone.com/PStill/Preferences_Hidden.html
---
Complete list of "OmniWeb's defaults".
Including hidden preferences:
http://www.omnigroup.com/Documentati...aultsList.html
---
To change preferences in Interarchy using the deafults tool.
For a description of the various preferences you can set:
http://www.interarchy.com/documentat...ef_preferences
---
DigiTunnel Preferences
http://www.gracion.com/vpn/Help/rsrc/setup.html
---
Kiosk - Details - Editing loginwindow preferences in macosxlabs.org:
http://www.macosxlabs.org/documentat...dowpreferences
---
Ittec - Hidden Preferences:
http://www.balance-software.com/itte...ces.php#hidden
---
Cocktail
http://www.macosxcocktail.com/support.html
---
PGP for Apple's Mail
A problem with toolbar items added by GPGMail, on some occasions:
GPGMail FAQ:
http://sente.epfl.ch/software/GPGMai...lproj/FAQ.html
---
TeXShop has hidden preferences to set the background color of the preview window:
http://www.versiontracker.com/dyn/moreinfo/macosx/8523
---
ToDo X FAQ:
http://www.nomicro.com/Products/ToDo/faq.html
---
FastScripts FAQ:
http://www.red-sweater.com/RedSweater/FSHelp.html
---



Another google search found the following:

---
Debug menu in the Address Book application:
defaults write com.apple.addressbook ABShowDebugMenu -bool true
---
Enabling the quit menu item to the Finder menu:
defaults write com.apple.finder QuitMenuItem YES
---
3 Label Lines:
defaults write com.apple.finder MaximumLabelLines 3
Change the number to 1 if you want to have just one label line.
This will only work with 1, 2 or 3.
---
To turn on a hidden 'Virtual Desktop' feature in Exposé:
defaults write com.apple.dock wvous-olddesktop -bool false; killall Dock
Instead of sending all of the windows to the very edge of your screen when you press the F11 key
(this is the default key, although you may have reassigned the action to something else) ,
it minimizes all off the windows into a tiny box that can be moved around your desktop.
To revert back to the default setting re-type the command and exchange 'false' for 'true'.
---
Hide Administrator Accounts from the login screen:
sudo defaults write com.apple.loginwindow HideAdminUsers true
To reverse the command:
sudo defaults write com.apple.loginwindow HideAdminUsers false

To login as the 'hidden' admin user:
1. Press the down arrow once at the login panel
2. Press option and Return at the same time.
3. You'll be presented with name and password fields.
4. Type your new short user name and your new password.
---
Add a text message to the login window in Panther:
right below the <dict> tag toward the top of the file add the lines:
<key>LoginwindowText</key>
<string>your text here</string>
---
Turn Off Guest Access in Personal File Sharing:
In com.apple.AppleFileServer.plist find the lines:
<key>guestAccess</key>
<true/>

Change <true/> to <false/>.
---

[kuwan]

I'm the developer of Defaults Manager which Sao mentioned above. There's just a few things that I'd like to add.

First, heed the warnings when messing around with plists. I would discourage using text editors when editing plist files because one misplaced character can render the plist useless and in many cases cause the plist's application to crash. I many times have left out a '>' character that has caused me much grief. It is much better to use a tool such as Property List Editor or Defaults Manager to edit your preferences because these tools will at least guarantee that the xml structure of the plist file is correct. I should note that Property List Editor has had some bugs in the past when displaying plist files. Quite often when you would change the value of a property, or add a new one, Property List Editor would not display the new values properly, though it would save them. I believe the Panther version has been fixed, but I don't use it enough to be sure.

Second, be sure to keep a backup of the plist files you edit. If you mess up the structure or change a property that messes things up then you'll need to have a backup around. Defaults Manager has the ability to save all of your defaults into a single file. You can then either restore some or all of the plist files on a per-application basis.

Searching for hidden preferences is more of an art than a science right now. The best way to find them is when the developer, or another insider, makes them public. If that doesn't happen then it becomes much more difficult. One way to find possible hidden property names is to look for plist files inside of an application's package. Look inside the /Contents/Resources/ folder of an application for plist files. Some developers will store their default preferences here. For example, I store the default preferences for all of my applications in a "defaults.plist" file in this folder. Some of the properties stored here may give you a clue as to possible hidden preferences.

As far as Defaults Manager goes, it will be completely free during its beta period (which will be for a long time). So give it a try, it's very useful for managing your preference files. I'd love it if more people would use it and help me to make it better.

Dave Thorup
Kuwan.net

[macubergeek]

I want to thank everyone, boy I'm glad I asked the question. This has been an incredibly deep and useful thread.

[JohnWiltbank]

Quote: --- To turn on a hidden 'Virtual Desktop' feature in Exposé: defaults write com.apple.dock wvous-olddesktop -bool false; killall Dock Instead of sending all of the windows to the very edge of your screen when you press the F11 key (this is the default key, although you may have reassigned the action to something else) , it minimizes all off the windows into a tiny box that can be moved around your desktop. To revert back to the default setting re-type the command and exchange 'false' for 'true'. ---

See this thread: http://forums.macosxhints.com/showth...293#post121293 for an issue I had using this "virtual desktop" feature. If you don't have the same problem, or you can live with it, then it is a pretty neat feature.

[sao]

JohnWiltbank,

Thanks for the tip. After investigating further, I found out that the un-clickable screen area is a known "bug" and is probably the reason why Apple didn't make it an option.