It's been a while since I've written about GitRaven.

This post will cover the new features I have introduced and talk about bug fixes.

AI Usage

I used ChatGPT or Google Gemini to help me for the updates shared below. They were very helpful in helping me see what I was doing wrong when working on stuff with GitRaven. For example, I ran into quite a few use-after-free bugs in the app because my understanding of freeing memory is different when compared to C++.

The most useful aspect of current AI is it's NLP tech that can understand the problem at hand and offer solutions for the code snippets and error logs I've shared.

I like to learn stuff by building apps and AI tech has made this approach less painful than it usually is.

Context menu actions in Tree:

GitRaven now supports context menu actions in the tree. This will allow users to quickly interact with a file/folder to stage/unstage, view in file manager or delete it entirely.

There are more items I'd like to bring onto context-menus but right now, my attention is drawn towards adding more Git related features (push/pull, fetch), etc.

Use Initializer Lists for initializing the app

This is a good milestone in my opinion. The research that went to helping me realize the problem with memory bugs in the app was mind-numbing.

Bug:
The app would randomly crash when performing git status equivalent. GitManager is an important class, used to perform all Git related actions on the repository.

Cause:

The crash happens at a function call when referenced via a pointer to GitManager class instance.

// inside header
// GitManager *m_gitManager;

// cpp code below
class Foo(GitManager *gitManager, QWidget *parent = nullptr)
    : QWidget{parent}
{
    m_gitManager = gitManager; // yikes!! but I didn't know this was bad then :(
}

void Foo::something()
{
  
  m->gitManager->doSomething(); // <- app crashed here
}

This class is initialized in main.cpp along with QApplication and MainWindow. It was my first "use-after-free" bug. I read about these in CVEs but to experience it first-hand in my app was a definite first.

Anyway, after back-and-forth with ChatGPT, I updated the code to init member variables at the initializer list so that they are available for constructor() to do stuff. It also ensures other widgets that depend on this widget can also safely access stuff as it's not corrupted memory anymore.

I have posted about this on my Mastodon at the time.

Checkout to different branches and tags

I am so happy to report git checkout is working on GitRaven. This feature has been on my mind since the project's inception and I am all here for it!!

There is a known issue at the time of writing where checking to remote branches or tags do not show their names rather they show the git commit hash that points to it.

I added a FIXME in the code so I might eventually get around to it.

Fun Fact: Testing this feature led to discovering more memory leaks within the app which I will in the next item :)

Memory leaks galore!!

The meat of this post is here! I ran into so many segmentation faults while testing the checkout feature with larger number of new/modified files. The app's would be stuck for few seconds while it renders the tree and updates the status bar.

It turns out, the leading cause for this was either missing destructors for QObject/QWidget classes and/or deleting variables or data incorrectly.

RavenTree class was notorious for crashing the app at unexpected times. The issue turned out to be incorrectly deleting QList<> foo; items.
The app kept allocating memory on every git status call without properly freeing the memory which was previously allocated to the QTreeView.

My JS experience is to be blamed here. JS has a garbage collector which in simple terms, is a background thread that runs as long as the app is running to check and free memory when it's no longer in use.
In the case of C++ with Qt, that job has fallen on to me. Although C++ offers smart pointers to address this issue, Gemini suggested not to use it with Qt because it messes with Qt's parent-child relationship. I didn't quite fully understand what it meant because on paper, smart pointers are the solution to my problem. They would manage the memory for me while I focus on building my app.

Also, I am familiar with the smart pointers concept because of Rust. I built a text editor with GTK + Rust few years back for fun.

Link to the fixed code:
https://github.com/shanmukhateja/gitraven/blob/9d5151009a777b0d88a1a18687b5580e1fdb8777/raventree.cpp#L117

The fix was two steps:

1. Add destructors to all classes that extend QObject or QWidget.

2. In order to clear a QList which holds list of pointers, we need to call qDeleteAll() followed by manually calling QList::clear on the member variables in RavenTree

Note: This isn't over yet. I have found another set of memory related bugs with my libgit2 usage code and I plan on fixing them someday.

I mentioned this briefly on Mastodon recently after struggling to understand why this was happening.

Async Git status checks

We now use a separate thread to handle GitManager::status for git status functionality via libgit2. Previously, the GUI thread would freeze up when GitManager::status was running on repositories with 100+ files.

The benefit is, the GUI thread isn't frozen although it stays a blank page - no indication that something is happening to the user.

Note to self - I need to add a progress bar when running long running tasks.

CLion migration

This is a personal change, not completely related to the project but I thought I'd share it here anyway. I migrated from Qt Creator to CLion last month to their free, non-commercial usage license tier.

Qt Creator is an excellent IDE however I am familiar with Jetbrains IDEs for work so I gave it a shot and I liked it.

Minor cosmetic things and bug fixes

1. The app now shows the currently open folder's full path in title bar like "GitRaven - '/home/user/app'"

2. Rewrite RavenTree's absolute path detection logic for individual node in the tree to fix bugs with parent-child relationship shown in the tree.

3. Add CLion specific folders/files to .gitignore

Thank you

Thank you for sticking to the end.

I hope to make time for this project and improve it further while I learn C++ and Qt.

You can follow me on Mastodon.

Bye for now :)

I came up with a simple GUI for stopping Linux from sleeping when idle using Python for fun. This project came to be because of my comment:

https://social.linux.pizza/@shanmukhateja/115843701361619857

You can find GitHub link for this project below:

https://github.com/shanmukhateja/sleep-stopper/

Theory

We use DBus interface org.freedesktop.ScreenSaver on Session Bus to tell Linux to disallow going to sleep on idle.

This feature is very useful when waiting on long-running tasks like system updates, media playback, etc. It is already part of all major applications like web browsers, system tools, media players, etc. and now, this project is also part of that list :)

I wrote this in Python as I’m very comfortable with it but it should be doable in any programming language.

The idea is to have 2 buttons - block sleep and unblock sleep shown to user by checking whether we have a valid cookie. This is an int value provided to us by Inhibit method from DBus interface when our app has successfully requested sleep inhibition.

In order to request inhibiting sleep, we need to provide 2 arguments:

1. App Title
   Shows the app calling for sleep inhibition to user

2. Reason
   Shows a label for reason behind sleep inhibition for user’s understanding.

We will need the following Python packages for this project:

1. GTK4 (for GUI)

2. dbus-fast (for communicating with DBus)

Implementation

Note: This code is hacked together in about 3 hours and it’s only goal is to work as expected. It is not meant to deliver a polished experience.

Let’s look at app.py which contains the GUI and the main logic:

from dbus import SleepStopperDBusClient

import gi

gi.require_version("Gtk", "4.0")
from gi.repository import Gtk


class SleepStopperApplication(Gtk.ApplicationWindow):
    def __init__(self, **kwargs):
        super().__init__(**kwargs, title="Sleep Stopper")
        self.set_size_request(300, 150)

        self.vbox = Gtk.Box()
        self.set_child(self.vbox)

        self.dbus = SleepStopperDBusClient()

        self.block_button = Gtk.Button.new_with_label("Block sleep")
        self.unblock_button = Gtk.Button.new_with_label("Unblock Sleep")

        self.block_button.set_hexpand(True)
        self.unblock_button.set_hexpand(True)

        self.vbox.append(self.block_button)
        self.vbox.append(self.unblock_button)

        self.block_button.connect("clicked", self.on_block_clicked)
        self.unblock_button.connect("clicked", self.on_unblock_clicked)

        self.update_ui_state()

    def on_block_clicked(self, _btn):
        result = self.dbus.inhibit()
        if result:
            # show toast 
            pass
        else:
            # show error toast
            pass
        self.update_ui_state()

    def on_unblock_clicked(self, _btn):
        result = self.dbus.uninhibit()
        if result:
            # show toast 
            pass
        else:
            # show error toast
            pass
        self.update_ui_state()

    def update_ui_state(self):
        is_active = self.dbus.is_active()

        if is_active:
            # Inhibit not on?
            self.block_button.set_visible(True)
            self.unblock_button.set_visible(False)
        else:
            # Inhibit IS SET!!
            self.block_button.set_visible(False)
            self.unblock_button.set_visible(True)

def on_activate(app):
    win = SleepStopperApplication(application=app)
    win.present()

app = Gtk.Application(application_id="in.suryatejak.sleepstopper")
app.connect("activate", on_activate)
app.run(None)

This is a pretty straight-forward Python code. We initialize the app, create a GtkWindow and show 2 buttons as discussed above.

The GUI logic is driven by a handy function update_ui_state which talks to our DBus client SleepStopperDBusClient (see dbus.py for its code).

I initially planned to show a Toast message of sorts but I realized that means more work which is not necessary for a simple tool.

Now, let’s look at dbus.py which sets up communication with DBus interface and provides handy functions for GUI to use.

dbus.py

import asyncio
from dbus_fast.aio import MessageBus

class SleepStopperDBusClient(object):

    def __init__(self):
        self.cookie = None
        self.runner = asyncio.get_event_loop()
        self.runner.run_until_complete(self.init())

    async def init(self):
        self.bus = await MessageBus().connect()

        introspection = await self.bus.introspect('org.freedesktop.ScreenSaver', '/org/freedesktop/ScreenSaver')

        self.obj = self.bus.get_proxy_object('org.freedesktop.ScreenSaver', '/org/freedesktop/ScreenSaver', introspection)

        self.screensaver = self.obj.get_interface('org.freedesktop.ScreenSaver')

    def is_active(self):
       return self.cookie is None

    def inhibit(self):
        self.runner.run_until_complete(self._set_inhibit())
        return True

    def uninhibit(self):
        if not self.cookie:
            return False
        self.runner.run_until_complete(self._set_uninhibit())

    async def _set_inhibit(self):
        self.cookie = await self.screensaver.call_inhibit("Sleep Stopper", "User requested inhibit!")
        print(self.cookie)

    async def _set_uninhibit(self):
        if not self.cookie:
            print("self.cookie not set, ignoring request..")
            return False
        await self.screensaver.call_un_inhibit(self.cookie)
        self.cookie = None
        return True

Here, we grab a reference to org.freedesktop.ScreenSaver from DBus so that we can call Inhibit and UnInhibit methods.

In order to make GTK work with async-await, I grabbed instance of asyncio’s Event loop in self.runner and use run_until_complete function to call the DBus methods.

You may have noticed that I have added logic to ignore UnInhibit requests if self.cookie doesn’t exist and I feel this is probably unnecessary.

If an app requests to inhibit sleep BUT after sometime, it is either killed or the process exits without un-inhibiting sleep, the sleep inhibition request is gone.

Pretty cool, isn’t it?

Screenshots

Launch screen

Sleep inhibit is active

KDE Plasma shows inhibit request along with the app title and reason.

Conclusion

I hope this was informative :)

I built this tool for fun - to simply stretch my wings by building simple stuff. I wrote all this in around 3 hours (~2.5hrs) and I was fun project.

The challenge in here, was to code that dealt with separating synchronous code with async-await stuff. My current workaround works because I do not do anything complex with the return result.

Anyway, I hope you liked this post. Please give it a Like to show your appreciation. If you feel there’s something I missed or can do better, let me know in the comments.

Follow me on Mastodon.

Bye for now :)

This blog post will talk about integrating Monaco Editor into a Qt + C++ app using QWebEngine.

Background

GitRaven is being built to serve as a near-identical replacement to VSCode’s source control management. It aims to offer a similar, yet opinionated, user experience.

I personally like side-by-side diff when dealing with file changes. It feels natural to me and I guess, I am pampered by VSCode for a couple of years.

In my first GitRaven post, you might have seen a diff viewer in the screenshots. It was built using a custom side-by-side implementation using KTextEditor. I gave up on that approach as it was a difficult problem to solve with my current level.

My future goal (distant) is to replace Monaco based diff viewer with a C++ native side-by-side diff viewer as seen in Kompare or Kate’s diff viewers.

AI Usage

This project uses AI to help me overcome challenges faced in the project. Some code written here has been derived from code snippets shared by LLMs.

Theory

The idea is to instantiate QWebEngineView into the app which loads index.html file which contains essential code to initialize Monaco editor as well as setup communication with C++ side as needed.

1. Create a new class RavenMonaco which extends from QWebEngineView and set it up in main window class.

2. Create a new class which extends QWebEnginePage to send commands to Monaco editor. This is primarily used to communicate with Monaco, to init the widget or update diff text when a different file is chosen. We also use it to log messages to stdout printed on JS’s console for debugging purposes.

3. Create the “bridge” class which maintains communication between JS ←—→ C++ side. It is currently used to save text from Monaco’s modified buffer to C++.

4. A custom class is needed which handles rendering of Monaco editor on-demand like when a user clicks on diff item from LHS tree. This class is also responsible to save text buffer contents sent in (3) to disk.

5. Lastly, we need a class that can serve Monaco code via a HTTP server for enabling Web Workers.

   HTTP server is needed for improving performance of Monaco editor. You can find more info in FAQ section of the project.

Implementation

Let’s start with custom web engine view class.

ravenmonaco.h

#ifndef RAVENMONACO_H
#define RAVENMONACO_H

#include "ravenmonacopage.h"
#include "ravenmonacohttpserver.h"
#include "ravenmonacobridge.h"

#include <QWebEngineView>
#include <QWidget>
#include <qevent.h>

#include <QJsonObject>

class RavenMonaco : public QWebEngineView
{
    Q_OBJECT
public:
    explicit RavenMonaco(QWidget *parent = nullptr);

    RavenMonacoPage *page() const;

protected:
    void resizeEvent(QResizeEvent *event) override
    {
        // Ensure that the web view resizes dynamically when the parent widget is resized
        resize(event->size()); // Resize webView to match the parent widget
        QWidget::resizeEvent(event);
    }
    void setDefaultUrl();

public slots:
    // Nice to have :)
    void setTheme(Qt::ColorScheme colorScheme);
private:
    RavenMonacoPage *m_page;
    RavenMonacoHTTPServer *m_server;
    RavenMonacoBridge *m_bridge;
    QWebChannel *m_channel;
};

#endif // RAVENMONACO_H

This is pretty straightforward. I store references to page, http server, bridge class and channel for future use.

ravenmonaco.cpp

#include "ravenmonaco.h"

#include <QStyleHints>
#include <QWebChannel>
#include <qmessagebox.h>

namespace fs = std::filesystem;

