DEV Community: Igor Montagner

Vala reactive programming: part 3

Igor Montagner — Sun, 02 Jan 2022 21:01:34 +0000

The last article showed how we could create a Window with two different forms with clear separation between application logic and GUI code. Most of our work consisted of binding properties and using signals to send information out of components. Although this seems to work well with our little example, our application didn't have any global state. One could argue that global state is a code smell (and a lot of people do), but the fact is that lot's of applications use it to some degree.

One of the problems of global state is that it increases coupling. Essentially, coupling represents the amount of interdependency between two or more modules. Frequently, in situations with large coupling a change in one module snowballs into lots changes in the related modules as well. This is why coupling is seen as bad: there's the possibility of a butterfly effect in which a small change in one module produces a large change overall.

We could simply add properties to our Application class pass them along to our components. This could be done either through bindings, via constructor parameters or by referencing the parent component using (Application) this.parent.property_name. All these options are fine, in the sense that they work but might cause coupling problems.

The first two may require passing a reference to or binding Application to basically every class you write. Not only this is annoying but it also makes testing harder. We might need to mock Application for basically every class we test, since we are introducing a hard dependency on Application existing even in functions where it's not used.

We could circunvent this by using parent references. However, we can easily get to a point where code like this is written: parent.parent.property_name = .... Not only this type creates highly coupled components, it's also very brittle. A component might break because of a change in the hierarchy of an apparently unrelated set of components. It might also be a nightmare to test, since we might need to reconstruct whole hierarchies of objects

It's possible to avoid this problems by being extra careful. The issue here is that it's easy to shoot yourself in the foot when using these approaches. So we'll try something different.

In this post we'll explore using a Singleton to store shared data and logic. A Singleton is a class that only has one instance which is shared. Although *Singleton*s look like classes with all static properties and methods, some key differences exist:

*Singleton*s can implement interfaces
*Singleton*s can lazy load resources
A Singleton instance can be passed a argument to other functions or methods

Building a singleton in Vala is easy:

class SingletonExample {
    private SingletonExample () {
        // TODO: initialize all resources here
    }

    private static SingletonExample? _instance;

    public static SingletonExample getInstance () {
        if (_instance == null) {
            _instance = new SingletonExample ();
        }
        return _instance;
    }

    // shared data is created using public properties

    // shared logic is created using public methods 
}

Using it is even easier:

SingletonExample.getInstance ().method_here ();
SingletonExample.getInstance ().property_name = XXX;

Make no mistake, if we need shared data we are going to have to deal with coupling.

By using a Singleton **all components depend on the Singleton , which helps us to avoid components depending on other components**.

The advantage of using a Singleton is that it concentrates the dependencies into a single class. Instead of using parent or passing references deep into our component hierarchies, we can access SingletonExample.getInstance () anywhere in our code. We can also bind to SingletonExample's properties and connect to signals it emits. Thus, our reactive components can now react to local as well as global state changes.

Some situations where using *Singleton*s may bring advantages include

sharing a list of opened folders/files in a text editor
saving/retrieving user settings from dot files and making them available to the rest of the application
storing a list media folders in a music/videos application

Global state should be minimized and good design helps both decreasing coupling and creating testable and quality code. However, sometimes using shared state leads to simpler design and less code. If this is the case, you might want to consider using Singleton in your next project.

Vala reactive programming: part 2

Igor Montagner — Fri, 24 Dec 2021 14:18:53 +0000

In the last article we explored how to use properties and bindings to create reactive style programming in Vala. All UI code was written in construct and all logic was represented by setting properties. UI was synchronized with the Widget state by binding properties to child widgets. Although the separation of concerns was nice, the example was too simple. There was only one component (the LoginForm) and no information was neither (i) sent to other components; or (ii) received from other components. In this article we'll create a second form that receives the validated user from LoginForm to a second form.

All the example code for this article is available at the part2 folder in this github repo

Our component architecture will be based on the following principle:

If two components share a parent, then it's the parent's resposability to connect them into a meaningful flow for the application

Let's use this principle to extend the example from the last article and add a UserInfoForm after a succesful sign in. We'll start from the part2/v0.vala file.

