zathura-plugin 0.4.0

Idiomatic wrapper around Zathura's Plugin interface
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

use {
    crate::{sys, DocumentRef},
    std::marker::PhantomData,
};

/// Reference to a page in a document.
///
/// This does not expose the `get/set_visibility` functions because they return
/// wildly inconsistent data between runs and even within the same Zathura
/// instance. Zathura only calls the render callback on visible pages, so this
/// API serves little purpose anyways.
#[derive(Debug)]
pub struct PageRef<'a> {
    ptr: *mut sys::zathura_page_t,
    _p: PhantomData<&'a mut ()>,
}

impl PageRef<'_> {
    /// Creates a page reference from a raw pointer.
    ///
    /// # Safety
    ///
    /// This method requires that `ptr` points to a valid `zathura_page_t`. The
    /// returned `PageRef` also has a dangling lifetime, which must be
    /// constrained by the caller so that it doesn't outlive the page or
    /// document.
    ///
    /// Only a single `PageRef` may be exist for the same page at any given
    /// time, since it is effectively a mutable reference. While a `PageRef`
    /// exists, no independent `DocumentRef`s to the document containing the
    /// page may exist.
    pub unsafe fn from_raw(ptr: *mut sys::zathura_page_t) -> Self {
        Self {
            ptr,
            _p: PhantomData,
        }
    }

    /// Obtains a reference to the Zathura document containing this page.
    ///
    /// The document reference is mutable, so it will borrow `self` until it
    /// goes out of scope.
    pub fn document<'a>(&'a mut self) -> DocumentRef<'a> {
        unsafe { DocumentRef::from_raw(sys::zathura_page_get_document(self.ptr)) }
    }

    /// Returns the index of this page in the document (zero-based).
    pub fn index(&self) -> usize {
        unsafe { sys::zathura_page_get_index(self.ptr) as usize }
    }

    /// Returns the width of this page in points.
    pub fn width(&self) -> f64 {
        unsafe { sys::zathura_page_get_width(self.ptr) }
    }

    /// Sets the width of this page.
    pub fn set_width(&mut self, width: f64) {
        unsafe { sys::zathura_page_set_width(self.ptr, width) }
    }

    /// Returns the height of this page in points.
    pub fn height(&self) -> f64 {
        unsafe { sys::zathura_page_get_height(self.ptr) }
    }

    /// Sets the height of this page.
    pub fn set_height(&mut self, height: f64) {
        unsafe { sys::zathura_page_set_height(self.ptr, height) }
    }

    /// Returns the plugin-controlled pointer associated with the document.
    ///
    /// This is mostly for internal use by this library and is usually unsafe
    /// to dereference.
    pub fn plugin_data(&self) -> *mut () {
        unsafe { sys::zathura_page_get_data(self.ptr) as *mut () }
    }

    /// Sets the custom plugin data pointer to `data`.
    ///
    /// # Safety
    ///
    /// This method is unsafe and should not be used by plugins. Instead, the
    /// `ZathuraPlugin` trait already provides an associated `PageData` type,
    /// which can be used instead.
    ///
    /// This library will assume that the plugin data is a
    /// `*mut Plugin::PageData` obtained from `Box::into_raw`, and frees the
    /// data automatically.
    pub unsafe fn set_plugin_data(&mut self, data: *mut ()) {
        sys::zathura_page_set_data(self.ptr, data as *mut _)
    }
}