glib: add new api to allow selecting annotations to render

This allows consumers to redraw some annotations as desired. In the
process, deprecate the render_printing_with_options, since it becomes
obsolete.

4 files changed, 141 insertions, 43 deletions

diff --git a/glib/poppler-page.cc b/glib/poppler-page.cc
index a9c34957..3e56a086 100644
--- a/glib/poppler-page.cc
+++ b/glib/poppler-page.cc
@@ -271,45 +271,41 @@ static TextPage *poppler_page_get_text_page(PopplerPage *page)
     return page->text;
 }
 
-static gboolean annot_is_markup(Annot *annot)
-{
-    switch (annot->getType()) {
-    case Annot::typeLink:
-    case Annot::typePopup:
-    case Annot::typeMovie:
-    case Annot::typeScreen:
-    case Annot::typePrinterMark:
-    case Annot::typeTrapNet:
-    case Annot::typeWatermark:
-    case Annot::type3D:
-    case Annot::typeWidget:
-        return FALSE;
-    default:
-        return TRUE;
-    }
-}
-
-static bool poppler_print_annot_cb(Annot *annot, void *user_data)
+static bool annots_display_decide_cb(Annot *annot, void *user_data)
 {
-    PopplerPrintFlags user_print_flags = (PopplerPrintFlags)GPOINTER_TO_INT(user_data);
-
-    if (user_print_flags & POPPLER_PRINT_STAMP_ANNOTS_ONLY && (annot->getType() == Annot::typeStamp)) {
-        return true;
-    }
+    PopplerRenderAnnotsFlags flags = (PopplerRenderAnnotsFlags)GPOINTER_TO_UINT(user_data);
+    Annot::AnnotSubtype type = annot->getType();
+    int typeMask = 1 << MAX(0, (((int)type) - 1));
 
-    if (user_print_flags & POPPLER_PRINT_MARKUP_ANNOTS && annot_is_markup(annot)) {
+    if (flags & typeMask) {
         return true;
     }
-
-    /* Form fields are always printed */
-    return (annot->getType() == Annot::typeWidget);
+    return false;
 }
 
-static void _poppler_page_render(PopplerPage *page, cairo_t *cairo, bool printing, PopplerPrintFlags print_flags)
+/**
+ * poppler_page_render_full:
+ * @page: the page to render from
+ * @cairo: cairo context to render to
+ * @printing: cairo context to render to
+ * @flags: flags which allow to select which annotations to render
+ *
+ * Render the page to the given cairo context, manually selecting which
+ * annotations should be displayed.
+ *
+ * The @printing parameter determines whether a page is rendered for printing
+ * or for displaying it on a screen. See the documentation for
+ * poppler_page_render_for_printing() for the differences between rendering to
+ * the screen and rendering to a printer.
+ *
+ * Since: 25.02
+ **/
+void poppler_page_render_full(PopplerPage *page, cairo_t *cairo, gboolean printing, PopplerRenderAnnotsFlags flags)
 {
     CairoOutputDev *output_dev;
 
     g_return_if_fail(POPPLER_IS_PAGE(page));
+    g_return_if_fail(cairo != nullptr);
 
     output_dev = page->document->output_dev;
     output_dev->setCairo(cairo);
@@ -319,12 +315,13 @@ static void _poppler_page_render(PopplerPage *page, cairo_t *cairo, bool printin
         page->text = new TextPage(false);
         output_dev->setTextPage(page->text);
     }
-    /* NOTE: instead of passing -1 we should/could use cairo_clip_extents()
-     * to get a bounding box */
+
     cairo_save(cairo);
     page->page->displaySlice(output_dev, 72.0, 72.0, 0, false, /* useMediaBox */
                              true, /* Crop */
-                             -1, -1, -1, -1, printing, nullptr, nullptr, printing ? poppler_print_annot_cb : nullptr, printing ? GINT_TO_POINTER((gint)print_flags) : nullptr);
+                             -1, -1, -1, -1, /* instead of passing -1 we could use cairo_clip_extents() to get a bounding box */
+
+                             printing, nullptr, nullptr, annots_display_decide_cb, GUINT_TO_POINTER((guint)flags));
     cairo_restore(cairo);
 
     output_dev->setCairo(nullptr);
@@ -345,9 +342,7 @@ static void _poppler_page_render(PopplerPage *page, cairo_t *cairo, bool printin
  **/
 void poppler_page_render(PopplerPage *page, cairo_t *cairo)
 {
-    g_return_if_fail(POPPLER_IS_PAGE(page));
-
-    _poppler_page_render(page, cairo, false, (PopplerPrintFlags)0);
+    poppler_page_render_full(page, cairo, false, POPPLER_RENDER_ANNOTS_ALL);
 }
 
 /**
@@ -363,13 +358,24 @@ void poppler_page_render(PopplerPage *page, cairo_t *cairo)
  * differences between rendering to the screen and rendering to a printer.
  *
  * Since: 0.16
+ *
+ * Deprecated: 25.02: Use poppler_page_render_full() instead.
  **/
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 void poppler_page_render_for_printing_with_options(PopplerPage *page, cairo_t *cairo, PopplerPrintFlags options)
 {
-    g_return_if_fail(POPPLER_IS_PAGE(page));
+    int flags = (int)POPPLER_RENDER_ANNOTS_PRINT_DOCUMENT;
+
+    if (options & POPPLER_PRINT_STAMP_ANNOTS_ONLY) {
+        flags |= POPPLER_RENDER_ANNOTS_PRINT_STAMP;
+    }
+    if (options & POPPLER_PRINT_MARKUP_ANNOTS) {
+        flags |= POPPLER_RENDER_ANNOTS_PRINT_MARKUP;
+    }
 
-    _poppler_page_render(page, cairo, true, options);
+    poppler_page_render_full(page, cairo, true, (PopplerRenderAnnotsFlags)flags);
 }
+G_GNUC_END_IGNORE_DEPRECATIONS
 
 /**
  * poppler_page_render_for_printing:
@@ -378,7 +384,8 @@ void poppler_page_render_for_printing_with_options(PopplerPage *page, cairo_t *c
  *
  * Render the page to the given cairo context for printing with
  * #POPPLER_PRINT_ALL flags selected.  If you want a different set of flags,
- * use poppler_page_render_for_printing_with_options().
+ * use poppler_page_render_full() with printing #TRUE and the corresponding
+ * flags.
  *
  * The difference between poppler_page_render() and this function is that some
  * things get rendered differently between screens and printers:
@@ -409,9 +416,7 @@ void poppler_page_render_for_printing_with_options(PopplerPage *page, cairo_t *c
  **/
 void poppler_page_render_for_printing(PopplerPage *page, cairo_t *cairo)
 {
-    g_return_if_fail(POPPLER_IS_PAGE(page));
-
-    _poppler_page_render(page, cairo, true, POPPLER_PRINT_ALL);
+    poppler_page_render_full(page, cairo, true, POPPLER_RENDER_ANNOTS_PRINT_ALL);
 }
 
 static cairo_surface_t *create_surface_from_thumbnail_data(guchar *data, gint width, gint height, gint rowstride)
diff --git a/glib/poppler-page.h b/glib/poppler-page.h
index de4896f7..d6872bdd 100644
--- a/glib/poppler-page.h
+++ b/glib/poppler-page.h
@@ -37,9 +37,13 @@ GType poppler_page_get_type(void) G_GNUC_CONST;
 POPPLER_PUBLIC
 void poppler_page_render(PopplerPage *page, cairo_t *cairo);
 POPPLER_PUBLIC
+void poppler_page_render_full(PopplerPage *page, cairo_t *cairo, gboolean printing, PopplerRenderAnnotsFlags flags);
+POPPLER_PUBLIC
 void poppler_page_render_for_printing(PopplerPage *page, cairo_t *cairo);
+G_GNUC_BEGIN_IGNORE_DEPRECATIONS
 POPPLER_PUBLIC
-void poppler_page_render_for_printing_with_options(PopplerPage *page, cairo_t *cairo, PopplerPrintFlags options);
+void poppler_page_render_for_printing_with_options(PopplerPage *page, cairo_t *cairo, PopplerPrintFlags options) G_GNUC_DEPRECATED_FOR(poppler_page_render_full);
+G_GNUC_END_IGNORE_DEPRECATIONS
 POPPLER_PUBLIC
 cairo_surface_t *poppler_page_get_thumbnail(PopplerPage *page);
 POPPLER_PUBLIC
diff --git a/glib/poppler.h b/glib/poppler.h
index 435e28c5..ed5edccd 100644
--- a/glib/poppler.h
+++ b/glib/poppler.h
@@ -132,6 +132,91 @@ typedef enum
 } PopplerSelectionStyle;
 
 /**
+ * PopplerRenderFlags:
+ * @POPPLER_RENDER_ANNOTS_NONE: do not render annotations
+ * @POPPLER_RENDER_ANNOTS_TEXT: render text annotations
+ * @POPPLER_RENDER_ANNOTS_LINK: render link annotations
+ * @POPPLER_RENDER_ANNOTS_FREETEXT: render freetext annotations,
+ * @POPPLER_RENDER_ANNOTS_LINE: render line annotations,
+ * @POPPLER_RENDER_ANNOTS_SQUARE: render square annotations,
+ * @POPPLER_RENDER_ANNOTS_CIRCLE: render circle annotations,
+ * @POPPLER_RENDER_ANNOTS_POLYGON: render polygon annotations,
+ * @POPPLER_RENDER_ANNOTS_POLYLINE: render polyline annotations,
+ * @POPPLER_RENDER_ANNOTS_HIGHLIGHT: render highlight annotations,
+ * @POPPLER_RENDER_ANNOTS_UNDERLINE: render underline annotations,
+ * @POPPLER_RENDER_ANNOTS_SQUIGGLY: render squiggly annotations,
+ * @POPPLER_RENDER_ANNOTS_STRIKEOUT: render strikeout annotations,
+ * @POPPLER_RENDER_ANNOTS_STAMP: render stamp annotations,
+ * @POPPLER_RENDER_ANNOTS_CARET: render caret annotations,
+ * @POPPLER_RENDER_ANNOTS_INK: render ink annotations,
+ * @POPPLER_RENDER_ANNOTS_POPUP: render popup annotations,
+ * @POPPLER_RENDER_ANNOTS_FILEATTACHMENT: render fileattachment annotations,
+ * @POPPLER_RENDER_ANNOTS_SOUND: render sound annotations,
+ * @POPPLER_RENDER_ANNOTS_MOVIE: render movie annotations,
+ * @POPPLER_RENDER_ANNOTS_WIDGET: render widget annotations,
+ * @POPPLER_RENDER_ANNOTS_SCREEN: render screen annotations,
+ * @POPPLER_RENDER_ANNOTS_PRINTERMARK: render printermark annotations,
+ * @POPPLER_RENDER_ANNOTS_TRAPNET: render trapnet annotations,
+ * @POPPLER_RENDER_ANNOTS_WATERMARK: render watermark annotations,
+ * @POPPLER_RENDER_ANNOTS_3D: render 3D annotations,
+ * @POPPLER_RENDER_ANNOTS_RICHMEDIA: render richmedia annotations,
+ * @POPPLER_RENDER_ANNOTS_PRINT_DOCUMENT: render the default annotations used for printing
+ * @POPPLER_RENDER_ANNOTS_PRINT_MARKUP: render markup annotations and default annotations used for printing
+ * @POPPLER_RENDER_ANNOTS_PRINT_STAMP: render stamp annotations and default annotations used for printing
+ * @POPPLER_RENDER_ANNOTS_PRINT_ALL: render all possible annotations used for printing
+ * @POPPLER_RENDER_ANNOTS_ALL: render all annotations
+ *
+ * Flags to select which annotations to render. If the flag corresponding to a
+ * certain annotation type is on, then such annotation type will be rendered,
+ * when appropriate (e.g: won't be renderer if the annotation is not visible).
+ * This allows to combine multiple flags, like
+ * `POPPLER_RENDER_ANNOTS_LINK | POPPLER_RENDER_ANNOTS_TEXT`, or disable some
+ * specific annotations like
+ * `POPPLER_RENDER_ANNOTS_ALL & (~POPPLER_RENDER_ANNOTS_TEXT)`
+ *
+ * Since: 25.02
+ */
+typedef enum /*< flags >*/
+{
+    POPPLER_RENDER_ANNOTS_NONE = 0,
+    POPPLER_RENDER_ANNOTS_TEXT = 1 << 0,
+    POPPLER_RENDER_ANNOTS_LINK = 1 << 1,
+    POPPLER_RENDER_ANNOTS_FREETEXT = 1 << 2,
+    POPPLER_RENDER_ANNOTS_LINE = 1 << 3,
+    POPPLER_RENDER_ANNOTS_SQUARE = 1 << 4,
+    POPPLER_RENDER_ANNOTS_CIRCLE = 1 << 5,
+    POPPLER_RENDER_ANNOTS_POLYGON = 1 << 6,
+    POPPLER_RENDER_ANNOTS_POLYLINE = 1 << 7,
+    POPPLER_RENDER_ANNOTS_HIGHLIGHT = 1 << 8,
+    POPPLER_RENDER_ANNOTS_UNDERLINE = 1 << 9,
+    POPPLER_RENDER_ANNOTS_SQUIGGLY = 1 << 10,
+    POPPLER_RENDER_ANNOTS_STRIKEOUT = 1 << 11,
+    POPPLER_RENDER_ANNOTS_STAMP = 1 << 12,
+    POPPLER_RENDER_ANNOTS_CARET = 1 << 13,
+    POPPLER_RENDER_ANNOTS_INK = 1 << 14,
+    POPPLER_RENDER_ANNOTS_POPUP = 1 << 15,
+    POPPLER_RENDER_ANNOTS_FILEATTACHMENT = 1 << 16,
+    POPPLER_RENDER_ANNOTS_SOUND = 1 << 17,
+    POPPLER_RENDER_ANNOTS_MOVIE = 1 << 18,
+    POPPLER_RENDER_ANNOTS_WIDGET = 1 << 19,
+    POPPLER_RENDER_ANNOTS_SCREEN = 1 << 20,
+    POPPLER_RENDER_ANNOTS_PRINTERMARK = 1 << 21,
+    POPPLER_RENDER_ANNOTS_TRAPNET = 1 << 22,
+    POPPLER_RENDER_ANNOTS_WATERMARK = 1 << 23,
+    POPPLER_RENDER_ANNOTS_3D = 1 << 24,
+    POPPLER_RENDER_ANNOTS_RICHMEDIA = 1 << 25,
+
+    /* Everything below are special flags to combine them all */
+    POPPLER_RENDER_ANNOTS_PRINT_DOCUMENT = POPPLER_RENDER_ANNOTS_WIDGET,
+    POPPLER_RENDER_ANNOTS_PRINT_MARKUP = ~(POPPLER_RENDER_ANNOTS_LINK | POPPLER_RENDER_ANNOTS_POPUP | POPPLER_RENDER_ANNOTS_MOVIE | POPPLER_RENDER_ANNOTS_SCREEN | POPPLER_RENDER_ANNOTS_PRINTERMARK | POPPLER_RENDER_ANNOTS_TRAPNET
+                                           | POPPLER_RENDER_ANNOTS_WATERMARK | POPPLER_RENDER_ANNOTS_3D),
+    POPPLER_RENDER_ANNOTS_PRINT_STAMP = POPPLER_RENDER_ANNOTS_WIDGET | POPPLER_RENDER_ANNOTS_STAMP,
+    POPPLER_RENDER_ANNOTS_PRINT_ALL = POPPLER_RENDER_ANNOTS_PRINT_MARKUP,
+    /* Enable all flags, by shifting and substracting the last one */
+    POPPLER_RENDER_ANNOTS_ALL = (POPPLER_RENDER_ANNOTS_RICHMEDIA << 1) - 1
+} PopplerRenderAnnotsFlags;
+
+/**
  * PopplerPrintFlags:
  * @POPPLER_PRINT_DOCUMENT: print main document contents
  * @POPPLER_PRINT_MARKUP_ANNOTS: print document and markup annotations
@@ -140,6 +225,9 @@ typedef enum
  *
  * Printing flags
  *
+ * Deprecated: 25.02: Use poppler_page_render_full() and
+ * #PopplerRenderAnnotsFlags instead.
+ *
  * Since: 0.16
  */
 typedef enum /*< flags >*/
@@ -148,7 +236,7 @@ typedef enum /*< flags >*/
     POPPLER_PRINT_MARKUP_ANNOTS = 1 << 0,
     POPPLER_PRINT_STAMP_ANNOTS_ONLY = 1 << 1,
     POPPLER_PRINT_ALL = POPPLER_PRINT_MARKUP_ANNOTS
-} PopplerPrintFlags;
+} PopplerPrintFlags G_GNUC_DEPRECATED_FOR(PopplerRenderAnnotsFlags);
 
 /**
  * PopplerFindFlags:
diff --git a/glib/reference/poppler-sections.txt b/glib/reference/poppler-sections.txt
index 95e6426e..86f7e361 100644
--- a/glib/reference/poppler-sections.txt
+++ b/glib/reference/poppler-sections.txt
@@ -77,6 +77,7 @@ poppler_page_get_thumbnail_size
 poppler_page_get_transition
 poppler_page_remove_annot
 poppler_page_render
+poppler_page_render_full
 poppler_page_render_for_printing
 poppler_page_render_for_printing_with_options
 poppler_page_render_selection