WebPreferences Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/WebKit.framework
Availability
Available in OS X v10.2 and later.
Companion guide
Declared in
WebPreferences.h

Overview

WebPreferences encapsulates the preferences you can change per WebView object. These preferences include font, text encoding, and image settings. Normally a WebView object uses the standard preferences returned by the standardPreferences class method. However, you can modify the preferences for individual WebView instances too. Use the setPreferencesIdentifier: WebView method to change a WebView object’s preferences, or to share preferences between WebView objects. Use the setAutosaves: method to specify if the preferences object should be automatically saved to the user defaults database.

WebPreferences also manages the font preferences for a web view. You can set custom font families for each of the primary web font styles (standard, serif, sans-serif, cursive, and fantasy) as well as their font sizes. The font size preferences alter the display font sizes in a certain way. If the HTML or CSS in the web view’s content specifies font sizes in a relative fashion (such as font size=-1 in HTML or font-size: medium in CSS), the default font size settings (set by the font size methods prefaced with “default”) have an effect. They do not have an effect for font sizes specified absolutely. The values specified by the minimum font size settings (set by the font size methods prefaced with “minimum”) override all the HTML and CSS font size definitions, and so have an effect on the entirety of the content. The values specified by the minimum logical font size settings (set by the font size methods prefaced with “minimumLogical”) affect all relative font size declarations for HTML and CSS, but also override any CSS font size declarations in the content, whether they are relative or absolute.

The font size for a web view is different than its logical font size. The minimum logical font size, for example, is the absolute minimum size at which the font will display onscreen. This is meant to be a functional boundary and not a style boundary. For example, the default value for a web view’s minimum logical font size is 9 points, because typical web content looks good on OS X at font sizes of 9 point and above. The constraint assures that web content will always look good in a web view. If you know that your content will look good only at 12 points or above, you should change the minimum font size to 12 points and leave the minimum logical font size alone. This will assure that your content will never display at sizes less than 12 points, but the functional font size boundary of the web view will remain at 9 points to prevent any chance of displaying unnecessarily small text.

Adopted Protocols

NSCoding

Tasks

Getting the Standard Preferences

Initializing Preferences

Getting the Identifier

Saving Preferences to the User Defaults Database

Enabling Java

Enabling JavaScript

Enabling Plug-ins

Enabling Style Sheets

Getting and Setting Fonts

Getting and Setting Font Sizes

Getting and Setting Text Encoding

Getting and Setting Incremental Rendering

Handling Images

Printing Backgrounds

Enabling Private Browsing

Controlling User Focus

Caching

Class Methods

standardPreferences

Returns the standard set of preferences that may be used by all WebView objects.

+ (WebPreferences *)standardPreferences
Return Value

A WebPreferences object containing the standard set of preferences that may be used by all WebView objects.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

Instance Methods

allowsAnimatedImageLooping

Returns whether or not the web view allows animated images to loop.

- (BOOL)allowsAnimatedImageLooping
Return Value

YES if the web view is configured to loop animated images, NO otherwise.

Discussion

The number of times that an image loops is determined by parameters of the image file itself and cannot be set in the web view.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

allowsAnimatedImages

Returns whether or not the web view allows animated images.

- (BOOL)allowsAnimatedImages
Return Value

YES if the web view allows animated images, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

arePlugInsEnabled

Returns whether or not the web view allows plug-ins.

- (BOOL)arePlugInsEnabled
Return Value

YES if the web view allows plug-ins, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

autosaves

Returns whether or not the receiver’s attributes are automatically stored in the user defaults database.

- (BOOL)autosaves
Return Value

YES if the receiver’s attributes are automatically stored, NO otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

cacheModel

Returns the cache model for a web view.

- (WebCacheModel)cacheModel
Return Value

The cache model for the web views associated with the receiver. Possible values are described in WebCacheModel.

Availability
  • Available in OS X v10.5 and later.
