KDE on Rebel Zhang's Blog

Finding the Implementation of a Functionality in a QtWidgets Application Using GammaRay

rebel1725@tilde.club (Rebel Zhang) — Sun, 09 Aug 2026 20:49:33 +0800

To exercise Freedom 1 and Freedom 3 of free software, and/or contribute to the free software community, we need to change the source code related to a functionality to make the software do something different. However, because we are not familiar with a project, we often do not know where the source code we need to change is. You may be lucky enough to find it by trying grep -R <some-user-facing-string> .; however, sometimes that will not work (see the previous post). In that case, we will need some advanced software introspection tools. For software developed with Qt, a powerful utility is GammaRay.

To use GammaRay, you first need to install it. If you want to introspect software installed from your distribution’s official repository, then install GammaRay from there too:

# apt install gammaray

If you are using kde-builder to develop KDE applications, add these lines to your ~/.config/kde-builder.yaml:

project gammaray:
  repository: https://github.com/KDAB/GammaRay.git

and build it into your working directory:

$ kde-builder gammaray

To use GammaRay, you need to have the application you want to introspect running. Then, fire up GammaRay and choose your application in the list.

Let’s take finding the slideshow logic in Gwenview as an example. Open Gwenview and then open an image, where you will see the Start Slideshow option in the menu:

By going through the list of widgets one by one, you will see that 0x13bda470 is the menu we want to introspect, which contains the Start Slideshow option:

And we will see a toggle_slideshow QAction in the Connections tab:

grep will tell us where such a QAction is:

~/kde/src/gwenview$ grep -R toggle_slideshow
app/fullscreencontent.cpp:    addAction(QStringLiteral("toggle_slideshow"));
app/gwenviewui.rc:        <Action name="toggle_slideshow" />
app/mainwindow.cpp:        mToggleSlideShowAction = view->addAction(QStringLiteral("toggle_slideshow"), q, &MainWindow::toggleSlideShow);

Open the project in your favourite IDE, for example Qt Creator, and search for the string in app/mainwindow.cpp. We will find toggle_slideshow here:

        mToggleSlideShowAction = view->addAction(QStringLiteral("toggle_slideshow"), q, &MainWindow::toggleSlideShow);
        q->updateSlideShowAction();
        connect(mSlideShow, &SlideShow::stateChanged, q, &MainWindow::updateSlideShowAction);

Now let us search for toggleSlideShow here, which will lead us to this function:

void MainWindow::toggleSlideShow()
{
    if (d->mSlideShow->isRunning()) {
        d->mSlideShow->pause();
    } else {
        if (!d->mViewAction->isChecked()) {
            d->mViewAction->trigger();
        }
        if (!d->mFullScreenAction->isChecked()) {
            d->mFullScreenAction->trigger();
        }
        QList<QUrl> list;
        for (int pos = 0; pos < d->mDirModel->rowCount(); ++pos) {
            QModelIndex index = d->mDirModel->index(pos, 0);
            KFileItem item = d->mDirModel->itemForIndex(index);
            MimeTypeUtils::Kind kind = MimeTypeUtils::fileItemKind(item);
            switch (kind) {
            case MimeTypeUtils::KIND_SVG_IMAGE:
            case MimeTypeUtils::KIND_RASTER_IMAGE:
            case MimeTypeUtils::KIND_VIDEO:
                list << item.url();
                break;
            default:
                break;
            }
        }
        d->mSlideShow->start(list);
    }
    updateSlideShowAction();
}

Continue searching for mSlideShow, and you will land here:

struct MainWindow::Private {
    ...
    SlideShow *mSlideShow = nullptr;
    ...
}

We can now see that d->mSlideShow is of type SlideShow *. Hovering over the SlideShow name with the mouse will tell us that the type is provided by lib/slideshow.h.

Now open lib/slideshow.cpp and lib/slideshow.h, and you are ready to go.

My Very First Steps Contributing to the Free Software Community (Existing Projects)

rebel1725@tilde.club (Rebel Zhang) — Sun, 02 Aug 2026 23:18:30 +0800

In recent days, I have contributed far less to the free software community than I have benefited from it, and what I have contributed has been limited to small, simple personal projects and non-code contributions (such as some translations, uploading a few screenshots to Debian Screenshots, and writing posts for the Free Software Chinese Site). Over the past year, I have learned C/C++, Qt, assembly, and some Rust, and I think it is time to do something meaningful for the free software community and the free software movement.

DISCLAIMER: This is not a guide! I am writing this post only to share my own experience. Please refer to the relevant documentation and consult experts to learn more about how to contribute to the free software community.

Why I chose KDE

Originally, I thought about contributing to postmarketOS. However, I felt that my skills fell far short of what was needed, and I decided to begin with something relatively simple. Since I am more familiar with C++ and Qt, I chose KDE for my first contribution to the community.

Feelings

My ability to read source code is poor. At around the beginning of 2025, I tried to read the source code of PDF Arranger, and I felt sick and overwhelmed.

However, thanks to the experience of learning reverse engineering, which requires reading assembly code, my ability to read high-level language source code has also improved. Therefore, I think I should try a real free software contribution in order to practise my skills in a real-world environment.

Before opening the source tree, I was somewhat nervous, and I was afraid that I would be overwhelmed by the source code, just as I had been when reading the source of PDF Arranger. Thanks to my friend Integral’s encouragement, I found the courage to take that step.

Tools

One of KDE’s recommended development environments is the latest version of Fedora KDE. Because I use Qubes OS, it is very easy for me to quickly set up a standalone HVM and do all my work inside it.

