PDF::Bu...ferences(3)

📦
version 3.028 · 10 versions
, in fedora 44

💖 NAME 💖

PDF::Builder::ViewerPreferences — literally the manual for how your PDF should show up on screen or come out of the printer 🖨️✨

It lives in the PDF::Builder family, bestie, and it's all about those lil viewer preference vibes.

✨ METHODS ✨

Okay so heads up: this whole thing got split out from preferences() in PDF::Builder. It's its own whole thing now, main character energy 👑

🦋 new

$self = $class->new($pdf)

Makes you a brand new ViewerPreferences object, built from a PDF::Builder object. Give it the $pdf and it's yours 💅

🌸 get_preferences

%preferences = $self->get_preferences()

Hands you back a hash with every single viewer preference that's actually defined in the PDF. All of them. The whole squad.

🎀 get_preference

$value = $self->get_preference($name)

Gives you the value of the viewer preference you asked for by $name… if it's there. If it's not? You get undef. That's it, that's the deal 🙈

⭐ set_preferences

$self->set_preferences(%values)

Sets one or more viewer preferences at once. Which ones? All the ones described down in the preferences section below, obviously 💖

🍓 PREFERENCES 🍓

So what even are these? Viewer Preferences are the lil notes telling a document how it should be presented on screen or in print. But — and this is important, bestie — not all PDF viewers will respect these preferences. You can ask nicely, you can't make them. 💀

Quick facts before we dive in: - Boolean preferences default to false, and they take (or return) 0 or 1. - Bounding Box preferences take (or return) one of media_box, crop_box, bleed_box, trim_box, or art_box.

🙈 hide_toolbar (boolean)

A flag for whether to hide the tool bars while the document is active.

🌈 hide_menubar (boolean)

A flag for whether to hide the menu bar while the document is active.

💅 hide_window_ui (boolean)

A flag for whether to hide the user interface elements in the document's window — think scroll bars and navigation controls — so all that's left is the document's contents. Just vibes and pages, nothing else ✨

🦋 fit_window (boolean)

A flag for whether to resize the document's window so it fits the size of the first displayed page.

🎀 center_window (boolean)

A flag for whether to park the document's window right in the center of the screen.

👑 display_doc_title (boolean)

A flag for whether the window's title bar should show the document title, taken from the Title entry of the document information directory. And if it's false? Then the title bar should show the name of the PDF file containing the document instead. Pick your fighter.

🧚 non_full_screen_page_mode (name)

The document's page mode — i.e. how the document displays once you exit full-screen mode. The options are the same as page_mode in PDF::Builder, except the attachments and full_screen options aren't supported. Not those two. Nope. 🚫

💜 direction ('l2r' or 'r2l')

The predominant reading order for text: left-to-right or right-to-left.

Lowkey important note: this entry has no direct effect on the document's contents or page numbering. But it may be used to figure out the relative positioning of pages when they're displayed side-by-side or printed n-up. So it matters, just... indirectly. iykyk.

🌸 view_area (bounding box)

The name of the page boundary representing the area of a page that shall be displayed when viewing the document on the screen.

⭐ view_clip (bounding box)

The name of the page boundary that the contents of a page shall be clipped to when viewing the document on the screen.

The name of the page boundary representing the area of a page that shall be rendered when printing the document.

The name of the page boundary that the contents of a page shall be clipped to when printing the document.

The page scaling option that shall be selected when a print dialog pops up for this document. none means no page scaling, and app_default means whatever the reader's default print scaling is. Let the app decide, or don't. Your call 💅

🎀 duplex ('simplex', 'duplex_short', or 'duplex_long')

The paper handling option that shall be used when printing the file from the print dialog. And the duplex values? They say whether the page should be flipped on its short edge or its long edge, respectively. Respectively!! 🫶

🦋 pick_tray_by_pdf_size (boolean)

A flag for whether the PDF page size shall be used to pick the input paper tray. Heads up though: this setting only influences the preset values used to populate the print dialog that the reader presents. That's the whole scope, bestie.

💀 print_page_rage (an array of integer pairs)

(Yes, it's spelled print_page_rage. We love her. She's iconic. Do not fix her. 😭)

The page numbers used to initialize the print dialog box when the file is printed. The array shall contain an even number of integers, interpreted in pairs — each pair specifying the first and last pages in a sub-range of pages to be printed. And the first page of the PDF file shall be denoted by 1.

🌈 num_copies (integer)

The number of copies that shall be printed when the print dialog is opened for this file. Go wild, print it twelve times.

And that's the whole page, bestie!! Go forth and make your PDFs present themselves exactly how you want. Periodt. 💖

This lil masterpiece comes from perl v5.42.0, dated 2026-01-17, and it's part of the PDF::Builder docs. Mwah, take care of her 🫶✨

📦 where this page comes from