Declared In
WebPreferences.h

cursiveFontFamily

Returns the cursive font family for the web view.

- (NSString *)cursiveFontFamily
Return Value

The default font used for cursive text.

Discussion

This preference affects text whose properties indicate that it should be displayed in a cursive font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

defaultFixedFontSize

Returns the default fixed font size for the web view.

- (int)defaultFixedFontSize
Return Value

The default font size used for content displayed in a fixed font if no font size is specified.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

defaultFontSize

Returns the default font size for the web view.

- (int)defaultFontSize
Return Value

The default font size used for content displayed in a fixed font if no font size or font family is specified.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

defaultTextEncodingName

Returns the default text encoding for the web view.

- (NSString *)defaultTextEncodingName
Return Value

The default text encoding used when interpreting content whose encoding is not specified.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

fantasyFontFamily

Returns the fantasy font family for the web view.

- (NSString *)fantasyFontFamily
Return Value

The font family used as the default for content marked with a fantasy font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a fantasy font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

fixedFontFamily

Returns the fixed font family for the web view.

- (NSString *)fixedFontFamily
Return Value

The font family used as the default for content marked with a fixed font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a fixed font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

identifier

Returns the receiver’s identifier.

- (NSString *)identifier
Return Value

The identifier of the WebPreferences object.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

initWithIdentifier:

Returns an initialized WebPreferences object, creating one if it does not exist.

- (id)initWithIdentifier:(NSString *)anIdentifier
Parameters
anIdentifier

A unique identifier for the WebPreferences object

Return Value

A newly initialized WebPreferences object with the identifier; if an existing WebPreferences object with that identifier exists, it is returned instead.

Discussion

The anIdentifier argument should be unique—it is prepended to the keys used to store the receiver’s attributes in the user defaults database. WebView objects can share a WebPreferences object by using the same preferences identifier.

Typically, you do not invoke this method directly. Instead, you set the preferences identifier by sending a setPreferencesIdentifier: message to your WebView object. This method is the designated initializer for the WebPreferences class.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

isJavaEnabled

Returns whether or not Java is enabled for the web view.

- (BOOL)isJavaEnabled
Return Value

YES if the view allows Java, NO otherwise.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

isJavaScriptEnabled

Returns whether or not JavaScript is enabled for the web view.

- (BOOL)isJavaScriptEnabled
Return Value

YES if the web view allows JavaScript, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

javaScriptCanOpenWindowsAutomatically

Returns whether or not JavaScript can open windows automatically for the web view.

- (BOOL)javaScriptCanOpenWindowsAutomatically
Return Value

YES if the web view allows JavaScript to open windows automatically, otherwise NO.

Discussion

Explicit calls to a JavaScript window opener that are activated by user action (such as a button click) are not affected by this setting.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

loadsImagesAutomatically

Returns whether images are loaded automatically for the web view.

- (BOOL)loadsImagesAutomatically
Return Value

YES if the web view allows images to be loaded automatically, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

minimumFontSize

Returns the minimum font size for the web view.

- (int)minimumFontSize
Return Value

The minimum font size that will be used for content regardless of the font size specified by that content.

Discussion

The default value is 1, meaning that the minimum font size is constrained only by the minimum logical font size.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

minimumLogicalFontSize

Returns the minimum logical font size for the web view.

- (int)minimumLogicalFontSize
Return Value

The minimum logical font size used by the web view.

Discussion

The minimum logical font size is the smallest font size that will display in a web view when the content’s font size is imprecisely specified. This includes content with logical sizes (such as small) or with a font size specified as a percentage of the default.

Its default value is a 9-point font size.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

privateBrowsingEnabled

Returns whether or not private browsing is enabled.

- (BOOL)privateBrowsingEnabled
Return Value

YES if private browsing is enabled, otherwise NO.

Discussion

Private browsing prevents the web view from maintaining any history, cache, or AutoFill information for the pages being visited.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

