1/*
2 * Copyright (C) 2003, 2004, 2005 Apple Computer, Inc.  All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without
5 * modification, are permitted provided that the following conditions
6 * are met:
7 *
8 * 1.  Redistributions of source code must retain the above copyright
9 *     notice, this list of conditions and the following disclaimer.
10 * 2.  Redistributions in binary form must reproduce the above copyright
11 *     notice, this list of conditions and the following disclaimer in the
12 *     documentation and/or other materials provided with the distribution.
13 * 3.  Neither the name of Apple Computer, Inc. ("Apple") nor the names of
14 *     its contributors may be used to endorse or promote products derived
15 *     from this software without specific prior written permission.
16 *
17 * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
18 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
19 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
20 * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
21 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
22 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
23 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
24 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
25 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
26 * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
27 */
28
29#import <Foundation/Foundation.h>
30
31#if MAC_OS_X_VERSION_MAX_ALLOWED <= MAC_OS_X_VERSION_10_4
32#define WebNSUInteger unsigned int
33#else
34#define WebNSUInteger NSUInteger
35#endif
36
37/*!
38@enum WebCacheModel
39
40@abstract Specifies a usage model for a WebView, which WebKit will use to
41determine its caching behavior.
42
43@constant WebCacheModelDocumentViewer Appropriate for a WebView displaying
44a fixed document -- like a splash screen, a chat document, or a word processing
45document -- with no UI for navigation. The WebView will behave like any other
46view, releasing resources when they are no longer referenced. Remote resources,
47if any, will be cached to disk. This is the most memory-efficient setting.
48
49Examples: iChat, Mail, TextMate, Growl.
50
51@constant WebCacheModelDocumentBrowser Appropriate for a WebView displaying
52a browsable series of documents with a UI for navigating between them -- for
53example, a reference materials browser or a website designer. The WebView will
54cache a reasonable number of resources and previously viewed documents in
55memory and/or on disk.
56
57Examples: Dictionary, Help Viewer, Coda.
58
59@constant WebCacheModelPrimaryWebBrowser Appropriate for a WebView in the
60application that acts as the user's primary web browser. The WebView will cache
61a very large number of resources and previously viewed documents in memory
62and/or on disk.
63
64Examples: Safari, OmniWeb, Shiira.
65*/
66enum {
67    WebCacheModelDocumentViewer = 0,
68    WebCacheModelDocumentBrowser = 1,
69    WebCacheModelPrimaryWebBrowser = 2
70};
71typedef WebNSUInteger WebCacheModel;
72
73@class WebPreferencesPrivate;
74
75extern NSString *WebPreferencesChangedNotification;
76
77/*!
78    @class WebPreferences
79*/
80@interface WebPreferences: NSObject <NSCoding>
81{
82@private
83    WebPreferencesPrivate *_private;
84}
85
86/*!
87    @method standardPreferences
88*/
89+ (WebPreferences *)standardPreferences;
90
91/*!
92    @method initWithIdentifier:
93    @param anIdentifier A string used to identify the WebPreferences.
94    @discussion WebViews can share instances of WebPreferences by using an instance of WebPreferences with
95    the same identifier.  Typically, instance are not created directly.  Instead you set the preferences
96    identifier on a WebView.  The identifier is used as a prefix that is added to the user defaults keys
97    for the WebPreferences.
98    @result Returns a new instance of WebPreferences or a previously allocated instance with the same identifier.
99*/
100- (id)initWithIdentifier:(NSString *)anIdentifier;
101
102/*!
103    @method identifier
104    @result Returns the identifier for this WebPreferences.
105*/
106- (NSString *)identifier;
107
108/*!
109    @method standardFontFamily
110*/
111- (NSString *)standardFontFamily;
112
113/*!
114    @method setStandardFontFamily:
115    @param family
116*/
117- (void)setStandardFontFamily:(NSString *)family;
118
119/*!
120    @method fixedFontFamily
121*/
122- (NSString *)fixedFontFamily;
123
124/*!
125    @method setFixedFontFamily:
126    @param family
127*/
128- (void)setFixedFontFamily:(NSString *)family;
129
130/*!
131    @method serifFontFamily
132*/
133- (NSString *)serifFontFamily;
134
135/*!
136    @method setSerifFontFamily:
137    @param family
138*/
139- (void)setSerifFontFamily:(NSString *)family;
140
141/*!
142    @method sansSerifFontFamily
143*/
144- (NSString *)sansSerifFontFamily;
145
146/*!
147    @method setSansSerifFontFamily:
148    @param family
149*/
150- (void)setSansSerifFontFamily:(NSString *)family;
151
152/*!
153    @method cursiveFontFamily
154*/
155- (NSString *)cursiveFontFamily;
156
157/*!
158    @method setCursiveFontFamily:
159    @param family
160*/
161- (void)setCursiveFontFamily:(NSString *)family;
162
163/*!
164    @method fantasyFontFamily
165*/
166- (NSString *)fantasyFontFamily;
167
168/*!
169    @method setFantasyFontFamily:
170    @param family
171*/
172- (void)setFantasyFontFamily:(NSString *)family;
173
174/*!
175    @method defaultFontSize
176*/
177- (int)defaultFontSize;
178
179/*!
180    @method setDefaultFontSize:
181    @param size
182*/
183- (void)setDefaultFontSize:(int)size;
184
185/*!
186    @method defaultFixedFontSize
187*/
188- (int)defaultFixedFontSize;
189
190/*!
191    @method setDefaultFixedFontSize:
192    @param size
193*/
194- (void)setDefaultFixedFontSize:(int)size;
195
196/*!
197    @method minimumFontSize
198*/
199- (int)minimumFontSize;
200
201/*!
202    @method setMinimumFontSize:
203    @param size
204*/
205- (void)setMinimumFontSize:(int)size;
206
207/*!
208    @method minimumLogicalFontSize
209*/
210- (int)minimumLogicalFontSize;
211
212/*!
213    @method setMinimumLogicalFontSize:
214    @param size
215*/
216- (void)setMinimumLogicalFontSize:(int)size;
217
218/*!
219    @method defaultTextEncodingName
220*/
221- (NSString *)defaultTextEncodingName;
222
223/*!
224    @method setDefaultTextEncodingName:
225    @param encoding
226*/
227- (void)setDefaultTextEncodingName:(NSString *)encoding;
228
229/*!
230    @method userStyleSheetEnabled
231*/
232- (BOOL)userStyleSheetEnabled;
233
234/*!
235    @method setUserStyleSheetEnabled:
236    @param flag
237*/
238- (void)setUserStyleSheetEnabled:(BOOL)flag;
239
240/*!
241    @method userStyleSheetLocation
242    @discussion The location of the user style sheet.
243*/
244- (NSURL *)userStyleSheetLocation;
245
246/*!
247    @method setUserStyleSheetLocation:
248    @param URL The location of the user style sheet.
249*/
250- (void)setUserStyleSheetLocation:(NSURL *)URL;
251
252/*!
253    @method isJavaEnabled
254*/
255- (BOOL)isJavaEnabled;
256
257/*!
258    @method setJavaEnabled:
259    @param flag
260*/
261- (void)setJavaEnabled:(BOOL)flag;
262
263/*!
264    @method isJavaScriptEnabled
265*/
266- (BOOL)isJavaScriptEnabled;
267
268/*!
269    @method setJavaScriptEnabled:
270    @param flag
271*/
272- (void)setJavaScriptEnabled:(BOOL)flag;
273
274/*!
275    @method JavaScriptCanOpenWindowsAutomatically
276*/
277- (BOOL)javaScriptCanOpenWindowsAutomatically;
278
279/*!
280    @method setJavaScriptCanOpenWindowsAutomatically:
281    @param flag
282*/
283- (void)setJavaScriptCanOpenWindowsAutomatically:(BOOL)flag;
284
285/*!
286    @method arePlugInsEnabled
287*/
288- (BOOL)arePlugInsEnabled;
289
290/*!
291    @method setPlugInsEnabled:
292    @param flag
293*/
294- (void)setPlugInsEnabled:(BOOL)flag;
295
296/*!
297    @method allowAnimatedImages
298*/
299- (BOOL)allowsAnimatedImages;
300
301/*!
302    @method setAllowAnimatedImages:
303    @param flag
304*/
305- (void)setAllowsAnimatedImages:(BOOL)flag;
306
307/*!
308    @method allowAnimatedImageLooping
309*/
310- (BOOL)allowsAnimatedImageLooping;
311
312/*!
313    @method setAllowAnimatedImageLooping:
314    @param flag
315*/
316- (void)setAllowsAnimatedImageLooping: (BOOL)flag;
317
318/*!
319    @method setWillLoadImagesAutomatically:
320    @param flag
321*/
322- (void)setLoadsImagesAutomatically: (BOOL)flag;
323
324/*!
325    @method willLoadImagesAutomatically
326*/
327- (BOOL)loadsImagesAutomatically;
328
329/*!
330    @method setAutosaves:
331    @param flag
332    @discussion If autosave preferences is YES the settings represented by
333    WebPreferences will be stored in the user defaults database.
334*/
335- (void)setAutosaves:(BOOL)flag;
336
337/*!
338    @method autosaves
339    @result The value of the autosave preferences flag.
340*/
341- (BOOL)autosaves;
342
343/*!
344    @method setShouldPrintBackgrounds:
345    @param flag
346*/
347- (void)setShouldPrintBackgrounds:(BOOL)flag;
348
349/*!
350    @method shouldPrintBackgrounds
351    @result The value of the shouldPrintBackgrounds preferences flag
352*/
353- (BOOL)shouldPrintBackgrounds;
354
355/*!
356    @method setPrivateBrowsingEnabled:
357    @param flag
358    @abstract If private browsing is enabled, WebKit will not store information
359    about sites the user visits.
360 */
361- (void)setPrivateBrowsingEnabled:(BOOL)flag;
362
363/*!
364    @method privateBrowsingEnabled
365 */
366- (BOOL)privateBrowsingEnabled;
367
368/*!
369    @method setTabsToLinks:
370    @param flag
371    @abstract If tabsToLinks is YES, the tab key will focus links and form controls.
372    The option key temporarily reverses this preference.
373*/
374- (void)setTabsToLinks:(BOOL)flag;
375
376/*!
377    @method tabsToLinks
378*/
379- (BOOL)tabsToLinks;
380
381/*!
382    @method setUsesPageCache:
383    @abstract Sets whether the receiver's associated WebViews use the shared
384    page cache.
385    @param UsesPageCache Whether the receiver's associated WebViews use the
386    shared page cache.
387    @discussion Pages are cached as they are added to a WebBackForwardList, and
388    removed from the cache as they are removed from a WebBackForwardList. Because
389    the page cache is global, caching a page in one WebBackForwardList may cause
390    a page in another WebBackForwardList to be evicted from the cache.
391*/
392- (void)setUsesPageCache:(BOOL)usesPageCache;
393
394/*!
395    @method usesPageCache
396    @abstract Returns whether the receiver should use the shared page cache.
397    @result Whether the receiver should use the shared page cache.
398    @discussion Pages are cached as they are added to a WebBackForwardList, and
399    removed from the cache as they are removed from a WebBackForwardList. Because
400    the page cache is global, caching a page in one WebBackForwardList may cause
401    a page in another WebBackForwardList to be evicted from the cache.
402*/
403- (BOOL)usesPageCache;
404
405/*!
406@method setCacheModel:
407
408@abstract Specifies a usage model for a WebView, which WebKit will use to
409determine its caching behavior.
410
411@param cacheModel The WebView's usage model for WebKit. If necessary, WebKit
412will prune its caches to match cacheModel.
413
414@discussion Research indicates that users tend to browse within clusters of
415documents that hold resources in common, and to revisit previously visited
416documents. WebKit and the frameworks below it include built-in caches that take
417advantage of these patterns, substantially improving document load speed in
418browsing situations. The WebKit cache model controls the behaviors of all of
419these caches, including NSURLCache and the various WebCore caches.
420
421Applications with a browsing interface can improve document load speed
422substantially by specifying WebCacheModelDocumentBrowser. Applications without
423a browsing interface can reduce memory usage substantially by specifying
424WebCacheModelDocumentViewer.
425
426If setCacheModel: is not called, WebKit will select a cache model automatically.
427*/
428- (void)setCacheModel:(WebCacheModel)cacheModel;
429
430/*!
431@method cacheModel:
432
433@abstract Returns the usage model according to which WebKit determines its
434caching behavior.
435
436@result The usage model.
437*/
438- (WebCacheModel)cacheModel;
439
440@end
441
442#undef WebNSUInteger
443