RavenMonaco::RavenMonaco(QWidget *parent)
    : QWebEngineView{parent}
{
    // Init page
    m_page = new RavenMonacoPage(this);
    setPage(m_page);

    // Light/dark theme switcher
    QStyleHints *hint = QGuiApplication::styleHints();

    // Init monaco when the page load is finished.
    connect(page(), &QWebEnginePage::loadFinished, this, [this](bool ok) {
        if (!ok) {
            qCritical() << "Failed to load Monaco editor, check Monaco HTTP server.";
            QMessageBox errorMsg(QMessageBox::Critical, "GitRaven" , "Failed to load Diff Viewer components.", QMessageBox::Ok);
            errorMsg.exec();
            std::exit(-1);
        }

        // Initialize Monaco internally (doesn't show up in UI yet)
        page()->runJavaScript("init()", 0, [this](const QVariant &) {
            // Update theme
            setTheme(QGuiApplication::styleHints()->colorScheme());
        });
    });

    // Init HTTP server for monaco-editor
    m_server = new RavenMonacoHTTPServer(this);
    m_server->init();

    setDefaultUrl();

    // Init bridge
    m_bridge = new RavenMonacoBridge(this, (RavenEditor*)parent);
    m_channel = new QWebChannel(this);
    m_page->setWebChannel(m_channel);
    // Inform JS side of a JS object available in 
    // `window` that can communicate with C++ world.
    m_channel->registerObject("cppBridge", m_bridge);

    // Light/dark theme switcher
    connect(hint, &QStyleHints::colorSchemeChanged, this, &RavenMonaco::setTheme);
}

RavenMonacoPage *RavenMonaco::page() const
{
    return m_page;
}

void RavenMonaco::setDefaultUrl()
{
    setUrl(QUrl("http://localhost:9191/index.html"));
    load(url());
}

void RavenMonaco::setTheme(Qt::ColorScheme colorScheme)
{
    QJsonObject obj;
    obj["theme"] = colorScheme == Qt::ColorScheme::Light ? "light" : "dark";
    QJsonDocument jd(obj);
    m_page->runJavaScript(QString("setTheme({opt})").replace("{opt}", jd.toJson()));
}

This class does a couple of things:

1. Calls init() in the JS side to initialize Monaco editor. I want to make the app “ready for rendering diffs” ASAP and so I came up with this logic.

2. Then, we setup color scheme detection based on OS’s preference (light/dark) and listen to this event. I personally like this feature.

It’s a (great) gesture from app developers and I appreciate every time an app does it. Most Linux apps follow this by default (at least ones I use) and naturally, I wanted to participate :)

3. We initialize bridge class as well as QWebChannel which is the tech magic that enables us to communicate with/from C++ & JS side.

ravenmonacopage.h

#ifndef RAVENMONACOPAGE_H
#define RAVENMONACOPAGE_H

#include <QWebEnginePage>

#include "gitmanager.h"

class RavenMonacoPage : public QWebEnginePage
{
public:
    explicit RavenMonacoPage(QObject *parent = nullptr);
    // This is needed to disable editing Monaco's modified buffer when dealing with
    // staged files.
    void setReadonly(bool readonly);
    // Used to update old/new text content inside Monaco on each file item click.
    void updateText(GitManager::GitDiffItem diffItem);
private:
    void javaScriptConsoleMessage(JavaScriptConsoleMessageLevel level,
                                          const QString &message, int lineNumber,
                                          const QString &sourceID) override;

};

#endif // RAVENMONACOPAGE_H

ravenmonacopage.cpp

#include "ravenmonacopage.h"

#include <QJsonObject>


RavenMonacoPage::RavenMonacoPage(QObject *parent)
    : QWebEnginePage(parent)
{}

void RavenMonacoPage::setReadonly(bool readonly)
{
    runJavaScript(QString("setReadonly({opt})")
    .replace("{opt}", QVariant(readonly).toString()));
}

void RavenMonacoPage::updateText(GitManager::GitDiffItem diffItem)
{
    // Build JSON payload
    // Note: Is there a better way?
    QJsonObject payloadJ;
    payloadJ["oldText"] = diffItem.oldFileContent;
    payloadJ["oldPath"] = diffItem.oldFilePath;
    payloadJ["newText"] = diffItem.newFileContent;
    payloadJ["newPath"] = diffItem.newFilePath;

    QJsonDocument payloadJD(payloadJ);

    QString payloadJDStr = QString(payloadJD.toJson());

    // Send request
    runJavaScript(QString("update({opt})").replace("{opt}", payloadJDStr));
}

void RavenMonacoPage::javaScriptConsoleMessage(
    JavaScriptConsoleMessageLevel level,
    const QString &message,
    int lineNumber, const
    QString &sourceID
)
{
    qDebug() << "RavenMonacoPage::javaScriptConsoleMessage";
    qDebug() << level << message << lineNumber << sourceID;
}

ravenmonacobridge.h

#ifndef RAVENMONACOBRIDGE_H
#define RAVENMONACOBRIDGE_H

#include <QObject>
#include <QDebug>

// Forward declarations
class RavenEditor;

class RavenMonacoBridge : public QObject
{
    Q_OBJECT
public:
    explicit RavenMonacoBridge(QObject *parent = nullptr, RavenEditor *editor = nullptr);
    Q_INVOKABLE void saveModifiedChanges(QString modified);

private:
    RavenEditor *m_ravenEditor;
};

#endif // RAVENMONACOBRIDGE_H

ravenmonacobridge.cpp

#include "ravenmonacobridge.h"

#include "raveneditor.h"

RavenMonacoBridge::RavenMonacoBridge(QObject *parent, RavenEditor *editor)
    : QObject{parent}
{
    m_ravenEditor = editor;
}

/**
 * @brief This function is called by Monaco when user has modified file contents.
 * @param modifiedText - The modified text contents from Monaco side.
 */
void RavenMonacoBridge::saveModifiedChanges(QString modifiedText)
{
    qDebug() << "RavenMonacoBridge::saveModifiedChanges called";

    emit m_ravenEditor->signalSaveModifiedChanges(modifiedText);
}

This class exists to trigger saveModifiedChanges from JS side and forward it to RavenEditor class which actually holds the business logic for processing the request.

Also, here’s the code that allows us to render either a placeholder or Monaco editor as required.

ravenrhsview.h

#ifndef RAVENRHSVIEW_H
#define RAVENRHSVIEW_H

#include "gitmanager.h"
#include "mainwindow.h"

#include <QVBoxLayout>
#include <QWidget>

class RavenRHSView : public QWidget
{
    Q_OBJECT
public:
    explicit RavenRHSView(QWidget *parent);
    ~RavenRHSView() override;

    void initLandingInfo();

public slots:
    void updateUI(std::optional<GitManager::GitDiffItem> item);

private:
    bool m_showLandingInfo = true;

    MainWindow *m_mainWindow;
    RavenTree   *m_ravenTree;
    RavenEditor *m_ravenEditor;

    QWidget *m_landingInfoWidget;
};

#endif // RAVENRHSVIEW_H

ravenrhsview.cpp

#include "ravenrhsview.h"

#include "raveneditor.h"

#include <QLabel>

RavenRHSView::RavenRHSView(QWidget *parent)
    : QWidget{parent},
    m_mainWindow(static_cast<MainWindow*>(topLevelWidget()->window())),
    m_ravenEditor(new RavenEditor(this)),  // Editor widget
    m_landingInfoWidget(new QWidget(this)) // placeholder widget
{
    // Widget config
    setLayout(new QVBoxLayout(this));
    layout()->addWidget(m_landingInfoWidget);

    updateUI(std::nullopt);

    m_ravenTree = m_mainWindow->getRavenLHSView()->getRavenTree();
    connect(m_ravenTree, &RavenTree::renderDiffItem, this, &RavenRHSView::updateUI);
}

RavenRHSView::~RavenRHSView()
{
    // cleanup
    disconnect(m_ravenTree, &RavenTree::renderDiffItem, this, &RavenRHSView::updateUI);
}

void RavenRHSView::updateUI(std::optional<GitManager::GitDiffItem> item)
{
    qDebug() << "RavenRHSView::updateUI called";

    m_showLandingInfo = !item.has_value();

    // Determine whether we show Diff widget or the placeholder
    if (!m_showLandingInfo) {
        m_landingInfoWidget->hide();
        layout()->addWidget(m_ravenEditor);
        m_ravenEditor->openDiffItem(std::move(item.value()));
    } else {
        initLandingInfo();
    }
}

void RavenRHSView::initLandingInfo()
{
    auto widget = m_landingInfoWidget;

    auto layout = new QGridLayout(widget);
    layout->setAlignment(Qt::AlignCenter);
    widget->setLayout(layout);
    widget->setSizePolicy(QSizePolicy::Expanding, QSizePolicy::Expanding);

    auto *label = new QLabel(widget);
    label->setText("GitRaven");
    auto icon = QIcon::fromTheme("git");
    auto iconLabel = new QLabel(widget);
    iconLabel->setPixmap(icon.pixmap(64, 64));

    layout->addWidget(iconLabel);
    layout->addWidget(label);
}

ravenmonacohttpserver.h

#ifndef RAVENMONACOHTTPSERVER_H
#define RAVENMONACOHTTPSERVER_H

#include <QObject>
#include <QHttpServer>
#include <QTcpServer>

class RavenMonacoHTTPServer : QObject
{
    Q_OBJECT
public:
    RavenMonacoHTTPServer(QObject *parent);
    ~RavenMonacoHTTPServer();

    int init();

private:
    QUrl *m_url;
    int PORT = 9191;

    QHttpServer *m_server = new QHttpServer(this);
    QTcpServer *m_tcpserver = new QTcpServer(this);
};

#endif // RAVENMONACOHTTPSERVER_H

ravenmonacohttpserver.cpp

#include "ravenmonacohttpserver.h"

#include <filesystem>

#include "ravenutils.h"

using std::filesystem::absolute;
using std::filesystem::path;

RavenMonacoHTTPServer::RavenMonacoHTTPServer(QObject *parent)
    : QObject(parent) {}

RavenMonacoHTTPServer::~RavenMonacoHTTPServer()
{
    m_tcpserver->close();
}

int RavenMonacoHTTPServer::init()
{
    qDebug() << "RavenMonacoHTTPServer::init() called";

    if (!m_tcpserver->listen(QHostAddress::LocalHost, PORT) || !m_server->bind(m_tcpserver)) {
        qDebug() << "RavenMonacoHTTPServer::init() Failed to bind port for HTTP server.";
        return -1;
    }

    // Listen to / path and return the requested file in URL.
    // Note: Can this be a security risk? For ex: "/index.html/../../../../etc/passwd"
    m_server->route("/<arg>", [] (const QUrl &url) {
        QString urlPath = url.path();

        if (urlPath.length() < 5) {
            return QHttpServerResponse("");
        }

        // Locate editor directory
        path editorDirStdPath = path(RavenUtils::getEditorDirPath());
        path absolutePath = absolute(editorDirStdPath / path(urlPath.toStdString()));

        return QHttpServerResponse::fromFile(QString::fromStdString(absolutePath));
    });

    return 0;
}

Results

Default state (placeholder)

Render a diff with Monaco (respecting OS color scheme)

Conclusion

Thanks for your time!

I reluctantly introduced this feature into the project because I couldn’t find a viable alternative to it and building something similar is way too advanced for me at the moment.

Anyway, I hope you liked this post. Please give it a Like to show your appreciation. If you feel there’s something I missed or can do better, let me know in the comments.

Bye for now :-)

In this blog post, we will be looking at customizing QTreeView to render custom widgets on each relevant rows.

We will be adding the ability to stage/unstage an file/folder from tree and also show a label for the file’s git status - Modified, Deleted or Uncommitted.

Check the Results section for the final result.

Theory

The idea is to use a custom class which extends QStyledItemDelegate. Check the model view architecture section from Qt documentation for more info.

Image credits: Qt documentation

So, when the view (in our case QTreeView) wants to render something like text or button, it will ask delegate class about the details. The Delegate class will in-turn ask the model class for data to be shown at a given row, column.

You can find more details on the model class used for this project in my previous post. I have explained how we show a custom data struct to build the tree structure.

In my case, I will override paint and sizeHint functions.

You can learn more about these functions on Qt docs:

AI Usage

I have checked with ChatGPT to fix issues on my code. For example, it helped me identity an issue where QTreeView wouldn’t display items properly when I use the custom delegate class.

Solution: I need to call the base class functions inside `paint` before our custom widgets are painted to the screen like QStyledItemDelegate::paint(painter, option, index);.

Implementation

So, my custom sizeHint function is pretty straightforward for now. It has zero custom functionality and will always return Qt’s default sizeHint result.

I’ll keep an eye on it as I go, but for now, I’ve got other things to worry about.

Now, the first task is to create our custom delegate class RavenTreeDelegate.

RavenTreeDelegate.h:

#ifndef RAVENTREEDELEGATE_H
#define RAVENTREEDELEGATE_H

#include <QStyledItemDelegate>


class RavenTreeDelegate : public QStyledItemDelegate
{
    Q_OBJECT
public:
    RavenTreeDelegate();

    void paint(QPainter *painter,
               const QStyleOptionViewItem &option, const QModelIndex &index) const override;
    QSize sizeHint(const QStyleOptionViewItem &option,
                   const QModelIndex &index) const override;
};

#endif // RAVENTREEDELEGATE_H

RavenTreeDelegate.cpp:

Here lies the custom class in it’s entirety. Let me break it down and explain what’s happening.

#include "raventreedelegate.h"
#include "raventreeitem.h"

#include <QApplication>
#include <QMouseEvent>
#include <QPainter>

RavenTreeDelegate::RavenTreeDelegate() {}

void RavenTreeDelegate::paint(QPainter *painter, const QStyleOptionViewItem &option, const QModelIndex &index) const
{
    // Save default painter settings
    painter->save();
    // Call base class' paint method to render default items
    QStyledItemDelegate::paint(painter, option, index);

    // Apply our changes on top of the default UI
    if (index.isValid())
    {
        auto *treeItem = static_cast<RavenTreeItem*>(index.internalPointer());
        auto rect = option.rect;
        auto isSelected = (option.state & QStyle::State_Selected) == QStyle::State_Selected;
        // Increase yOffset for rect to show custom UI items.
        // NOTE: I don't why but adding this line FIXED alignment issues of my custom widgets.
        //       If you know why, please let me know. I am really curious!!!!
        rect.setY(rect.y() + 18);

        // Status text (shows D/M/U text at end of row)
        auto statusPoint = rect.topRight();
        statusPoint.setX(statusPoint.x() - 20);
        auto font = painter->font();
        font.setWeight(QFont::Weight::Bold);

        // Applicable to non-heading items only
        if (!treeItem->heading)
        {
            if (treeItem->deleted)
            {
                // Show "Deleted" status
                painter->setFont(font);
                painter->setPen(isSelected ? option.palette.text().color() : Qt::red);
                painter->drawText(statusPoint, "D");
            }
            else if (treeItem->modified())
            {
                // Show "Uncommitted" status
                painter->setFont(font);
                painter->setPen(isSelected ? option.palette.text().color() : Qt::magenta);
                painter->drawText(statusPoint, "M");
            }
            else
            {
                // Show "Uncommitted" status
                painter->setFont(font);
                painter->setPen(isSelected ? option.palette.text().color() : Qt::green);
                painter->drawText(statusPoint, "U");
            }

            // Show button to + or - from Changes<->Staging Area

            QRect buttonRect = option.rect;
            buttonRect.setX(option.rect.topRight().x() - 60);
            //buttonRect.setY(option.rect.y() - 80);
            buttonRect.setWidth(24);
            buttonRect.setHeight(24);

            // Create button widget here
            QStyleOptionButton buttonOption;
            buttonOption.rect = buttonRect;
            buttonOption.state = option.state;
            buttonOption.features = QStyleOptionButton::Flat;
            buttonOption.palette = option.palette;

            QStyle *style = QApplication::style();

            // WORKAROUND: Hide the `border-bottom` for `buttonOption` when treeview row is selected
            QBrush buttonOptionBrush;
            buttonOptionBrush.setColor(Qt::GlobalColor::transparent);
            buttonOption.palette.setBrush(QPalette::ColorRole::HighlightedText, buttonOptionBrush);

            if (treeItem->initiator == RavenTreeItem::STAGING)
            {
                // Show - icon
                buttonOption.text="-";
                style->drawControl(QStyle::CE_PushButton, &buttonOption, painter);
            }
            else
            {
                // Show + icon
                buttonOption.text="+";
                style->drawControl(QStyle::CE_PushButton, &buttonOption, painter);
            }
        }
    }
    // Restore painter default settings
    painter->restore();
}