sansSerifFontFamily

Returns the sans serif font family for the web view.

- (NSString *)sansSerifFontFamily
Return Value

The font family used as the default for content marked with a sans-serif font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a sans-serif font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

serifFontFamily

Returns the serif font family for the web view.

- (NSString *)serifFontFamily
Return Value

The font family used as the default for content marked with a serif font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a serif font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setAllowsAnimatedImageLooping:

Sets whether or not the receiver allows animated images to loop.

- (void)setAllowsAnimatedImageLooping:(BOOL)flag
Parameters
flag

YES if the web view should loop animated images, NO otherwise.

Discussion

If image looping is disabled, the web view displays it as a static image. The number of times that an image loops is determined by parameters of the image file itself and cannot be set in the web view.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setAllowsAnimatedImages:

Sets whether or not the receiver allows animated images.

- (void)setAllowsAnimatedImages:(BOOL)flag
Parameters
flag

Set to YES if the web view should allow animated images, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setAutosaves:

Sets whether or not the receiver’s attributes are stored in the user defaults database.

- (void)setAutosaves:(BOOL)flag
Parameters
flag

Set to YES if the receiver’s attributes should be automatically stored in the user defaults database, NO otherwise.

Discussion

The default value is NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setCacheModel:

Sets the cache model for the web views associated with the receiver.

- (void)setCacheModel:(WebCacheModel)cacheModel
Parameters
cacheModel

The cache model for the web views associated with the receiver. Possible values are described in WebCacheModel.

Discussion

Set this property to optimize WebKit's cache footprint (on disk and in memory) to best fit the use of the web view. If a web view is used only for a single webpage, use the WebCacheModelDocumentViewer constant instead.

Availability
  • Available in OS X v10.5 and later.
Declared In
WebPreferences.h

setCursiveFontFamily:

Sets the cursive font family of the web view.

- (void)setCursiveFontFamily:(NSString *)family
Parameters
family

The font family to use as the default font for cursive text.

Discussion

This preference affects text whose properties indicate that it should be displayed in a cursive font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setDefaultFixedFontSize:

Sets the default fixed font size of the web view.

- (void)setDefaultFixedFontSize:(int)size
Parameters
size

The default font size to use for content displayed in a fixed font if no font size is specified.

Discussion

The font size specified by size should always be greater than zero.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setDefaultFontSize:

Sets the default font size of the web view.

- (void)setDefaultFontSize:(int)size
Parameters
size

The default font size to use for content displayed in a fixed font if no font size or font family is specified.

Discussion

The font size specified by size should always be greater than zero.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setDefaultTextEncodingName:

Sets the default text encoding of the web view.

- (void)setDefaultTextEncodingName:(NSString *)encoding
Parameters
encoding

The default text encoding to use when interpreting content whose encoding is not specified.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setFantasyFontFamily:

Sets the fantasy font family of the web view.

- (void)setFantasyFontFamily:(NSString *)family
Parameters
family

The font family to use as the default for content marked with a fantasy font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a fantasy font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setFixedFontFamily:

Sets the fixed font family of the web view.

- (void)setFixedFontFamily:(NSString *)family
Parameters
family

The font family to use as the default for content marked with a fixed font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a fixed font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setJavaEnabled:

Sets whether or not the web view allows Java.

- (void)setJavaEnabled:(BOOL)flag
Parameters
flag

Set to YES to indicate that the web view allows Java, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setJavaScriptCanOpenWindowsAutomatically:

Sets whether or not the web view allows JavaScript to open windows automatically.

- (void)setJavaScriptCanOpenWindowsAutomatically:(BOOL)flag
Parameters
flag

Set to YES if the web view should allow JavaScript to open windows automatically, otherwise NO.

Discussion

Explicit calls to a JavaScript window opener that are activated by user action (such as a button click) are not affected by this setting.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setJavaScriptEnabled:

