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,no_run
35//! use std::path::Path;
36//! use winprint_ext::printer::FilePrinter;
37//! use winprint_ext::printer::PrinterDevice;
38//! use winprint_ext::printer::XpsPrinter;
39//!
40//! let my_device = PrinterDevice::all()
41//! .expect("Failed to get printers")
42//! .into_iter()
43//! .next()
44//! .expect("No printer found");
45//! let xps = XpsPrinter::new(my_device);
46//! let path = Path::new("path/to/test/document.xps");
47//! xps.print(path, Default::default()).unwrap();
48//! ```
49//!
50//! ## Specify the printing preferences
51//! Print ticket is a set of options that can be to specify the printing preferences,
52//! It can be used to set options such as the media size, orientation, and so on.
53//! If you want to specify the printing preferences, you may use print tickets.
54//!
55//! See [Print Schema Specification] for technical details.
56//!
57//! Here is an example presenting how to use print tickets with this crate:
58//! - Fetch print capabilities from the printer device.
59//! - Filter the capabilities you want to use.
60//! - Create a print ticket builder for your printer device.
61//! - Merge the capabilities into the print ticket you are to build.
62//! - Build the print ticket.
63//! - Print the file with the print ticket.
64//!
65//! ```rust,no_run
66//! use std::path::Path;
67//! use winprint_ext::printer::FilePrinter;
68//! use winprint_ext::printer::PrinterDevice;
69//! use winprint_ext::printer::XpsPrinter;
70//! use winprint_ext::ticket::FeatureOptionPackWithPredefined;
71//! use winprint_ext::ticket::PredefinedMediaName;
72//! use winprint_ext::ticket::PrintCapabilities;
73//! use winprint_ext::ticket::PrintTicket;
74//! use winprint_ext::ticket::PrintTicketBuilder;
75//!
76//! let my_device = PrinterDevice::all()
77//! .expect("Failed to get printers")
78//! .into_iter()
79//! .next()
80//! .expect("No printer found");
81//! let capabilities = PrintCapabilities::fetch(&my_device).unwrap();
82//! let a4_media = capabilities
83//! .page_media_sizes()
84//! .find(|x| x.as_predefined_name() == Some(PredefinedMediaName::ISOA4))
85//! .unwrap();
86//! let mut builder = PrintTicketBuilder::new(&my_device).unwrap();
87//! builder.merge(a4_media).unwrap();
88//! let ticket = builder.build().unwrap();
89//! let xps = XpsPrinter::new(my_device);
90//! let path = Path::new("path/to/test/document.xps");
91//! xps.print(path, ticket).unwrap();
92//! ```
93//!
94//! [Print Schema Specification]: https://learn.microsoft.com/en-us/windows/win32/printdocs/printschema
95//!
96//! # Features
97//! - `pdfium`: Enable PDFium support for printing PDF files.
98
99mod bindings;
100/// Provides a way to print various types of data to a printer device.
101pub mod printer;
102/// Utilities for testing
103pub mod test_utils;
104/// Provides a way to specify the printing preferences.
105pub mod ticket;
106mod utils;
107