diff --git a/src/types.jl b/src/types.jl index cd4afed..4e19c6b 100644 --- a/src/types.jl +++ b/src/types.jl @@ -63,6 +63,7 @@ for more. `AbstractCachedDocument`s must implement the [`AbstractDocument`](@ref) API, as well as the following: - `rasterize(doc::AbstractCachedDocument, [scale::Real = 1])::Matrix{ARGB32}` - `draw_to_cairo_surface(doc::AbstractCachedDocument, surf::CairoSurface)` +- `update_handle!(doc::AbstractCachedDocument)::` """ abstract type AbstractCachedDocument <: AbstractDocument end @@ -83,9 +84,49 @@ calls the appropriate rendering function for the document type. """ function draw_to_cairo_surface end +""" + update_handle!(doc::AbstractCachedDocument) + +Update the internal handle/pointer to the loaded document in a `CachedDocument`, and returns it. + +This function is used to refresh the handle/pointer to the loaded document in case it has been +garbage collected or invalidated. It should return the updated handle/pointer. + +For example, in `CachedPDF`, this function would reload the PDF document using the `doc.doc` field +and update the `ptr` field with the new Poppler handle, **if it is found to be invalid**. + +Note that this function needs to be implemented for each concrete subtype of `AbstractCachedDocument`, +as the handle/pointer type and the method to load/update it will be different for different document +types (e.g., PDF, SVG, etc.). +""" +function update_handle! end + +#= + +## Generic dispatches for documents + +Define generic functions for all AbstractDocuments, with special emphasis on Makie +compatibility and conversions. + +### Generic dispatches + +=# -# Define Makie conversion functions which keep these types in the pipeline. -# The backend-specific functions and rasterizers are kept in the backends' extensions. +Base.convert(::Type{String}, doc::AbstractDocument) = Base.convert(String, getdoc(doc)) +Base.convert(::Type{UInt8}, doc::AbstractDocument) = Vector{UInt8}(Base.convert(String, doc)) + +Base.convert(::Type{Matrix{T}}, doc::AbstractDocument) where T <: Colors.Color = T.(Base.convert(Matrix{ARGB32}, doc)) +Base.convert(::Type{Matrix{ARGB32}}, doc::AbstractDocument) = Base.convert(Matrix{ARGB32}, Cached(doc)) +Base.convert(::Type{Matrix{ARGB32}}, cached::AbstractCachedDocument) = rasterize(doc) + + +#= + +### Makie.jl function definitions +The backend-specific functions and rasterizers are kept in the backends' extensions. + +These functions are generic to the Makie API. +=# Makie.convert_attribute(x::AbstractCachedDocument, ::Makie.key"marker") = x Makie.convert_attribute(x::AbstractCachedDocument, ::Makie.key"marker", ::Makie.key"scatter") = x Makie.to_spritemarker(x::AbstractCachedDocument) = x @@ -97,7 +138,11 @@ Makie.convert_attribute(x::AbstractDocument, ::Makie.key"marker", ::Makie.key"sc Makie.to_spritemarker(x::AbstractDocument) = Cached(x) # this should never be called #= +## Concrete type definitions + Now, we define the structs which hold the documents and their cached versions. + +### Raw documents =# """ @@ -115,7 +160,7 @@ getdoc(doc::SVGDocument) = doc.doc mimetype(::SVGDocument) = MIME"image/svg+xml"() """ - PDFDocument(pdf::AbstractString) + PDFDocument(pdf::AbstractString, [page = 0]) A document type which holds a raw PDF as a string. @@ -146,16 +191,18 @@ Cached(x::EPSDocument) = CachedPDF(x) getdoc(doc::EPSDocument) = doc.doc mimetype(::EPSDocument) = MIME"application/postscript"() - -struct TeXDocument <: AbstractDocument +# This will be documented elsewhere in the package. +struct TEXDocument <: AbstractDocument contents::String page::Int end -TeXDocument(contents) = TeXDocument(contents, 0) -Cached(x::TeXDocument) = CachedTeX(x) -getdoc(doc::TeXDocument) = doc.doc -mimetype(::TeXDocument) = MIME"application/x-tex"() +TEXDocument(contents) = TEXDocument(contents, 0) +Cached(x::TEXDocument) = CachedTeX(x) +getdoc(doc::TEXDocument) = doc.doc +mimetype(::TEXDocument) = MIME"application/x-tex"() +const TeXDocument = TEXDocument +Base.@deprecate TeXDocument TEXDocument # To keep consistency, we deprecate the TeX in favour of TEX. This will require a large refactor everywhere, but should be worth it. """ TeXDocument(contents::AbstractString, add_defaults::Bool; requires, preamble, class, classoptions) @@ -222,9 +269,7 @@ Available keyword arguments are: """ texdoc(contents; kwargs...) = TeXDocument(contents, true; kwargs...) -function Base.convert(::Type{String}, doc::TeXDocument) - return Base.convert(String, doc.contents) -end + mutable struct CachedTeX <: AbstractCachedDocument "The original `TeXDocument` which is compiled."