Sets whether or not the web view allows JavaScript.

- (void)setJavaScriptEnabled:(BOOL)flag
Parameters
flag

Set to YES if the web view should allow JavaScript, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setLoadsImagesAutomatically:

Sets whether or not the web view allows images to be loaded automatically.

- (void)setLoadsImagesAutomatically:(BOOL)flag
Parameters
flag

YES if the web view should allow images to be loaded automatically, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setMinimumFontSize:

Sets the minimum font size of the web view.

- (void)setMinimumFontSize:(int)size
Parameters
size

The minimum font size to use for content regardless of the font size specified by that content.

Discussion

This method sets the minimum display font size for the web view, overriding all content-specified styles, including explicitly specified font sizes.

The font size specified by size should always be greater than zero.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setMinimumLogicalFontSize:

Sets the minimum logical font size of the web view.

- (void)setMinimumLogicalFontSize:(int)size
Parameters
size

The minimum logical font size that the web view should use.

Discussion

The minimum logical font size is the smallest font size that will display in a web view when the content’s font size is imprecisely specified. This includes content with logical sizes (such as small) or with a font size specified as a percentage of the default.

Most clients will not want to use this method; rather, explicitly set the minimum display font size using the setMinimumFontSize: method.

The font size specified by size should always be greater than zero.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

setPlugInsEnabled:

Sets whether or not the web view allows plug-ins.

- (void)setPlugInsEnabled:(BOOL)flag
Parameters
flag

Set to YES if the web view should allow plug-ins, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setPrivateBrowsingEnabled:

Sets whether or not private browsing is enabled.

- (void)setPrivateBrowsingEnabled:(BOOL)flag
Return Value

YES if private browsing should be enabled, otherwise NO.

Discussion

If private browsing is enabled, the web view does not store information about the websites the user visits. Private browsing prevents the web view from maintaining any history, cache, or AutoFill information for the pages being visited.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

setSansSerifFontFamily:

Sets the sans serif font family of the web view.

- (void)setSansSerifFontFamily:(NSString *)family
Parameters
family

The font family to use as the default for content marked with a sans-serif font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a sans-serif font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setSerifFontFamily:

Sets the serif font family of the web view.

- (void)setSerifFontFamily:(NSString *)family
Parameters
family

The font family to use as the default for content marked with a serif font.

Discussion

This preference affects text whose properties indicate that it should be displayed in a serif font but do not specify a particular font.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setShouldPrintBackgrounds:

Sets whether or not the web view should include backgrounds when printing.

- (void)setShouldPrintBackgrounds:(BOOL)flag
Parameters
flag

Set to YES if the web view should print backgrounds, otherwise NO.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

setStandardFontFamily:

Sets the standard font family of the web view.

- (void)setStandardFontFamily:(NSString *)family
Parameters
family

The font family to use as the default for content that does not specify a font.

Discussion

This preference affects text whose properties do not indicate that they should be displayed in a particular font or class of fonts (such as sans-serif).

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setSuppressesIncrementalRendering:

Sets whether incremental rendering should be suppressed.

- (void)setSuppressesIncrementalRendering:(BOOL)suppressesIncrementalRendering
Parameters
suppressesIncrementalRendering

Pass YES to suppress incremental rendering, or NO otherwise.

Availability
  • Available in OS X v10.8 and later.
Declared In
WebPreferences.h

setTabsToLinks:

Sets whether or not the web view will focus control on links when tabbing.

- (void)setTabsToLinks:(BOOL)flag
Return Value

YES if the user is able to navigate to links by pressing the tab key, NO otherwise.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

setUserStyleSheetEnabled:

Sets whether or not user style sheets are enabled in the web view.

- (void)setUserStyleSheetEnabled:(BOOL)flag
Parameters
flag

Set to YES if the user style sheets should be enabled in the web view, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setUserStyleSheetLocation:

Sets the location of the user style sheet.