Dealing with events inside a component

Events are a place where UI and logic code seems hard to separate. It's quite natural, for instance, to create a login_btn_click event handler that uses both GUI calls to get information from the UI and properties. Fortunately, Vala also provides us with a very nice way of separating this: lambda functions as event handlers.

private void do_login () {
    // check database and validate login here
    // GUI calls are forbidden here, only properties and other methods can be used
}

construct {
    // ....

    login_btn.clicked.connect (() => {
        // extract all info from the UI using GUI calls
        do_login (); 
    });
}

In the lambda event handler we can extract all info from the UI using GUI calls and then pass this information along to a method. Since we can use bindings to link information between properties and GUI elements, the amount of code inside the lambda event handler can be quite small. In fact, it might only treat the event information and pass it on to a method that uses it. Another interesting point is that lambda can ignore arguments and their types, so if we don't use the GEvent that the handler is supposed to receive we can just ignore it in our declaration.

This has two advantages:

do_login does not receive Gtk.Event (or similar), which means it can be called from anywhere in the code, not only in response to an user generated event.
Event handlers often receive different arguments depending on which event they handle. The lambdahandler is used to treat this arguments, so do_login is not tied to a single type of event.

Sending information out

For sending information out of our components we can use signals. For instance, upon succesful login our LoginForm could emit a login_succesful signal that sends a User instance with the currently logged in user info. Now it's up to the parent of LoginForm to receive the signal and connect it to the next part of the application flow.

First we modify LoginForm. For now our User class only contains the username property. Also, username is can only be assigned when creating an User instance.

class User : Object {
    public string username { get; construct; }

    public User (string username) {
        Object (username: username);
    }
}


class LoginForm : Gtk.Grid {
    public signal void login_succesful (User u);

    // ....

    private void do_login() {
        login_succesful (new User (username));
    }
}

Then we receive this information in our Application class:

class Application : Gtk.Application {

    protected override void activate () {
        var win = new Gtk.ApplicationWindow (this);
        var login_form = new LoginForm ();
        login_form.login_succesful.connect ((u) => {
            print ("%s\n", u.username);
        });
        win.add (login_form);
        win.show ();
    }

}

The complete code is shown in part2/v1.vala.

Intermission: `Application` mixes UI and logic

Our Application class is not following the principles outline in the last article. Let's fix that while we add a new Gtk.Stack to hold our new HelloForm.

class HelloForm : Gtk.Grid {
    construct {
        expand = true;
        valign = Gtk.Align.CENTER;
        halign = Gtk.Align.CENTER;

        var label = new Gtk.Label ("Hello (username goes here)");
        attach (label, 0, 0);
    }
}

Instead of creating widgets inside Application we introduce a ApplicationWidget, a class with the sole purpose of creating the workflow of data between our components. Our first version is shown below.

class ApplicationWidget : Gtk.Stack {
    construct {
        // ...

        var login_form = new LoginForm ();
        add_named (login_form, "login_form");

        var hello_form = new HelloForm ();
        add_named (hello_form, "hello_form");

        visible_child_name = "login_form";
    }
}

The complete code is shown in part2/v2.vala. Our application works exactly the same as before, but now UI is separated from the rest of the app in Application as well.

Receiving information from other components

For receiving information from the "outside" worlds we have two options: regular instance methods or public properties. The advantage of using instance methods is that they can be directly connected to other components' signals. However, we must take care of only updating properties inside it so we don't mix UI and logic. We can also use public properties to receive data from the "outside world".

Use methods if something besides updating the UI is necessary (i.e. pulling information from the database or the web)
Use properties otherwise

We add a user property to HelloForm so it can receive the currently logged in user. We then connect the components in our ApplicationWidget:

class HelloForm : Gtk.Grid {
    public User user { get; set; }

    // ...
}

class ApplicationWidget : Gtk.Stack {
    construct {
        // ...

        login_form.login_succesful.connect ((u) => {
            hello_form.user = u;
            visible_child_name = "hello_form";
        });

    }
}

