From af8a468f3468d13ec297ebba1ddf80462c1096c6 Mon Sep 17 00:00:00 2001 From: "Jorj X. McKie" Date: Fri, 30 May 2025 08:10:18 -0400 Subject: [PATCH] Update widget.rst Clarify lifespan of widgets. --- docs/widget.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/widget.rst b/docs/widget.rst index b9b4be108..381c8c753 100644 --- a/docs/widget.rst +++ b/docs/widget.rst @@ -12,6 +12,8 @@ This class represents a PDF Form field, also called a "widget". Throughout this Like annotations, widgets live on PDF pages. Similar to annotations, the first widget on a page is accessible via :attr:`Page.first_widget` and subsequent widgets can be accessed via the :attr:`Widget.next` property. +Like annotations, widgets also lose connection to their page when the page becomes unavailable, please see `here `_ for details. This is relevant especially when updating the widget: this will fail if the original page object is no longer available. + *(Changed in version 1.16.0)* MuPDF no longer treats widgets as a subset of general annotations. Consequently, :attr:`Page.first_annot` and :meth:`Annot.next` will deliver **non-widget annotations exclusively**, and be ``None`` if only form fields exist on a page. Vice versa, :attr:`Page.first_widget` and :meth:`Widget.next` will only show widgets. This design decision is purely internal to MuPDF; technically, links, annotations and fields have a lot in common and also continue to share the better part of their code within (Py-) MuPDF.