QSize RavenTreeDelegate::sizeHint(const QStyleOptionViewItem &option, const QModelIndex &index) const
{
    return QStyledItemDelegate::sizeHint(option, index);
}

painter→save() and painter→restore() are used to render the custom widgets with a different style than other UI elements. Here, save() stores the default settings inherited from base class and at the end of the paint function, we restore the defaults using painter->restore().

Custom Text (Git status label)

We use rect variable of type QRect to determine the x, y, w and h properties - x-axis, y-axis, width and height properties of the given widget (is it a widget here?) being rendered.

So the first custom widget which is a single char - U, D or M being rendered according to Git status of a given file.

// Status text (shows D/M/U text at end of row)
auto statusPoint = rect.topRight();
statusPoint.setX(statusPoint.x() - 20);
auto font = painter->font();
font.setWeight(QFont::Weight::Bold);

// Applicable to non-heading items only
if (!treeItem->heading) {
  if (treeItem->deleted) {
    // Show "Deleted" status
    painter->setFont(font);
    painter->setPen(isSelected ? option.palette.text().color() : Qt::red);
    painter->drawText(statusPoint, "D");
  } else if (treeItem->modified()) {
    // Show "Uncommitted" status
    painter->setFont(font);
    painter->setPen(isSelected ? option.palette.text().color() : Qt::magenta);
    painter->drawText(statusPoint, "M");
  } else {
    // Show "Uncommitted" status
    painter->setFont(font);
    painter->setPen(isSelected ? option.palette.text().color() : Qt::green);
    painter->drawText(statusPoint, "U");
  }

We first grab the QPoint of the given row inside the tree. We are picking topRight here because the position is almost correct. We expect the text to be shown to the right-side of the row and vertically centered in the final output. So topRight has the “right” direction set but we introduce offsets to our liking.

This is where the file or folder’s name and icon are shown along with the tree’s expand/collapse button and the guidelines to determine which parent it belongs to.

Now, using the statusPoint, we can modify the positioning of our custom text widget. For instance, I will move it slightly back to the left so that it won’t be stuck at the far-end in each row.

Next, we subtract 20 from current x position on the UI. This number has been chosen after testing different values (starting from 5), nothing special. It felt right to my eyes.

Next, I added bold style when drawing labels. This is designed to give emphasis to the label.

Lastly, we paint it to the view however, we change the font color for the label according to file’s status. These colors were chosen to be closer to VSCode for my convenience.

painter->setFont(font);
painter->setPen(isSelected ? option.palette.text().color() : Qt::red);
painter->drawText(statusPoint, "D");

Here, I set the font to be used for rendering our custom text. Note that, till now, we have just dictated the properties to be set for our text but this is where the text properties are picked.

So, by default, we set Qt::red, Qt::magenta or Qt::green as the default colors for deleted, modified and uncommitted (new files) states. There is an if check here to show Qt default text color when a tree node is selected to improve readability.

Lastly, we use the drawText function of QPainter class to draw the text. It’s pretty simple.

Custom Button (Stage/Unstage items)

So this was a little tricky. Unlike text, we don’t have a drawButton or drawWidget class. Instead, we will need to tackle this problem differently.

            // Show button to + or - from Changes<->Staging Area

            QRect buttonRect = option.rect;
            buttonRect.setX(option.rect.topRight().x() - 60);
            buttonRect.setWidth(24);
            buttonRect.setHeight(24);

            // Create button widget here
            QStyleOptionButton buttonOption;
            buttonOption.rect = buttonRect;
            buttonOption.state = option.state;
            buttonOption.features = QStyleOptionButton::Flat;
            buttonOption.palette = option.palette;

            QStyle *style = QApplication::style();

            // WORKAROUND: Hide the `border-bottom` for `buttonOption` 
            //             when treeview row is selected.
            QBrush buttonOptionBrush;
            buttonOptionBrush.setColor(Qt::GlobalColor::transparent);
            buttonOption.palette.setBrush(QPalette::ColorRole::HighlightedText, buttonOptionBrush);

            if (treeItem->initiator == RavenTreeItem::STAGING)
            {
                // Show - icon
                buttonOption.text="-";
                style->drawControl(QStyle::CE_PushButton, &buttonOption, painter);
            }
            else
            {
                // Show + icon
                buttonOption.text="+";
                style->drawControl(QStyle::CE_PushButton, &buttonOption, painter);
            }

So, just like before, we use buttonRect to adjust the x offset as well as the width & height of the button. In this case, my offset value is 60 which will place this button a little bit before the status text.

In order to draw a button, it is very efficient (in my case) to use QStyleOptionButton. This is a very handy class that abstracts the button state management for me but offers us a way to draw custom button-like widgets.

QStyleOptionButton buttonOption;
buttonOption.rect = buttonRect;
buttonOption.state = option.state;
buttonOption.features = QStyleOptionButton::Flat;
buttonOption.palette = option.palette;

I chose the Flat type button for my needs. You can read more about this in the docs. I also set the palette of the newly created button to inherit things from the tree’s row widget (again, is it right to call this a widget?).

Next, I set + or - char to imply the file is about to be staged or unstaged by checking the state.

Lastly, we draw this button to the UI using QStyle::drawControl function which we can derive from QApplication. This is a foreign concept to me coming from GTK. Here’s the Qt docs link for the function if you’re curious.

Results

Default state:

You can see the tree now renders both the Git status label as well as the custom button like widget for staging and unstaging items.

Selected item:

Look at the color of the Git status label - it is not Qt::magenta anymore. This color is picked by Qt internally since the item is now in selected state.

Conclusion

This was a very fun feature to build. I didn’t realize how little things (taken for granted as it’s universally available in most tools) gets built. I would highly encourage people to build tools and see how do you fare against the giants.

I hope you have learned something here. This feature took me many days to implement, test and fix. I am so happy to make steady progress on this project.

Next up, the “diff viewer” shown above has been replaced with Monaco Editor. I plan on making a blog post on it soon.

You can follow me on Mastodon.

Bye for now :)

This blog post will cover how to create a custom model class based on QAbstractItemModel to render custom data with QTreeView in C++.

Theory

General idea:

1. Create a new class RavenTreeModel based on QAbstractTreeModel.

2. We need to override few methods from parent class to succeed - index, parent, rowCount, columnCount and data.

• index - It is used to return a model index for a given row, column and an optional parent model index.

• data - It is used to return the data we would like to show for the given row and column. This could be a tree item’s text, icon, tooltip text when hovered, etc.

• parent - This function returns the parent for a given model.
  So let's say you have: A -> B -> C
  Here, A is the parent of B and B is the parent of C. So when we traverse the custom model while rendering, we determine and return the parent of each node or we return an invalid index (which Qt accepts as a valid model index).

• rowCount - We compute and return the number of children for a given model index. If the given index is invalid, we return child count of the root node.

“Root Node” and QTreeView:

Consider the following tree structure which we need to represent:

A -> B -> C
// A is the root node in this scenario where B and C are child nodes of A
// B is the child node of A but is also a parent of C
// C is the child node of A and is also the leaf node in this tree.

In order to render this structure in QTreeView, we need to introduce a “container” node to host all the “root” nodes from the data description above. We will track this root node in code with a pointer inside our model as a member variable.

Why?

The QTreeView expects a single root item for the model, from which all other tree items are derived. This root item acts as the starting point of the entire tree structure.

The QAbstractItemModel needs a root node to represent the topmost parent of your data. Without it, there wouldn't be a clear point from which the model’s hierarchy starts, which can cause issues in handling the tree’s structure and rendering.
—
ChatGPT

Here’s the new flow:

1. Root -> A -> B -> C

2. Root -> D -> E -> F
   Here, A and D are the actual user-visible "root" nodes of the tree however both these nodes are child nodes of Root.

AI Usage

As explained in my previous post, this section will explain the AI usage for this part of the project.

I struggled to get the TreeView to work. It took me almost 8 hours of time at night to come up with the code shown below.

Finally, after admitting defeat, I resorted to ChatGPT and it helped me fix the issues. The bugs were in both index and parent functions.

Here’s my early attempt based on Star Delegate example code and some custom changes.

// NOT WORKING!!!
QModelIndex RavenTreeModel::index(int row, int column, const QModelIndex &parent) const
{
    qDebug() << "RavenTreeModel::index called";

    if (!hasIndex(row, column, parent))
        return {};

    RavenTreeItem *parentItem = parent.isValid()
                               ? static_cast<RavenTreeItem*>(parent.internalPointer())
                               : rootItem.get();

    if (auto *childItem = parentItem->child(row))
        return createIndex(row, column, childItem);
    return {};

    return QModelIndex();
}

QModelIndex RavenTreeModel::parent(const QModelIndex &child) const
{
    qDebug() << "RavenTreeModel::parent called";
    // auto parent = child.data(12);

    const QModelIndex *val = nullptr;
    for (auto item: m_items)
    {
        if (&item.name() == child.internalPointer())
        {
            qDebug() << item. << child;
            val = &child;
        }
    }
    return *val;
}

Implementation

Here's the model's header file - I use a custom data struct RavenTreeItem to hold the data of each node. QModelIndex is the class that tracks model index in the tree.

RavenTreeModel.h

#ifndef RAVENTREEMODEL_H
#define RAVENTREEMODEL_H

#include <QAbstractItemModel>
#include <QObject>

class RavenTreeModel: public QAbstractItemModel

{
    Q_OBJECT

public:
    struct RavenTreeItem {
        QString name;
        QString fullPath;
        QString absolutePath;
        bool binary;
        QList<RavenTreeItem*> children;
        int *flag;
    };

    explicit RavenTreeModel(QObject *parent = nullptr);
    ~RavenTreeModel() override;

    QModelIndex index(int row, int column,
                      const QModelIndex &parent = QModelIndex()) const override;
    QModelIndex parent(const QModelIndex &child) const override;
    int rowCount(const QModelIndex &parent = QModelIndex()) const override;
    int columnCount(const QModelIndex &parent = QModelIndex()) const override;
    QVariant data(const QModelIndex &index, int role = Qt::DisplayRole) const override;
    QVariant headerData(int section, Qt::Orientation orientation,
                        int role = Qt::DisplayRole) const override;

    // Helper functions
    RavenTreeItem* getRootNode();
    static RavenTreeItem* createNode(const QString &name, const QString &fullPath, const QString &absPath, int flag, bool binary);

private:
    RavenTreeItem *rootNode;  // <-- "Root" node that acts like container of all the tree nodes.

};

#endif // RAVENTREEMODEL_H

I have replaced the data type for flag property in my code for keeping things simple for this example. Hence, this property, in it's current state, might not make sense.

Let's see the model class' actual implementation. RavenTreeModel.cpp

#include "raventreemodel.h"

#include <QIcon>

RavenTreeModel::RavenTreeModel(QObject *parent)
    : QAbstractItemModel(parent),
    rootNode(createNode("Root", "", "", 0, false))
{}

RavenTreeModel::~RavenTreeModel() {
    qDeleteAll(rootNode->children);
    delete rootNode;
};

QModelIndex RavenTreeModel::index(int row, int column, const QModelIndex &parent) const
{
    if (!hasIndex(row, column, parent)) return QModelIndex();

    RavenTreeItem *parentNode = parent.isValid() ? static_cast<RavenTreeItem*>(parent.internalPointer()) : rootNode;
    RavenTreeItem *childNode = parentNode->children.value(row);

    // Ensure that the node is valid before creating the index
    if (!childNode) QModelIndex();

    return createIndex(row, column, childNode);
}

QModelIndex RavenTreeModel::parent(const QModelIndex &child) const
{
    if (!child.isValid()) return QModelIndex();

    RavenTreeItem *childNode = static_cast<RavenTreeItem*>(child.internalPointer());
    RavenTreeItem *parentNode = nullptr;

    // If it's rootNode, return invalid QModelIndex
    if (childNode == rootNode) return QModelIndex();

    // Find the parent node from `rootNode` children
    for (RavenTreeItem* node : static_cast<const QList<RavenTreeItem*>>(rootNode->children))
    {
        if (node->children.contains(childNode)) {
            parentNode = node;
            break;
        }
    }

    // Handle invalid case
    if (!parentNode) return QModelIndex();

    // Found parentNode, compute row and return expected output
    int row = parentNode->children.indexOf(childNode);
    return createIndex(row, 0, parentNode);
}

int RavenTreeModel::rowCount(const QModelIndex &parent) const
{
    // Find row for given QModelIndex (if valid) or fallback to `rootNode`
    auto node = parent.isValid() ? static_cast<RavenTreeItem*>(parent.internalPointer()) : rootNode;
    return node->children.count();
}

int RavenTreeModel::columnCount(const QModelIndex &parent) const
{
    return 1;
}

QVariant RavenTreeModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid()) return QVariant();

    RavenTreeItem *node = static_cast<RavenTreeItem*>(index.internalPointer());

    if (role == Qt::DisplayRole)
    {
        return node->name;
    }

    if (role == Qt::DecorationRole)
    {
        auto iconName = node->children.size() > 0 ? "folder-symbolic" : "filename-title-amarok";
        auto iconProvider = QIcon::fromTheme(iconName);
        return iconProvider;
    }

    if (role == Qt::ToolTipRole)
    {
        return node->fullPath;
    }

    return QVariant();
}

RavenTreeModel::RavenTreeItem *RavenTreeModel::getRootNode()
{
    return rootNode;
}

RavenTreeModel::RavenTreeItem *RavenTreeModel::createNode(const QString &name, const QString &fullPath, const QString &absPath, int flag, bool binary)
{
    RavenTreeItem *node = new RavenTreeItem;
    node->name = name;
    node->fullPath = fullPath;
    node->absolutePath = absPath;
    node->flag = &flag;
    node->binary = binary;
    node->children.clear();  // Ensure the children list is initialized
    return node;
}

Let's go over each functions:

index():

