【Qtプログラミング】QFileDialog::getOpenFileNames()徹底解説！代替手段も紹介

QStringList QFileDialog::getOpenFileNames() とは

QFileDialog::getOpenFileNames() は、Qt の QFileDialog クラスが提供する静的（static）関数の一つで、ユーザーにファイル選択ダイアログを表示し、複数の既存ファイルを選択させるための便利な関数です。

ユーザーがファイル選択ダイアログで1つ以上のファイルを選択し、「開く」ボタン（またはプラットフォームに応じた同様のボタン）をクリックすると、選択されたすべてのファイルの絶対パスが QStringList 型で返されます。もしユーザーが「キャンセル」ボタンをクリックした場合、または何もファイルを選択しなかった場合は、空の QStringList が返されます。

この関数を使用することで、開発者が自分でファイル選択ダイアログを構築する手間を省き、プラットフォームネイティブのファイル選択ダイアログ（Windowsであればエクスプローラー風、macOSであればFinder風のダイアログ）を利用できるため、アプリケーションのOSへの統合がスムーズになります。

いくつかオーバーロードがありますが、よく使われるものの一般的な形は以下のようになります。

QStringList QFileDialog::getOpenFileNames(
    QWidget *parent = nullptr,
    const QString &caption = QString(),
    const QString &dir = QString(),
    const QString &filter = QString(),
    QString *selectedFilter = nullptr,
    Options options = Options()
);

各引数の意味は以下の通りです。

---

QStringList QFileDialog::getOpenFileNames() の一般的なエラーとトラブルシューティング

ダイアログが表示されない、またはハングする

問題
getOpenFileNames() を呼び出してもファイルダイアログが表示されず、アプリケーションがフリーズしたり、クラッシュしたりする場合があります。特に、ネイティブダイアログ（QFileDialog::DontUseNativeDialog オプションを指定しない場合）で発生しやすいです。

原因とトラブルシューティング

• Qtのデプロイメントの問題（Windowsの場合）
  リリースビルドで Qt の一部のDLL（platforms フォルダ内の qwindows.dll など）が不足している場合、ダイアログが表示されないことがあります。
  • 対策
    windeployqt ツールを使用して、必要なDLLがすべて含まれていることを確認してください。
• システム固有の問題（シェル拡張など）
  WindowsなどのOSでは、サードパーティ製のシェル拡張（エクスプローラーの右クリックメニューに追加される機能など）が原因で、ネイティブファイルダイアログの動作が不安定になることがあります。
  • 対策
    
    • まず、QFileDialog::DontUseNativeDialog オプションを getOpenFileNames() に渡して、Qtの組み込みダイアログを使用してみてください。これで問題が解決する場合、ネイティブダイアログに関する問題である可能性が高いです。
    • 特定のサードパーティ製ソフトウェアやシェル拡張を無効にする、または一時的にアンインストールすることで、問題が解決するか試す。これは根本的な解決策ではありませんが、原因の特定に役立ちます。
    • Qtのバージョンを最新のものにアップデートする。既知のバグが修正されている可能性があります。
• 初期ディレクトリの不正
  dir 引数に存在しない、またはアクセス権のないパスを指定すると、ダイアログの表示に失敗したり、遅延が発生したりすることがあります。
  • 対策
    QDir::homePath() や QCoreApplication::applicationDirPath() など、確実に存在するパスを初期ディレクトリとして指定してみてください。デバッグ中に qDebug() で dir の値を出力して確認するのも有効です。
• GUIスレッド以外からの呼び出し
  QFileDialog はGUI要素であり、必ずQtのメイン（GUI）スレッドから呼び出す必要があります。別のスレッドから呼び出すと、予期せぬ動作やクラッシュの原因になります。
  • 対策
    ファイルダイアログの呼び出しがメインスレッドで行われていることを確認してください。もしバックグラウンドスレッドでファイル選択が必要な場合は、シグナル/スロット機構などを使ってメインスレッドに処理を委譲してください。

選択されたファイルパスが期待通りでない

問題
getOpenFileNames() が返す QStringList が空である、または意図しないパスが含まれている。

原因とトラブルシューティング

• フィルタの指定ミス
  filter 引数のフォーマットが間違っていると、ファイルが正しくフィルタリングされなかったり、ダイアログに何も表示されなかったりすることがあります。
  • 対策
    フィルタ文字列の書式 ("説明 (*.拡張子);;別の説明 (*.別の拡張子)") が正しいか確認してください。特にワイルドカード * やセミコロン ;; の使い方が重要です。
    • 例: "画像ファイル (*.png *.jpg);;テキストファイル (*.txt);;すべてのファイル (*.*)"
• ユーザーがキャンセルした
  ユーザーがファイルダイアログで「キャンセル」ボタンをクリックした場合、QStringList は空になります。
  • 対策
    返り値が isEmpty() かどうかをチェックし、空の場合はユーザーがキャンセルしたと判断して、適切な処理（例: エラーメッセージを表示しない、次の処理に進まない）を行うようにします。

    QStringList selectedFiles = QFileDialog::getOpenFileNames(...);
    if (selectedFiles.isEmpty()) {
        qDebug() << "ファイル選択がキャンセルされました。";
        return; // 以降の処理を中断
    }
    // ファイルを使った処理
    

ダイアログの見た目や動作がプラットフォームと異なる

問題
WindowsでmacOSのようなダイアログが表示される、またはその逆で、プラットフォームネイティブの見た目にならない。

原因とトラブルシューティング

• プラットフォームプラグインの不足
  Linux環境などで、Qtが使用するプラットフォームテーマ（例: GTK+2/3、KDE）のライブラリが適切にインストールされていない場合、ネイティブダイアログが利用できず、Qtのフォールバックダイアログが表示されることがあります。
  • 対策
    該当するLinuxディストリビューションのQt関連パッケージ（qt5-qtbase-gui や qt5-plugin-platformtheme-gtk2/3 など）が正しくインストールされているか確認してください。
• QFileDialog::DontUseNativeDialog オプションの使用
  このオプションを明示的に指定すると、Qtはネイティブダイアログではなく、Qtが独自に実装したダイアログを使用します。
  • 対策
    ネイティブダイアログを使用したい場合は、このオプションを指定しないでください。デフォルトではネイティブダイアログが優先されます。

this ポインタの問題（親ウィジェットの指定）

問題
parent 引数に無効な this ポインタを渡すと、ダイアログが表示されなかったり、クラッシュしたりすることがあります。特に、QObject は継承しているが QWidget は継承していないクラスのメンバー関数から this を渡す場合に発生します。

原因とトラブルシューティング

• parent 引数が QWidget 型ではない
  QFileDialog::getOpenFileNames() の parent 引数は QWidget* 型を期待しています。QWidget を継承していないクラスのインスタンスを this として渡すと、コンパイルエラーになるか、実行時エラーになります。
  • 対策
    
    • もし、ダイアログを呼び出すクラスが QWidget を継承している場合は、そのクラスの this を渡します。
    • もし、ダイアログを呼び出すクラスが QWidget を継承していない場合は、parent 引数に nullptr を渡すか、適切に QWidget のインスタンスを取得して渡すようにします。nullptr の場合、ダイアログは独立したウィンドウとして表示されます。

Qtバージョン間の互換性

問題
Qtのバージョンをアップグレードした後に、以前は動いていた QFileDialog のコードが動作しなくなる。

• APIの変更
  Qtのメジャーバージョンアップ（例: Qt4からQt5、Qt5からQt6）では、一部のAPIが変更されたり、非推奨になったりすることがあります。
  • 対策
    Qtの公式ドキュメント（バージョンごとの変更履歴）を確認し、使用しているAPIに変更がないか確認してください。コンパイラの警告メッセージも役立ちます。

• Qt Creator のデバッガ
  Qt Creator のデバッガを使用して、ステップ実行や変数の監視を行い、プログラムの実行フローや変数の状態を確認します。
• オプションを減らして試す
  filter や dir、options などの引数を省略したり、シンプルなものに変えたりして、問題が解決するか試します。
• 最小限の再現コード
  問題が発生した場合、その現象を再現できる最小限のコードを作成します。これにより、問題の原因を特定しやすくなります。
• qDebug() の活用
  各引数や返り値の QStringList の中身を qDebug() で出力して、期待通りの値が設定されているか、または返されているかを確認します。

---

QFileDialog::getOpenFileNames() は、ユーザーに複数のファイルを選択させるための非常に便利な静的関数です。様々な引数を指定することで、ダイアログの振る舞いや表示内容を制御できます。

例1: 最もシンプルな使用例

タイトルとフィルタのみを指定し、親ウィジェットなしで、現在の作業ディレクトリからファイルを選択させる例です。

#include <QApplication>
#include <QFileDialog>
#include <QStringList>
#include <QDebug> // デバッグ出力用

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    qDebug() << "ファイル選択ダイアログを表示します...";

    // 最もシンプルな形でファイル選択ダイアログを表示
    // 引数: parent, caption, dir, filter
    QStringList selectedFiles = QFileDialog::getOpenFileNames(
        nullptr, // 親ウィジェットなし (ダイアログは独立したウィンドウになる)
        "複数の画像ファイルを選択してください", // ダイアログのタイトル
        QString(), // 初期ディレクトリ (空文字列の場合、デフォルトの動作: 最後に開いたディレクトリなど)
        "画像ファイル (*.png *.jpg *.jpeg *.gif);;すべてのファイル (*.*)" // フィルタ
    );

    // ユーザーがファイルを選択したか確認
    if (!selectedFiles.isEmpty()) {
        qDebug() << "選択されたファイル数:" << selectedFiles.size();
        qDebug() << "選択されたファイルパス:";
        for (const QString &filePath : selectedFiles) {
            qDebug() << "  " << filePath;
        }
    } else {
        qDebug() << "ファイル選択がキャンセルされました。またはファイルが選択されませんでした。";
    }

    // 通常、QApplication::exec() でイベントループを開始し、GUIを動作させる
    // この例ではダイアログ表示後にプログラムが終了するため不要だが、
    // 実際のGUIアプリケーションでは必要
    // return app.exec();
    return 0; // 簡単な例なので0を返す
}

解説

• filter 文字列はセミコロン ;; で区切られた複数のフィルタを持ちます。それぞれのフィルタは 説明 (*.拡張子) の形式です。
• QString() を dir に渡すことで、Qtがデフォルトの初期ディレクトリ（通常は最後に使われたディレクトリやアプリケーションの作業ディレクトリ）を使用します。
• nullptr を parent に渡すことで、ダイアログは独立したウィンドウとして表示されます。

例2: 親ウィジェットを指定し、特定の初期ディレクトリを設定する

メインウィンドウ（または他のウィジェット）の子としてダイアログを表示し、特定のディレクトリからファイル選択を開始する例です。

#include <QApplication>
#include <QMainWindow>
#include <QPushButton>
#include <QVBoxLayout>
#include <QFileDialog>
#include <QStringList>
#include <QDebug>
#include <QDir> // QDir::homePath() を使うため

// メインウィンドウクラス
class MyMainWindow : public QMainWindow {
    Q_OBJECT // シグナル/スロットを使用するために必要

public:
    MyMainWindow(QWidget *parent = nullptr) : QMainWindow(parent) {
        setWindowTitle("ファイル選択テスト");
        resize(400, 300);

        QWidget *centralWidget = new QWidget(this);
        setCentralWidget(centralWidget);

        QVBoxLayout *layout = new QVBoxLayout(centralWidget);

        QPushButton *openFileButton = new QPushButton("ファイルを選択", this);
        layout->addWidget(openFileButton);

        // ボタンがクリックされたら openFiles() スロットを呼び出す
        connect(openFileButton, &QPushButton::clicked, this, &MyMainWindow::openFiles);
    }

private slots:
    void openFiles() {
        qDebug() << "「ファイルを選択」ボタンがクリックされました。";

        // ユーザーのドキュメントディレクトリを初期ディレクトリとする
        QString initialDir = QDir::homePath();
#ifdef Q_OS_WIN
        // Windowsではマイドキュメントがよく使われる
        initialDir = QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation);
#endif
        if (!QDir(initialDir).exists()) {
            initialDir = QDir::homePath(); // 存在しない場合はホームディレクトリにフォールバック
        }


        QStringList selectedFiles = QFileDialog::getOpenFileNames(
            this, // 親ウィジェットを現在のウィンドウ (MyMainWindow) に設定
            "設定ファイルまたはデータファイルを選択",
            initialDir, // 初期ディレクトリ
            "設定ファイル (*.conf *.ini);;データファイル (*.dat);;すべてのファイル (*.*)"
        );

        if (!selectedFiles.isEmpty()) {
            qDebug() << "選択されたファイル数:" << selectedFiles.size();
            qDebug() << "選択されたファイルパス:";
            for (const QString &filePath : selectedFiles) {
                qDebug() << "  " << filePath;
            }
        } else {
            qDebug() << "ファイル選択がキャンセルされました。";
        }
    }
};

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);

    MyMainWindow mainWindow;
    mainWindow.show(); // メインウィンドウを表示

    return app.exec(); // アプリケーションのイベントループを開始
}

#include "main.moc" // mocファイルをインクルード（Qtのビルドシステムが生成）

• QDir::homePath() や QStandardPaths::writableLocation(QStandardPaths::DocumentsLocation) を使用して、プラットフォームに依存しない形で初期ディレクトリを設定しています。
• MyMainWindow を親ウィジェットとして this を渡しています。これにより、ダイアログは MyMainWindow に対してモーダルになり、MyMainWindow の中央に表示されます。

例3: 選択されたフィルタを取得し、特定のオプションを設定する

---

主に以下の3つのアプローチが考えられます。

1. QFileDialog クラスをインスタンス化して使用する
2. 独自のファイル選択ダイアログを実装する
3. OSネイティブのAPIを直接呼び出す (Qtの範疇外)

QFileDialog クラスをインスタンス化して使用する

getOpenFileNames() のような静的関数は手軽ですが、QFileDialog オブジェクトを直接インスタンス化して使用することで、より詳細な制御やカスタマイズが可能になります。これは QFileDialog::DontUseNativeDialog オプションを使用した場合の動作に似ていますが、オブジェクト指向的なアプローチです。

メリット

• QFileDialog を継承して、カスタムウィジェットを追加するなどの拡張が可能（ただし、Qt 4以降は困難になり、推奨されない場合が多い）。
• Qtスタイルシートを適用して、ダイアログの見た目をカスタマイズしやすい（ネイティブダイアログでは制限がある）。
• ダイアログのライフサイクルを細かく制御できる。
• ダイアログの表示前に、より多くのプロパティ（例: setViewMode(), setNameFilterDetailsVisible(), setSidebarUrls() など）を設定できる。

使用例

#include <QApplication>
#include <QMainWindow>
#include <QPushButton>
#include <QVBoxLayout>
#include <QFileDialog>
#include <QStringList>
#include <QDebug>
#include <QDir>

class CustomFileDialogExample : public QMainWindow {
    Q_OBJECT

public:
    CustomFileDialogExample(QWidget *parent = nullptr) : QMainWindow(parent) {
        setWindowTitle("QFileDialog インスタンス使用例");
        resize(400, 300);

        QWidget *centralWidget = new QWidget(this);
        setCentralWidget(centralWidget);

        QVBoxLayout *layout = new QVBoxLayout(centralWidget);

        QPushButton *openButton = new QPushButton("ファイルを開く (インスタンス)", this);
        layout->addWidget(openButton);

        connect(openButton, &QPushButton::clicked, this, &CustomFileDialogExample::openFilesWithInstance);
    }

private slots:
    void openFilesWithInstance() {
        qDebug() << "QFileDialog インスタンスを使用してダイアログを表示します...";

        // QFileDialog オブジェクトをインスタンス化
        QFileDialog dialog(this, "複数のドキュメントを選択", QDir::homePath());

        // 複数のファイルを選択可能に設定
        dialog.setFileMode(QFileDialog::ExistingFiles);

        // フィルタを設定
        dialog.setNameFilter("テキストドキュメント (*.txt *.md);;コードファイル (*.cpp *.h *.py);;すべてのファイル (*.*)");

        // ダイアログの表示モードを詳細表示に設定
        dialog.setViewMode(QFileDialog::Detail);

        // ネイティブダイアログを使わないように強制 (スタイルシートを適用したい場合など)
        dialog.setOption(QFileDialog::DontUseNativeDialog, true);
        // 例: ダイアログ内のボタンのスタイルを変更 (DontUseNativeDialog が必要)
        dialog.setStyleSheet("QPushButton { background-color: lightblue; border: 1px solid blue; padding: 5px; }");

        // ダイアログを表示し、ユーザーの操作を待つ
        if (dialog.exec()) { // exec() はモーダルダイアログを表示し、ユーザーがOKすると true を返す
            QStringList selectedFiles = dialog.selectedFiles(); // 選択されたファイルパスを取得
            qDebug() << "選択されたファイル数:" << selectedFiles.size();
            qDebug() << "選択されたファイルパス:";
            for (const QString &filePath : selectedFiles) {
                qDebug() << "  " << filePath;
            }
            qDebug() << "選択されたフィルタ:" << dialog.selectedNameFilter();
        } else {
            qDebug() << "ファイル選択がキャンセルされました。";
        }
    }
};

int main(int argc, char *argv[]) {
    QApplication app(argc, argv);
    CustomFileDialogExample window;
    window.show();
    return app.exec();
}

#include "main.moc" // mocファイルをインクルード

独自のファイル選択ダイアログを実装する

これは最も柔軟な方法ですが、最も手間がかかります。QDialog を継承し、QFileSystemModel と QTreeView または QListView を組み合わせて、ゼロからファイル選択インターフェースを作成します。

メリット

• 特定のアプリケーション要件（例: ファイルプレビュー、カスタムメタデータ表示）に特化したUIを作成できる。
• ファイルシステム以外のデータソース（例: ネットワークドライブ、クラウドストレージの仮想パス）を統合できる。
• 完全に自由なレイアウト、見た目、機能のカスタマイズが可能。

デメリット

• アクセシビリティや国際化対応もすべて自分で行う必要がある。
• OSネイティブの見た目や操作感とは異なるため、ユーザーが戸惑う可能性がある。
• 開発コストが非常に高い（UIデザイン、ファイルシステム操作ロジック、エラーハンドリングなど全てを自分で実装する必要がある）。

基本的なアプローチ

1. QDialog を継承した新しいクラスを作成します。
2. このダイアログ内に、QTreeView (または QListView)、QLineEdit (パス表示用)、QPushButton (OK/キャンセル、ディレクトリ移動ボタンなど) を配置します。
3. QFileSystemModel を QTreeView のモデルとして設定し、ファイルシステムの内容を表示させます。
4. ユーザーの選択、ボタンクリック、ディレクトリ変更などのイベントを処理するスロットを実装します。
5. 最終的に、選択されたファイルのパスを返すメソッド（例: selectedFiles()）を提供します。

実装は複雑になるため、具体的なコード例は省略しますが、概念としては以下のようになります。

// MyCustomFileDialog.h
#pragma once
#include <QDialog>
#include <QFileSystemModel>
#include <QTreeView>
#include <QLineEdit>
#include <QPushButton>
#include <QVBoxLayout>
#include <QItemSelectionModel> // 選択モデル用

class MyCustomFileDialog : public QDialog {
    Q_OBJECT

public:
    explicit MyCustomFileDialog(QWidget *parent = nullptr);
    QStringList selectedFiles() const;

private slots:
    void on_treeView_doubleClicked(const QModelIndex &index);
    void on_selection_changed(const QItemSelection &selected, const QItemSelection &deselected);
    void acceptDialog();
    void rejectDialog();

private:
    QFileSystemModel *fileSystemModel;
    QTreeView *treeView;
    QLineEdit *pathLineEdit;
    QPushButton *okButton;
    QPushButton *cancelButton;
    QStringList m_selectedFiles;
};

// MyCustomFileDialog.cpp (簡略化)
#include "MyCustomFileDialog.h"
#include <QDebug>
#include <QMessageBox>

MyCustomFileDialog::MyCustomFileDialog(QWidget *parent)
    : QDialog(parent) {
    setWindowTitle("カスタムファイル選択");
    resize(600, 400);

    fileSystemModel = new QFileSystemModel(this);
    fileSystemModel->setRootPath(QDir::homePath());
    fileSystemModel->setFilter(QDir::AllEntries | QDir::NoDotAndDotDot | QDir::Hidden); // フィルタ設定

    treeView = new QTreeView(this);
    treeView->setModel(fileSystemModel);
    treeView->setRootIndex(fileSystemModel->index(QDir::homePath()));
    treeView->setSelectionMode(QAbstractItemView::ExtendedSelection); // 複数選択可能に

    // カラムの表示設定（例: サイズ、タイプ、更新日時を非表示）
    for (int i = 1; i < fileSystemModel->columnCount(); ++i) {
        treeView->hideColumn(i);
    }
    treeView->header()->setSectionResizeMode(0, QHeaderView::Stretch); // 名前カラムを拡張

    pathLineEdit = new QLineEdit(this);
    pathLineEdit->setReadOnly(true);

    okButton = new QPushButton("OK", this);
    cancelButton = new QPushButton("キャンセル", this);

    QHBoxLayout *buttonLayout = new QHBoxLayout();
    buttonLayout->addStretch();
    buttonLayout->addWidget(okButton);
    buttonLayout->addWidget(cancelButton);

    QVBoxLayout *mainLayout = new QVBoxLayout(this);
    mainLayout->addWidget(pathLineEdit);
    mainLayout->addWidget(treeView);
    mainLayout->addLayout(buttonLayout);

    connect(treeView, &QTreeView::doubleClicked, this, &MyCustomFileDialog::on_treeView_doubleClicked);
    connect(treeView->selectionModel(), &QItemSelectionModel::selectionChanged, this, &MyCustomFileDialog::on_selection_changed);
    connect(okButton, &QPushButton::clicked, this, &MyCustomFileDialog::acceptDialog);
    connect(cancelButton, &QPushButton::clicked, this, &MyCustomFileDialog::rejectDialog);
}

QStringList MyCustomFileDialog::selectedFiles() const {
    return m_selectedFiles;
}

void MyCustomFileDialog::on_treeView_doubleClicked(const QModelIndex &index) {
    if (fileSystemModel->isDir(index)) {
        treeView->setRootIndex(index);
        pathLineEdit->setText(fileSystemModel->filePath(index));
    } else {
        // ファイルがダブルクリックされたら、そのファイルを選択してダイアログを閉じる
        m_selectedFiles.clear();
        m_selectedFiles << fileSystemModel->filePath(index);
        accept();
    }
}

void MyCustomFileDialog::on_selection_changed(const QItemSelection &selected, const QItemSelection &deselected) {
    Q_UNUSED(deselected);
    m_selectedFiles.clear();
    for (const QModelIndex &index : selected.indexes()) {
        if (!fileSystemModel->isDir(index)) { // ディレクトリは選択対象外とする
            m_selectedFiles << fileSystemModel->filePath(index);
        }
    }
    // OKボタンの有効/無効を切り替えるなど
    okButton->setEnabled(!m_selectedFiles.isEmpty());
}

void MyCustomFileDialog::acceptDialog() {
    // 選択されたファイルがなければエラーメッセージなど
    if (m_selectedFiles.isEmpty()) {
        QMessageBox::warning(this, "ファイル選択", "ファイルを選択してください。");
        return;
    }
    accept(); // QDialog::accept() を呼び出し、ダイアログを閉じ、exec() が true を返すようにする
}

void MyCustomFileDialog::rejectDialog() {
    reject(); // QDialog::reject() を呼び出し、ダイアログを閉じ、exec() が false を返すようにする
}

OSネイティブのAPIを直接呼び出す (Qtの範疇外)

Qtを使わずに、Windows API (COMインターフェースの IFileOpenDialog など)、macOS (Cocoaの NSOpenPanel など)、Linux (GTK+やKDEのAPIなど) を直接呼び出す方法です。

メリット

• Qtが提供しない特定のネイティブダイアログ機能を利用できる可能性がある。
• Qtの依存関係を減らせる（場合によっては）。
• 最大限にOSネイティブの見た目と操作感を実現できる。

• 通常、Qtアプリケーションでこれを行うメリットは少ない（QFileDialog が既にネイティブダイアログを優先的に使用するため）。
• Qtのイベントループとの統合が複雑になる可能性がある。
• C++の他のライブラリ（WindowsではCOMなど）に関する知識が必要になる。
• クロスプラットフォーム性が失われる（OSごとに異なるコードを書く必要がある）。