NAME

       tcl::chan::events - Event support for reflected/virtual channels

SYNOPSIS

       package require Tcl  8.5

       package require TclOO

       package require tcl::chan::core  ?1?

       package require tcl::chan::events  ?1?

       ::tcl::chan::events objectName

       objectName finalize thechannel

       objectName watch thechannel eventmask

       objectName allow eventname...

       objectName disallow eventname...

_________________________________________________________________

DESCRIPTION

       The  tcl::chan::events package provides a TclOO class implementing common behaviour needed
       by virtually every reflected or virtual channel supporting event driven IO. It is  a  sub-
       class of tcl::chan::core, inheriting all of its behaviour.

       This  class  expects to be used as either superclass of a concrete channel class, or to be
       mixed into such a class.

CLASS API

       ::tcl::chan::events objectName
              This command creates a new channel event core object with an associated global  Tcl
              command  whose  name  is  objectName.  This  command  may be used to invoke various
              operations on the object, as described in the section for the Instance API.

INSTANCE API

       The API of channel event core instances provides only four methods, two  corresponding  to
       channel handler commands (For reference see TIP 219 [http:/tip.tcl.tk/219]), and the other
       two for use by sub-classes to control event generation. They former expect  to  be  called
       from whichever object instance the channel event core was made a part of.

       objectName finalize thechannel
              This  method  implements  standard  behaviour  for  the  finalize method of channel
              handlers.  It  overrides  the  behaviour   inherited   from   tcl::chan::core   and
              additionally disables any and all event generation before destroying itself.

       objectName watch thechannel eventmask
              This method implements standard behaviour for the watch method of channel handlers.
              Called by the IO system whenever the interest  in  event  changes  it  updates  the
              instance  state  to  activate  and/or  suppress  the  generation  of  the events of
              (non-)interest.

       objectName allow eventname...

       objectName disallow eventname...
              These two methods are exported to sub-classes, so that their instances  can  notify
              their  event  core  of  the events the channel they implement can (allow) or cannot
              (disallow) generate.  Together with the information about the events  requested  by
              Tcl's  IO  system  coming  in  through  the  watch method the event core is able to
              determine which events it should (not) generate and act accordingly.

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.   Please  report  such  in  the  category  virtchannel of the Tcllib SF Trackers
       [http://sourceforge.net/tracker/?group_id=12883].   Please  also  report  any  ideas   for
       enhancements you may have for either package and/or documentation.

KEYWORDS

       event management, reflected channel, tip 219, virtual channel

CATEGORY

       Channels

COPYRIGHT

       Copyright (c) 2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>