/image/public/imgIDecoderObserver.idl

http://github.com/zpao/v8monkey · IDL · 174 lines · 22 code · 15 blank · 137 comment · 0 complexity · ec4f325525ede9359e222cf236ac9e0a MD5 · raw file

  1. /** -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*-
  2. *
  3. * ***** BEGIN LICENSE BLOCK *****
  4. * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  5. *
  6. * The contents of this file are subject to the Mozilla Public License Version
  7. * 1.1 (the "License"); you may not use this file except in compliance with
  8. * the License. You may obtain a copy of the License at
  9. * http://www.mozilla.org/MPL/
  10. *
  11. * Software distributed under the License is distributed on an "AS IS" basis,
  12. * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  13. * for the specific language governing rights and limitations under the
  14. * License.
  15. *
  16. * The Original Code is mozilla.org code.
  17. *
  18. * The Initial Developer of the Original Code is
  19. * Netscape Communications Corporation.
  20. * Portions created by the Initial Developer are Copyright (C) 2001
  21. * the Initial Developer. All Rights Reserved.
  22. *
  23. * Contributor(s):
  24. * Stuart Parmenter <pavlov@netscape.com>
  25. * Bobby Holley <bobbyholley@gmail.com>
  26. *
  27. * Alternatively, the contents of this file may be used under the terms of
  28. * either the GNU General Public License Version 2 or later (the "GPL"), or
  29. * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  30. * in which case the provisions of the GPL or the LGPL are applicable instead
  31. * of those above. If you wish to allow use of your version of this file only
  32. * under the terms of either the GPL or the LGPL, and not to allow others to
  33. * use your version of this file under the terms of the MPL, indicate your
  34. * decision by deleting the provisions above and replace them with the notice
  35. * and other provisions required by the GPL or the LGPL. If you do not delete
  36. * the provisions above, a recipient may use your version of this file under
  37. * the terms of any one of the MPL, the GPL or the LGPL.
  38. *
  39. * ***** END LICENSE BLOCK ***** */
  40. #include "imgIContainerObserver.idl"
  41. interface imgIRequest;
  42. interface imgIContainer;
  43. %{C++
  44. #include "nsRect.h"
  45. %}
  46. /**
  47. * imgIDecoderObserver interface
  48. *
  49. * This interface is used both for observing imgIDecoder objects and for
  50. * observing imgIRequest objects. In the former case, aRequest is
  51. * always null.
  52. *
  53. * We make the distinction here between "load" and "decode" notifications. Load
  54. * notifications are fired as the image is loaded from the network or
  55. * filesystem. Decode notifications are fired as the image is decoded. If an
  56. * image is decoded on load and not visibly discarded, decode notifications are
  57. * nested logically inside load notifications as one might expect. However, with
  58. * decode-on-draw, the set of decode notifications can imgRcome completely _after_
  59. * the load notifications, and can come multiple times if the image is
  60. * discardable. Moreover, they can be interleaved in various ways. In general,
  61. * any presumed ordering between load and decode notifications should not be
  62. * relied upon.
  63. *
  64. * Decode notifications may or may not be synchronous, depending on the
  65. * situation. If imgIDecoder::FLAG_SYNC_DECODE is passed to a function that
  66. * triggers a decode, all notifications that can be generated from the currently
  67. * loaded data fire before the call returns. If FLAG_SYNC_DECODE is not passed,
  68. * all, some, or none of the notifications may fire before the call returns.
  69. *
  70. * This interface will be cleaned up in bug 505385.
  71. *
  72. * @author Stuart Parmenter <pavlov@netscape.com>
  73. * @version 0.1
  74. * @see imagelib2
  75. */
  76. [scriptable, uuid(5ca71b89-1a2f-475f-881d-d76c1531c4c8)]
  77. interface imgIDecoderObserver : imgIContainerObserver
  78. {
  79. /**
  80. * Load notification.
  81. *
  82. * called at the same time that nsIRequestObserver::onStartRequest would be
  83. * (used only for observers of imgIRequest objects, which are nsIRequests,
  84. * not imgIDecoder objects)
  85. */
  86. void onStartRequest(in imgIRequest aRequest);
  87. /**
  88. * Decode notification.
  89. *
  90. * Called as soon as the image begins getting decoded. This does not include
  91. * "header-only" decodes used by decode-on-draw to parse the width/height
  92. * out of the image. Thus, it is a decode notification only.
  93. */
  94. void onStartDecode(in imgIRequest aRequest);
  95. /**
  96. * Load notification.
  97. *
  98. * Called once enough data has been loaded from the network that we were able
  99. * to parse the width/height from the image. By the time this callback is been
  100. * called, the size has been set on the container and STATUS_SIZE_AVAILABLE
  101. * has been set on the associated imgRequest.
  102. */
  103. void onStartContainer(in imgIRequest aRequest, in imgIContainer aContainer);
  104. /**
  105. * Decode notification.
  106. *
  107. * called when each frame is created.
  108. */
  109. void onStartFrame(in imgIRequest aRequest, in unsigned long aFrame);
  110. /**
  111. * Decode notification.
  112. *
  113. * called when there is more to paint.
  114. */
  115. [noscript] void onDataAvailable(in imgIRequest aRequest, in boolean aCurrentFrame, [const] in nsIntRect aRect);
  116. /**
  117. * Decode notification.
  118. *
  119. * called when a frame is finished decoding.
  120. */
  121. void onStopFrame(in imgIRequest aRequest, in unsigned long aFrame);
  122. /**
  123. * Do not implement this. It is useless and going away.
  124. */
  125. void onStopContainer(in imgIRequest aRequest, in imgIContainer aContainer);
  126. /**
  127. * Notification for when an image is known to be animated. This should be
  128. * fired at the earliest possible time.
  129. */
  130. void onImageIsAnimated(in imgIRequest aRequest);
  131. /**
  132. * In theory a decode notification, but currently a load notification.
  133. *
  134. * Ideally this would be called when the decode is complete. Unfortunately,
  135. * this is currently the only way to signal decoding errors to consumers,
  136. * and the only decoding errors that consumers care about (indeed, the only
  137. * ones that they're prepared to hear about) are failures to instantiate the
  138. * decoder (<img src="foo.html"> for example). Thus, currently this is just
  139. * a companion to onStopDecode to signal success or failure. This will be
  140. * revisited in bug 505385. If you're thinking of doing something new with
  141. * this, please talk to bholley first.
  142. */
  143. void onStopDecode(in imgIRequest aRequest, in nsresult status,
  144. in wstring statusArg);
  145. /**
  146. * Load notification.
  147. *
  148. * called at the same time that nsIRequestObserver::onStopRequest would be
  149. * (used only for observers of imgIRequest objects, which are nsIRequests,
  150. * not imgIDecoder objects)
  151. */
  152. void onStopRequest(in imgIRequest aRequest, in boolean aIsLastPart);
  153. /**
  154. * Called when the decoded image data is discarded. This means that the frames
  155. * no longer exist in decoded form, and any attempt to access or draw the
  156. * image will initiate a new series of progressive decode notifications.
  157. */
  158. void onDiscard(in imgIRequest aRequest);
  159. };