hi,

Are there any tutorials on the custom event functions with A5. The docs are a bit beyond me.

I'm not even sure if it's the best way forward for what I want to do but still, if not I'd like to understand those functions.

EDIT : thanks Trent. Leaving the thread unreplied to so I can when I come up with a a question.

I don't think there are any tutorials specifically for user events. You could do what I did and experiment with them and find out how they work practically. You could ask questions as you go about specific things that you don't understand.

Caution: I don't fully understand them yet myself, I would have to use the manual and look at my code again to answer any questions about them or to reimplement them.

As I see it, an ALLEGRO_USER_EVENT is a sub type of an ALLEGRO_EVENT. It has a user field which has 4 intptr_t fields called data1, data2, data3, and data4. To use it, declare an ALLEGRO_EVENT object and assign values to event.user.data1 and so on...

First you need to declare an event source and then you need to initialize it.

ALLEGRO_EVENT_SOURCE evsrc;
al_init_user_event_source(&evsrc);

After that you register your event source with the event queues you want them to show up in.

ALLEGRO_EVENT_QUEUE* queue = al_create_event_queue();
al_register_event_source(queue , &evsrc);

When you want to send an event to the queue you do :

ALLEGRO_EVENT ev;
ev.type = SOME_MAGIC_NUMBER;// Not sure if you should do this
ev.user.data1 = (int*)42;

al_emit_user_event(&evsrc , &ev , NULL);// this may set ev.type, I don't know

I'm not clear on how to read a user event from the event queue, and the manual doesn't explain it. I would update the docs if I knew the answer to the two questions I posted there.

So I guess you set your event's type to some magic number before you emit it, and then you check for that magic number when you read it from the queue.

ALLEGRO_EVENT ev;
al_wait_for_event(queue , &ev);
if (ev.type == SOME_MAGIC_NUMBER) {
   printf("The answer to life is %i\n" , (int)ev.user.data1);
}

With regards to this:
http://www.liballeg.org/a5docs/refman/events.html#allegro_user_event

I just added this to SVN, as well as more cross-references, if that helps:

@@ -399,9 +399,16 @@ These are the public fields:
 -   intptr_t data3;
 -   intptr_t data4;
 
-Note that like all other event types this structure is a part of the
-ALLEGRO_EVENT union. Therefore to create a new user event you would
-do this:
+Like all other event types this structure is a part of the ALLEGRO_EVENT union.
+To access the fields in an ALLEGRO_EVENT variable `ev`, you would use:
+
+-   ev.user.source
+-   ev.user.data1
+-   ev.user.data2
+-   ev.user.data3
+-   ev.user.data4
+
+To create a new user event you would do this:
 
     ALLEGRO_EVENT_SOURCE my_event_source;
     ALLEGRO_EVENT my_event;
@@ -415,6 +422,10 @@ do this:
     
     al_emit_user_event(&my_event_source, &my_event, NULL);
 
+Event type identifiers for user events are assigned by the user.
+Please see the documentation for [ALLEGRO_GET_EVENT_TYPE] for the rules you
+should follow when assigning identifiers.
+
 See also: [al_emit_user_event], [ALLEGRO_GET_EVENT_TYPE]

The answer is: the same as any other event. I'm genuinely curious how this could have come up, as I would have thought the reason you start investigating user events is because you want something that acts the same (or as reasonably close) as other Allegro events.

Again, in the same way you test for other event types, by checking the .type field matches some magic constant. For user events you are in charge of assigning the event type identifiers. That is described at:

http://www.liballeg.org/a5docs/refman/events.html#allegro_get_event_type

I've added a few extra cross-references to that as well.

Further suggestions are welcome.

I use the docs here on allegro.cc, and they don't say anything about the user field or how to check/set the event type of an ALLEGRO_USER_EVENT. I guess I should be using the ones on www.liballeg.org instead then.

Note : It says event type ids below 1024 are reserved for Allegro. So use something else and you'll be fine, and you do set the type yourself.

That's a good explanation, thanks. Althought I still don't understand what the dtor function pointer is for in the al_emit_user_event() function.

The destructor is there to let you clean up any memory that you have allocated while creating your event.

When the reference count of the event drops to zero, the destructor will be called with the address of the event to clean up.

Thanks Edgar. I think I get it now.

So basically if we want to detect a situation and deal with it later we can use user defined events emit them and later check for them in the event queue.