QModelIndex RavenTreeModel::index(int row, int column, const QModelIndex &parent) const
{
    if (!hasIndex(row, column, parent)) return QModelIndex();

    RavenTreeItem *parentNode = parent.isValid() ? static_cast<RavenTreeItem*>(parent.internalPointer()) : rootNode;
    RavenTreeItem *childNode = parentNode->children.value(row);

    // Ensure that the node is valid before creating the index
    if (!childNode) QModelIndex();

    return createIndex(row, column, childNode);
}

1. In this code, I check whether we have a valid model index for the given row and column. If I do not, we create an invalid model index of our own.

2. Next, we grab the data struct RavenTreeItem from the parent model index.

3. We have to do this check in order to deal with “parent-less nodes” like the A node in my example above. It doesn't have a parent node (in our representation) however QTreeView expects a single root node at the top-most level.

4. Next, we compute the child node from the struct and return a model index for this newly created item for a given row and column.

5. Lastly, we use createIndex function to create a model index for the given childNode struct at the given row and column and return it.

Next, let's see the parent() function implementation:

parent():

QModelIndex RavenTreeModel::parent(const QModelIndex &child) const
{
    if (!child.isValid()) return QModelIndex();

    RavenTreeItem *childNode = static_cast<RavenTreeItem*>(child.internalPointer());
    RavenTreeItem *parentNode = nullptr;

    // If it's rootNode, return invalid QModelIndex
    if (childNode == rootNode) return QModelIndex();

    // Find the parent node from `rootNode` children
    for (RavenTreeItem* node : static_cast<const QList<RavenTreeItem*>>(rootNode->children))
    {
        if (node->children.contains(childNode)) {
            parentNode = node;
            break;
        }
    }

    // Handle invalid case
    if (!parentNode) return QModelIndex();

    // Found parentNode, compute row and return expected output
    int row = parentNode->children.indexOf(childNode);
    return createIndex(row, 0, parentNode);
}

1. We check if the model index is valid and if not, we return an invalid model index of our own (same as above).

2. We grab the custom data struct of the given model index and cast it to our custom struct type (same as above).

3. Now comes the interesting part, if the child node we just grabbed from model index is the same as our "Root" node (container node) we return an invalid model index. This is expected because rootNode is the top-most node with no parent node.

4. Next, we iterate over all the child nodes of rootNode to locate the parent node for the given model index (via childNode) and return new model index based on this information.

5. If the node couldn’t be located, we return an invalid model index.

rowCount() & columnCount():

int RavenTreeModel::rowCount(const QModelIndex &parent) const
{
    // Find row for given QModelIndex (if valid) or fallback to `rootNode`
    auto node = parent.isValid() ? static_cast<RavenTreeItem*>(parent.internalPointer()) : rootNode;
    return node->children.count();
}

int RavenTreeModel::columnCount(const QModelIndex &parent) const
{
    return 1;
}

1. In the case of row count, we return the number of child nodes for a given valid model index. If the given model index is invalid, we return rootNode's child count as fallback.

I am assuming this means we have just started rendering the tree and we are currently at the top-most tree node. It might also be an invalid state but I am not sure how that can happen.

If you have more details, I am very interested in learning more. Please comment below or tag me on social media with the details. :)

2. For columnCount, I return 1 because my UI doesn't require any more columns.

Note: If you change the column count, my code won’t work for your use case. You might need to make additional tweaks. See Star Delegate example implementation for more details.

data():

QVariant RavenTreeModel::data(const QModelIndex &index, int role) const
{
    if (!index.isValid()) return QVariant();

    RavenTreeItem *node = static_cast<RavenTreeItem*>(index.internalPointer());

    if (role == Qt::DisplayRole)
    {
        return node->name;
    }

    if (role == Qt::DecorationRole)
    {
        auto iconName = node->children.size() > 0 ? "folder-symbolic" : "filename-title-amarok";
        auto iconProvider = QIcon::fromTheme(iconName);
        return iconProvider;
    }

    if (role == Qt::ToolTipRole)
    {
        return node->fullPath;
    }

    // Default value??
    return QVariant();
}

1. We check if the model index is valid or return an invalid index of our own.

2. Grab the data from model index and cast it to our custom data struct.

3. Next, we need to know what kind of data is being rendered at the moment. These are described by roles where each role has it's own part to play. You can read more about Roles in Qt here.

   I’m interested in only 3 roles:
   - DisplayRole for displaying text on each tree node
   - DecorationRole for showing a folder or file icon on each tree node
   - ToolTipRole for showing tooltip text when user hovers on a tree node

createNode():

Lastly, here's createNode function which generates new custom nodes inside my model.

RavenTreeModel::RavenTreeItem *RavenTreeModel::createNode(const QString &name, const QString &fullPath, const QString &absPath, int flag, bool binary)
{
    RavenTreeItem *node = new RavenTreeItem;
    node->name = name;
    node->fullPath = fullPath;
    node->absolutePath = absPath;
    node->flag = &flag;
    node->binary = binary;
    node->children.clear();  // Ensure the children list is initialized
    return node;
}

Results

Here’s a screenshot of the final result. I realize this isn’t much in terms of looks but it serves as a very good starting point for building something complex.

You will see how I customized this UI in future posts. :)

Conclusion

I hope you learned something new in this post. This is my first C++ project so there may be better way(s) to handle certain scenarios.

Please leave a comment below on your thoughts. You can also @ me on Mastodon here.

This project isn’t currently hosted anywhere yet. The code shown here is a few weeks old as of writing however it is good enough to be a starting point.

I don’t even use Git to manage the code. I have a bunch of _final_final files to sort. I can see the irony here but I have yet to decide on project’s license. More details in my previous post.

Bye for now :)

It’s been a while since I built something for fun. I will be covering my journey on GitRaven. It’s a VCS GUI similar to GitHub Desktop or SourceTree without the code reviews, PR merge or other advanced capabilities.

The idea is to try to build this project in a new language with little experience and take my readers along for the ride. This will be my interesting project of 2025 and beyond.

Background

GitRaven will serve as MY replacement for VS Code’s Version Control feature. I use it on all projects even when using a different IDE. It is easy to work with (to me at least) and helps me visualize the git status output.

The project aims to help me maintain my projects wrt source code management. See my goals below pushing the changes to the remote Git server. This means no PRs, MRs, ticket management, etc. It’s a simple diff viewer + editor and general Git repo management tool.

The project is being built on C++ with Qt Widgets. This will be my first huge project on C++ however I have written C++ before.

Goals

Primary

1. Serve as my VS Code’s replacement tool for managing Git repos.

2. Cleaner design, simple to use. Always be “straight to the point”.

3. Use libgit2 for dealing with Git stuff instead of relying on Git binary (unlike VS Code).

4. Use KTextEditor for text viewing and editing purposes. I have been wanting to try it ever since I used GtkSourceView on my other project.

Bonus

1. Learn Git internals

2. Learn C++

3. Fewer progress bars, loading screens and “Please wait” messages when using the app.

Tech Stack

TL;DR

1. C++

2. Qt

3. KTextEditor

4. libgit2

I originally intended to use Rust just like my other toy project and I did build a prototype with it. I went so far as fetching Git branch details from a given local directory using libgit2 but I later realized it didn’t support KTextEditor.

I was leaning towards C++ by then as I have been itching to try it ever since I got a confidence boost when I created a my own KDE Dolphin plugin. You can read about it here.

I did try using Qt with Rust with cxx-qt but I couldn’t figure out how to use a struct as a child property inside a parent struct. I opened a ticket on the Discussions section of cxx-qt here.

Meanwhile, I wanted to try C++ approach for testing purposes and so, I put my Rust+Qt prototype on hold and fired up Qt Creator to experiment with C++ with Qt. I was trying to replicate the prototype functionality in C++.

I managed to make good progress on it and go beyond the details. I was already having fun figuring out C++ and Qt nuances while working on the prototype like using a QSplitter for QTreeView and diff view, add mock data to render the tree items just like the prototype, etc.

Finally, I decided to pull the plug on Rust implementation and focus on the C++ app.

Current Progress

Here’s how the app looks like as of writing:

I managed to write a custom delegate class for rendering the Git status text (the “D” and “U” text on the right)

You can see a basic diff view of the selected file using KTextEditor . It is still long ways before I can call it a “diff” without the quotes but its a start.

AI Usage

I used ChatGPT and Gemini on this project to solve certain challenging problems after many hours of researching didn’t yield results. I have searched including but not limited to Qt forum, StackOverflow, dev blog posts, etc.

I personally am not a fan of AI tools. There is a potential use case in the future but right now it’s imitation imitating reality at the worst case and I do not like it. Hence, they are my last resort.

When I am stuck with an issue, I ask my query and look for some context. If it presents an answer which worked, I went back to compare my code with it’s proposed changes to figure that part.

It was a wild run and I am happy with my choices so far. I will list down these adventures in my future posts.

Next Steps

Diff Viewer & Editor

Need to decide on approach

1. Build a diff viewer on top of KTextEditor

2. Replace KTextEditor with QtWebEngine + monaco-editor. Monaco provides an out-of-the-box diff viewer component which can be seen inside VS Code and it’s forks.

   Want to learn more about Monaco editor? I wrote about it some time ago here.

I am personally not a fan of (2). It embeds a web browser into the project just for diff viewer component. I would much rather stick with (1) and figure out how to build a diff viewer out of KTextEditor. This will be a technical challenge due to my beginner C++ skill level.

Also, I am aware of Kompare app by KDE. It uses its own diff viewer component similar to my (1) approach. Kompare is a GPL project and I intend to license GitRaven as MIT just like all my other projects. This means, I need to carefully figure out how to integrate GPL code into an MIT project.

I was thinking of moving the diff viewer code into a GPL licensed libravendiff static library. I can dynamically link it to GitRaven’s executable.
This way, I need to make changes to the library while respecting both licenses. Is this feasible?

Lastly, what approach would you pick?

Git Features

1. git fetch

2. List all branches and checkout to different branch

3. Pull/Push changes

4. Generate or apply Patch files for selected files.

5. Stash

6. Rebase & Merge support

Conclusion

Thank you for reading my post. I plan on updating the blog when I’ve made some progress on the project.

You can @ me on Mastodon or leave a comment below if I missed something.

Bye for now :-)

This post is a reference on how to generate `Ctrl+Shift+<key>` keybindings for Neovim. As you know, Vim (apparently) doesn’t support this since some terminal emulators do not pass key combinations.

Theory

1. What we’ll be doing instead is asking the terminal emulator (in my case Alacritty) to send a different character (char) when `Ctrl+Shift+<key>` is pressed.

2. So, when the key combination is pressed, a different character will be sent to Neovim.

3. At Neovim end, we will bind the required Neovim action to this character instead of C<-S-f> or something.

For my usage, I will be triggering Snacks.picker.grep() whenever I press Ctrl+Shift+F on my keyboard.

I use this particular keyboard shortcut very often in VSCode and so trying to retain the pattern in nvim (for muscle memory’s sake) if possible :)

Implementation

The steps are intended for Alacritty terminal emulator. If you’re using something else, please note, the instructions might be slightly different but you’ll be achieving the same goal here.

1. Open Alacritty config at $USER/.config/alacritty/alacritty.toml

2. Add the following code snippet below:

# Global search in nvim
# I am using the `https://www.compart.com/en/unicode/U+058D` character as the replacement.
[keyboard]
bindings = [
  { key = "F", mods = "Control|Shift", chars = "֍" },
]

3. Now, let’s go to nvim config file at $HOME/.config/nvim/lua/config/keymaps.lua

-- Global search
map("n", "֍", function()  Snacks.picker.grep() end, {desc="Global search", remap = true })

4. Save all changes and test. You should see the “Grep” window open inside nvim when you press Ctrl+Shift+F

Conclusion

This post was quickly put together for reference purposes. Sorry if it didn’t include your specific terminal emulator.

Thanks for reading!

Bye for now :)

In this blog post, I will be sharing how to create a plugin for KDE Dolphin to view “File version” info off a Windows EXE & DLL file.

Background

This project was born out of necessity to install mods for Skyrim on Linux. I needed to know the version number of Skyrim’s binary to proceed and it wasn’t readily available on Dolphin.

I found out about the excellent https://pypi.org/project/pefile/ Python library which helped me but I wanted to embed this functionality into Dolphin (if possible).

Later found out we can create custom plugins for Dolphin and the research began. As of writing, there is surprisingly very little information about building plugins for KDE Dolphin (not to be confused with “Services” which is available here).

AI Notice

The use of AI was necessary for this particular project. Read on to find my reasoning.

Firstly, I am not a C++ developer and this was my first C++ project. I prefer Python or Rust to build stuff but KDE Dolphin plugins must be built out of C++ as far as I understand (correct me if I am wrong here).

I’ve used ChatGPT on this project for 3 things:

1. Setup the development environment with CMake
This meant learning about CMakeLists.txt to detect required KDE & Qt dependencies. KDevelop was chosen as the IDE for this project.

2. KDE Dolphin plugin boilerplate code
Got to know about KPropertiesDialogPlugin and saw boilerplate code which was meant for Qt5 but it was a good lead. I later found KDE API reference page which gave me confidence to continue the project.

3. C++ Programming Language:
As a beginner in C++ with a big task of solve, I used ChatGPT to deal with low-level stuff like converting data into different type (std::string , QString, const char *), typecasting pointers, the use of #pragma once, unique_ptr, etc.

Lastly, the code on the project is largely based on my research including checking out “Version Control” plugin for KDE Dolphin (dolphin-plugins), API reference pages for KDE & Qt, Qt forums, grep.app to check implementation of a class and StackOverflow.

Requirements

1. Qt 6.8

2. KDE Dolphin 24.12.3 (might work on older versions)

3. pe-parse library from https://github.com/trailofbits/pe-parse

4. KDevelop (or any other IDE of your choice)

Refer to CMakeLists.txt listed below for the exact requirements.

Theory

The idea is create a custom class which extends KPropertiesDialogPlugin that parses PE header of the Windows executables or DLL file (selected by the user) and dynamically places a “Version: “ QLabel in the “General” tab of Properties dialog.

We build a shared library out of this custom class which will be installed at /usr/lib/qt6/plugins/kf6/propertiesdialog/ .
We will also create a manifest file so that KDE Dolphin can dynamically load the library when we right-click a file/folder.

Implementation

You can find the Git repo with latest changes here.

Here’s the project structure for reference:

helloworld
├── CMakeLists.txt                    # CMake
├── hello-dolphin-plugin.json         # Manifest file
├── helloworld.kdev4                  # KDevelop related
└── src
    ├── hello-dolphin-plugin.cpp      # Plugin source
    ├── hello-dolphin-plugin.h
    ├── pe-parser-wrapper.cpp         # Deals with PE files
    └── pe-parser-wrapper.h

Let’s setup CMake for the project. It will help us manage all dependencies.

# CMakeLists.txt

# Set minimum CMake version
cmake_minimum_required(VERSION 3.16)
# Set project name
project(hello-dolphin-plugin)

