From eb5ffac358dd731d942fd7f50795079b7b7a5066 Mon Sep 17 00:00:00 2001 From: vidur Date: Wed, 15 Apr 1998 19:37:44 +0000 Subject: [PATCH] Documenting image library interfaces --- gfx/src/nsIImageGroup.h | 87 ++++++++++++++++++++++++-------------- gfx/src/nsIImageManager.h | 36 +++++++++++----- gfx/src/nsIImageObserver.h | 70 +++++++++++++++++++++--------- gfx/src/nsIImageRequest.h | 39 ++++++++++++----- 4 files changed, 160 insertions(+), 72 deletions(-) diff --git a/gfx/src/nsIImageGroup.h b/gfx/src/nsIImageGroup.h index 97cbc5793cb..a16126f972f 100644 --- a/gfx/src/nsIImageGroup.h +++ b/gfx/src/nsIImageGroup.h @@ -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); diff --git a/gfx/src/nsIImageManager.h b/gfx/src/nsIImageManager.h index 2187cce20ea..8e1d9310026 100644 --- a/gfx/src/nsIImageManager.h +++ b/gfx/src/nsIImageManager.h @@ -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); diff --git a/gfx/src/nsIImageObserver.h b/gfx/src/nsIImageObserver.h index 5d6f6c1eaef..ee841fd3296 100644 --- a/gfx/src/nsIImageObserver.h +++ b/gfx/src/nsIImageObserver.h @@ -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; }; diff --git a/gfx/src/nsIImageRequest.h b/gfx/src/nsIImageRequest.h index cd5129b3e5d..4c1c83313ac 100644 --- a/gfx/src/nsIImageRequest.h +++ b/gfx/src/nsIImageRequest.h @@ -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 + * GetImage method of the nsIImageGroup + * 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