After that, I set up kde-builder according to the official documentation for KDE developers.

Working

I scanned through the bug list hosted by KDE’s official Bugzilla. I noticed a bug that seemed very easy to fix, but after pulling the source code and building the binary, I found that the bug was not reproducible in my environment with the latest version of Ark.

Then I went back to the bug list and spotted another bug that seemed trivial. The system environment and software version in the bug report were the same as mine (Fedora KDE, 26.04), and the bug was reproducible in the application offered by Fedora’s official repository. After confirming this, I pulled the source code and built it.

I fired up GDB on the binary ~/kde/build/konsole/bin/konsole. After pasting the string mentioned in the bug report (calt,liga,ss03, ss07,ss09) into the field, I noticed this output in the console:

The tag name must be exactly 4 characters long!

After several chats with an LLM, I found a way to locate the line printing this alert in the source code, using a GDB Python script:

python
import gdb

TARGET = b"The tag name must be exactly 4 characters long!"

class FilteredWrite(gdb.Breakpoint):
    def stop(self):
        fd = int(gdb.parse_and_eval("$rdi"))
        if fd not in (1, 2):
            return False

        buf = int(gdb.parse_and_eval("$rsi"))
        count = int(gdb.parse_and_eval("$rdx"))

        try:
            data = gdb.selected_inferior().read_memory(buf, count).tobytes()
        except gdb.MemoryError:
            return False

        if TARGET in data:
            gdb.write("\n=== matched output ===\n")
            gdb.write(data.decode("utf-8", "replace") + "\n")
            gdb.execute("bt full")
            return True

        return False

FilteredWrite("write")

After a GDB session, I confirmed that the alert was raised from the file kfontchooser.cpp in kwidgetsaddons. I also found the function that raises the alert:

void KFontChooserPrivate::slotFeaturesChanged(const QString &features)
{
    m_selectedFont.clearFeatures();

    if (features.isEmpty()) {
        return;
    }

    const QStringList rawFeaturesList = features.split(QLatin1Char(','), Qt::SkipEmptyParts);
    for (const QString &feature : rawFeaturesList) {
        auto f = QStringView(feature).trimmed();
        if (f.isEmpty()) {
            continue;
        }
        QList<QStringView> parts = f.split(QStringLiteral("="), Qt::SkipEmptyParts);
        if (parts.length() == 2) {
            const auto tag = QFont::Tag::fromString(parts[0]);
            bool ok = false;
            const int number = parts[1].toInt(&ok);
            if (tag.has_value() && ok) {
                m_selectedFont.setFeature(tag.value(), number);
            }
        } else if (f.size() <= 4) {
            const auto tag = QFont::Tag::fromString(feature);
            if (tag.has_value()) {
                m_selectedFont.setFeature(tag.value(), 1);
            }
        }
    }

    Q_EMIT q->fontSelected(m_selectedFont);
}

I noticed that the split result was trimmed:

auto f = QStringView(feature).trimmed();

but the original, untrimmed string was still used as the tag:

const auto tag = QFont::Tag::fromString(feature);

This seems to be a mistake made by the developer. To fix the issue, we only need to change the untrimmed string to the trimmed one:

const auto tag = QFont::Tag::fromString(f);

After that, it was time to create a branch, commit the change to that branch, and submit a merge request. However, due to my limited experience with Git, I ran into a problem:

warning: redirecting to https://invent.kde.org/rebellfs/kwidgetsaddons.git/
Enumerating objects: 21973, done.
Counting objects: 100% (21973/21973), done.
Delta compression using up to 4 threads
Compressing objects: 100% (2790/2790), done.
Writing objects: 100% (21973/21973), 41.17 MiB | ... KiB/s, done.
Total 21973 (delta 13428), reused 21374 (delta 12884), pack-reused 0 (from 0)
remote: Resolving deltas: 100% (13428/13428), done.
remote: Audit failure - Commit 046e4bb16e60b66070ee4a00c368ca6924db3a08 - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 046e4bb16e60b66070ee4a00c368ca6924db3a08 - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit c8c7ab3d0e7ca825bbb01d58de005d4d589b12cc - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit c8c7ab3d0e7ca825bbb01d58de005d4d589b12cc - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 62e5736a1f4afc2d24ef2c4d643a98bc60e6d6cd - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit 62e5736a1f4afc2d24ef2c4d643a98bc60e6d6cd - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit f317243c63620acec15a46c412502e73b9a04e2a - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Audit failure - Commit f317243c63620acec15a46c412502e73b9a04e2a - Email address has an invalid domain : [kde@randomguy3.me.uk](mailto:kde@randomguy3.me.uk)
remote: Push declined - commits failed audit
remote: Should the audit failures above mention issues regarding your name, please ensure that your Git username has been set to your full name.
remote: Please see https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup for more details on ensuring Git has been fully configured.
remote: In the event that your full name has been set and is shown above as being rejected, please file a Sysadmin ticket at https://go.kde.org/systickets
To https://invent.kde.org/rebellfs/kwidgetsaddons
! [remote rejected]     work/rebel1725/fix523757 -> work/rebel1725/fix523757 (pre-receive hook declined)
error: failed to push some refs to 'https://invent.kde.org/rebellfs/kwidgetsaddons'

In the end, I submitted the change through the browser, since it was only a trivial change to a single file.

Conclusion

Today, I made my very first contribution to the free software community, and I also became a brand-new free software contributor. In the future, I hope to contribute more and more, sharpen my skills, and become more beneficial to the community and the free software movement.