- (void)setUserStyleSheetLocation:(NSURL *)URL
Parameters
URL

An NSURL object containing the location of the user style sheet.

Discussion

The user style sheet will override all existing CSS definitions on the page. setUserStyleSheetEnabled: must have already been set to YES for this method to have an effect.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

setUsesPageCache:

Sets whether the web views associated with the receiver should use the shared page cache.

- (void)setUsesPageCache:(BOOL)usesPageCache
Parameters
usesPageCache

YES if the web views should use a page cache; otherwise, NO.

Discussion

Pages are cached when they are added to a back-forward list, and removed from the cache when they are removed from a back-forward list. Because the page cache is global, caching a page in one back-forward list may cause a page in another back-forward list to be removed from the cache.

Availability
  • Available in OS X v10.5 and later.
Declared In
WebPreferences.h

shouldPrintBackgrounds

Returns whether the web view should include backgrounds when printing.

- (BOOL)shouldPrintBackgrounds
Return Value

YES if the web view prints backgrounds, otherwise NO.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

standardFontFamily

Returns the standard font family used by the web view.

- (NSString *)standardFontFamily
Return Value

The font family used as the default for content that does not specify a font.

Discussion

This preference affects text whose properties do not indicate that they should be displayed in a particular font or class of fonts (such as sans-serif).

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

suppressesIncrementalRendering

Returns whether incremental rendering is suppressed.

- (BOOL)suppressesIncrementalRendering
Availability
  • Available in OS X v10.8 and later.
Declared In
WebPreferences.h

tabsToLinks

Returns whether or not the tab key will focus links.

- (BOOL)tabsToLinks
Return Value

YES if the user should be able to navigate to links by pressing the tab key, NO otherwise.

Availability
  • Available in OS X v10.3 and later.
Declared In
WebPreferences.h

userStyleSheetEnabled

Returns whether user style sheets are enabled in the web view.

- (BOOL)userStyleSheetEnabled
Return Value

YES if the user style sheets are enabled in the web view, otherwise NO.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

userStyleSheetLocation

Returns the location of the user style sheet.

- (NSURL *)userStyleSheetLocation
Return Value

An NSURL object containing the location of the user style sheet.

Availability
  • Available in OS X v10.2 and later.
Declared In
WebPreferences.h

usesPageCache

Returns whether the web views associated with the receiver should use the shared page cache.

- (BOOL)usesPageCache
Return Value

YES if the web views should use a page cache; otherwise, NO.

Availability
  • Available in OS X v10.5 and later.
Declared In
WebPreferences.h

Constants

WebCacheModel

Specifies the caching model for a web view.

enum {
   WebCacheModelDocumentViewer = 0,
   WebCacheModelDocumentBrowser = 1,
   WebCacheModelPrimaryWebBrowser = 2
};
typedef NSUInteger WebCacheModel;
Constants
WebCacheModelDocumentViewer

Releases resources when they are no longer referenced and caches remote resources on disk. This model is appropriate for displaying a static document with no navigation user interface. This is the most memory-efficient model.

Available in OS X v10.5 and later.

Declared in WebPreferences.h.

WebCacheModelDocumentBrowser

Caches a reasonable number of resources and previously viewed documents in memory and on disk. This model is appropriate for displaying and navigating between multiple documents.

Available in OS X v10.5 and later.

Declared in WebPreferences.h.

WebCacheModelPrimaryWebBrowser

Caches a large number of resources and previously viewed documents in memory and on disk. This model is appropriate for a web view that behaves like a web browser.

Available in OS X v10.5 and later.

Declared in WebPreferences.h.

Availability
  • Available in OS X v10.5 and later.
Declared In
WebPreferences.h

Notifications

WebPreferencesChangedNotification

Posted when the web preference settings are changed.

The notification object is the WebPreferences object that changed. This notification does not contain a userInfo dictionary.

Availability
Declared In
WebPreferences.h