Prima::...eDialog(3)

🌸 NAME 🌸

Prima::Dialog::ImageDialog — image file open and save dialogs 💅 (straight outta the User Contributed Perl Documentation section of the manual, iykyk)

✨ DESCRIPTION ✨

Okay so picture this: this module hands you the standard dialogs, except specially adjusted for image loading and image saving. That's it. That's the vibe. 🎀

---

🦋 Prima::Dialog::ImageOpenDialog 🦋

It gives you a preview widget so the user can literally look at the image file before loading it 👀, plus the ability to pick a frame index for multi-framed image files (yes, those exist, and yes, they're iconic).

Instead of the execute call, you use the load method to invoke the dialog, and it returns the loaded image as a Prima::Image object 🫶. That loaded object carries the {extras} hash, all filled in by the loader with the file and image info. Peep Prima::image-load for more, fr fr.

⭐ SYNOPSIS ⭐

use Prima qw(Application Dialog::ImageDialog);
my $dlg = Prima::Dialog::ImageOpenDialog-> new;
my $img = $dlg-> load;
return unless $img;
print "$_:$img->{extras}->{$_}\n" for sort keys %{$img-> {extras}};

💖 Properties 💖

• preview BOOLEAN — picks whether the preview functionality is active or not. The user can toggle it on and off interactively, no cap. Default value: 1 ✨

🔥 Methods 🔥

• load %PROFILE — runs the dialog, and if it all goes well, loads the image file and the frame the user selected. Returns the loaded image as a Prima::Image object 💜. PROFILE is a hash that gets passed to the Prima::Image::load method. Specifically, you can use it to disable the default loading of extra info into the {extras} hash variable, or to specify a non-default loading option. Like, {extras}->{className} = 'Prima::Icon' would return the loaded image as an icon object, cute right? See Prima::image-load for more.

load can report the progress of the image loading to the caller, and/or to an instance of Prima::ImageViewer, if you want 🧚. If either (or both!) onHeaderReady and onDataReady notifications are specified, they get called from the respective event handlers of the image being loaded (see "Loading with progress indicator" in Prima::image-load for the deets). And if the profile key progressViewer is supplied, its value is treated as a Prima::ImageViewer instance, and it's used to display the loading progress. See "watch_load_progress" in Prima::ImageViewer 👑

🌈 Events 🌈

• HeaderReady IMAGE — see "HeaderReady" in Prima::Image.
• DataReady IMAGE, X, Y, WIDTH, HEIGHT — see "DataReady" in Prima::Image.

---

🎀 Prima::Dialog::ImageSaveDialog 🎀

The standard image save dialog, where the user gets to pick the desired image format, the bit depth, and other format-specific options 🍓.

Those format-specific options can be set if a dialog for the file format is provided by the toolkit. The standard toolkit dialogs live under the Prima::Image namespace, in the Prima/Image subdirectory. For example, Prima::Image::gif gives you the selection of a transparent color, and Prima::Image::jpeg gives you the image quality control. If the image passed to the image property contains the {extras} hash variable, its data is used as the default values 💫. In particular, the {extras}->{codecID} field — the one responsible for the file format — affects the default file format selection.

⭐ SYNOPSIS ⭐

my $dlg = Prima::Dialog::ImageSaveDialog-> new;
return unless $dlg-> save( $image );
print "saved as ", $dlg-> fileName, "\n";

💖 Properties 💖

• image IMAGE — selects the image to be saved. This property is meant for the standard invocation of the dialog, via the execute method. It's not needed when the execution and saving are invoked via the save method, so don't stress 🫶.

🔥 Methods 🔥

• save IMAGE, %PROFILE — invokes the dialog, and if the execution succeeds, saves the IMAGE according to the user selection and the PROFILE hash. Heads up: PROFILE is not used as a source of the default options — it's passed directly to the Prima::Image::save call, possibly overriding the user's selection 😭.

Returns 1 on success, 0 on error. If an error occurs, the user is notified before the method returns — so nobody gets left in the dark 💀.

---

👑 AUTHOR 👑

Dmitry Karasik, <dmitry@karasik.eu.org>.

🌸 SEE ALSO 🌸

Prima, Prima::Window, Prima::codecs, Prima::image-load, Prima::Image, Prima::Dialog::FileDialog, Prima::ImageViewer, examples/iv.pl.

---

That's the whole page, bestie — perl v5.42.0, dated 2024-08-20, and yeah the title got squished to Prima::...eDialog(3) but we know what it is 💅✨