Tag Archives: Documentation

glibmm: Deprecated Glib::Threads

General, , , ,

As of glibmm 2.47 (currently unstable), we have deprecated the glibmm threads API, which wrapped the glib threads API. That’s because C++11 finally has its own standard threading API, and in C++14 its complete enough to replace all of Glib::Threads.

Here’s what replaces what:

We’ve replaced use of Glib::Threads in our example code and tests, such as the example in our multithreading chapter in the gtkmm book.

This is quite a relief because we never wanted to be in the concurrency API business anyway, and having a standard C++ concurrency API makes it far easier to write cross-platform code. Now if we could just have a standard C++ network IO API and maybe a file structure API, that would be nice.

 

Rygel Documentation

General, , , ,

Over the last few months, I have worked on Rygel‘s documentation, along with Krzesimir Nowak and Jens Georg here at Openismus. Most of that work is now finished. It’s been a great investment of time that should be of real benefit to the project.

We’ve massively improved Rygel’s (C) API documentation, which was rather bare after Rygel’s initial split into shared libraries. We had to investigate how the current plugins use the API, and sometimes improved the API in response. (The very latest API documentation improvements will be online soon, when we do a new Rygel release.)

We’ve added both simple and real-world examples, linking to them from sections in the API documentation and describing how those examples work. Those real-world examples are standalone GStreamer-0.10-based versions of the regular Rygel media engine and of its media-export server plugins, plus a GStreamer-0.10 version of the standalone renderer example.The original code for these (now using GStreamer-1.0) was in Vala, like the rest of Rygel, so we had to convert them to C. To maintain functionality, we chose to clean up the horribly-obfuscated C code generated by Vala. That took us a few frustrating weeks to finish but we got it done.

The new Rygel Integration page provides an overview of the APIs that platforms should find interesting, linking to the various documents that we’ve created during this effort. That Integration page is part of a complete overhaul of Rygel’s wiki project pages to make them more attractive and useful.

To help with maintenance of Rygel itself, we now have a Rygel Architecture page with descriptions of Rygel’s program flow in various situations, and a Rygel architecture diagram showing how the various parts of Rygel work together.

 

 

Clutter Tutorial done for now

General, , ,

Now that Clutter 0.6 is out, I found the time to finish the planned sections for the Clutter tutorial that I mentioned in December, for Openismus. Here is the html version and a PDF, though of course the PDF doesn’t have the nice links into the API reference documentation and the links to the actual files of the examples.

The guys at OpenedHand haven’t had time to review this yet, so be aware that there could be significant errors. But I think it’s mostly accurate, useful, and unique, though the appendices and full example are obviously lacking. I’ll try to keep it up to date and correct as I get feedback.

Having done all this investigation into Clutter, I have formed some opinions:

  • Clutter is a nice way to move semi-3D things around on the screen to create “innovative” user interfaces. Its abstractions for actors and behaviours really give you something to work with compared to using OpenGL directly. But it’s still hard to create natural-feeling responsive applications and I don’t know exactly what’s lacking. It feels like there is a disconnect between the act of coding and the very dynamic UIs that the code creates. I sometimes feel I’d like to just put actors on a rail, twist that rail about, connect some actors together with struts or springs, start them moving, let the user push and pull them around within constraints, and trigger extra behaviour when they reach certain positions, or reach each other.
  • Clutter is now a very basic API. You will need to implement a lot of simple functionality to create applications that act as today’s users expect. The Tidy “reference-implementation” example toolkit thing is not a shared library – it’s meant as an inspiration for you to do all this yourself, and it is itself not very complete. I don’t think that is a wise strategy, though rampant bad reimplementation is the standard in today’s mobile/embedded development projects.
  • Neither you or Clutter should want to reimplement the huge amount of UI logic that is, for instance, in GTK+. Without reusing all that work, Clutter applications will generally have inconsistent or inadequate text editing, scrolling, focus, keyboard accessibility, right-to-left language support, etc. Applications will share little common API so it won’t be easy to throw new developers at your project. Somehow we need a way to use some GTK+ widgets in Clutter without them looking and feeling like they are visitors from an extra dimension.

These problems could probably be solved by lots of hard work by smart people. I don’t know what the near-future strategy for Clutter is, so I don’t know if the current state is intentional or if anything particular is planned. It’s certainly getting better all the time.

Clutter Tutorial

General, , ,

Over the last couple of weeks, I’ve been writing a Clutter tutorial for Openismus. Clutter is a “2.5D” canvas API maintained by OpenedHand.

Here you can see a preview of the tutorial, though some sections just have TODOs for now. I think it’s already the only place to find a useful description of Clutter Timelines, Effects and Behaviours and how they relate to each other, and it’s the only place that I’ve seen mention of how to manage the refcounting of the various objects. Thanks to the OpenedHand guys for answering my questions so patiently.

I’m waiting for the new high-level Clutter library to be created before completing the remaining sections, because the containers have already been moved out of the main clutter library, and that new library should have some interesting (but maybe not perfect at first) actors for doing scrolling and lists of text.

It’s DocBook, with some scripts to pull in the example code, in the clutter-tutorial module in OpenedHand’s svn repository:

As I’ve done in the past for gtkmm documentation, the examples are almost mind-numbingly simple so people have the best chance of seeing the use of the relevant API. However, there is one slightly more realistic full example. I hope that the containers in the new library will help me to make it prettier.

I guess you should report bugs in the tutorial in Clutter’s bugzilla, in the Documentation component.