The final part of this is to connect a change in HelloForm.user with the UI. A first could be creating a binding between user.username to the label text. This won't work, as we are not changing the username property of user, we are overwritting the whole user object. Our binding must reflect that and listen to changes on the entire user object.

Up until this point we only used bindings with the same source and target type. GObject also allows transformation bindings, in which we bind properties with different types and provide a function to transform on type into the other.

class HelloForm : Gtk.Grid {
    public User user { get; set; }

    construct {
        // ...

        bind_property ("user", label, "label", BindingFlags.DEFAULT, (binding, srcval, ref targetval) => {
            var user = (User) srcval.get_object ();
            targetval.set_string("Hello, %s!".printf (user.username));
            return true;
        });

    }
}

Transformation functions receive GLib.Value, so we need to convert to the type of objects we need. Now our HelloForm reacts to a change in the application state in a complex way. And this concludes our experimentation with "reactive" Vala and GTK+.

I personally like this style of code much more than what I usually read in desktop GUI applications. What do you think?

If you liked this post consider buying me a coffe and/or following me on twitter at @igor_montagner.

Vala reactive programming

Igor Montagner — Mon, 06 Dec 2021 20:03:52 +0000

I've been doing some web programming using preact these last weeks and one of the things that impressed the most was the way logic and UI are split in code. When doing functional components this is specially explicit. Your function returns whatever should be displayed by the component and receives a props object containing all the information the components need to render. A component rerenders when some of its props are changed, either because an external component made changes or in response to an event.

IMHO, this really helps to organize code and separate concerns. All the logic is written in terms of the components' properties. The GUI is updated in response to changes in the properties in order to synchronize the component state with what is shown on screen.

We can also achieve this in Vala using properties and bindings from GLib. In this article we will produce a login screen that validates the username and password fields. All code is available at Github.

Important: The repo contains many iterations of the code presented in this article. A comment containing the name of the original file is shown at the top of each code listing.

Let's start with the basic code to build the form above. This is just standard GTK code: all the ui elements are created in the construct method. The original file (v1/main.vala) also contains a Gtk.Application subclass that handles initialization and showing our form.

Vala tip: the construct block runs during an object's creation and after named constructors are called.

// excerpt from v1.vala

class LoginForm : Gtk.Grid {
    // ......

    construct {
        width_request = 300;
        margin = 10;
        column_homogeneous = false;
        expand = false;
        valign = Gtk.Align.CENTER;
        halign = Gtk.Align.CENTER;

        var username_field = new Gtk.Entry () {
            hexpand = true,
            margin = 4
        };
        var password_field = new Gtk.Entry () {
            hexpand = true,
            margin = 4
        };
        var validation_warning = new Gtk.Label ("") {
            wrap = true,
            height_request = 50
        };
        var login_btn = new Gtk.Button.with_label ("Login") {
            expand = false,
            halign = Gtk.Align.END
        };
        attach (new Gtk.Label ("Username"), 0, 0);
        attach (username_field, 1, 0);
        attach (password_field, 1, 1);
        attach (new Gtk.Label ("Password"), 0, 1);
        attach (validation_warning, 1, 2);
        attach (login_btn, 1, 3);

        show_all ();
    }
}

There's no interactivity in this form yet. In fact, it already starts in an inconsistent state: the Login button is enabled even though block fields are empty. We could fix this simply by setting sensitive=false in login_btn initialization, but we won't. Instead we will create a property called is_valid and bind its value to login_btn.sensitive. Every time one of the values change the other is instantly updated. Bindings can also be created with many values as long as a cicle is not introduced.

Let's use this now in our program: first we create a property is_valid and then we use bind_property to bind its value to login_btn.sensitive. Our binding flags indicate that the binding is bidirectional and that the value is synchronized when the binding is created.

// excerpt from v2.vala

class LoginForm : Gtk.Grid {
    public bool is_valid { get; set; default = false; }

    construct {
        // GUI creation code

        bind_property ("is_valid", login_btn, "sensitive", BindingFlags.BIDIRECTIONAL | BindingFlags.SYNC_CREATE);
    }

Now the login button is disabled when the app starts and will remain so until we set is_valid=true. Unfortunately this never happens, so let's add a property username and bind it to username_field.text. When username is set we check if its length is larger than 0 and set is_valid accordingly.

// excerpt from v3.vala

class LoginForm : Gtk.Grid {
    public bool is_valid { get; set; default = false; }

