Gtk2::E...ooseFile(3)

📦
version 0.11 · 2 versions
, in fedora 43

✨ Gtk2::Ex::Dialogs::ChooseFile ✨

okay bestie so real talk, you know how sometimes you need to pop up a lil window and be like "hey, pick a file"? yeah. that's this. 💅

this page lives in the User Contributed Perl Documentation manual, section 3, and it's all about Gtk2::Ex::Dialogs::ChooseFile — a module that gives you a file selection dialog. yes, the full name is extremely long, that's just how Perl modules are, we don't make the rules 🫶

🌸 NAME 🌸

Gtk2::Ex::Dialogs::ChooseFile — Provides a file selection dialog.

like. that's it. that's the whole job. and it does it beautifully ✨

🎀 SYNOPSIS 🎀

here's the vibe, copy it, love it, live it:

use Gtk2::Ex::Dialogs::ChooseFile ( destroy_with_parent => TRUE,
                                    modal => TRUE );

# do some stuff like creating your app's main $window then,
# to ensure that all messages use the right parent, set it:
$Gtk2::Ex::Dialogs::ChooseFile::parent_window = $window;

# now popup a new dialog for opening a file
my $file = ask_to_open
            Gtk2::Ex::Dialogs::ChooseFile ( "/path/to/something" );

# ok, now we need to save (as...) a file
my $save = ask_to_save
            Gtk2::Ex::Dialogs::ChooseFile ( "/path/to/something" );

see that parent_window line? do not skip it. it's the whole reason your dialogs will behave and land in the right place instead of floating around like they don't know anybody. 🙈

🦋 DESCRIPTION 🦋

This module provides a simple file chooser api that wraps Gtk2::FileChooser objectively. The objective is a simple ways to prompt a user to open or save a file.

translation: it's a glow-up wrapper. Gtk2::FileChooser is the raw ingredient, this module is the whole main character meal prep so you don't have to assemble it yourself. you want someone to open a file? prompt. you want someone to save a file? prompt. done. periodt. 👑

💖 OPTIONS 💖

All public methods (and the entire class) support the following options. so like, every single one of them. no gatekeeping:

  • title => STRING — The text string to use as the title of the dialog window. Defaults to either "Open" or "Save" based on the action context.
  • path => STRING — The path to a file or directory to initialize the dialog with. Defaults to the current working directory.
  • parent_window => Gtk2::Window — Reference to the main application window.
  • destroy_with_parent => BOOL — When the parent_window is destroyed, what do we do? Defaults to FALSE.
  • modal => BOOL — Does this dialog make the parent_window freeze while the dialog exists. Defaults to FALSE.
  • must_exist => BOOL — The end-user must supply a path to an existing file or directory. Should the end-user provide a non-existant path, the dialog will be respawned until an existing file is chosen. Defaults to FALSE.

ngl must_exist is giving persistent queen — it will literally just keep coming back until they give you a real path. iconic behaviour honestly 🎀

🌈 PUBLIC METHODS 🌈

💫 OBJECT = new ( OPTIONS | PATH )

Create a Gtk2::FileChooserDialog with the options given and show it to the end-user. Once the user has selected a file return only the path to the file and clean up. In the special case of being passed only one argument, all options are set to defaults and the one argument is used as the path argument.

so: hand it a big ol' options hash, or just yeet a single path at it and everything else defaults. it builds the dialog, shows it, waits, gives you back the path, tidies up after itself. a whole self-sufficient icon 💅

💫 RESPONSE = ask_to_open ( OPTIONS | PATH )

Supports all the same arguments as new(). This will create a new Gtk2::Ex::Dialogs::ChooseFile, with some specific defaults, and return the user's response. In the event of being given only one argument, it will be used as the path option.

same arguments as new(), but it's the open flavoured one and it hands you back the user's response. one lone argument? that's your path. easy 🫶

💫 RESPONSE = ask_to_save ( OPTIONS | PATH )

Supports all the same arguments as new(). This will create a new Gtk2::Ex::Dialogs::ChooseFile, with some specific defaults, and return the user's response. In the event of being given only one argument, it will be used as the path option.

literally the same deal as ask_to_open except it's the save sibling. same args, same single-argument path rule, returns the response. twins fr fr 🌸

👀 SEE ALSO 👀

go read these too, they're all part of the same friend group:

  • Gtk2::FileChooser
  • Gtk2::FileChooserDialog
  • Gtk2::Ex::Dialogs
  • Gtk2::Ex::Dialogs::ChooseDirectory
  • Gtk2::Ex::Dialogs::ChoosePreviewFile
  • Gtk2::Ex::Dialogs::ErrorMsg
  • Gtk2::Ex::Dialogs::Message
  • Gtk2::Ex::Dialogs::Question

💀 BUGS 💀

Please report any bugs to the mailing list.

not me asking you to file a bug report, but like, gently, through the mail 🥺 details below.

📬 MAILING LIST 📬

👑 AUTHORS 👑

  • Kevin C. Krinke, <kckrinke@opendoorsoftware.com>
  • James Greenhalgh, <jgreenhalgh@opendoorsoftware.com>

two legends, one module. slay 🫶

Gtk2::Ex::Dialogs::ChooseFile - Provides a file selection dialog. Copyright (C) 2005 Open Door Software Inc. <ods@opendoorsoftware.com>

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

okay so like the "WITHOUT ANY WARRANTY" bit is NOT a joke bestie, it's in all caps for a reason. no warranty. none. the LGPL said what it said. 💀

and that's the whole page!! this was rendered from perl v5.42.0, dated 2025-07-25, in the User Contributed Perl Documentation manual. go forth and choose files, my love 💖✨🎀🦋🌸

📦 where this page comes from