set(QT_MIN_VERSION "6.8.2")
set(KF_MIN_VERSION "6.11.0")

# Ensure the build directory is set early in the configuration
set(CMAKE_BINARY_DIR "${CMAKE_SOURCE_DIR}/build" CACHE PATH "Build directory" FORCE)

# ECM setup
find_package(ECM ${KF_MIN_VERSION} CONFIG REQUIRED)
set(CMAKE_MODULE_PATH ${ECM_MODULE_PATH} ${CMAKE_SOURCE_DIR}/cmake)
include(QtVersionOption)
include(ECMSetupVersion)
include(KDEInstallDirs)
include(KDECMakeSettings)
include(KDECompilerSettings NO_POLICY_SCOPE)
include(ECMDeprecationSettings)
include(ECMOptionalAddSubdirectory)

find_package(pe-parse REQUIRED)

find_package(Qt6 ${QT_MIN_VERSION} REQUIRED COMPONENTS
    Core
    Core5Compat
    Widgets
    Network
    DBus
)
find_package(KF6 ${KF_MIN_VERSION} REQUIRED COMPONENTS
    XmlGui
    I18n
    KIO
    TextWidgets
    Config
    CoreAddons
    WidgetsAddons
    Solid
)

# Add the shared library target
add_library(
    hello-dolphin-plugin
    SHARED
    src/hello-dolphin-plugin.h
    src/hello-dolphin-plugin.cpp
    src/pe-parser-wrapper.h
    src/pe-parser-wrapper.cpp
)

# Set properties for the shared library
set_target_properties(hello-dolphin-plugin PROPERTIES
    VERSION "${RELEASE_SERVICE_VERSION}"
    SOVERSION "1"
)

target_link_libraries(hello-dolphin-plugin KF6::CoreAddons KF6::XmlGui)
target_link_libraries(hello-dolphin-plugin KF6::KIOCore KF6::KIOFileWidgets KF6::KIOWidgets)
target_link_libraries(hello-dolphin-plugin pe-parse::pe-parse)

# Include directories for the project
include_directories(
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${Qt6Widgets_INCLUDE_DIRS}
    ${KF6_INCLUDE_DIRS}
)

# Ensure that all output directories are set explicitly to the build directory
set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
set(CMAKE_LIBRARY_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})
set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR})

# Set the destination for installation if needed
install(TARGETS hello-dolphin-plugin DESTINATION ${KDE_INSTALL_PLUGINDIR}/kf6/propertiesdialog/)
install(FILES hello-dolphin-plugin.json DESTINATION  ${KDE_INSTALL_PLUGINDIR}/kf6/propertiesdialog/)

Let’s take a look at PEWrapper class. It’s main job is to parse an .exe or .dll file and extract it’s version number.

src/pe-parser-wrapper.h:

#pragma once

#include <pe-parse/parse.h>
#include <pe-parse/nt-headers.h>

#include <memory>

#include <QString>

#define MAX_MSG 81

using namespace std;

using ParsedPeRef =
unique_ptr<peparse::parsed_pe, void (*)(peparse::parsed_pe *)>;

class PEParserWrapper {

public:
  // This struct wasn't part of peparse library.
  struct VS_FIXEDFILEINFO {
    uint32_t dwSignature;
    uint32_t dwStrucVersion;
    uint32_t dwFileVersionMS;
    uint32_t dwFileVersionLS;
    uint32_t dwProductVersionMS;
    uint32_t dwProductVersionLS;
    uint32_t dwFileFlagsMask;
    uint32_t dwFileFlags;
    uint32_t dwFileOS;
    uint32_t dwFileType;
    uint32_t dwFileSubtype;
    uint32_t dwFileDateMS;
    uint32_t dwFileDateLS;
  };

  PEParserWrapper();
  virtual ~PEParserWrapper();
  string parseFile(QString filePath);
};

src/pe-parser-wrapper.cpp:

#include <pe-parse/parse.h>

#include <QString>
#include <QDebug>
#include <qlogging.h>

#include "pe-parser-wrapper.h"

using namespace std;

PEParserWrapper::PEParserWrapper()
{
}


PEParserWrapper::~PEParserWrapper()
{
}

// This code is based off readpe (previously pev) project.
// Source: https://github.com/mentebinaria/readpe/blob/master/src/peres.c#L551
int resource_callback(void *cbd, const peparse::resource &resource)
{
    if (resource.type == peparse::RT_VERSION) {

        // PE offset
        uint8_t pe_offset = 32;

        // This offset allows us to skip to the required VS_FIXEDFILEINFO data
        // which can now be casted to struct.
        // If you have more info about this, please let me know. 
        uint8_t my_offset = 8;

        // NOTE: KDevelop complains with `-Wclass-align` here.
        // I don't know what that is and Google hasn't been helpful.
        // If you know what this is and how to fix it, please let me know :)
        auto verInfo = (const PEParserWrapper::VS_FIXEDFILEINFO *) (resource.buf->buf + pe_offset + my_offset);

        // Additional check to make sure we're on the right track.
        if (verInfo->dwSignature == 0xfeef04bd)
        {
            char value[MAX_MSG] = {0};

            sprintf(value, "%u.%u.%u.%u",
                    (uint32_t)(verInfo->dwFileVersionMS & 0xffff0000) >> 16,
                    (uint32_t)verInfo->dwFileVersionMS & 0x0000ffff,
                    (uint32_t)(verInfo->dwFileVersionLS & 0xffff0000) >> 16,
                    (uint32_t)verInfo->dwFileVersionLS & 0x0000ffff);

            // This is used to pass the data back to calling function
            vector<char>& vecPointer = *(vector<char> *)cbd;

            // This is used to store contents of `value`
            vector<char> v2 = {};

            // We insert at the end so that it will return
            // in correct (expected) order when the data is passed back
            for(char c: value)
            {
                // FIXME: Need to ensure only valid ASCII characters are inserted here.
                //        Right now, we are allowing `\x00' chars (NULL bytes?).
                v2.insert(v2.end(), c);
            }

            // Update reference here so vecPointer points to v2;
            vecPointer = v2;

            return 1;
        }
    }

    return 0;
}


string PEParserWrapper::parseFile(QString filePath)
{
    // The factory function does not throw exceptions!
    ParsedPeRef ref(peparse::ParsePEFromFile(filePath.toUtf8().data()),
                    peparse::DestructParsedPE);
    if (!ref) {
        qWarning() << "Failed to parse file " << filePath;
        return "";
    }

    vector<char> result;

    peparse::IterRsrc(ref.get(), resource_callback, &result);

    if (result.size() == 0)
    {
        return "";
    }

    return string(result.begin(), result.end());
}

Now, let’s check out the actual KDE Dolphin plugin code.

src/hello-dolphin-plugin.h:

#pragma once

#include <QObject>
#include <QString>

#include <KFileItem>
#include <KPropertiesDialogPlugin>

#include "pe-parser-wrapper.h"

using namespace std;

class HelloDolphinPlugin : public KPropertiesDialogPlugin
{
    Q_OBJECT

public:
    HelloDolphinPlugin(QObject *parent);

protected:
    PEParserWrapper *peWrapper;
    std::string version = "";
    // List the file types we're interested in.
    const std::vector<std::string> ALLOW_LIST = {".exe", ".dll"};

    void init();
    void injectFileVersionIntoGeneralTab(KPageWidgetItem *current, KPageWidgetItem *before);
    // This should be in camelCase, isn't it?
    bool is_target_file_type(QString fileName);

};

src/hello-dolphin-plugin.cpp:

#include <QObject>
#include <QWidget>
#include <QString>
#include <QVBoxLayout>
#include <QLabel>
#include <QUrl>

#include <KPluginFactory>
#include <kpluginfactory.h>
#include <KFileItem>
#include <KPageDialog>
#include <KPropertiesDialog>
#include <KSqueezedTextLabel>

#include <regex>

#include "hello-dolphin-plugin.h"
#include "pe-parser-wrapper.h"

using namespace std;

HelloDolphinPlugin::HelloDolphinPlugin(QObject *parent) : KPropertiesDialogPlugin(parent)
{
    this->peWrapper = new PEParserWrapper();
    this->init();
}

void HelloDolphinPlugin::init()
{
    if (this->properties->items().size() == 1)
    {

        QUrl itemUrl = this->properties->item().url();
        QString filePath = itemUrl.path();
        QString fileName = itemUrl.fileName();

        if (this->is_target_file_type(fileName))
        {

            this->version = this->peWrapper->parseFile(filePath);

            if (!this->version.empty())
            {
                // Injects "File Version" details in General tab.
                connect(
                    properties,
                    &KPropertiesDialog::currentPageChanged,
                    this,
                    &HelloDolphinPlugin::injectFileVersionIntoGeneralTab,
                    Qt::ConnectionType::SingleShotConnection
                );

            }
        }
    }
}

void HelloDolphinPlugin::injectFileVersionIntoGeneralTab(KPageWidgetItem *current, [[maybe_unused]] KPageWidgetItem *before)
{
    string tabName = current->name().toStdString();

    // Remove '&' character used for pneumatics.
    // There might be an easy way here :)
    std::regex pattern("&");
    tabName = std::regex_replace(tabName, pattern, "");

    // Looking for General tab to add the File Version
    if (tabName == "General")
    {
        QVBoxLayout *vbox = (QVBoxLayout*) current->widget()->children().first();
        QGridLayout *gridLayout = (QGridLayout*) vbox->children().first();

        QLabel *fileVersionLabelKey = new QLabel(QString::fromUtf8("Version:"));
        QLabel *fileVersionLabelValue = new QLabel(QString::fromUtf8(this->version));

        // 18 refers to row where the widgets will be placed. It is not in use so 
        // I am hoping this won't overlap any other widget.
        // Confirmed by browsing `kio` repo at invent.kde.org
        gridLayout->addWidget(fileVersionLabelKey, 18, 0, Qt::AlignRight|Qt::AlignVCenter);
        gridLayout->addWidget(fileVersionLabelValue, 18, 1, Qt::AlignLeft|Qt::AlignVCenter);
    }
}

bool HelloDolphinPlugin::is_target_file_type(QString fileName)
{
    for (std::string ext: this->ALLOW_LIST)
    {
        if (fileName.endsWith(QString::fromUtf8(ext))) return 1;
    }

    return 0;
}


// Here we register the class as a plugin with additional metadata
// is available at the JSON file
K_PLUGIN_CLASS_WITH_JSON(HelloDolphinPlugin, "hello-dolphin-plugin.json")


// MOC file
#include "hello-dolphin-plugin.moc"

Lastly, here’s the manifest file which ties all this together.

hello-dolphin-plugin.json:

{
    "KPlugin": {
        "Description": "This plugin inserts 'Version' row in General tab for EXE/DLL files.",
        "Icon": "document-open",
        "MimeTypes": [
            "application/octet-stream"
        ],
        "Name": "Hello Dolphin plugin",
        "EnabledByDefault": true,
        "MimeType": "application/octet-stream",
        "X-KDE-Protocols": [
            "file",
            "desktop"
        ]
    }
}

End Result

You can see the version number for an EXE file:

Here’s the screenshot for a DLL file:

I have one nitpick with QGridLayout:
It doesn’t automatically push widgets down by 1 when we’re trying to place a new widget at it’s place.
This meant I could’ve shown “Version” info just below “Type” which would’ve made a lot of sense but I have to take the win here, I guess.

Conclusion

This project was a lot of fun! I learned a few things:

1. C++ is a language I am mildly comfortable with

2. Using CMake for a project,

3. File headers and dealing with offsets

4. Concept of pointers is much clearer

5. Qt can be a viable replacement to GTK3 (which I like)

Thank you for taking the time to read the blog post in it’s entirety. I would appreciate if you could drop a Like to this post. It helps out the algorithm.

You can also @ me on Mastodon here :)

Bye for now.

I will show you how to quickly and easily setup open-webui in your Linux distro.

This will allow using Ollama models (which you have already installed locally) from a web user interface (similar to ChatGPT).

Prerequisites

Python 3.11 is recommended for the project. You can try this with global Python installation but make sure the version numbers match.

If you’d like to install Python 3.11 manually, please look into pyvenv.

Installation

1. I use a “Projects“ folder to store all active projects.

$ cd /home/$USER/Projects

2. Now, we’ll create a virtual environment to isolate open-webui project. (Recommended for Arch and Arch based distros)

Note for Arch & Arch-like distro users: As of writing, Arch and Arch-like distros are shipping Python 3.13 which open-webui doesn’t support yet. (tested on v0.5.10 GitHub)

# Make a virtualenv for this project called "webui".
$ python3 -m venv webui

# In case of Pyenv
$ pyenv exec python -m venv webui

3. Install the open-webui package.

# The below commands work in both global as well as pyenv installation of Python

$ cd /home/$USER/Projects/webui
$ source bin/activate
$ pip install open-webui

This command will now install open-webui to your project This will take some time depending on your internet connection.

4. Run open-webui

$ open-webui serve

This should initialize the software and start listening for connections at http://localhost:8080.

5. Open Firefox/Chrome and go to http://localhost:8080. Provide a name, email and password to login to your instance and that’s it!!

   

   Update open-webui

1. To update open-webui to latest version, look for a notification from open-webui screen informing us there is a new version as shown below:

   

2. Now, stop all processes of open-webui locally. This step is important. In most cases, you simply need to close the terminal which is running open-webui serve.

3. Run the commands below:

$ cd /home/$USER/Projects/webui
$ source bin/activate
# Replace <version> with the version number from notification.
# In my case, it is `0.5.12`
$ pip install open-webui==<version>
# Assuming no errors, let's run the serve command now.
$ open-webui serve

4. If you do not see any errors, try visiting http://localhost:8080. In most cases, this will work out-of-the-box.

Conclusion

This blog post summarizes the steps involved in getting open-webui working on my machine. The instructions are generic enough to be used for other Linux distros.

Please leave a comment if I missed something.

You can also follow me on Mastodon for more updates.

Bye for now :)

This is final part of the GhostLLM project. The goal was to introduce “Rewrite Text” functionality to GTK3 TextView using Ollama.

If you haven’t been following this project, you can find the links below:
Part 1
Part 2
Part 3

In this part, I have updated GtkTextView widget with relevant GhostLLM code for the text rewrite functionality.

Theory

We need to adapt the GhostLLM related code from gtkentry.c to gtktextview.c and test the features. This code has proven to be working with GtkEntry in the last part so I am not expecting any issues now.

Implementation

You will find latest changes on Github repo here.

Here’s the relevant code:

gtktextview.c (GhostLLM callback code):

