[Tickit-dev] API changes to Tickit object event bindings

[Paul "LeoNerd" Evans]

I've been shuffling some code around to try to get things in a neater
structure for a root object (the C library equivalent of the 'Tickit'
main class in Perl), to act as an overall container and event loop and
so on.

One thing I've realised is that the signature for event bindings
currently defined on pens/terminals/windows is not quite right for
being easy to reuse on the toplevel object for timers and idle queue
callbacks.

To hopefully accommodate this a little better I've change the way that
the event bindings specify their events. Previously, the various
"_bind_event()" functions used to take a bitmask set of flags
corresponding to individual events, plus the special 'DESTROY' or
'UNBIND' events. The handler when run would then take a bitmask of the
same to tell it which event(s) actually happened.

  typedef int TickitPenEventFn(TickitPen *tt, TickitEventType ev,
    void *info, void *user);

  int  tickit_pen_bind_event(TickitPen *tt, TickitEventType ev,
    TickitBindFlags flags, TickitPenEventFn *fn, void *user);

  etc...

This bitmask is somewhat inflexible for future extensions, so I've
changed it to a per-class enumeration of interesting events. Callback
functions can now be bound to one kind of event, and take flags to say
if it also wants to be told of unbind or destroy. Additionally, for
callbacks on just object destruction alone, there's a special "DESTROY"
event defined for all object types.

  typedef enum {
    TICKIT_EV_FIRE = (1 << 0),
    TICKIT_EV_UNBIND = (1 << 1),
    TICKIT_EV_DESTROY = (1 << 2),
  } TickitEventFlags;

  typedef int TickitPenEventFn(TickitPen *tt, TickitEventFlags
  flags, void *info, void *user);

  typedef enum {
    TICKIT_BIND_FIRST   = 1<<0,
    TICKIT_BIND_UNBIND  = 1<<1,
    TICKIT_BIND_DESTROY = 1<<2,
  } TickitBindFlags;

  typedef enum {
    TICKIT_PEN_ON_DESTROY,
    TICKIT_PEN_ON_CHANGE,
  } TickitPenEvent;

  int  tickit_pen_bind_event(TickitPen *tt, TickitPenEvent ev,
    TickitBindFlags flags, TickitPenEventFn *fn, void *user);

  etc...

This new API shape should make it easier to reuse more code
implementation and data structures for timer and idle queues on the
main object, and will also be simpler for higher-level library
wrappings to provide similar, such as a widget library providing
per-widget class events.

This API will be part of libtickit 0.2, though there's still a fair bit
to add yet. Converting 0.1 code to this new API shape will be very
simple *provided* that you don't make use of the current ability to
bind to multiple events in the same handler function. I think that
should be fairly rare in code currently, but you might just want to
check and split your handlers up if that's the case, to be ready for
0.2.

Speaking of 0.2, there's still a way to go on that yet, as I've not
made a lot of progress on the milestones yet:

  https://launchpad.net/libtickit/+milestone/v0.2

so don't expect a 0.2 imminently; this is mostly just a heads-up of an
upcoming change, so you can ensure you can easily cope with it when it
arrives.

-- 
Paul "LeoNerd" Evans

leonerd at leonerd.org.uk      |  https://metacpan.org/author/PEVANS
http://www.leonerd.org.uk/  |  https://www.tindie.com/stores/leonerd/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: OpenPGP digital signature
URL: <http://mail.leonerd.org.uk/pipermail/tickit-dev/attachments/20171013/c5cfff1b/attachment.sig>