зеркало из https://github.com/mozilla/pjs.git
Documenting image library interfaces
This commit is contained in:
vidur
Родитель
e331812381
Коммит
eb5ffac358
|
|
@ -29,13 +29,13 @@ class nsIImageRequestObserver;
|
|||
class nsIImageRequest;
|
||||
class nsIRenderingContext;
|
||||
|
||||
/* For important images, like backdrops. */
|
||||
/** For important images, like backdrops. */
|
||||
#define nsImageLoadFlags_kHighPriority 0x01
|
||||
/* Don't throw this image out of cache. */
|
||||
/** Don't throw this image out of cache. */
|
||||
#define nsImageLoadFlags_kSticky 0x02
|
||||
/* Don't get image out of image cache. */
|
||||
/** Don't get image out of image cache. */
|
||||
#define nsImageLoadFlags_kBypassCache 0x04
|
||||
/* Don't load if image cache misses. */
|
||||
/** Don't load if image cache misses. */
|
||||
#define nsImageLoadFlags_kOnlyFromCache 0x08
|
||||
|
||||
// IID for the nsIImageGroup interface
|
||||
|
|
@ -43,50 +43,75 @@ class nsIRenderingContext;
|
|||
{ 0xbe927e40, 0xaeaa, 0x11d1, \
|
||||
{ 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
|
||||
|
||||
//----------------------------------------------------------------------
|
||||
//
|
||||
// Image group. A convenient way to group a set of image load requests
|
||||
// and control them as a group.
|
||||
/**
|
||||
*
|
||||
* Image group. A convenient way to group a set of image load requests
|
||||
* and control them as a group.
|
||||
*/
|
||||
class nsIImageGroup : public nsISupports
|
||||
{
|
||||
public:
|
||||
/**
|
||||
* Initialize an image group with a rendering context. All images
|
||||
* in this group will be decoded for the specified rendering context.
|
||||
*/
|
||||
virtual nsresult Init(nsIRenderingContext *aRenderingContext) = 0;
|
||||
|
||||
// Add and remove observers to listen in on image group notifications
|
||||
/**
|
||||
* Add an observers to be informed of image group notifications.
|
||||
*
|
||||
* @param aObserver - An observer to add to the observer list.
|
||||
* @param boolean indicating whether addition was successful.
|
||||
*/
|
||||
virtual PRBool AddObserver(nsIImageGroupObserver *aObserver) = 0;
|
||||
|
||||
/**
|
||||
* Remove a previously added observer from the observer list.
|
||||
*
|
||||
* @param aObserver - An observer to remove from the observer list.
|
||||
* @param boolean indicating whether the removal was successful.
|
||||
*/
|
||||
virtual PRBool RemoveObserver(nsIImageGroupObserver *aObserver) = 0;
|
||||
|
||||
// Fetch the image corresponding to the specified URL.
|
||||
//
|
||||
// The observer is notified at significant points in image loading.
|
||||
//
|
||||
// The width and height parameters specify the target dimensions of
|
||||
// the image. The image will be stretched horizontally, vertically or
|
||||
// both to meet these parameters. If both width and height are zero,
|
||||
// the image is decoded using its "natural" size. If only one of
|
||||
// width and height is zero, the image is scaled to the provided
|
||||
// dimension, with the unspecified dimension scaled to maintain the
|
||||
// image's original aspect ratio.
|
||||
//
|
||||
// If the background color is NULL, a mask will be generated for any
|
||||
// transparent images. If background color is non-NULL, it indicates
|
||||
// the RGB value to be painted into the image for "transparent" areas
|
||||
// of the image, in which case no mask is created. This is intended
|
||||
// for backdrops and printing.
|
||||
//
|
||||
// Image load flags are specified above
|
||||
/**
|
||||
* Fetch the image corresponding to the specified URL.
|
||||
*
|
||||
* @param aUrl - the URL of the image to be loaded.
|
||||
* @param aObserver - the observer is notified at significant
|
||||
* points in image loading.
|
||||
* @param aWidth, aHeight - These parameters specify the target
|
||||
* dimensions of the image. The image will be stretched
|
||||
* horizontally, vertically or both to meet these parameters.
|
||||
* If both width and height are zero, the image is decoded
|
||||
* using its "natural" size. If only one of width and height
|
||||
* is zero, the image is scaled to the provided dimension, with
|
||||
* the unspecified dimension scaled to maintain the image's
|
||||
* original aspect ratio.
|
||||
* @param aBackgroundColor - If the background color is NULL, a mask
|
||||
* will be generated for any transparent images. If background
|
||||
* color is non-NULL, it indicates the RGB value to be painted
|
||||
* into the image for "transparent" areas of the image, in which
|
||||
* case no mask is created. This is intended for backdrops and
|
||||
* printing.
|
||||
* @param aFlags - image loading flags are specified above
|
||||
*
|
||||
* @return the resulting image request object.
|
||||
*/
|
||||
virtual nsIImageRequest* GetImage(const char* aUrl,
|
||||
nsIImageRequestObserver *aObserver,
|
||||
nscolor aBackgroundColor,
|
||||
PRUint32 aWidth, PRUint32 aHeight,
|
||||
PRUint32 aFlags) = 0;
|
||||
|
||||
// Halt decoding of images or animation without destroying associated
|
||||
// pixmap data. All ImageRequests created with this ImageGroup
|
||||
// are interrupted.
|
||||
/**
|
||||
* Halt decoding of images or animation without destroying associated
|
||||
* pixmap data. All ImageRequests created with this ImageGroup
|
||||
* are interrupted.
|
||||
*/
|
||||
virtual void Interrupt(void) = 0;
|
||||
};
|
||||
|
||||
/// Factory method for creating an image group
|
||||
extern NS_GFX nsresult
|
||||
NS_NewImageGroup(nsIImageGroup **aInstancePtrResult);
|
||||
|
||||
|
|
|
|||
|
|
@ -38,29 +38,45 @@ typedef enum
|
|||
{ 0x9f327100, 0xad5a, 0x11d1, \
|
||||
{ 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
|
||||
|
||||
//----------------------------------------------------------------------
|
||||
//
|
||||
// Image manager. There is only a single instance, created when the
|
||||
// class is initially loaded.
|
||||
/**
|
||||
*
|
||||
* Image manager. There is only a single instance, returned when invoking
|
||||
* the factory instantiation method. A user of the image library should
|
||||
* hold on to the singleton image manager.
|
||||
*/
|
||||
class nsIImageManager : public nsISupports
|
||||
{
|
||||
public:
|
||||
/// Initialization method to be called before use
|
||||
virtual nsresult Init() = 0;
|
||||
|
||||
// Set and get the cache size in bytes
|
||||
/// Set the size (in bytes) image cache maintained by the image manager
|
||||
virtual void SetCacheSize(PRInt32 aCacheSize) = 0;
|
||||
|
||||
/// @return the current size of the image cache (in bytes)
|
||||
virtual PRInt32 GetCacheSize(void) = 0;
|
||||
|
||||
// Attempts to release some memory by freeing an image from the image
|
||||
// cache. This may not always be possible either because all images
|
||||
// in the cache are in use or because the cache is empty. Returns the
|
||||
// new approximate size of the imagelib cache.
|
||||
/**
|
||||
* Attempts to release some memory by freeing an image from the image
|
||||
* cache. This may not always be possible either because all images
|
||||
* in the cache are in use or because the cache is empty.
|
||||
*
|
||||
* @return the new approximate size of the imagelib cache.
|
||||
*/
|
||||
virtual PRInt32 ShrinkCache(void) = 0;
|
||||
|
||||
// Determine the type of the image, based on the first few bytes of data.
|
||||
/**
|
||||
* Determine the type of the image, based on the first few bytes of data.
|
||||
*
|
||||
* @param buf - a buffer of image data
|
||||
* @param length - the length of the buffer
|
||||
*
|
||||
* @return the type of the image, if known
|
||||
*/
|
||||
virtual nsImageType GetImageType(const char *buf, PRInt32 length) = 0;
|
||||
};
|
||||
|
||||
/// Factory method to get a reference to the singleton image manager
|
||||
extern NS_GFX nsresult
|
||||
NS_NewImageManager(nsIImageManager **aInstancePtrResult);
|
||||
|
||||
|
|
|
|||
|
|
@ -27,8 +27,8 @@ class nsIImage;
|
|||
class nsIImageRequest;
|
||||
class nsIImageGroup;
|
||||
|
||||
/// Image request notifications
|
||||
typedef enum {
|
||||
// Image request notifications
|
||||
nsImageNotification_kStartURL, // Start of decode/display for URL.
|
||||
nsImageNotification_kDescription, // Availability of image description.
|
||||
nsImageNotification_kDimensions, // Availability of image dimensions.
|
||||
|
|
@ -51,6 +51,7 @@ typedef enum {
|
|||
nsImageNotification_kInternalImage, // Internal image icon.
|
||||
} nsImageNotification;
|
||||
|
||||
/// Image group notifications
|
||||
typedef enum {
|
||||
|
||||
// Start of image loading. Sent when a loading image is
|
||||
|
|
@ -75,6 +76,7 @@ typedef enum {
|
|||
|
||||
} nsImageGroupNotification;
|
||||
|
||||
/// Image loading errors
|
||||
typedef enum {
|
||||
nsImageError_kNotInCache, // Image URL not available in cache when
|
||||
// kOnlyFromCache flag was set.
|
||||
|
|
@ -98,40 +100,66 @@ typedef enum {
|
|||
{ 0xb3cad300, 0xb8f4, 0x11d1, \
|
||||
{ 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
|
||||
|
||||
/**
|
||||
* Image request observer interface. The implementor will be notified
|
||||
* of significant loading events or loading errors.
|
||||
*/
|
||||
class nsIImageRequestObserver : public nsISupports {
|
||||
public:
|
||||
// Notify the observer of some significant image event. The parameter
|
||||
// values depend on the notification type as specified below:
|
||||
//
|
||||
// kDescription - aParam3 is a string containing the human readable
|
||||
// description of an image, e.g. "GIF89a 320 x 240 pixels".
|
||||
// The string storage is static, so it must be copied if
|
||||
// it is to be preserved after the call to the observer.
|
||||
// kDimensions - aParam1 and aParam2 are the width and height respectively
|
||||
// of the image.
|
||||
// kPixmapUpdate - aParame3 is a pointer to a nsRect struct containing the
|
||||
// rectangular area of pixels which has been modified by
|
||||
// the image library. This notification enables the
|
||||
// client to drive the progressive display of the image.
|
||||
// kProgress - aParam1 represents the estimated percentage decoded. This
|
||||
// notification occurs at unspecified intervals. Provided
|
||||
// that decoding proceeds without error, it is guaranteed that
|
||||
// notification will take place on completion with a
|
||||
// percent_progress value of 100.
|
||||
//
|
||||
/**
|
||||
* Notify the observer of some significant image event. The parameter
|
||||
* values depend on the notification type as specified below.
|
||||
*
|
||||
* kDescription - aParam3 is a string containing the human readable
|
||||
* description of an image, e.g. "GIF89a 320 x 240 pixels".
|
||||
* The string storage is static, so it must be copied if
|
||||
* it is to be preserved after the call to the observer.
|
||||
* kDimensions - aParam1 and aParam2 are the width and height respectively
|
||||
* of the image.
|
||||
* kPixmapUpdate - aParame3 is a pointer to a nsRect struct containing the
|
||||
* rectangular area of pixels which has been modified by
|
||||
* the image library. This notification enables the
|
||||
* client to drive the progressive display of the image.
|
||||
* kProgress - aParam1 represents the estimated percentage decoded. This
|
||||
* notification occurs at unspecified intervals. Provided
|
||||
* that decoding proceeds without error, it is guaranteed that
|
||||
* notification will take place on completion with a
|
||||
* percent_progress value of 100.
|
||||
*
|
||||
* @param aImageRequest - the image request in question
|
||||
* @param aImage - the corresponding image object
|
||||
* @param aNotificationType - the type of notification
|
||||
* @param aParam1, aParam2, aParam3 - additional information as described
|
||||
* above.
|
||||
*/
|
||||
virtual void Notify(nsIImageRequest *aImageRequest,
|
||||
nsIImage *aImage,
|
||||
nsImageNotification aNotificationType,
|
||||
PRInt32 aParam1, PRInt32 aParam2,
|
||||
void *aParam3)=0;
|
||||
|
||||
// Notify the observer of an error during image loading.
|
||||
/**
|
||||
* Notify the observer of an error during image loading.
|
||||
*
|
||||
* @param aImageRequest - the image request in question
|
||||
* @param aErrorType - the error code
|
||||
*/
|
||||
virtual void NotifyError(nsIImageRequest *aImageRequest,
|
||||
nsImageError aErrorType)=0;
|
||||
};
|
||||
|
||||
/**
|
||||
* Image group observer interface. The implementor will be notified
|
||||
* of significant image group events.
|
||||
*/
|
||||
class nsIImageGroupObserver : public nsISupports {
|
||||
public:
|
||||
/**
|
||||
* Notify the observer of some significant image group event.
|
||||
*
|
||||
* @param aImageGroup - the image group in question
|
||||
* @param aNotificationType - the notification code
|
||||
*/
|
||||
virtual void Notify(nsIImageGroup *aImageGroup,
|
||||
nsImageGroupNotification aNotificationType)=0;
|
||||
};
|
||||
|
|
|
|||
|
|
@ -31,24 +31,43 @@ class nsIImage;
|
|||
{ 0xc31444c0, 0xaec9, 0x11d1, \
|
||||
{ 0x9b, 0xc3, 0x00, 0x60, 0x08, 0x8c, 0xa6, 0xb3 } }
|
||||
|
||||
/**
|
||||
*
|
||||
* An image request generated as a result of invoking the
|
||||
* <code>GetImage</code> method of the <code>nsIImageGroup</code>
|
||||
* interface.
|
||||
*/
|
||||
class nsIImageRequest : public nsISupports {
|
||||
public:
|
||||
// Get the image associated with the request.
|
||||
/// @return the image object associated with the request.
|
||||
virtual nsIImage* GetImage() = 0;
|
||||
|
||||
// Return the natural dimensions of the image. Returns 0,0
|
||||
//if the dimensions are unknown.
|
||||
/**
|
||||
* Returns the natural dimensions of the image. Returns 0,0
|
||||
* if the dimensions are unknown.
|
||||
*
|
||||
* @param aWidth, aHeight - pointers to integers to be filled in with
|
||||
* the dimensions.
|
||||
*/
|
||||
virtual void GetNaturalDimensions(PRUint32 *aWidth, PRUint32 *aHeight) = 0;
|
||||
|
||||
// Add and remove observers to listen in on image loading notifications
|
||||
|
||||
/**
|
||||
* Add an observers to be informed of image loading notifications.
|
||||
*
|
||||
* @param aObserver - An observer to add to the observer list.
|
||||
* @param boolean indicating whether addition was successful.
|
||||
*/
|
||||
virtual PRBool AddObserver(nsIImageRequestObserver *aObserver) = 0;
|
||||
|
||||
/**
|
||||
* Remove a previously added observer from the observer list.
|
||||
*
|
||||
* @param aObserver - An observer to remove from the observer list.
|
||||
* @param boolean indicating whether the removal was successful.
|
||||
*/
|
||||
virtual PRBool RemoveObserver(nsIImageRequestObserver *aObserver) = 0;
|
||||
|
||||
// Interrupt loading of just this image.
|
||||
/// Interrupt loading of just this image.
|
||||
virtual void Interrupt() = 0;
|
||||
};
|
||||
|
||||
extern NS_GFX nsresult
|
||||
NS_NewImageRequest(nsIImageRequest **aInstancePtrResult);
|
||||
|
||||
#endif
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче