Qt フォルダ選択で困らない！QFileDialog::directory() のエラーと解決策

QFileDialog::directory() は、静的（スタティック）な関数で、ユーザーにディレクトリ（フォルダ）を選択させるための標準的なファイルダイアログを表示し、選択されたディレクトリのパスを表す QString オブジェクトを返します。もしユーザーがキャンセルした場合や、エラーが発生した場合は、空の QString が返されます。

この関数は、以下のような状況で非常に便利です。

• シンプルなディレクトリ選択ダイアログを手軽に実装したい場合。
• アプリケーションでユーザーに特定のディレクトリを指定してもらいたい場合（例：データの保存先、ログファイルの出力先など）。

関数の基本的な使い方

QString directory = QFileDialog::getExistingDirectory(
    parent,
    caption,
    dir,
    options
);

if (!directory.isEmpty()) {
    // ユーザーがディレクトリを選択し、そのパスが directory に格納されています。
    qDebug() << "選択されたディレクトリ:" << directory;
} else {
    // ユーザーがキャンセルしたか、エラーが発生しました。
    qDebug() << "ディレクトリの選択がキャンセルされました。";
}

引数の説明

• options (QFileDialog::Options = Options()): ダイアログの動作や外観をカスタマイズするためのオプションです。例えば、読み取り専用のディレクトリのみを表示したり、新しいフォルダを作成するボタンを表示したりすることができます。複数のオプションをビット演算子 (|) で組み合わせることができます。
• dir (const QString& = QString()): ダイアログが開いたときに最初に表示するディレクトリのパスです。省略した場合や空の文字列を指定した場合は、通常、ユーザーのホームディレクトリや最後に使用したディレクトリが表示されます。特定のディレクトリをデフォルトで開きたい場合に指定します。
• caption (const QString&): ダイアログのタイトルバーに表示する文字列です。「フォルダを選択」のような説明的なテキストを設定します。
• parent (QWidget*): ダイアログの親ウィジェットを指定します。通常は、ダイアログを表示するウィジェット（例えば、メインウィンドウ）を渡します。nullptr を渡すことも可能ですが、親ウィジェットを指定することで、ダイアログが親ウィジェットの中央に表示されたり、親ウィジェットが閉じられる際に一緒に閉じられたりするなどの関連付けが行われます。

• ユーザーが「キャンセル」ボタンを押した場合や、何らかのエラーが発生した場合は、空の QString が返されます。
• ユーザーがディレクトリを選択して「OK」ボタンなどを押した場合、選択されたディレクトリの絶対パスを含む QString オブジェクトが返されます。

• より複雑なファイルダイアログのカスタマイズが必要な場合は、QFileDialog クラスのインスタンスを作成して、各種設定を行った後に exec() メソッドで表示する方法があります。
• QFileDialog::getExistingDirectory() はモーダルなダイアログを表示します。つまり、このダイアログが閉じられるまで、ユーザーはアプリケーションの他の部分を操作できません。

---

一般的なエラーとトラブルシューティング

1. ダイアログが表示されない
   

   • 親ウィジェット (parent) が無効 (nullptr) である
     getExistingDirectory() に渡す親ウィジェットが nullptr の場合、ダイアログがタスクバーに表示されるだけで前面に出てこないことがあります。有効な親ウィジェット（通常はメインウィンドウなど）を渡すようにしてください。
   • 親ウィジェットが非表示である
     親ウィジェットが hide() されているなど、非表示の状態だと、子であるダイアログも表示されません。親ウィジェットが表示されていることを確認してください。
   • スロットやイベントループの問題
     何らかの理由でイベントループが正常に処理されていない場合、ダイアログの表示が遅延したり、完全に表示されなかったりすることがあります。特にマルチスレッドを使用している場合は注意が必要です。
   • 他のモーダルダイアログが既に表示されている
     別のモーダルダイアログが表示されている間は、新しいモーダルダイアログを表示できません。
   • parent に有効な QWidget ポインタを渡しているか確認します。
   • 親ウィジェットが isVisible() で true を返しているか確認します。
   • イベントループがブロックされていないか確認します。
   • 他のモーダルダイアログが表示されていないか確認します。

2. 期待したディレクトリが初期表示されない
   

   • 初期ディレクトリ (dir) が無効なパスである
     dir に存在しないパスやアクセス権のないパスを指定すると、デフォルトのディレクトリ（通常はホームディレクトリ）が表示されます。指定するパスが有効であることを確認してください。
   • 相対パスの扱い
     相対パスを指定した場合、アプリケーションの実行時のカレントディレクトリからの相対パスとして解釈されます。意図した場所からの相対パスになっているか確認してください。絶対パスを使用することを推奨します。
   • ファイルシステムのエラー
     ディスクのエラーやネットワークの問題で、指定されたディレクトリにアクセスできない場合があります。

   トラブルシューティング
   

   • 指定するパスが存在し、アプリケーションがそのパスへの読み取り権限を持っているか確認します。
   • 相対パスを使用している場合は、アプリケーションの実行時のカレントディレクトリを確認し、意図したパスになっているか確認します。
   • 絶対パスを使用するように変更してみます。

3. 選択されたディレクトリが空の文字列 (QString) で返ってくる
   

   • ユーザーが「キャンセル」ボタンを押した
     これは正常な動作です。ユーザーがディレクトリを選択せずにダイアログを閉じた場合、空の文字列が返ります。
   • エラーが発生した
     ファイルシステムのアクセスエラーなど、何らかのエラーが発生した場合も空の文字列が返ることがあります。

   トラブルシューティング
   

   • 戻り値が空の文字列の場合、ユーザーがキャンセルしたのか、本当にエラーが発生したのかを区別するために、必要に応じて追加のエラー処理を実装することを検討してください（ただし、getExistingDirectory() 自体は詳細なエラー情報を提供しません）。

4. ダイアログのオプション (options) が期待通りに機能しない
   

   • オプションの指定ミス
     ビット演算子 (|) を使って複数のオプションを組み合わせる際に、誤った組み合わせ方をすると意図しない動作になることがあります。ドキュメントをよく確認し、正しいオプションを指定してください。
   • プラットフォームによる差異
     一部のオプションは、特定のプラットフォームでのみ有効であったり、挙動が異なったりする場合があります。

   トラブルシューティング
   

   • 指定しているオプションが正しいか、ドキュメントで確認します。
   • 異なるプラットフォームでテストし、挙動の違いを確認します。

5. ダイアログのカスタマイズがうまくいかない
   

   • getExistingDirectory() は簡易的なダイアログ表示関数であり、高度なカスタマイズはできません。より詳細なカスタマイズが必要な場合は、QFileDialog クラスのインスタンスを作成し、各種メソッド（例えば setFileMode(), setViewMode(), setOption() など）を使用して設定する必要があります。

   トラブルシューティング
   

   • 高度なカスタマイズが必要な場合は、QFileDialog クラスを直接使用する方法に切り替えることを検討してください。

デバッグのヒント

• 簡単なテストプログラムを作成し、様々なケース（有効なパス、無効なパス、キャンセルなど）で getExistingDirectory() の動作を確認します。
• qDebug() を使用して、getExistingDirectory() に渡している引数（parent, caption, dir, options) の値や、戻り値の directory の値を出力して確認します。

---

基本的なディレクトリ選択ダイアログの表示

この例では、親ウィジェットを指定せずに、シンプルなディレクトリ選択ダイアログを表示します。選択されたディレクトリのパスをコンソールに出力します。

#include <QApplication>
#include <QFileDialog>
#include <QDebug>

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

    QString directory = QFileDialog::getExistingDirectory(
        nullptr, // 親ウィジェット（nullptr の場合はトップレベルウィンドウ）
        "フォルダを選択", // ダイアログのタイトル
        QDir::homePath() // 初期表示するディレクトリ（ここではユーザーのホームディレクトリ）
    );

    if (!directory.isEmpty()) {
        qDebug() << "選択されたディレクトリ:" << directory;
    } else {
        qDebug() << "ディレクトリの選択がキャンセルされました。";
    }

    return 0;
}

親ウィジェットを指定した例

この例では、メインウィンドウ (QMainWindow) を親ウィジェットとして指定し、ダイアログを表示します。

#include <QApplication>
#include <QMainWindow>
#include <QFileDialog>
#include <QPushButton>
#include <QVBoxLayout>
#include <QWidget>
#include <QDebug>

class MainWindow : public QMainWindow {
public:
    MainWindow(QWidget *parent = nullptr) : QMainWindow(parent) {
        QWidget *centralWidget = new QWidget;
        QVBoxLayout *layout = new QVBoxLayout;
        QPushButton *selectDirButton = new QPushButton("フォルダを選択");

        connect(selectDirButton, &QPushButton::clicked, this, &MainWindow::openDirectoryDialog);

        layout->addWidget(selectDirButton);
        centralWidget->setLayout(layout);
        setCentralWidget(centralWidget);
    }

private slots:
    void openDirectoryDialog() {
        QString directory = QFileDialog::getExistingDirectory(
            this, // 親ウィジェットとして MainWindow のインスタンスを指定
            "保存先フォルダを選択",
            QDir::currentPath() // 初期表示するディレクトリ（ここでは現在の作業ディレクトリ）
        );

        if (!directory.isEmpty()) {
            qDebug() << "選択された保存先:" << directory;
            // 選択されたディレクトリを使って何か処理を行う
        } else {
            qDebug() << "保存先の選択がキャンセルされました。";
        }
    }
};

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainWindow w;
    w.show();
    return a.exec();
}

オプションを指定した例

この例では、QFileDialog::DontUseNativeDialog オプションを指定して、Qt 独自のファイルダイアログを使用するようにします。また、新しいフォルダを作成するボタンを表示する QFileDialog::ShowDirsOnly オプションも指定しています。

#include <QApplication>
#include <QFileDialog>
#include <QDebug>

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

    QFileDialog::Options options = QFileDialog::DontUseNativeDialog | QFileDialog::ShowDirsOnly;
    QString directory = QFileDialog::getExistingDirectory(
        nullptr,
        "出力フォルダを選択",
        "/home", // Linux/macOS での例
        options
    );

    if (!directory.isEmpty()) {
        qDebug() << "選択された出力フォルダ:" << directory;
    } else {
        qDebug() << "出力フォルダの選択がキャンセルされました。";
    }

    return 0;
}

• private slots は、Qt のシグナルとスロットの仕組みで使用される特別なメンバ関数です。ボタンがクリックされたときに openDirectoryDialog() が呼び出されるように接続しています。
• QFileDialog::Options には、他にも様々なオプションがあります。例えば、読み取り専用のディレクトリのみを表示する QFileDialog::ReadOnly などがあります。詳細は Qt のドキュメントを参照してください。
• QDir::homePath() や QDir::currentPath() は、それぞれユーザーのホームディレクトリと現在の作業ディレクトリを取得するための便利な関数です。
• これらの例をコンパイルして実行するには、Qt の開発環境がセットアップされている必要があります。.pro ファイルを作成し、必要なモジュール（QtWidgets など）を追加してビルドしてください。

---

QFileDialog クラスを直接使用する

QFileDialog クラスのインスタンスを作成し、各種設定を行った後に exec() メソッドでダイアログを表示する方法です。これにより、より多くのオプションや機能を制御できます。

#include <QApplication>
#include <QFileDialog>
#include <QDebug>

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

    QFileDialog dialog(nullptr, "ディレクトリを選択");
    dialog.setFileMode(QFileDialog::Directory); // ディレクトリのみを選択可能にする
    dialog.setOption(QFileDialog::DontUseNativeDialog, true); // Qt 独自のダイアログを使用（必要に応じて）
    dialog.setDirectory(QDir::homePath()); // 初期表示ディレクトリを設定

    QString selectedDirectory;
    if (dialog.exec() == QDialog::Accepted) {
        selectedDirectory = dialog.selectedFiles().first();
        qDebug() << "選択されたディレクトリ:" << selectedDirectory;
    } else {
        qDebug() << "ディレクトリの選択がキャンセルされました。";
    }

    return 0;
}

利点

• 複数のディレクトリを選択可能にする setSelectionMode(QAbstractItemView::MultiSelection) などの設定も可能です（ただし、ディレクトリ選択の文脈では一般的ではありません）。
• setFilter() や setNameFilter() はディレクトリ選択には直接関係ありませんが、ファイル選択ダイアログと共通のクラスであるため、将来的にファイル選択機能を追加する際に柔軟に対応できます。
• setOption() メソッドを使用して、ネイティブダイアログの使用有無、新しいフォルダの作成ボタンの表示、読み取り専用のディレクトリのみの表示など、より細かなオプションを設定できます。
• setFileMode(QFileDialog::Directory) を使用することで、確実にディレクトリのみを選択するように制限できます。

カスタムのディレクトリ選択 UI を作成する

QTreeView や QListView などのウィジェットと QFileSystemModel を組み合わせて、独自のディレクトリ選択UIを作成する方法です。これにより、外観や動作を完全にカスタマイズできます。

#include <QApplication>
#include <QMainWindow>
#include <QTreeView>
#include <QFileSystemModel>
#include <QVBoxLayout>
#include <QWidget>
#include <QPushButton>
#include <QLineEdit>
#include <QItemSelectionModel>
#include <QDebug>

class CustomDirSelector : public QWidget {
public:
    CustomDirSelector(QWidget *parent = nullptr) : QWidget(parent) {
        QVBoxLayout *layout = new QVBoxLayout;
        model_ = new QFileSystemModel(this);
        model_->setRootPath(QDir::homePath());
        treeView_ = new QTreeView(this);
        treeView_->setModel(model_);
        pathLineEdit_ = new QLineEdit(this);
        selectButton_ = new QPushButton("選択", this);

        connect(treeView_->selectionModel(), &QItemSelectionModel::currentChanged,
                this, &CustomDirSelector::updatePath);
        connect(selectButton_, &QPushButton::clicked, this, &CustomDirSelector::emitSelectedPath);

        layout->addWidget(treeView_);
        layout->addWidget(pathLineEdit_);
        layout->addWidget(selectButton_);
        setLayout(layout);
    }

signals:
    void directorySelected(const QString &path);

private slots:
    void updatePath(const QModelIndex &current, const QModelIndex &previous) {
        Q_UNUSED(previous);
        pathLineEdit_->setText(model_->filePath(current));
    }

    void emitSelectedPath() {
        emit directorySelected(pathLineEdit_->text());
    }

private:
    QFileSystemModel *model_;
    QTreeView *treeView_;
    QLineEdit *pathLineEdit_;
    QPushButton *selectButton_;
};

class MainWindow : public QMainWindow {
public:
    MainWindow(QWidget *parent = nullptr) : QMainWindow(parent) {
        QWidget *centralWidget = new QWidget;
        QVBoxLayout *layout = new QVBoxLayout;
        customDirSelector_ = new CustomDirSelector(this);
        pathDisplay_ = new QLineEdit(this);
        pathDisplay_->setReadOnly(true);

        connect(customDirSelector_, &CustomDirSelector::directorySelected,
                this, &MainWindow::displaySelectedPath);

        layout->addWidget(customDirSelector_);
        layout->addWidget(pathDisplay_);
        centralWidget->setLayout(layout);
        setCentralWidget(centralWidget);
    }

private slots:
    void displaySelectedPath(const QString &path) {
        pathDisplay_->setText(path);
    }

private:
    CustomDirSelector *customDirSelector_;
    QLineEdit *pathDisplay_;
};

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainWindow w;
    w.show();
    return a.exec();
}

利点

• 他のカスタムウィジェットと統合しやすいです。
• 特定のディレクトリ構造を強調したり、フィルタリングしたりするなど、より複雑な表示や操作が可能です。
• UI の外観を完全に制御できます。

欠点

• ファイルシステムの操作やモデル／ビューの概念に関する理解が必要です。
• QFileDialog::getExistingDirectory() よりも多くのコードを記述する必要があります。

サードパーティ製のライブラリやカスタムウィジェットを使用する

Qt のエコシステムには、より高度なファイルダイアログやディレクトリ選択ウィジェットを提供するサードパーティ製のライブラリが存在する場合があります。また、必要に応じて完全に独自のカスタムウィジェットを作成することも可能です。

利点

• 特定のニーズに合わせた高度な機能やUIを提供できる可能性があります。

• カスタムウィジェットの開発には時間と労力がかかります。
• 外部ライブラリの依存関係が増える可能性があります。

• サードパーティ製ライブラリやカスタムウィジェット
  特定の高度なニーズに対応できますが、依存関係や開発コストが増加する可能性があります。
• QTreeView と QFileSystemModel を使用
  UI を完全にカスタマイズでき、複雑な表示や操作が可能です。
• QFileDialog クラスを直接使用
  より多くのオプションを制御でき、基本的なカスタマイズに適しています。
• QFileDialog::getExistingDirectory()
  最も簡単で手軽な方法ですが、カスタマイズの自由度は限られます。