    private string _username = "";
    public string username { get {
        return _username;
    }
    set {
        _username = value;
        if (value.length > 0) {
            is_valid = true;
        }
        else {
            is_valid = false;
        }
    }}

    construct {
        // GUI creation code

        bind_property ("is_valid", login_btn, "sensitive", BindingFlags.BIDIRECTIONAL | BindingFlags.SYNC_CREATE);
        bind_property ("username", username_field, "text", BindingFlags.BIDIRECTIONAL | BindingFlags.SYNC_CREATE);
    }

Run the app and test the new validation: the login button should be disable when the app starts and respond to is_valid. IMHO, the impressive part of this code is that all GUI code is on construct and our logic is written only in terms of properties. When we update the Widget's properties the UI will update in response, so our application state is always consistent.

Now the final step is to set validation_error to a meaningful message. We can do this with another property binding. To make code more readble we also refactor all our validation code into a function void validate_form ().

// excerpt from v4.vala

class LoginForm : Gtk.Grid {
    public string validation_error { get; set; default = ""; }
    public string username { get {
        return _username;
    }
    set {
        _username = value;
        validate_form ();
    } }

    //....

    construct {
        // ....

        bind_property ("validation_error", validation_warning, "label", BindingFlags.DEFAULT | BindingFlags.SYNC_CREATE);
    }

