winprint_ext/
lib.rs

1#![cfg(windows)]
2#![warn(missing_docs)]
3
4//! A crate for printing to a Windows printer device using Windows API.
5//!
6//! # Examples
7//! ## Print a file
8//! For a simple example presenting how to print a file:
9//! - Filter for the device you want to use.
10//! - Wrap the printer device with a printer.
11//! - Send a file to the printer.
12//!
13//! First, get all printer devices via `PrinterDevice::all()` and filter for the device you want to use.
14//!
15//! ```rust
16//! use winprint_ext::printer::PrinterDevice;
17//!
18//! fn get_my_device() -> PrinterDevice {
19//!     let printers = PrinterDevice::all().expect("Failed to get printers");
20//!     printers
21//!         .into_iter()
22//!         .find(|x| x.name() == "My Printer")
23//!         .expect("My Printer not found")
24//! }
25//! ```
26//!
27//! Then, create a printer and send a file to it. Currently, there are two kinds of printers available:
28//! - [`printer::XpsPrinter`]: For printing XPS files.
29//! - [`printer::PdfiumPrinter`]: For printing PDF files via PDFium library. (Feature `pdfium` must be enabled)
30//!
31//! **Note**: The concept *`Printer`* here is a warpper of device for printing specific types of data,
32//! not meaning the printer device.
33//!
34//! ```rust
35//! use std::path::Path;
36//! use winprint_ext::printer::FilePrinter;
37//! use winprint_ext::printer::PrinterDevice;
38//! use winprint_ext::printer::XpsPrinter;
39//! # use winprint_ext::test_utils::null_device::thread_local as get_my_device;
40//!
41//! let my_device = get_my_device();
42//! let xps = XpsPrinter::new(my_device);
43//! let path = Path::new("path/to/test/document.xps");
44//! # let path_buf = Path::new(env!("CARGO_MANIFEST_DIR")).join("test_data/test_document.xps");
45//! # let path = path_buf.as_path();
46//! xps.print(path, Default::default()).unwrap();
47//! ```
48//!
49//! ## Specify the printing preferences
50//! Print ticket is a set of options that can be to specify the printing preferences,
51//! It can be used to set options such as the media size, orientation, and so on.
52//! If you want to specify the printing preferences, you may use print tickets.
53//!
54//! See [Print Schema Specification] for technical details.
55//!
56//! Here is an example presenting how to use print tickets with this crate:
57//! - Fetch print capabilities from the printer device.
58//! - Filter the capabilities you want to use.
59//! - Create a print ticket builder for your printer device.
60//! - Merge the capabilities into the print ticket you are to build.
61//! - Build the print ticket.
62//! - Print the file with the print ticket.
63//!
64//! ```rust
65//! use std::path::Path;
66//! use winprint_ext::printer::FilePrinter;
67//! use winprint_ext::printer::PrinterDevice;
68//! use winprint_ext::printer::XpsPrinter;
69//! use winprint_ext::ticket::FeatureOptionPackWithPredefined;
70//! use winprint_ext::ticket::PredefinedMediaName;
71//! use winprint_ext::ticket::PrintCapabilities;
72//! use winprint_ext::ticket::PrintTicket;
73//! use winprint_ext::ticket::PrintTicketBuilder;
74//! # use winprint_ext::test_utils::null_device::thread_local as get_my_device;
75//!
76//! let my_device = get_my_device();
77//! let capabilities = PrintCapabilities::fetch(&my_device).unwrap();
78//! let a4_media = capabilities
79//!     .page_media_sizes()
80//!     .find(|x| x.as_predefined_name() == Some(PredefinedMediaName::ISOA4))
81//!     .unwrap();
82//! let mut builder = PrintTicketBuilder::new(&my_device).unwrap();
83//! builder.merge(a4_media).unwrap();
84//! let ticket = builder.build().unwrap();
85//! let xps = XpsPrinter::new(my_device);
86//! let path = Path::new("path/to/test/document.xps");
87//! # let path_buf = Path::new(env!("CARGO_MANIFEST_DIR")).join("test_data/test_document.xps");
88//! # let path = path_buf.as_path();
89//! xps.print(path, ticket).unwrap();
90//! ```
91//!
92//! [Print Schema Specification]: https://learn.microsoft.com/en-us/windows/win32/printdocs/printschema
93//!
94//! # Features
95//! - `pdfium`: Enable PDFium support for printing PDF files.
96
97mod bindings;
98/// Provides a way to print various types of data to a printer device.
99pub mod printer;
100/// Utilities for testing
101pub mod test_utils;
102/// Provides a way to specify the printing preferences.
103pub mod ticket;
104mod utils;
105#[cfg(test)]
106mod tests {
107    use ctor::ctor;
108
109    #[ctor]
110    fn setup() {
111        env_logger::init();
112    }
113}
114
winprint_ext/lib.rs

winprint_ext/
lib.rs