static void
ghostllm_rewrite_text_cb (GtkWidget *widget)
{
  GtkTextView *text_view = GTK_TEXT_VIEW (widget);
  GtkTextBuffer *buffer;
  GtkTextIter start_iter, end_iter;

  buffer = text_view->priv->buffer;

  // Get selection bounds for string
  gtk_text_buffer_get_selection_bounds (buffer, &start_iter, &end_iter);

  // Get selected text from selection bounds
  char *input_str = gtk_text_buffer_get_text (buffer, &start_iter, &end_iter, FALSE);

  // Rewrite the input string
  char* response = ghostllm_rewrite_text(input_str);

  if (response == NULL) {
    g_printerr("Unable to generate GhostLLM response.");
    return;
  }

  // HACK: Delete user selected text using "Cut" operation
  gtk_text_view_cut_clipboard(text_view);

  // Insert rewritten text
  gtk_text_view_insert_at_cursor(text_view, response);

  g_free (response);

}

gtktextview.c (Context menu code)

// This code goes after line number 9586

// GhostLLM stuff

// The root GtkMenuItem that shows "GhostLLM" option on the context menu
GtkWidget *ghostllm_root_menuitem = gtk_menu_item_new_with_mnemonic (_("GhostLLM"));
gtk_widget_set_sensitive(ghostllm_root_menuitem, gtk_text_buffer_get_char_count (priv->buffer) > 0);
// The GtkMenu widget which holds the LLM menu options.
GtkWidget *ghostllm_submenu = gtk_menu_new ();

menuitem = gtk_menu_item_new_with_mnemonic (_("_Rewrite Text"));
g_signal_connect_swapped (menuitem, "activate", G_CALLBACK (ghostllm_rewrite_text_cb), text_view);
gtk_widget_show (menuitem);
// Append "Rewrite Text" option into LLM submenu
gtk_menu_shell_append (GTK_MENU_SHELL (ghostllm_submenu), menuitem);
// Set submenu options for GhostLLM root menu item
gtk_menu_item_set_submenu ( GTK_MENU_ITEM (ghostllm_root_menuitem), ghostllm_submenu);
gtk_widget_show(menuitem);
gtk_widget_show(ghostllm_root_menuitem);
// Append the GhostLLM root GtkMenuItem into GtkEntry's context menu
gtk_menu_shell_append (GTK_MENU_SHELL (priv->popup_menu), ghostllm_root_menuitem);

I have tested my changes using the “sunny” example provided on the GTK repo. I had to make the following change in meson.build at the project root and compiled the whole thing.

diff --git a/meson.build b/meson.build
index 67b24e5e7d..9df8fae828 100644
--- a/meson.build
+++ b/meson.build
@@ -857,6 +857,7 @@ subdir('gdk')
 subdir('gtk')
 subdir('modules')
 subdir('libgail-util')
+subdir('examples')
 if get_option('demos')
   subdir('demos')
 endif
@@ -864,9 +865,8 @@ if get_option('tests')
   subdir('tests')
   subdir('testsuite')
 endif
-if get_option('examples')
-  subdir('examples')
-endif
+#if get_option('examples')
+#endif

 # config.h
 configure_file(

Screenshots

User input screen

Output screen

My Opinion on LLMs

I personally feel the current LLM “AI” stuff is just hype around a new technology and just like “dot com bubble” as well as the crypto crap a few years back, this too shall wither away in the future.

I do see the potential with this technology as a completely offline auto complete or auto suggestions like functionality based on this however that would involve using much smaller LLM models. In this example, I am using qwen2.5:3b which did the job but it’s 1.9GB in size and it took a few seconds for my GTX 1050 Ti to process the request. This would only increase with the input tokens.

Conclusion

This marks the end of the fun (and silly) GhostLLM project. I learned a lot working on this and has proven yet again why I prefer GTK+ on my projects.

Thanks for following along on this project. Please leave a Like on the post to show your appreciation.

Bye for now :-)

This is part three of my GhostLLM project. This project is about integrating “Rewrite Text” functionality natively into GTK3 widgets. Check the part one and part two in case you missed it.

Theory

We will be working with gtkentry.c for this part. The goal is to implement ghostllm_rewrite_text_cb callback function to replace the user selected text.

The idea is to declare new files - ghostllm.c & the header file ghostllm.h to deal with DBus related communications. We also update meson.build file to include them in the build system.

Implementation

The code lives on GitHub repo here. Please refer the repo link for latest changes :)

Here’s the relevant code:

ghostllm.h:

// This is the only line in this file!
char* ghostllm_rewrite_text(char* input_str);

ghostllm.c

#include "config.h"

#include <gtk/gtk.h>

#include <gio/gio.h>

char *ghostllm_rewrite_text(char *input_str) {
  // Connect to DBus Session Bus
  GDBusConnection *conn = g_bus_get_sync(G_BUS_TYPE_SESSION, NULL, NULL);

  // Define the remote service and object path
  char *service_name = "in.suryatejak.ghostllm";
  char *object_path = "/in/suryatejak/ghostllm";

  // This is required for communicating with DBus.
  GDBusMessage *call_message = NULL;
  GDBusMessage *reply_message = NULL;
  GError **error = NULL;

  // Define the DBus message to be sent.
  call_message = g_dbus_message_new_method_call(service_name, object_path,
                                                service_name, "RewriteText");

  // Set arguments
  g_dbus_message_set_body(call_message, g_variant_new("(s)", input_str));

  // Call the RewriteText method on the remote service
  reply_message = g_dbus_connection_send_message_with_reply_sync(
      conn, call_message, G_DBUS_SEND_MESSAGE_FLAGS_NONE, -1, NULL, NULL,
      error);

  // Retrieve the response data from DBus
  GDBusMessageType reply_type = g_dbus_message_get_message_type(reply_message);

  if (reply_type == G_DBUS_MESSAGE_TYPE_ERROR) {
    // TODO: show error to user
    g_dbus_message_to_gerror(reply_message, error);
    return NULL;
  }

  if (reply_type == G_DBUS_MESSAGE_TYPE_METHOD_RETURN) {
    // We got something!
    GVariant *response = g_dbus_message_get_body(reply_message);

    /**
     * We receive a tuple which contains required string.
     * Now, we fetch the first item and extract the string.
     */
    gsize index = {0};
    response = g_variant_get_child_value(response, index);

    if (response == NULL) {
      return NULL;
    }

    char *msg = g_variant_get_string(response, NULL);

    return msg;
  }

  return NULL;
}

As seen above, we call our RewriteText method with the user’s selected text. It returns a tuple (DBus type: (s)) from which we extract rewritten string.

gtkentry.c:

static void
// If you've seen this function in part one, you'll
// notice the change in function arguments.
ghostllm_rewrite_text_cb (GtkEntry *entry)
{

  // Get selection bounds for string
  GtkEditable *editable = GTK_EDITABLE (entry);
  gint start, end;
  gtk_editable_get_selection_bounds (editable, &start, &end);

  // Get selected text from selection bounds
  gchar *input_str = _gtk_entry_get_display_text (entry, start, end);

  // Rewrite the input string
  char* response = ghostllm_rewrite_text(input_str);

  if (response == NULL) {
    g_printerr("Unable to generate GhostLLM response.");
    return;
  }

  // HACK: Delete user selected text using "Cut" operation
  gtk_entry_cut_clipboard(entry);

  // Insert rewritten text
  gtk_entry_insert_text(editable, response, strlen(response), &start);

  g_free (response);

}

In this step, we simply generate new text from our server, then copy the user’s selected input text to the clipboard and lastly insert this new text at the cursor position.

It might take a few seconds depending on your machine but in the end, it works. I noticed this still works even when the window is inactive.

Demo

User Input:

Ollama response:

As you can see, the output has changed. Now, this is just to demonstrate something like this is doable even when it isn’t practical.

I was worried about the additional work involved in replacing the user selected text with the rewritten text but, as it turns out, I can cheat a little here using clipboard. :)

Next Steps

The idea is to implement this feature to GtkTextView widget which was the original goal of this project. I will keep the GtkEntry changes as-is for my amusement.

Conclusion

Thanks for your time!

This was a very fun project however I think the next part would mark the end for this. As always, the code will live on my GitHub.

I hope you liked this post. Please give it a Like to show your appreciation. If you feel there’s something I missed or can do better, let me know in the comments.

Bye for now :-)

This is part two of my GhostLLM project. This project is about integrating “Rewrite Text” functionality natively into GTK3 widgets. Check the part one post if you missed it.

In this part, I will going over the DBus server code (written in Python) which will be exposing DBus interface on the Session Bus with a method “RewriteText” which accepts user input (String) and returns the rewritten sentence as the output.

Implementation

The code for this project lives on GitHub here.

The main part here is to setup DBus interface. I used dbus-fast to simplify this.

server.py:

# File: server.py

# DBus interface is declared here
# The `_` prefix is to indicate this is an internal class.
class _GhostLLMDBusInterface(ServiceInterface):

    def __init__(self):
        super().__init__(DBUS_ADDRESS_NAME)
        self.ollama = OllamaController()

    @method()
    def RewriteText(self, input_text: 's') -> 's':
        return self.ollama.chat(input_text)

# Wrapper class that simplifies executing this code from `__main__.py`
class GhostLLMDBus():

    async def init(self):
        # Connect to Session Bus
        bus = await MessageBus(bus_type=BusType.SESSION).connect()
        # Implement the DBus interface
        interface = _GhostLLMDBusInterface()
        bus.export(DBUS_INTERFACE_NAME, interface)
        await bus.request_name(DBUS_ADDRESS_NAME)

        print(f"DBUS Service initialized at {DBUS_INTERFACE_NAME}")

        await bus.wait_for_disconnect()

    # We call this in `__main__.py` that will kick things off!
    def listen(self):
        asyncio.run(self.init())

ollama.py:

# File: ollama.py
from ollama import generate
from ollama import GenerateResponse

from .constants import OLLAMA_MODEL_NAME, OLLAMA_SYSTEM_PROMPT

class OllamaController():

    def chat(self, input_str: str) -> str:
        response: GenerateResponse = generate(
            model=OLLAMA_MODEL_NAME, # qwen2.5:3b
            system=OLLAMA_SYSTEM_PROMPT,
            stream=False,
            prompt= f'rewrite "{input_str}"'
        )

        return response.response

This code is pretty straight-forward. I used the usage code from Ollama Python library. I use /generate endpoint to customize the prompt to fit the needs. The constants here could be replaced with a config file for easier access.

You should always use ‘system’ role to set your instructions. This way, your users wouldn’t be able to change or override your instructions. That’s called a prompt injection attack. Learn more about it on Wikipedia.

__main__.py:

import sys

from .server import GhostLLMDBus

if __name__ == '__main__':
    try:
        gh = GhostLLMDBus()
        gh.listen()
    except KeyboardInterrupt:
        sys.exit(0)

I tried this code with LLAMA3.2 model but it didn’t respect the system prompt. It always tried to process the user prompt rather than simply rewriting the text. Hence, I went with qwen2.5:3b model with the following prompt:

// SYSTEM PROMPT:
Your work is to rewrite sentences to make them more professional. Reply with 1 rewritten sentence. do not say anything else.

// USER PROMPT:
rewrite "xxx"

You run the project using:

$ cd <project-root> # like cd ~/Projects/ghostllm-dbus
# You need to run `pip install -r requirements.txt` first!!
$ python -m ghostllm-dbus

Screenshot

I used QTDBusViewer software to test the server. You can use any other software :)

Input prompt:

Response:

Next Steps

The next part is going to be difficult. I need to figure out C code that will interact with DBus instance and present it to the user.

I will also need to figure out a way to replace the selected text in buffer with GhostLLM’s response.

Conclusion

Thanks for reading! I would appreciate if you could leave a Like to this post.

Please leave a comment if you think I missed something :)

Bye for now :-)

This is part one of my series of fun project that felt challenging for me. Read on to know more :)

Background

I’ve been using Ollama for running LLM models locally on my Linux machine for more than a year. It allows us to use many LLM models from the CLI.

During Apple’s Keynote this year, I was fascinated with “AI sentence rewriting” feature available starting from macOS Sequoia.

This led me down a rabbit hole for ways to extend existing input fields (at least ones that use GTK3) with LLM model for quickly rewriting sentences.

It is possible that things might not go my way however I picked up this project for 2 things:

1. Better understanding of GTK text entry widgets

2. A silly project to keep my nerdy brain occupied :)

I have decided to name this project “GhostLLM”. It is based on the word ghostwriter with “LLM” joined to the hip. I think it fits simply because the LLM models will be the ghostwriters every time I ask it to rewrite a sentence.

Theory

The idea is to fork GTK library and add a dedicated “GhostLLM” submenu for right-click context menu when text is selected. When user selects “Rewrite Text” option inside this menu, we will call DBus interface which will provide the alternative sentences.

This means I need to setup DBus address that can process the request. It would be written in Python (or Rust) and will be responsible to communicate with Ollama for models.

I will be using GTK3 version 3.24.43 for this project. It’s what Manjaro Linux (my daily driver) shipped as of writing.

GtkEntry instead of GTKTextView

As of writing, I could not find software that still used GTK3 + GTKTextView on Manjaro’s repos. Honestly, I didn't search thoroughly so I will revisit this in the future.

For the time-being, I chose GtkEntry widget. It is used as the address bar on Thunar (which I have installed on my machine alongside Dolphin). It will make it easier to compile and test my changes.

Code

I have written the necessary boilerplate code to get things moving. The callback for “Rewrite Text” option simply prints sample text to the console.

diff --git a/gtk/gtkentry.c b/gtk/gtkentry.c
index a71578218c..3bafbee079 100644
--- a/gtk/gtkentry.c
+++ b/gtk/gtkentry.c
@@ -5921,6 +5921,12 @@ gtk_entry_backspace (GtkEntry *entry)
   gtk_entry_pend_cursor_blink (entry);
 }

