feat(document): deprecate the four drawing element types

CHANGELOG.md

@@ -16,6 +16,11 @@ The release run heads these entries with the version and opens a fresh
 
 ## Unreleased
 
+- The drawing elements `Rect`, `Line`, `Circle` and `CustomShape`, their
+  `ElementType` values and `Element::as_rect`/`as_line`/`as_circle`/
+  `as_custom_shape` are deprecated: they collapse into `Frame`, which gains a
+  shape kind. Mirrored in the JNI, Apple and Python bindings. Towards #773.
+
 - New `File::name()`: the file name on disk, the entry name inside an archive,
   or the name `File::from_memory(data, name)` was given. A named in-memory file
   gets the same name-derived type candidate a path does, so `notes.md` bytes

CMakeLists.txt

@@ -327,6 +327,8 @@ target_link_libraries(odr
 # types - so a consumer of those needs the same layout. `cpp_info.defines` in
 # conanfile.py is the same thing for the conan package.
 target_compile_definitions(odr INTERFACE PUGIXML_COMPACT)
+# Silences `ODR_DEPRECATED` for the library's own translation units.
+target_compile_definitions(odr PRIVATE ODR_INTERNAL_BUILD)
 
 if (ODR_WITH_HTTP_SERVER)
     find_package(httplib REQUIRED)

apple/CMakeLists.txt

@@ -68,6 +68,8 @@ add_library(odr_apple SHARED
 )
 target_include_directories(odr_apple PRIVATE "include" "src")
 target_link_libraries(odr_apple PRIVATE odr "-framework Foundation")
+# The bindings mirror the deprecated api, so `ODR_DEPRECATED` is off here too.
+target_compile_definitions(odr_apple PRIVATE ODR_INTERNAL_BUILD)
 target_compile_options(odr_apple PRIVATE -fobjc-arc)
 
 configure_file("Info.plist.in" "${CMAKE_CURRENT_BINARY_DIR}/Info.plist" @ONLY)

apple/include/OdrCoreObjC/ODRDocumentElement.h

@@ -42,10 +42,14 @@ typedef NS_ENUM(NSInteger, ODRElementType) {
 
   ODRElementTypeFrame,
   ODRElementTypeImage,
-  ODRElementTypeRect,
-  ODRElementTypeLine,
-  ODRElementTypeCircle,
-  ODRElementTypeCustomShape,
+  ODRElementTypeRect DEPRECATED_MSG_ATTRIBUTE(
+      "merging into ODRElementTypeFrame"),
+  ODRElementTypeLine DEPRECATED_MSG_ATTRIBUTE(
+      "merging into ODRElementTypeFrame"),
+  ODRElementTypeCircle DEPRECATED_MSG_ATTRIBUTE(
+      "merging into ODRElementTypeFrame"),
+  ODRElementTypeCustomShape DEPRECATED_MSG_ATTRIBUTE(
+      "merging into ODRElementTypeFrame"),
 
   ODRElementTypeGroup,
 } NS_SWIFT_NAME(ElementType);
@@ -293,6 +297,7 @@ NS_SWIFT_NAME(Frame)
 
 /// `odr::Rect`.
 NS_SWIFT_NAME(Rect)
+DEPRECATED_MSG_ATTRIBUTE("merging into ODRFrame")
 @interface ODRRect : ODRElement
 @property(nonatomic, readonly) ODRMeasure *x;
 @property(nonatomic, readonly) ODRMeasure *y;
@@ -304,6 +309,7 @@ NS_SWIFT_NAME(Rect)
 
 /// `odr::Line`.
 NS_SWIFT_NAME(Line)
+DEPRECATED_MSG_ATTRIBUTE("merging into ODRFrame")
 @interface ODRLine : ODRElement
 @property(nonatomic, readonly) ODRMeasure *x1;
 @property(nonatomic, readonly) ODRMeasure *y1;
@@ -315,6 +321,7 @@ NS_SWIFT_NAME(Line)
 
 /// `odr::Circle`.
 NS_SWIFT_NAME(Circle)
+DEPRECATED_MSG_ATTRIBUTE("merging into ODRFrame")
 @interface ODRCircle : ODRElement
 @property(nonatomic, readonly) ODRMeasure *x;
 @property(nonatomic, readonly) ODRMeasure *y;
@@ -326,6 +333,7 @@ NS_SWIFT_NAME(Circle)
 
 /// `odr::CustomShape`.
 NS_SWIFT_NAME(CustomShape)
+DEPRECATED_MSG_ATTRIBUTE("merging into ODRFrame")
 @interface ODRCustomShape : ODRElement
 @property(nonatomic, readonly, nullable) ODRMeasure *x;
 @property(nonatomic, readonly, nullable) ODRMeasure *y;

apple/src/ODRDocumentElement.mm

@@ -10,6 +10,9 @@
 
 #include <optional>
 
+// The mirror has to keep serving the api it deprecates.
+#pragma clang diagnostic ignored "-Wdeprecated-declarations"
+
 using odr::apple::box;
 using odr::apple::guarded;
 using odr::apple::guarded_value;

jni/CMakeLists.txt

@@ -50,6 +50,8 @@ if (NOT ANDROID)
     target_include_directories(odr_jni PRIVATE ${JNI_INCLUDE_DIRS})
 endif ()
 target_link_libraries(odr_jni PRIVATE ${ODR_JNI_ODR_TARGET})
+# The bindings mirror the deprecated api, so `ODR_DEPRECATED` is off here too.
+target_compile_definitions(odr_jni PRIVATE ODR_INTERNAL_BUILD)
 if (ODR_WITH_HTTP_SERVER)
     target_compile_definitions(odr_jni PRIVATE ODR_WITH_HTTP_SERVER)
 endif ()

jni/java/app/opendocument/core/Circle.java

@@ -1,6 +1,11 @@
 package app.opendocument.core;
 
-/** Circle element. Mirrors {@code odr::Circle}. */
+/**
+ * Circle element. Mirrors {@code odr::Circle}.
+ *
+ * @deprecated See {@link Rect}.
+ */
+@Deprecated
 public final class Circle extends Element {
   Circle(long handle, Object owner) {
     super(handle, owner);

jni/java/app/opendocument/core/CustomShape.java

@@ -1,6 +1,11 @@
 package app.opendocument.core;
 
-/** Custom shape element. Mirrors {@code odr::CustomShape}; x/y may be {@code null}. */
+/**
+ * Custom shape element. Mirrors {@code odr::CustomShape}; x/y may be {@code null}.
+ *
+ * @deprecated See {@link Rect}.
+ */
+@Deprecated
 public final class CustomShape extends Element {
   CustomShape(long handle, Object owner) {
     super(handle, owner);

jni/java/app/opendocument/core/Element.java

@@ -171,21 +171,37 @@ public Frame asFrame() {
     return h == 0 ? null : new Frame(h, owner());
   }
 
+  /**
+   * @deprecated Merging into {@link #asFrame()}.
+   */
+  @Deprecated
   public Rect asRect() {
     long h = asRectNative(handle());
     return h == 0 ? null : new Rect(h, owner());
   }
 
+  /**
+   * @deprecated See {@link #asRect()}.
+   */
+  @Deprecated
   public Line asLine() {
     long h = asLineNative(handle());
     return h == 0 ? null : new Line(h, owner());
   }
 
+  /**
+   * @deprecated See {@link #asRect()}.
+   */
+  @Deprecated
   public Circle asCircle() {
     long h = asCircleNative(handle());
     return h == 0 ? null : new Circle(h, owner());
   }
 
+  /**
+   * @deprecated See {@link #asRect()}.
+   */
+  @Deprecated
   public CustomShape asCustomShape() {
     long h = asCustomShapeNative(handle());
     return h == 0 ? null : new CustomShape(h, owner());

jni/java/app/opendocument/core/ElementType.java

@@ -2,10 +2,54 @@
 
 /** Mirrors {@code odr::ElementType}; constant order must match the C++ declaration. */
 public enum ElementType {
-  NONE, ROOT, SLIDE, SHEET, PAGE, MASTER_PAGE, SHEET_CELL, TEXT, LINE_BREAK,
-  PAGE_BREAK, PARAGRAPH, SPAN, LINK, BOOKMARK, LIST, LIST_ITEM, TABLE,
-  TABLE_COLUMN, TABLE_ROW, TABLE_CELL, FRAME, IMAGE, RECT, LINE, CIRCLE,
-  CUSTOM_SHAPE, GROUP;
+  NONE,
+  ROOT,
+  SLIDE,
+  SHEET,
+  PAGE,
+  MASTER_PAGE,
+  SHEET_CELL,
+  TEXT,
+  LINE_BREAK,
+  PAGE_BREAK,
+  PARAGRAPH,
+  SPAN,
+  LINK,
+  BOOKMARK,
+  LIST,
+  LIST_ITEM,
+  TABLE,
+  TABLE_COLUMN,
+  TABLE_ROW,
+  TABLE_CELL,
+  FRAME,
+  IMAGE,
+
+  /**
+   * @deprecated Merging into {@link #FRAME}, which gains a shape kind.
+   */
+  @Deprecated
+  RECT,
+
+  /**
+   * @deprecated See {@link #RECT}.
+   */
+  @Deprecated
+  LINE,
+
+  /**
+   * @deprecated See {@link #RECT}.
+   */
+  @Deprecated
+  CIRCLE,
+
+  /**
+   * @deprecated See {@link #RECT}.
+   */
+  @Deprecated
+  CUSTOM_SHAPE,
+
+  GROUP;
 
   static ElementType fromNative(int code) {
     return code < 0 ? null : values()[code];

jni/java/app/opendocument/core/Line.java

@@ -1,6 +1,11 @@
 package app.opendocument.core;
 
-/** Line element. Mirrors {@code odr::Line}. */
+/**
+ * Line element. Mirrors {@code odr::Line}.
+ *
+ * @deprecated See {@link Rect}.
+ */
+@Deprecated
 public final class Line extends Element {
   Line(long handle, Object owner) {
     super(handle, owner);

jni/java/app/opendocument/core/Rect.java

@@ -1,6 +1,11 @@
 package app.opendocument.core;
 
-/** Rectangle element. Mirrors {@code odr::Rect}. */
+/**
+ * Rectangle element. Mirrors {@code odr::Rect}.
+ *
+ * @deprecated Merging into {@link Frame}, which gains a shape kind.
+ */
+@Deprecated
 public final class Rect extends Element {
   Rect(long handle, Object owner) {
     super(handle, owner);

python/CMakeLists.txt

@@ -40,6 +40,8 @@ pybind11_add_module(pyodr_core
         "src/bind_style.cpp"
 )
 target_link_libraries(pyodr_core PRIVATE ${ODR_PYTHON_ODR_TARGET})
+# The bindings mirror the deprecated api, so `ODR_DEPRECATED` is off here too.
+target_compile_definitions(pyodr_core PRIVATE ODR_INTERNAL_BUILD)
 # The `$<1:...>` genex keeps multi-config generators from appending a
 # per-config subdirectory; the module must sit inside the `pyodr` package.
 set_target_properties(pyodr_core PROPERTIES

python/src/bind_document.cpp

@@ -35,10 +35,11 @@ py::object make_children_iterator(const odr::Element &element) {
 
 /// `__bool__` has to come from the derived type: `Element::operator bool`
 /// ignores the typed adapter, so a failed `as_*` cast would look valid.
-template <typename T>
-py::class_<T, odr::Element> bind_element(py::module_ &m, const char *name) {
-  return py::class_<T, odr::Element>(m, name).def("__bool__",
-                                                  &T::operator bool);
+template <typename T, typename... Extra>
+py::class_<T, odr::Element> bind_element(py::module_ &m, const char *name,
+                                         const Extra &...extra) {
+  return py::class_<T, odr::Element>(m, name, extra...)
+      .def("__bool__", &T::operator bool);
 }
 
 } // namespace
@@ -67,10 +68,14 @@ void odr_python::bind_document(py::module_ &m) {
       .value("table_cell", odr::ElementType::table_cell)
       .value("frame", odr::ElementType::frame)
       .value("image", odr::ElementType::image)
-      .value("rect", odr::ElementType::rect)
-      .value("line", odr::ElementType::line)
-      .value("circle", odr::ElementType::circle)
-      .value("custom_shape", odr::ElementType::custom_shape)
+      .value("rect", odr::ElementType::rect,
+             "Deprecated: merging into `frame`.")
+      .value("line", odr::ElementType::line,
+             "Deprecated: merging into `frame`.")
+      .value("circle", odr::ElementType::circle,
+             "Deprecated: merging into `frame`.")
+      .value("custom_shape", odr::ElementType::custom_shape,
+             "Deprecated: merging into `frame`.")
       .value("group", odr::ElementType::group);
 
   py::enum_<odr::AnchorType>(m, "AnchorType")
@@ -173,10 +178,14 @@ void odr_python::bind_document(py::module_ &m) {
       .def("as_table_row", &odr::Element::as_table_row, keep_self_alive)
       .def("as_table_cell", &odr::Element::as_table_cell, keep_self_alive)
       .def("as_frame", &odr::Element::as_frame, keep_self_alive)
-      .def("as_rect", &odr::Element::as_rect, keep_self_alive)
-      .def("as_line", &odr::Element::as_line, keep_self_alive)
-      .def("as_circle", &odr::Element::as_circle, keep_self_alive)
-      .def("as_custom_shape", &odr::Element::as_custom_shape, keep_self_alive)
+      .def("as_rect", &odr::Element::as_rect,
+           "Deprecated: merging into `as_frame`.", keep_self_alive)
+      .def("as_line", &odr::Element::as_line,
+           "Deprecated: merging into `as_frame`.", keep_self_alive)
+      .def("as_circle", &odr::Element::as_circle,
+           "Deprecated: merging into `as_frame`.", keep_self_alive)
+      .def("as_custom_shape", &odr::Element::as_custom_shape,
+           "Deprecated: merging into `as_frame`.", keep_self_alive)
       .def("as_image", &odr::Element::as_image, keep_self_alive);
 
   bind_element<odr::TextRoot>(m, "TextRoot")
@@ -304,31 +313,32 @@ void odr_python::bind_document(py::module_ &m) {
       .def("transform", &odr::Frame::transform)
       .def("style", &odr::Frame::style);
 
-  bind_element<odr::Rect>(m, "Rect")
+  bind_element<odr::Rect>(m, "Rect", "Deprecated: merging into `Frame`.")
       .def("x", &odr::Rect::x)
       .def("y", &odr::Rect::y)
       .def("width", &odr::Rect::width)
       .def("height", &odr::Rect::height)
       .def("transform", &odr::Rect::transform)
       .def("style", &odr::Rect::style);
 
-  bind_element<odr::Line>(m, "Line")
+  bind_element<odr::Line>(m, "Line", "Deprecated: merging into `Frame`.")
       .def("x1", &odr::Line::x1)
       .def("y1", &odr::Line::y1)
       .def("x2", &odr::Line::x2)
       .def("y2", &odr::Line::y2)
       .def("transform", &odr::Line::transform)
       .def("style", &odr::Line::style);
 
-  bind_element<odr::Circle>(m, "Circle")
+  bind_element<odr::Circle>(m, "Circle", "Deprecated: merging into `Frame`.")
       .def("x", &odr::Circle::x)
       .def("y", &odr::Circle::y)
       .def("width", &odr::Circle::width)
       .def("height", &odr::Circle::height)
       .def("transform", &odr::Circle::transform)
       .def("style", &odr::Circle::style);
 
-  bind_element<odr::CustomShape>(m, "CustomShape")
+  bind_element<odr::CustomShape>(m, "CustomShape",
+                                 "Deprecated: merging into `Frame`.")
       .def("x", &odr::CustomShape::x)
       .def("y", &odr::CustomShape::y)
       .def("width", &odr::CustomShape::width)

src/odr/definitions.hpp

@@ -2,6 +2,15 @@
 
 #include <cstdint>
 
+/// Marks a public declaration as deprecated. Expands to nothing inside the
+/// library and its own bindings, which have to keep serving what they
+/// deprecate.
+#ifdef ODR_INTERNAL_BUILD
+#define ODR_DEPRECATED(message)
+#else
+#define ODR_DEPRECATED(message) [[deprecated(message)]]
+#endif
+
 namespace odr {
 
 using ElementIdentifier = std::uint64_t;