In the beginning, there is only one user. You have to please that one first.

Hello everyone!
Is there a complete working example of algui and Allegro 5? (only basic features)
I'm trying to learn Allegro (and since I'm at it, I figured the latest version would be better) and need a GUI.
Alternatively, if someone could indicate a simple GUI (buttons and editboxes are all I need now), It would do me very good.

Regards,
Laurentiu

PS: Using VS 2008, if it matters.
PPS: The link from http://www.allegro.cc/resource/CodeGallery/TextInput seems dead, if anyone cares

Once I'm done with saving and loading layouts. Declaring all the widgets in your entire program can be done with one line of code. Or at least just a few...

Something along these lines. Note that I'm not using a single global anywhere.

//Setup
Layout layout("myinterface.layout");
My_controller controller(layout);
//Main loop
layout.Get_root().Handle_event(allegro_event);
controller.Update();
layout.Get_root().Render();

Here is a compromise between the event design and the callback design:

• a widget can have one more callbacks.

• a callback has an event id and a callback procedure.

• the event id is automatically generated or manually set.

• if the callback is invoked and the callback procedure is not null, then the callback procedure is invoked, otherwise an event is posted to the event queue.

So, you event queue lovers can do this:

And we callback lovers can do this:

What do you people think?

Being a little more realistic :

Advantages of events posted in event queue.

• access to the local context.

• can deal with all events in a single place, limiting the amount of searching necessary to find relevant code

Disadvantages of events posted in event queue:

• manual management of event id constants.
  There's nothing to manage about an event id. All you do is declare it :

  if (wmsg == WidgetMsg(&button , TOPIC_BUTTON , BUTTON_CLICKED)) {do_stuff();}
  

• huge switch or if-then-else statements.
  This is not a disadvantage if you like all of your event handling in a single place.

• not good for injecting code into algorithms.
  You can use whatever code you want inside an if clause.

• makes debugging asynchronous and hence more difficult than it ought to be.
  Debugging with events is not any more difficult if you know how to debug in the first place. Set a breakpoint inside the message check, or inside QueueUserMessage. Easy as pie.

• heavy fragmentation of memory.
  I don't believe that allocating and deallocating memory on the stack fragments memory. Prove me wrong if you like.

• difficult to extend via C++ (see message maps vs virtual functions debates).
  You can do whatever you like inside an if clause. Provide some proof for this one.

Disadvantages of callbacks:

• no access to the local context.
  Which forces use of either :

  • global variables

  • pointless structs just to bind data to another context

Advantages of callbacks:

• cleaner code by using smaller functions.
  If clauses are just as modular as functions are, without scattering code all across your source file(s).

• suitable for code injection in predefined algorithms.
  Define code injection, and tell me why you think local event code is unsuitable for it.

• synchronous debugging.
  Event code debugging is just as linear as call back debugging. There's still a defined order to your code, and it's just as easy to follow.

• does not require memory allocations/deallocations.

• easy to extend via C++.
  You can extend event code just as easily as you can callback code.

• no need to manage constants manually.
  What are you talking about? There's nothing to manage. All you do is compare an object to a constant object.

Look closer. Because I can't see how callbacks are better.

//Setup
Layout layout("myinterface.layout");
My_controller controller(layout);

Sounds ambitious. How do you expect your controller to be able to set callbacks / respond to events without using a predefined set of names for your widgets in your layout file? Ie... how will you hook code up to widget actions?

I think it's better than locking your users into callbacks only.

I use a similar mechanism in my GUI, except that const char* id is just string wname and you use FindWidgetByName(string name).

What I was getting at is that there is no way to hook widgets up to actions without using a predefined set of names in your controller, thus rendering a single controller only useful for a single set of named widgets.

Can anyone come up with a way to hook widgets up to actions at runtime without using a predefined set of names and functions?

You mean like embedding a scripting language into the layout? (Similar to JavaScript inside HTML.) If so, that's definitely overkill for what my goals for a GUI would be.

I've not given any thought to localization yet. But something like this would let you do whatever you wanted:

algui_set_text_localization(my_proc);

ALLEGRO_USTR *my_proc(const char *text)
{
  return al_ustr_new(text);
}

// in the internal algui "set title" function
window->title = algui_localization_proc(title);

then you could do whatever you wanted for localization.

Then you would do this:

algui_xml("<button text='1' />");

and your localization function would do a number to text mapping. It's up to you.

Text that requires context should be avoided. E.g.:

[ ] Choice One
[ ] Choice Two
[ ] Choice Three

| PROCESS ITEM(S) |

There the text on the button depends on the number of items selected. A better approach is to just use the text "PROCESS." Hopefully that eliminates the need for complex rules.

But in situations where it cannot be avoided, I don't see why the GUI should solve the problem for you. In that case, you'll need to pass the context along to your own localization function to get the proper string.

@Edgar Reynaldo:

1) you have to mange the constants TOPIC BUTTON, BUTTON CLICK, etc. And if you want to extend the library, you have to define new constants. If you then want to change the code, you have to maintain the constants.

2) even if you like all your event code in one place, it soon becomes unmanagable. Good coding practices require breaking long functions into smaller ones.

3) if i put a breakpoint inside QueueUserMessage, then the execution will be interrupted for all messages. It makes debugging more difficult.

