CEGUI update / mini review

I’ve been using CEGUI for a couple of weeks now. I’ve been trying to get a string to show up, with word wrap, for 5 days. Not actively, but on and off I’ve been pursuing this topic for that long.

My difficulty lies in that I don’t need to use their window system, with selectable text, etc. And I don’t want to define my text in an xml file, the preferred way to setup your interface. I simply want to do the equivalent of printing “Hello World” purely from code, including word wrap.

My first approach was to use the Font class. It seemed pretty good – there is a function to tell you how long a string was and how many lines it would span. I didn’t see a function to tell you where exactly the string was split but it’s a good start. The problem was that it didn’t work. So I asked about this on the forum. A day later I was essentially told not to use that class directly. It didn’t bother me too much, because I had a hunch of the technical reasons why this might be, but user classes should have clearly been delineated from internal classes and marked as such. As an aside, in RakNet all classes are independently functional and are documented as to their use, not just with Doxygen.

Anyway, to display text, you have to create a window and set the text for that window. How do you do this? There’s a Window class, a StaticText class, a DefaultWindow type, and a GUISheet class. GUISheet is the one to use although StaticText is the one you would think to use, with functions to set the text color, formatting, and other things. However, StaticText contains abstract functions, meaning you can’t use it directly, as I found out after I went to the trouble of trying to use it and then compiling. It turns out this is a class for internal use only. Arguably this was my fault for not looking closely enough to see that there were pure virtual functions. This is the same problem as before though – it should have been marked which classes were for the user and which not.

It’s definitely not obvious that GUISheet is the class you would use to display text. This is doubly the case because GUISheet does not contain functions related to text. It turns out the way it supports text operation is through a setProperty function which takes a string for the action to be performed and a string for the parameter. For example. “HorizFormatting” followed by “LeftAligned” (or something similar). I’m not sure how you are supposed to know this. In order to determine what properties were supported I had to search the source code for “: public Property”

Using strings as the native interface to set properties is a design mistake because it adds an unnecessary layer of abstraction between the user and the intended functionality. Rather than simply passing native types around (such as numbers) I have to convert them to strings. When I want to get the native type back from the string I have to do a reverse conversion, which I’m not sure is even supported. The reason they did this was to more easily support scripting. However, the proper way to architect this would have been to provide a translation layer from script strings to native types, such as numbers, with the reverse operation supported as well, rather than taking strings directly and hiding the native types.

CEGUI is very powerful if you stick to the mechanisms they give you. With almost no effort you can add tables, scroll bars, buttons, input windows, and other widgets. However, these widgets do not provide everything you might need. For example, my current difficulty comes from the fact that I’m trying to fade out and then delete text over time, a function not natively provided. It seems like cracks in the armor start to show through in those instances.

For API usability I’d give CEGUI a C-. It’s well documented at the level of Doxygen. They use Doxygen much better than RakNet does. Depreciated and non-user classes are not documented as such that I was able to see. The newer features seem to have worse architecture than the older features. However, the availability of the source code is a huge plus: it makes what would be otherwise insurmountable problems minor inconveniences.

For functionality I’d give it a B+. It does a lot and covers most of the common features. My favorite feature is input parsing, so it will natively understand double clicks. It also supports copy/paste, text highlighting, tables, and scroll bars. The GUI editor is a major benefit.