+static void
+ghostllm_rewrite_text_cb (GtkMenuItem *menuitem, gpointer user_data)
+{
+  g_print("hello from rewrite text callback!!");
+}
+
 static void
 gtk_entry_copy_clipboard (GtkEntry *entry)
 {
@@ -9601,6 +9607,26 @@ popup_targets_received (GtkClipboard     *clipboard,
                             mode == DISPLAY_NORMAL &&
                             info_entry_priv->current_pos != info_entry_priv->selection_bound);

+      // GhostLLM stuff
+      
+      // The root GtkMenuItem that shows "GhostLLM" option on the context menu
+      GtkWidget *ghostllm_root_menuitem = gtk_menu_item_new_with_mnemonic (_("GhostLLM"));
+      gtk_widget_set_sensitive(ghostllm_root_menuitem, info_entry_priv->editable && info_entry_priv->current_pos != info_entry_priv->selection_bound);
+
+      // The GtkMenu widget which holds the LLM menu options.
+      GtkWidget *ghostllm_submenu = gtk_menu_new ();
+      
+      menuitem = gtk_menu_item_new_with_mnemonic (_("_Rewrite Text"));
+
+      g_signal_connect_swapped (menuitem, "activate", G_CALLBACK (ghostllm_rewrite_text_cb), entry);
+      gtk_widget_show (menuitem);
+
+      // Append "Rewrite Text" option into LLM submenu
+      gtk_menu_shell_append (GTK_MENU_SHELL (ghostllm_submenu), menuitem);
+
+      // Set submenu options for GhostLLM root menu item
+      gtk_menu_item_set_submenu ( GTK_MENU_ITEM (ghostllm_root_menuitem), ghostllm_submenu);
+
       append_action_signal (entry, menu, _("_Paste"), "paste-clipboard",
                             info_entry_priv->editable && clipboard_contains_text);

@@ -9615,6 +9641,11 @@ popup_targets_received (GtkClipboard     *clipboard,
       gtk_widget_show (menuitem);
       gtk_menu_shell_append (GTK_MENU_SHELL (menu), menuitem);

+      gtk_widget_show(menuitem);
+      gtk_widget_show(ghostllm_root_menuitem);
+      // Append the GhostLLM root GtkMenuItem into GtkEntry's context menu
+      gtk_menu_shell_append (GTK_MENU_SHELL (menu), ghostllm_root_menuitem);
+
       menuitem = gtk_menu_item_new_with_mnemonic (_("Select _All"));
       gtk_widget_set_sensitive (menuitem, gtk_entry_buffer_get_length (info_entry_priv->buffer) > 0);
       g_signal_connect_swapped (menuitem, "activate",

LD_PRELOAD

After successfully compiling GTK library with the above changes, I found the modified GTK3 library at ./_build/gtk/libgtk-3.so.

You can find building instructions on INSTALL.md file after checking out the 3.24.43 tag.

I tried sudo meson install -C_build to install this version globally on the system but it didn’t work. Hence, I went with `LD_PRELOAD` approach to test the changes.

$ LD_PRELOAD=/home/suryateja/Projects/gtk3/_build/gtk/libgtk-3.so thunar

What’s Next?

In the next part, I will write GhostLLM daemon which will create DBus address that will talk to LLM models via Ollama endpoints.

I have yet to decide whether to go with Python or Rust for this part. Please add a comment to let me know your thoughts.

Conclusion

Thank you for reading. Give this post a Like to show your appreciation for this post.

You can follow me on Mastodon for more updates.

Bye for now :-)

It is with a heavy heart that I have decided to shut down the fedIMG project. This project started out of my curiosity towards the ActivityPub protocol. It began as a silly, fun and a “toy” server for educational purposes but as the development went on, I wanted to try my hand at turning into something serious (like snac).

I had also planned to run a dev series on the blog (akin to MyStudio IDE) however I quit working on the project around the end of March 2023 because of my inability to solve several features, one of which was “Follow” user feature.

This bug haunted me for the coming months as I went through several stages to grief every time I saw activity related to ActivityPub software. After a 6 month hiatus, I returned to the project with a vengeance. I had managed to fix the bug (Link) which was therapeutic and satisfying to say the least. I slept like a baby that night!!

With the newly found interest, I continued development and managed to land some bug fixes and other misc. additions to the project but I soon realized the original spark had died. I wasn’t feeling the fun with this project and the work kept piling up.

Also, the project was costing me money regardless of my engagement towards it. Now, due to technical reasons, I created 2 AWS EC2 instances for this project - one for the NodeJS server and the other was dedicated MySQL database. I know I could’ve used something like ngrok but their offerings needed a paid account for my needs. Also, I had to pay extra to my ISP for needing a static IP address so that I can SSH into the server to test things when they break.

Looking back, this project was a lot of fun. It was very educational and it taught me many things. After a lot of consideration, this project is being shutdown. I would rather see the project archived than let it die a slow death (abandoned).

The code will live on GitHub here and the repo will be archived once the article is published. I hope this will help others venturing into ActivityPub.

A huge thanks to https://social.linux.pizza/@selea for allowing me to test fedIMG against his Mastodon server. I really appreciate his patience and compassion towards me and this project. ❤️

Here’s hoping my next passion project will succeed.

Thank you for your time.

Bye for now :-)

I started the project just because I wanted to build something again. After looking at some projects which I use daily, I realized I wanted to build an ActivityPub server.

I go into detail in the article but this spec has been a fascinating concept ever since I learned about its existence back in 2022.

I believe in “learning by building stuff” ideology and as such, this project will help me understand a lot of concepts including ActivityPub, building sophisticated social media experiences and so on.

Inspiration

I have been following activity around ActivityPub since 2022. It was also around the time when I migrated from Twitter to Mastodon.

I would highly recommend checking out Mastodon and ActivityPub. It could truly be the next-gen social media platform, if given a chance.

There are several projects which implement ActivityPub but the way they currently work is, each project manages one type of content - for example:

1. Mastodon is a microblogging platform.

2. Lemmy & Kbin are link aggregator platforms similar to Reddit.

3. PeerTube is a video sharing platform.

Unlike traditional social media platforms, these software have 2 fascinating features:

1. Allow following users across different ActivityPub servers (collectively called the #Fediverse).

2. Users are allowed to migrate to different server hosted at a different domain within the same project. For example, a user from mastodonserver1.com can migrate to another Mastodon server hosted at techstuffonly.com.

Goals

I aim to accomplish the following goals for this project:

1. Multiple content types are supported - text, images and short videos (sometime in the near future)

2. “My Feed” section that is tuned according to your followers & following collections. I need to research this a lot before I begin!

License

I wanted to go with MIT license just like I do with all my personal projects but after some consideration, I decided to go with AGPLv3 for this project. It is identical to that of Mastodon. The rationale for this choice stems from the fact that I studied Mastodon’s code for many days for implementation purposes.

Progress

This project lives on GitHub here. It is bare-bones as of writing as I have prioritized building necessary features into the project.

This is actively under development and things will change (and break) often.

I have recently returned to the project from a 7 month hiatus. This personal time has allowed me to think clearly and I am happy to report it’s been a good decision. The project lives!!! :)

What works:

1. Webfinger endpoint [Ref][Code]

2. NodeInfo endpoint [Ref] [Code]

3. User registration & login

4. Follow a remote user

5. Accept remote user’s Follow request (can’t Reject though!)

6. Profile page with option to upload profile picture and set “display name”

What’s missing:

There are many things missing in my implementation but here’s an overview of what I think is important at the moment.

1. Landing page

2. UI is terrible and in some cases, it doesn’t exist yet.

3. Reject a remote user’s follow - UI & backend

4. Create Activity management

5. Undo activity management

6. Implement /actor/outbox endpoint

7. Severe lack of documentation for project

Challenges

1. It was hell trying to implement HTTP Signatures. This was mandatory as all AP severs won’t accept certain requests without it. I remember spending several weeks trying different things to get the expected output.

2. I ran into trouble setting up generating public & private keys for registered users.

3. Staying motivated was a HUGE problem. I always got cornered with imposter syndrome when something fails.

4. The “do it right the first time” entity in my head was difficult to negotiate. We currently have several FIXME comments throughout the code because that’s the ONLY way I was able to move forward when building something this huge.

Conclusion

I am excited about this project and the learning potential I gain from this experiment is immense. Consider following my Mastodon account here or following my project’s hashtag here for more updates.

I plan on making this a series provided I have something new to report!

Bye for now :)

Now, don't get me wrong. It's a great library but it has a huge problem. JavaScript's native Date class offers very little to what I need in terms of functionality and so I relied on momentjs for all this time.

The problem is momentjs has been deprecated for a while. I didn't know about this until I stumbled upon it while searching for API reference in the documentation.

Now, let's talk alternatives - we have many including ones recommended by Moment.js

My answer?

I started using date-fns for smaller projects. I know its not a "drop-in" replacement but the learning curve isn't that bad in my opinion*.*

..there was one more!

As recommended by Momentjs, for a brief time I gave another library a shot - Luxon. Check out Luxon project's website for more details.

It is authored by Isaac Cambron, a long-time contributor to Moment.

--
Moment.js docs

Just like moment.js, it shares a similar drawback - higher bundle size. There is an open issue (as of writing) on project's repo (link) which has some solutions but I didn't want to meddle with that.

I just want to build my app!!! I wanted something that's lightweight and flexible. In the end, I started using date-fns in more projects.

Speaking of bundle size, date-fns has a webpack section in their docs to reduce the build size (if you're interested).

date-fns - Quick Start

Let's get cracking with date-fns.

Note: I am using date-fns v3.0.0 on the snippets below.

// helloworld.js

import { format, compareAsc } from "date-fns";

const formattedDate = format(new Date(), 'dd-MM-yyyy');
console.log(formattedDate);
// Output: '18-12-2023'

// difference in days
import { differenceInDays } from "date-fns";

const date = new Date();

// Did you know Month starts with 0 in JS's `Date`?
const dateDec1 = new Date(2023, 11, 1);
const diffDays = differenceInDays(date, dateDec1);

console.log(diffDays);
// Output: 17

There are other handy helper functions like differenceInBusinessDays , differenceInHours, etc. Be sure to check the documentation for more info.

The future?

If you're wondering why are we still thinking of third-party libraries for such an important feature, I have some good news!

Temporal is a work-in-progress specification started 2 years ago and can be considered a much needed enhancement over Date .

It was originally drafted in 2017 and has received Stage 3 status back in 2021.

Since it is only stage 3, it is considered experimental and not recommended for production usage just yet.

If you'd like to report bugs, feel free to give it a try!
GitHub Link: https://github.com/tc39/proposal-temporal

Temporal - Quick Start

Let's create an NPM project. You will need Node.JS v14 or later.

# Setup a folder to try the APIs
$ mkdir temporal-research
$ cd temporal-research
$ npm init -y

# Install the polyfill (requires Node v14 or later)
$ npm install @js-temporal/polyfill

Let's print the current date and time in ISO format.

// index.js 
// running on Node v18

// Import Temporal
const { Temporal } = require("@js-temporal/polyfill");
// Get current time/date.
const now = Temporal.Now.instant().toString();
console.log('Temporal: ' + now);
// Output: "Temporal: 2023-09-29T13:47:49.625269601Z"

// I got curious comparing it with `Date` so here you go :)
console.log('Date: ' + new Date().toISOString());
// Output: "Date: 2023-09-29T13:47:49.630Z"

Conclusion

I hope you've learned something new here.

If you've liked this post, show your support by using the emojis on the right. It pleases the algorithm :^)

You can also @ me on Mastodon here.

Bye for now.

In this post, I will explain how to convert an HTML table to PDF. This applies to other HTML widgets but I will be focusing on table which has a large dataset and vertical scrolling to not clutter the page.

Prerequisites

We are going to use 2 libraries to achieve this.

1. html2canvas

2. jspdf

I am using the following versions for this example taken from my package.json.

{
  "html2canvas": "^1.4.1",
  "jspdf": "^2.5.1"
}

Disclaimer

html2canvas:

As the name suggests, html2canvas processes and converts a given HTML DOM node into an image using canvas under the hood while keeping the styling intact.

1. This library is considered "experimental" (as of writing) by its author and should not be used for production.

2. Please take a look at the Features list and verify whether this library supports all features that are required by your web app.

jsPDF:

It is used to generate a PDF file based on the image (created from the html2canvas library).

Learn more on their GitHub here.

Theory

The idea is very simple:

1. We use html2canvas to generate an canvas object with the table.

2. We then use the canvas#toDataURL function (MDN) to generate a data URL.

3. We initialize jsPDF, use addImage function to set the image via data URL.

4. ..

5. Profit?

Implementation

1. Let's create a new Angular project.

$ ng new testpdf

1. Install both the libraries from NPM

$ npm install jspdf html2canvas

1. HTML code for Angular component

<!-- app.component.html -->

  <!-- Export button -->
  <div class="my-3">
    <button class="btn btn-primary" (click)="export()">Export to PDF</button>
  </div>

  <!-- Table -->
  <h3>Preview:</h3>
  <div class="table-container">

    <table id="data-table" class="table table-bordered">
      <thead>
        <tr>
          <th>ID</th>
          <th>First name</th>
          <th>Last name</th>
        </tr>
      </thead>
      <tbody>
        <tr>
          <td>3</td>
          <td>Cartman</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>10</td>
          <td>Cartman</td>
          <td>Titi</td>
        </tr>
        <tr>
          <td>11</td>
          <td>Toto</td>
          <td>Lara</td>
        </tr>
        <tr>
          <td>22</td>
          <td>Luke</td>
          <td>Yoda</td>
        </tr>
        <tr>
          <td>26</td>
          <td>Foo</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>31</td>
          <td>Luke</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>32</td>
          <td>Batman</td>
          <td>Lara</td>
        </tr>
        <tr>
          <td>37</td>
          <td>Zed</td>
          <td>Kyle</td>
        </tr>
        <tr>
          <td>39</td>
          <td>Louis</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>41</td>
          <td>Superman</td>
          <td>Yoda</td>
        </tr>
        <tr>
          <td>42</td>
          <td>Batman</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>43</td>
          <td>Zed</td>
          <td>Lara</td>
        </tr>
        <tr>
          <td>46</td>
          <td>Foo</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>47</td>
          <td>Superman</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>48</td>
          <td>Toto</td>
          <td>Bar</td>
        </tr>
        <tr>
          <td>48</td>
          <td>Batman</td>
          <td>Lara</td>
        </tr>
        <tr>
          <td>54</td>
          <td>Luke</td>
          <td>Bar</td>
        </tr>
        <tr>
          <td>62</td>
          <td>Foo</td>
          <td>Kyle</td>
        </tr>
        <tr>
          <td>80</td>
          <td>Zed</td>
          <td>Kyle</td>
        </tr>
        <tr>
          <td>87</td>
          <td>Zed</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>87</td>
          <td>Toto</td>
          <td>Yoda</td>
        </tr>
        <tr>
          <td>88</td>
          <td>Toto</td>
          <td>Titi</td>
        </tr>
        <tr>
          <td>89</td>
          <td>Luke</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>97</td>
          <td>Zed</td>
          <td>Bar</td>
        </tr>
        <tr>
          <td>101</td>
          <td>Someone First Name</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>104</td>
          <td>Toto</td>
          <td>Kyle</td>
        </tr>
        <tr>
          <td>105</td>
          <td>Toto</td>
          <td>Titi</td>
        </tr>
        <tr>
          <td>107</td>
          <td>Cartman</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>107</td>
          <td>Louis</td>
          <td>Lara</td>
        </tr>
        <tr>
          <td>113</td>
          <td>Foo</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>114</td>
          <td>Someone First Name</td>
          <td>Titi</td>
        </tr>
        <tr>
          <td>119</td>
          <td>Zed</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>121</td>
          <td>Toto</td>
          <td>Bar</td>
        </tr>
        <tr>
          <td>131</td>
          <td>Louis</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>133</td>
          <td>Cartman</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>134</td>
          <td>Someone First Name</td>
          <td>Someone Last Name</td>
        </tr>
        <tr>
          <td>134</td>
          <td>Toto</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>135</td>
          <td>Superman</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>144</td>
          <td>Someone First Name</td>
          <td>Yoda</td>
        </tr>
        <tr>
          <td>154</td>
          <td>Luke</td>
          <td>Moliku</td>
        </tr>
        <tr>
          <td>154</td>
          <td>Batman</td>
          <td>Bar</td>
        </tr>
        <tr>
          <td>155</td>
          <td>Louis</td>
          <td>Whateveryournameis</td>
        </tr>
        <tr>
          <td>156</td>
          <td>Someone First Name</td>
          <td>Lara</td>
        </tr>
      </tbody>
    </table>
  </div>

1. CSS styling (optional)

/* app.component.css */
.table-container {
  height: 50vh;
  overflow: auto;
}

1. Attempt - 1:
   exportPDF function

// app.component.ts
export() {
    // 1. Get a reference to the DOM node.
    const component = document.getElementById('data-table')!;
    // 2. Get a reference to width, height of DOM node.
    const componentWidth = component.offsetWidth
    const componentHeight = component.offsetHeight

    // 3. Generate <canvas> from HTML node.
    html2canvas(component).then((canvas) => {
      // 4. Generate Data URL from <canvas>
      const imgData = canvas.toDataURL('image/png');
      // 5. Create an instance of `jsPDF`
        // 5.1 `orientation`  -> 'landscape' || 'portrait'
        // 5.2 `unit`         -> 'px' (mandatory)
      const pdf = new jsPDF({ orientation: 'landscape', unit: 'px'});
      // 6. Use `addImage` to render generated image into PDF page.
      pdf.addImage(imgData, 'PNG', 0, 0, componentWidth, componentHeight)
      // 7. Download PDF
      pdf.save('filename.pdf')
    })
  }

Results - I

Expected output:

Actual output:

So, what went wrong? There are 3 observations to be made.

1. The contents inside the PDF file are distorted.

2. The content hasn't scaled very well making it blurry (I mean look at the actual result screenshot!).

3. The third column is entirely missing.

After researching this for a while, I came across this StackOverflow post which helped me understand the issue.

My theory is that the width and height properties of the jsPDF's internal page are much smaller than the <table> DOM node. This means we are trying to fit something so big inside something much smaller. So, when we try to fit in a "large" image inside a jsPDF page, it would (obviously) be cut off.

So, how do we fix this?

We need to somehow adjust the width and height properties of the PDF file to match the DOM's width and height.

Let's try this again.

// app.component.ts
export() {
    // 1. Get a reference to the DOM node.
    const component = document.getElementById('data-table')!;
    // 2. Get a reference to width, height of DOM node.
    const componentWidth = component.offsetWidth
    const componentHeight = component.offsetHeight

    // 3. Generate <canvas> from HTML node.
    html2canvas(component).then((canvas) => {
      // 4. Generate Data URL from <canvas>
      const imgData = canvas.toDataURL('image/png');
      // 5. Create an instance of `jsPDF`
        // 5.1 `orientation`  -> 'landscape' || 'portrait'
        // 5.2 `unit`         -> 'px' (mandatory)
      const pdf = new jsPDF({ orientation: 'landscape', unit: 'px'});

      // NEW - set jsPDF page width/height the same as the DOM node.
      pdf.internal.pageSize.width = componentWidth;
      pdf.internal.pageSize.height = componentHeight;

      // 6. Use `addImage` to render generated image into PDF page.
      pdf.addImage(imgData, 'PNG', 0, 0, componentWidth, componentHeight)
      // 7. Download PDF
      pdf.save('filename.pdf')
    })
  }

Results - II

Yup! It works.

If you're wondering whether the "Actual Results" image from above was taken from the output of this code, then you're right :P

Bonus content

There is a chance you're seeing large file sizes on the generated PDF files. This could happen if your table uses too much CSS.
The solution is to enable compress: true option in jsPDF initialization options like so:

// app.component.ts
export() {
    ...

    const pdf = new jsPDF({
        ...,
        compress: true    // reduces PDF file size
    });

    ...
 }

Conclusion

I hope you've learned something in this post.

If you've liked this post, show your support by using the emojis on the right. It pleases the algorithm :^)

You can also @ me on Mastodon here.

Bye for now.

I wanted to make a quick blog post regarding my decision to archive the MyStudio IDE project.

This project has been a huge learning opportunity for me in terms of developing GUI applications, GTK toolkit, and Rust programming language.

The IDE is more than 2 years old and was a fun little project to pick up and work on on and off. As one might've noticed, there haven't been any new commits since February.

I would like to thank the "Rust India Telegram group" for guiding me with a feature I had originally planned. Their insight into the problem made me realise some major architecture-level problems needed to be fixed.

This means a rewrite of the project was necessary but that requires a deeper understanding of multi-threaded applications and async Rust.

After a lot of R&D on this a few times in the past year, I realised I need to learn more to develop it at a level I can be proud of and make this IDE worth someone's time. I couldn't write a half-baked code on a project I love.

Hence, it is with a heavy heart, this project has reached its end on 11 November 2023. The project's GitHub repo has also been archived.

I might work on something else in the future and it could be an IDE but nothing's set in stone yet.

Thank you for your time!

Happy Diwali to you and your family! 🪔

Bye for now :-)

