gfx/thebes/PrintTarget.h

   1 /* -*- Mode: C++; tab-width: 20; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this
   4  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   5
   6 #ifndef MOZILLA_GFX_PRINTTARGET_H
   7 #define MOZILLA_GFX_PRINTTARGET_H
   8
   9 #include <functional>
  10
  11 #include "mozilla/RefPtr.h"
  12 #include "mozilla/gfx/2D.h"
  13 #include "nsISupportsImpl.h"
  14 #include "nsStringFwd.h"
  15
  16 namespace mozilla {
  17 namespace gfx {
  18
  19 class DrawEventRecorder;
  20
  21 /**
  22  * A class that is used to draw output that is to be sent to a printer or print
  23  * preview.
  24  *
  25  * This class wraps a cairo_surface_t* and provides access to it via a
  26  * DrawTarget.  The various checkpointing methods manage the state of the
  27  * platform specific cairo_surface_t*.
  28  */
  29 class PrintTarget {
  30  public:
  31   typedef std::function<void(nsresult)> PageDoneCallback;
  32
  33   NS_INLINE_DECL_REFCOUNTING(PrintTarget);
  34
  35   /// Must be matched 1:1 by an EndPrinting/AbortPrinting call.
  36   virtual nsresult BeginPrinting(const nsAString& aTitle,
  37                                  const nsAString& aPrintToFileName,
  38                                  int32_t aStartPage, int32_t aEndPage) {
  39     return NS_OK;
  40   }
  41   virtual nsresult EndPrinting() { return NS_OK; }
  42   virtual nsresult AbortPrinting() {
  43 #ifdef DEBUG
  44     mHasActivePage = false;
  45 #endif
  46     return NS_OK;
  47   }
  48   virtual nsresult BeginPage() {
  49 #ifdef DEBUG
  50     MOZ_ASSERT(!mHasActivePage, "Missing EndPage() call");
  51     mHasActivePage = true;
  52 #endif
  53     return NS_OK;
  54   }
  55   virtual nsresult EndPage() {
  56 #ifdef DEBUG
  57     mHasActivePage = false;
  58 #endif
  59     return NS_OK;
  60   }
  61
  62   /**
  63    * Releases the resources used by this PrintTarget.  Typically this should be
  64    * called after calling EndPrinting().  Calling this more than once is
  65    * allowed, but subsequent calls are a no-op.
  66    *
  67    * Note that any DrawTarget obtained from this PrintTarget will no longer be
  68    * useful after this method has been called.
  69    */
  70   virtual void Finish();
  71
  72   /**
  73    * Returns true if to print landscape our consumers must apply a 90 degrees
  74    * rotation to our DrawTarget.
  75    */
  76   virtual bool RotateNeededForLandscape() const { return false; }
  77
  78   const IntSize& GetSize() const { return mSize; }
  79
  80   /**
  81    * Makes a DrawTarget to draw the printer output to, or returns null on
  82    * failure.
  83    *
  84    * If aRecorder is passed a recording DrawTarget will be created instead of
  85    * the type of DrawTarget that would normally be returned for a particular
  86    * subclass of this class.  This argument is only intended to be used in
  87    * the e10s content process if printing output can't otherwise be transfered
  88    * over to the parent process using the normal DrawTarget type.
  89    *
  90    * NOTE: this should only be called between BeginPage()/EndPage() calls, and
  91    * the returned DrawTarget should not be drawn to after EndPage() has been
  92    * called.
  93    *
  94    * XXX For consistency with the old code this takes a size parameter even
  95    * though we already have the size passed to our subclass's CreateOrNull
  96    * factory methods.  The size passed to the factory method comes from
  97    * nsIDeviceContextSpec::MakePrintTarget overrides, whereas the size
  98    * passed to us comes from nsDeviceContext::CreateRenderingContext.  In at
  99    * least one case (nsDeviceContextSpecAndroid::MakePrintTarget) these are
 100    * different.  At some point we should align the two sources and get rid of
 101    * this method's size parameter.
 102    *
 103    * XXX For consistency with the old code this returns a new DrawTarget for
 104    * each call.  Perhaps we can create and cache a DrawTarget in our subclass's
 105    * CreateOrNull factory methods and return that on each call?  Currently that
 106    * seems to cause Mochitest failures on Windows though, which coincidentally
 107    * is the only platform where we get passed an aRecorder.  Probably the
 108    * issue is that we get called more than once with a different aRecorder, so
 109    * storing one recording DrawTarget for our lifetime doesn't currently work.
 110    *
 111    * XXX Could we pass aRecorder to our subclass's CreateOrNull factory methods?
 112    * We'd need to check that our consumers always pass the same aRecorder for
 113    * our entire lifetime.
 114    *
 115    * XXX Once PrintTargetThebes is removed this can become non-virtual.
 116    *
 117    * XXX In the long run, this class and its sub-classes should be converted to
 118    * use STL classes and mozilla::RefCounted<> so the can be moved to Moz2D.
 119    *
 120    * TODO: Consider adding a SetDPI method that calls
 121    * cairo_surface_set_fallback_resolution.
 122    */
 123   virtual already_AddRefed<DrawTarget> MakeDrawTarget(
 124       const IntSize& aSize, DrawEventRecorder* aRecorder = nullptr);
 125
 126   /**
 127    * Returns a reference DrawTarget. Unlike MakeDrawTarget, this method is not
 128    * restricted to being called between BeginPage()/EndPage() calls, and the
 129    * returned DrawTarget is still valid to use after EndPage() has been called.
 130    */
 131   virtual already_AddRefed<DrawTarget> GetReferenceDrawTarget();
 132
 133   /**
 134    * If IsSyncPagePrinting returns true, then a user can assume the content of
 135    * a page was already printed after EndPage().
 136    * If IsSyncPagePrinting returns false, then a user should register a
 137    * callback function using RegisterPageDoneCallback to receive page print
 138    * done notifications.
 139    */
 140   virtual bool IsSyncPagePrinting() const { return true; }
 141   void RegisterPageDoneCallback(PageDoneCallback&& aCallback);
 142   void UnregisterPageDoneCallback();
 143
 144   static void AdjustPrintJobNameForIPP(const nsAString& aJobName,
 145                                        nsCString& aAdjustedJobName);
 146   static void AdjustPrintJobNameForIPP(const nsAString& aJobName,
 147                                        nsString& aAdjustedJobName);
 148
 149  protected:
 150   // Only created via subclass's constructors
 151   explicit PrintTarget(cairo_surface_t* aCairoSurface, const IntSize& aSize);
 152
 153   // Protected because we're refcounted
 154   virtual ~PrintTarget();
 155
 156   static already_AddRefed<DrawTarget> CreateRecordingDrawTarget(
 157       DrawEventRecorder* aRecorder, DrawTarget* aDrawTarget);
 158
 159   cairo_surface_t* mCairoSurface;
 160   RefPtr<DrawTarget> mRefDT;  // reference DT
 161
 162   IntSize mSize;
 163   bool mIsFinished;
 164 #ifdef DEBUG
 165   bool mHasActivePage;
 166 #endif
 167
 168   PageDoneCallback mPageDoneCallback;
 169 };
 170
 171 }  // namespace gfx
 172 }  // namespace mozilla
 173
 174 #endif /* MOZILLA_GFX_PRINTTARGET_H */