    private void validate_form () {
        if (_username.length == 0) {
            is_valid = false;
            validation_error = "Empty username";
            return;
        }
        is_valid = true;
        validation_error = "";
    }

And that's it for the username field. We can do exactly the same for the password field and arrive at the final code available at final.vala in the example repository.

Another interesting project is Blueprint compiler, which creates a sort of DSL for Gtk components. So, what do you think about this style of Gtk programming? Join the conversation in the comments ;)

One PR a month: February and March

Igor Montagner — Sun, 28 Mar 2021 15:23:12 +0000

Since I did not publish a report in February, I am doing a joint February + March post using a couple PRs I recently sent.

One of the things I like about elementary is the care taken with UX. For instance, for less experienced users pasting random commands in the terminal is a sensitive operation, specially if these commands involve administrative privileges. For this reason, elementary's terminal app shows a warning when the user pastes commands involving sudo or with newlines.

Two issues were raised with this dialog:

That details field did not exist (issue #562), so it was hard for the used to check the if the command being pasted was really dangerous
Pressing Escape would paste the text anyway (issue #293).

Although both seem like very simple issues, everything is done taking into account these small details. This contributes to the polished feeling elementary has.

Fixing the first was really simple: the paste protection dialog inherits from Granite.MessageDialog. This class has a method show_error_details that creates the small collapsible text box. I just needed to call it with the appopriate text and call it a day: PR #563. It was almost instantly approved.

The second issue was also simple: the dialog returns 1 if the "Paste Anyway" button is pressed and 0 if the "Don't paste" button is pressed. The code that checked if pasting should be cancelled was akin to if (response == 0). I'm not sure what pressing Escape returns, but I'm pretty sure that text should only be pasted if response == 1. So I changed the condition and now pasting works. This was done in PR #569.

An important point of both PRs is that they are very simple. I used these to emphasize the contributing does not require superior ultra coding skills, just some pacience and a little effort. There are many issues that are easy and up for grabs not only in elementary but also in many other projects.

If you decide to take this challenge as well leave a comment. Or if you need help finding easy issues in elementary ;) Or anything , really.

One Pull Request per month: January

Igor Montagner — Sun, 31 Jan 2021 00:52:39 +0000

This year I'll be doing a challenge: submit at least one Pull Request to a FLOSS project. January's PR is a fix to No audio is recorded with videos #148 , a bug in Elementary OS 6's "rewrite" of the Camera app. The backend was changed to pure GStreamer and this introduced some regressions. However, it also allows for better device detection and possibly more control over video and audio settings. Hopefully this new version will solve many of the "Camera does not work on XXX" issues.

Having worked on Camera in the past (see my contributions in my previous post), I decided to tackle a new issue: no sound was being recorded on the app. After some investigation I realized that this was expected: the app never requested sound to be recorded!

GStreamer works with data processing pipelines with three basic elements:

sources, such as webcams, microphones or files, forward data from an external source to the pipeline
sinks, such as files or user interface elements, receive data from the pipeline and either save it or display it.
elements receive data from the pipeline, transform it and forward this result to other elements or a sink.

Thus, data flow from one or more sources, passes thru many elements that transform it and finally reaches a sink where it is stored or shown to the user. The following pipeline was being used:

"v4l2src device=%s name=v4l2src !"
"video/x-raw, width=640, height=480, framerate=30/1 ! " +
"videoflip method=horizontal-flip name=hflip ! " +
"videobalance name=balance ! " +
"tee name=tee ! " +
"queue leaky=downstream max-size-buffers=10 ! " +
"videoconvert ! " +
"videoscale ! " +
"gtksink name=gtksink"

We only have a single source, v4l2src, which corresponds to a Video for Linux 2 device (usually webcams or other external USB cameras). Data is passed thru many elements using a "!" character until reaching a gtksink that shows the video preview. To record videos a new branch was connected to the tee element that included a video encoder and a filesink that finally stored the video to a file. Thus, the current pipeline only has a single source that produces video frames.

To record audio we need a source that produces audio. This can be done by adding an alsasrc element that produces audio using the ALSA sound system. Gstreamer offers a very neat way of testing pipelines: the gst-launch-1.0 app.
The following sequence of elements obtains data from the microphone using ALSA, encodes it using the Vorbis codec and packages it into a Ogg container.

gst-launch-1.0 -e alsasrc ! audioconvert ! vorbisenc ! oggmux !  filesink location="aa.ogg"

Notice that we still can't produce a file with both audio and video! Both pipelines produce only one or the other. That's where the oggmux element comes into play: its role is to combine audio and video streams into a stream. Thus, to record audio as well we only need to add the elements above to the existing pipeline and link them to the existing oggmux element. The code below does the job and is the basis of my January PR: Add audio recording elements to record_bin. #153 .


var alsasrc = Gst.ElementFactory.make ("alsasrc", null);
if (alsasrc == null) {
    missing_messages += Gst.PbUtils.missing_element_installer_detail_new ("alsasrc");
}

var audio_queue = Gst.ElementFactory.make ("queue", null);

var audio_convert = Gst.ElementFactory.make ("audioconvert", null);
if (audio_convert == null) {
    missing_messages += Gst.PbUtils.missing_element_installer_detail_new ("audioconvert");
}

var audio_vorbis = Gst.ElementFactory.make ("vorbisenc", null);
if (audio_vorbis == null) {
    missing_messages += Gst.PbUtils.missing_element_installer_detail_new ("vorbisenc");
}

// ...

record_bin.add_many (alsasrc, audio_queue, audio_convert, audio_vorbis);
alsasrc.link_many (audio_queue, audio_convert, audio_vorbis, muxer);

The code is rather self explanatory and is basically a Vala version of the command line pipeline I showed earlier. And... that's it. I'm now waiting for the maintainers to review it and begin the improvements so it eventually gets merged. Now I only have 11 PRs left for 2021. Let's keep them coming!

Treat Pull Requests are conversations, not code donations

Igor Montagner — Mon, 25 Jan 2021 14:00:54 +0000

Developers create and contribute to Free and Open Source Software for various reasons and it seems more and more people are interested in doing it. There are many articles that sound like Start contributing to open source in X steps and Hacktoberfest-like events that aim to increase engagement in FLOSS. It's not that most of these articles offer bad advice and some are actually pretty good. However, they miss a key element that I experienced time and time again when contributing to Elementary OS: sending a Pull Request is the starting line, not the finish. No matter how many magical features you implement, no project is going to accept your code if it's a mess and/or does not follow the projects design/code guidelines. For maintainers, code donation does not help: either a contribution is fit for merging or it isn't. Since fixing other people's code is hard, maintainers prefer to ignore contributors that are not open to getting their code up to the projects' standards.

In my previous article I comment on many PRs I proposed in 2020. The only ones were accepted without modifications were simple bug fixes that were very local and did not significantly impact the apps. Every other PR started (sometimes long) discussions about how to improve the proposed changes, including many design changes and even discussions if the feature should be implemented at all.

To illustrate this I'll comment the process for getting Add option to mirror the webcam image #138 accepted. My first try looked like the GIF below:

Many design issues were raised and I created a second version:

I received some curious feedback on this one:

After some misunderstandings I was finally able to produce an acceptable version. Notice that now there are sliders in the menu! They were introduced after my first attempt and I needed to add my option to the menu without breaking these new modifications.

This conversation highlights a very reasonable principle: unless you are already invested in a project and know it very well, your first PRs are probably not good enough to be accepted without modifications. And that's OK and expected. So instead of thinking that you are helping a project or donating/giving code to a project, it makes more sense to understand that proposing a Pull Request is equivalent to starting a conversation.

The conversation metaphor is interesting because it emphasizes that it takes two (or more) people to get a PR accepted:

maintainers help newcomers and external contributors to adapt their changes so they are up to the project's standards;
contributors continue to engage and improve their proposals until they are finally merged.

If any part disengages then the changes won't be merged and part of that effort might be wasted. Since PRs are public this might still be used by some future PR and eventually get accepted, but the odds are not favourable.

One of the good points about viewing PRs as conversations is that it is acceptable, maybe even natural, to reach out if it becomes stale. Sending messages like "Let me know if any changes are needed" or pinging people after addressing their feedback are good ways to keep the conversation alive. Just don't abuse it: maintainers are usually overworked, so sending too many messages actually makes things worse. Be polite, open to improvements and do you best to help them help you become an even better developer.

My year in review: contributions to Elementary OS

Igor Montagner — Fri, 18 Dec 2020 14:19:29 +0000

This year I decided to take my open source contributions to the next level and focus my attention on a single project: Elementary Linux. I choose this project for three simple reasons:

I use it for both work and personal use;
It has a strong focus on design. I suck at design, so contributing with elementary might help me to learn a thing or two about it;
It focuses on providing nice defaults. I have wasted too many hours customizing KDE and other WMs, but with elementary everything works well out of the box.

Camera

The Camera app is migrating toward using GStreamer directly and a lot of things are changing right now. My first contributions were aimed at better camera detection: there are many reports of non-working cameras and PRs #127 - Setting v4l device now works correctly and #128 -
Use gst.DeviceMonitor to list video sources include better detection by using GStreamer to enumerate available cameras.

Another area of improvement was to allow simple image adjustments in the app. Mirroring was added in #138 and brightness and contrast in #139.

IMHO, my largest contributions was actually #134 - Add option to switch cameras. I frequently use two cameras for classes and this not being able to select which to use was quite a limitation. After some back and forth regarding design issues it was finally merged!

I am still waiting for feedback in #142 - Send notification when recording has finished, but it looks promising as well.

Code editor

A first simple contribution was to enable changing tabs using Ctrl+Tab. This scratched an itch that was bothering me for a long time: I've lost count of how many times I tried to use the shortcut with Code... and now I don't need to count anymore. The PR was accepted and is already shipping in the pre-release images for Elementary 6!

A second item on my wishlist was better markdown support. I like using Code to edit markdown. Somehow I'm more focused when using it for writing that VSCode, which is my goto editor for code. And issue #850 was a good start. It proposed the inclusion of shortcuts for common formatting such as bold, italics and links. Many other editors use these for accelerating markdown editing and this is now possible since PR #890 was accepted!

I even sent a second PR building a "list mode" of sorts and opened an issue requesting other shortcuts.

Conclusion

This year has been great for me. I've learned a lot about Vala, GTK and design by contributing to elementary. I have even contributed to fix issues that are actually going to be useful for me, which is an even bigger plus. The only downside is that elementary is not a large project with lots of people reviewing code, so sometimes PRs take weeks to finally get merged. Anyways, let's hope that next year brings more learning and merge Pull Requests 🎉️