In this post, I am going to show you an easier way to generate Angular forms (with validations!) using a simple JSON object.

TL;DR

For example, to generate a form for user login, we would provide the following JSON payload.

fields = [
{
    key: "email",         # <-- unique identifier for the field
    type: "input",        # <-- Inform library to render a text field
    props: {
        type: "text",     # <-- Informs what kind of `<input>`    
        required: true,    # <-- equivalent to `Validators.required`
        label: "Email",
        placeholder: "Enter email address" 
    }
},
{
    key: "password",         # <-- unique identifier for the field
    type: "input",        # <-- Inform library to render a text field
    props: {
        type: "password",     # <-- Declaring a password field    
        label: "Password",
        required: true,    # <-- equivalent to `Validators.required`
        minLength: 6,    # <-- equivalent to `Validators.minLength(6)`
    }
},

]

It's that simple! Do I have your attention now? Read on.

Implementation

Let's create a new Angular project.

$ ng new json-forms

We need to install a couple of things:

1. @ngx-formly/core - This library provides us with a simple way to build JSON based forms

2. Styling the forms - I am using Bootstrap as an example.
   1. bootstrap - The will change depending on your chosen UI library.
   2. @ngx-formly/bootstrap - Formly's wrapper UI library for Bootstrap

   There are a wide variety of UI libraries supported by Formly. Check the link for more info.

$ npm install @ngx-formly/core @ngx-formly/bootstrap bootstrap@latest

We import FormlyModule and FormlyBootstrapModule into app.module.ts.

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

import { ConfigOption, FormlyModule } from '@ngx-formly/core';
import { FormlyBootstrapModule } from '@ngx-formly/bootstrap';

import { AppComponent } from './app.component';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';
import { FormlyController } from './formly.controller';

const formlyConfig: ConfigOption = {
...
};

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FormlyModule.forRoot(formlyConfig),
    FormlyBootstrapModule,
    FormsModule,
    ReactiveFormsModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Let's see what goes into Formly's config file. This is the real deal. We specify all your (global) validation controllers & their error messages, custom Formly components for advanced usages, etc.

I found it easier in my projects to export all things Formly inside a formly.controller.ts file and simply import them into AppModule.

FormlyController class

This is a custom TypeScript class comprising static functions that help organize the root config of Formly. I found this to be easier when working on other projects.

Here is the final formly.controller.ts that works for setting up the user login page.

Feel free to adapt this to your needs.

// formly.controller.ts
import { Validators } from "@angular/forms";
import { TypeOption, ValidationMessageOption, ValidatorOption } from "@ngx-formly/core/lib/models";

export class FormlyController {

  // A helper function containing all your required validators.
  // Here, you can specify any custom validations that you might need.
  static getValidators(): ValidatorOption[] {
    return [
       {
        name: 'email',
        validation: (control) => {
          const result = Validators.email(control);
          if (!result) return {email: true};
          return null
        }
      }
    ];
  }

  // Declare a suitable error message for validation errors.
  // Note: In my case, I had to declare messages for 
  // built-in Validation types.
  static getValidationMessages(): ValidationMessageOption[] {
    return [
      {
        name: 'required',
        message: 'This field is required'
      },
      {
        name: 'minLength',
        message: (_, f) => 'This field should be atleast '+f.props?.minLength+' characters'
      },
      {
        name: 'email',
        message: 'Invalid email address'
      }
    ]
  }

  // Here, we declare all your custom Angular components
  // that need to render inside <formly-form>.
  static getTypes(): TypeOption[] {
    return []
  }
}

Let's look at AppModule where we initialize and use this config.

// Declare Formly config
const formlyConfig: ConfigOption = {
  validators: FormlyController.getValidators(),
  types: FormlyController.getTypes(),
  validationMessages: FormlyController.getValidationMessages()
};

// Initialize Formly with the config
@NgModule({
    ...,
    imports: [
    FormlyModule.forRoot(formlyConfig),
    ...,
    ],
})
export class AppModule { }

Progress #1

This code should be just enough to render the form. Let's quickly run ng serve on our test project and look at the output.

First look:

We test required validator below:

We test the "invalid email" validator and the password's "minLength" validator:

Awesome! How do I submit this form?

How to submit this form?

There are two ways to do this:

1. The easy way would be to add a <button> into the HTML file, bind disabled property (of the button) to the form and set up a click listener that processes your request.

2. Create a custom button widget in Formly which is reusable.

I will be covering the second way in another post. The link will be added here once it's up.

To get started, let's create our HTML file.

<!-- app.component.html -->
<div class="login-container">

  <div class="card">
    <div class="card-body">
      <h2 class="card-title text-center">Sign in to continue</h2>
      <form [formGroup]="formGroup">
        <formly-form [fields]="fields" [form]="formGroup"></formly-form>

        <button class="w-100 btn btn-primary" [disabled]="formGroup.invalid" (click)="processSignIn()">Sign In</button>
      </form>
    </div>
  </div>
</div>

And here is the source code for the TS file:

// app.component.ts

export class AppComponent implements OnInit {
  formGroup = new FormGroup({});

  fields: FormlyFieldConfig[] = [
    {
      key: "email",
      type: "input",
      props: {
        type: "email",
        required: true,
        label: "Email",
        placeholder: "Enter email address"
      },
      validators: ['email']
    },
    {
      key: "password",
      type: "input",
      props: {
        type: "password",
        label: "Password",
        required: true,
        minLength: 6,
        placeholder: '*******'
      }
    },
  ]

  ngOnInit(): void {
  }

  processSignIn() {
    alert('Sign in called');
  }
}

Lastly, here is the stylesheet used

.login-container {
  display: flex;
  align-items: center;
  justify-content: center;
  height: 100vh;
}

.login-container .card {
  min-width: 600px;
}

End Result

Invalid form details

Notice the button is disabled when validation fails.

Sign In button is clicked.

Conclusion

I hope you've learned something new in this post. Please feel free to add your thoughts below. I would love to know them!

Formly is a great tool for cases where you know the web app has so many HTML forms to write.

Check out Formly by visiting their website here.

If you've liked this post, show your support by using the emojis on the right. It pleases the algorithm :^)

You can also @ me on Mastodon here.

Bye for now.

In my previous posts here and here, I talked about creating a Python app that switches my KDE Plasma's theme to light or dark according to the system time. This app uses a config file that lives in $HOME/.config/auto-dark-theme as per XDG user base specification.

Background

I wanted a way to "force" light or dark theme using my app for testing purposes without having to tweak the config file (and restart the systemd service).

This CLI will help me temporarily switch the theme irrespective of system time until the next trigger.

Theory

The idea is the CLI should allow users to forcefully switch from a light or dark theme with a simpler syntax.

Next, it should allow the user to view their current config preferably in a table on their terminal.

We should provide a helper shell script to call cli.py without having to use python -m auto-dark-theme.cli every time.

Valid commands

1. It should support a --theme option with -t as its shorthand that allows either light or dark as the supported parameters.

2. It should support a --list-config option that parse the config file and displays it in a table.

Implementation

You can find the latest code for the CLI on the GitHub repo here.

I create a new file cli.py inside auto-dark-theme as shown below:

App_Root
├── auto-dark-theme
│   ├── cli.py          # Hello, there.
│   ├── config.py
│   ├── dbus.py
│   ├── __init__.py
│   ├── __main__.py
│   ├── __pycache__
│   ├── spawn.py
│   └── switcher.py
├── config
│   ├── autodarktheme   # Helper shell script.
│   ├── auto-dark-theme.service
│   └── config.sample.ini
├── LICENSE
├── pyvenv.cfg
├── README.md
├── requirements.txt
└── setup.cfg

I will be using the excellent argparse library for this as I have prior experience with it.

# cli.py

import argparse
# Create an instance of ArgumentParser
parser = argparse.ArgumentParser(
    prog='auto-dark-theme', 
    description='Switch your DE theme between light/dark themes acc. to specified time for KDE Plasma'
)

ArgumentParser takes care of managing the CLI interface and setting up some defaults like printing output similar to other CLIs, printing the usage section if user inputs were incorrect and type-casting user inputs (for int, float, etc.) among others.

# cli.py

# Add arguments supported by CLI
# -t || --theme
parser.add_argument(
    '-t', '--theme', choices=['light', 'dark'], required=False, help='Forcefully switch between light/dark theme.')
# List config
parser.add_argument(
    '-l', '--list-config', action='store_true', help='List current config.')

We use add_argument here to add arguments supported by our app. In this case, I need to support 2 arguments:

1. -t or --theme for theme switching

2. -l or --list-config for listing current config

# cli.py

from tabulate import tabulate
from .switcher import ThemeSwitcher
from .config import AppConfig

# Parse & process
result = parser.parse_args()

# Trigger theme change if provided
if result.theme == 'light':
    ThemeSwitcher().switch_to_light()
if result.theme == 'dark':
    ThemeSwitcher().switch_to_dark()

if (result.list_config):
    app_config = AppConfig().list_config()
    print(tabulate(app_config, headers=['Option', 'Value'], tablefmt="outline"))

In the above lines lies the core logic for driving the argument parsing and performing tasks according to user input.

parser.parse_args() will run the parser on user input and place the resultant values inside the result object.

If -t or --theme are used, the first two if 's will be triggered according to user input.

If -l or --list-config is used, we create an instance of AppConfig which returns a list of items to be shown to the user. I am using tabulate Python library for generating pretty tables for this. It's so nice :^)

Lastly, let's create a helper script for running auto-dark-theme CLI without calling the Python file directly.

#!/bin/sh

# I know, I know. This is hardcoded and will be fixed 
# once I figure out setup.py for distribution.
/home/suryateja/Projects/auto-dark-theme/bin/python -m auto-dark-theme.cli $1

Result

Here lies the screenshot of the usage section for the newly created CLI:

And the output for the list config argument is shown below:

Next steps

Create a setup.py file for two reasons:

1. Installing the app should be a simple pip install --user auto-dark-theme away!

2. Get rid of all hardcoded paths that link to my local machine.

Conclusion

I hope you've learned something new in this post. Please feel free to add your thoughts below. I would love to know them!

If you've liked this post, show your support by using the emojis on the right. It pleases the algorithm :^)

You can also @ me on Mastodon here.

Bye for now.