Fixed: <rdar://problem/3890944> disable icon database for Dashboard
[WebKit-https.git] / WebKit / Misc.subproj / WebIconDatabase.h
1 /*
2     WebIconDatabase.h
3     Copyright 2001, 2002, Apple, Inc. All rights reserved.
4 */
5
6 #import <Cocoa/Cocoa.h>
7
8 // Sent whenever a site icon has changed. The object of the notification is the icon database.
9 // The userInfo contains the site URL who's icon has changed.
10 // It can be accessed with the key WebIconNotificationUserInfoURLKey.
11 extern NSString *WebIconDatabaseDidAddIconNotification;
12
13 extern NSString *WebIconNotificationUserInfoURLKey;
14
15 extern NSString *WebIconDatabaseDirectoryDefaultsKey;
16 extern NSString *WebIconDatabaseEnabledDefaultsKey;
17
18 extern NSSize WebIconSmallSize;  // 16 x 16
19 extern NSSize WebIconMediumSize; // 32 x 32
20 extern NSSize WebIconLargeSize;  // 128 x 128
21
22 @class WebIconDatabasePrivate;
23
24 /*!
25     @class WebIconDatabase
26     @discussion Features:
27         - memory cache icons at different sizes
28         - disk storage
29         - icon update notification
30         
31         Uses:
32         - WebIconLoader to cache icon images
33         - UI elements to retrieve icons that represent site URLs.
34         - Save icons to disk for later use.
35  
36     Every icon in the database has a retain count.  If an icon has a retain count greater than 0, it will be written to disk for later use. If an icon's retain count equals zero it will be removed from disk.  The retain count is not persistent across launches. If the WebKit client wishes to retain an icon it should retain the icon once for every launch.  This is best done at initialization time before the database begins removing icons.  To make sure that the database does not remove unretained icons prematurely, call delayDatabaseCleanup until all desired icons are retained.  Once all are retained, call allowDatabaseCleanup.
37     
38     Note that an icon can be retained after the database clean-up has begun. This just has to be done before the icon is removed. Icons are removed from the database whenever new icons are added to it.
39     
40     Retention methods can be called for icons that are not yet in the database.
41 */
42 @interface WebIconDatabase : NSObject {
43
44 @private
45     WebIconDatabasePrivate *_private;
46 }
47
48
49 /*!
50     @method sharedIconDatabase
51     @abstract Returns a shared instance of the icon database
52 */
53 + (WebIconDatabase *)sharedIconDatabase;
54
55 /*!
56     @method iconForURL:withSize:
57     @discussion Calls iconForURL:withSize:cache: with YES for cache.
58     @param URL
59     @param size
60 */
61 - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size;
62
63 /*!
64     @method iconForURL:withSize:cache:
65     @discussion Returns an icon for a web site URL from memory or disk. nil if none is found.
66     Usually called by a UI element to determine if a site URL has an associated icon.
67     Often called by the observer of WebIconChangedNotification after the notification is sent.
68     @param URL
69     @param size
70     @param cache If yes, caches the returned image in memory if not already cached
71 */
72 - (NSImage *)iconForURL:(NSString *)URL withSize:(NSSize)size cache:(BOOL)cache;
73
74 /*!
75     @method iconURLForURL:withSize:cache:
76     @discussion Returns an icon URL for a web site URL from memory or disk. nil if none is found.
77     @param URL
78 */
79 - (NSString *)iconURLForURL:(NSString *)URL;
80
81 /*!
82     @method defaultIconWithSize:
83     @param size
84 */
85 - (NSImage *)defaultIconWithSize:(NSSize)size;
86
87 /*!
88     @method retainIconForURL:
89     @abstract Increments the retain count of the icon.
90     @param URL
91 */
92 - (void)retainIconForURL:(NSString *)URL;
93
94 /*!
95     @method releaseIconForURL:
96     @abstract Decrements the retain count of the icon.
97     @param URL
98 */
99 - (void)releaseIconForURL:(NSString *)URL;
100
101 /*!
102     @method delayDatabaseCleanup:
103     @discussion Only effective if called before the database begins removing icons.
104     delayDatabaseCleanUp increments an internal counter that when 0 begins the database clean-up.
105     The counter equals 0 at initialization.
106 */
107 - (void)delayDatabaseCleanup;
108
109 /*!
110     @method allowDatabaseCleanup:
111     @discussion Informs the database that it now can begin removing icons.
112     allowDatabaseCleanup decrements an internal counter that when 0 begins the database clean-up.
113     The counter equals 0 at initialization.
114 */
115 - (void)allowDatabaseCleanup;
116
117 @end