4) i was not talking about local variables, but about messages put in the queues: the is allocation/deallocation all the time.

5) with events, you must bind c++ methods to events via a message map, which is awkward. With callbacks, it's much easier.

6)if clauses are not as modular as functions, because functions can have parameters.

7) code injection is an algorithm with hooks. you cannot insert hooks with events. You cannot specialize an algorithm with events.

For all the above, events are inferior to callbacks. Howeve, i am willing to offer a solution which covers both camps. What do you think of that?

I still don't know what you mean by 'manage' the event id's. They're just a set of predefined constants at the top of each widget header. Adding new TOPIC_*'s is just adding a simple external constant, initialized by NextFreeTopicId(). The constants and enums defined by the library will most likely never change (not to say that more can't be added easily without breaking existing code).

I still haven't found this to be the case. All it takes to find an event is to do a Find in your editor for the address of the widget you want to know about.

Well, this is true, but it's very rare that you get more than one message per update. I would guess that the same memory slot is just reused, but I can't say for sure. I really don't think it amounts to much in the end though.

I still don't know what a message map is. Can you give a small code example of this? Also, why can't you just call your C++ method from the if clause that handles the message?

I don't understand this very well. Can you give me a code example? Why can't you just call your algorithm locally after specifying the hook's callback? Any code you can call with a callback can be called from an if clause.

Fine by me.

My lib has the function algui_set_translation to set the text, which is loaded from a config file. Each widget receives the relevant message and reads the appropriate string from the config file.

@Edgar:

1)@when you make new classes and when you remove classes, when you make new event constants and delete old ones, or modify existing ones, that's what i mean about managing event ids...not at run time, but at compile time.

2) the long functions are truly difficult to maintain. Imagine having, let's say, 200 widgets...if each event takes 10 lines of code, the main loop would be 2000 lines of code! for just one loop!

3) if your widgets produce events like "value changed" when the mouse is moved, for example a slider, then hundreds, maybe thousands of message structs will be allocate each second.

4) i am posting this from my mobile phone, so it's kind of difficult to give you a message map example. You can search in google and you will find many. A message map is a way to bind messages to functions.

Calling a method of an object for each possible combination of message and method manually is impractical.

5) having to manually invoke an algorithm's continuation from the event loop is impractical.

I was just being pedantic.

But with callbacks you don't need to write even a single constant.

Yes, 200 different functions can be organized much better than a continuous function spanning, let's say, 2000 lines of code.

And with such long functions you quickly lose track of variables.

With Allegro 5, as with any other event system, the rate of mouse position change does not depend on the screen refresh rate. So, it really depends on how fast the user moves the mouse and how fast the hardware can read mouse events.

If you use a vector, you have two problems in your hand: a) the reallocation of the vector's internal buffer, b) the copying of elements when you remove an element from the front of the vector.

If you use a list, then you have fragmentation. The same memory slot may or may not be reused, since there can be other allocations at the same time.

It is, in memory-tight systems. For example, the iPhone gives you 48 MB of memory to play with.

Even if it's not a problem in modern PCs, though, I don't see why there has to be an allocation, since it's not required.

You don't understand the use case. Suppose you want to make a set of objects with virtual functions that correspond to events. Also suppose you want this binding of events to virtual functions to be permanent, so you can reuse the same components as-is.

The only way to do the permanent binding is to use a message map, i.e. a static map of event bindings to virtual functions, like MFC does.

Programming message maps is cumbersome and has a lot of problems.

With your system, though, you can't even do message maps, since events do not have static ids.

Remember, you want a permanent reusable binding.

Suppose a widget defines a procedure (not a piece of code, but a series of steps), and also suppose this procedure has steps that must be supplemented by the end-user programmer. With events, in order to have these procedure execute from start to finish, the programmer is forced to respond to the events. With callbacks, no such thing is required: the injected code (i.e. the steps supplemented by the end-user programmer) can be bound permanently to components.

EDIT:

For the first version of algui, I am planning to do the following widgets:

Static widgets:

• label; text label.

• image; image label.

• frame; a rectangular area with a background and a border. The background will be a color, a picture, or a gradient (horizontal/vertical), and the border would be a bitmap, or a 3d sunken/raised rectangle.

Buttons:

• push button; standard button with a click event.

• check box; standard check box with a tick.

• radio button; standard radio button with an associated group; only one button can be selected.

Bars:

• scroll bar; either horizontal or vertical.

• progress bar; either horizontal or vertical.

• slider; either horizontal or vertical.

Editors:

• text box; a single line text editor.

• combo box; a combination of text box and a list view.

• spin box; a text box with buttons that allow the change of the value with a device other than the keyboard.

Views:

• list view; items arranged vertically in a list.

• tree view; items arranged in a hierarchical view.

• table view; items arranged in a grid.

Layout managers:

• horizontal box; widgets laid out horizontally.

• vertical box; widgets laid out vertically.

• grid box; widgets laid out in a grid.

• splitter; child widgets will be resizable via handle bars.

Standard dialogs:

• message dialog; a dialog with a text message, an icon, and one or more buttons.

• file dialog; save or load a file or choose a folder.

Menus:

• menu; horizontal/vertical menu.

• menu item; item of a menu.

What do you think about these? do you think there is something important left out?