AMIGA - CTL_#?
 ----------------------------------------------------------------------------

   NAME

      ctl_addidcmphandler() - Attaches your IDCMP related code to
                              particular 'cc' window.



   SYNOPSIS

      ctl_addidcmphandler(cc, ci);

      __interrupt void ctl_addidcmphandler(
                   struct ctl_csn_cwin *, struct ctl_csn_ient *);



   FUNCTION

      This function allows to attach your IDCMP_#? event to the
      particular fullscreen console window.



   INPUTS

      cc    - Pointer to one of the windows as intialised by the
              'ctl_openconscreen()'.

      ci    - Structure that carries code and data pointers. You
              must really allocate memory for data since private
              task exceptions are rather stack hungry!



   RETURNS

      No output.



   BASES

      SysBase



   NOTES

      Although this routine does not return anything it will fail
      if 'ci' node area is not NULL initially and lh members are
      NULL. This protects from Guru on multiple calls.

      If you did overlook the ient structure then you know that
      it carries the exact number of nodes as there is windows.
      This allows to use single structure to attach the very same
      code to all windows if necessary. General rule is: One node
      == one event.

      Important! Member 'cc_imsg' contains current Intuition msg.
      but do not 'ReplyMsg()' to it! This will be done by the
      master handler code.

      Note! Your code will be called in a private task exception.
      This means that the only safe way to call most of the OS
      functions is to 'CreateTask()' first. Functions considered
      interrupt-safe are OK here tho, but 'Wait()' is not one of
      them ;-) . And one more thing, always add the '__interrupt'
      attribute before CB body!

      This function automatically enables the event as found in
      'ci_idcmpev'!

      Member 'cc_numwin' is used to select 'ient' node. Its very
      important for this value to be sane.

      ORing('|')  QDEV_CTL_LFLPRIV_HEAD against 'cc_lflags' makes
      it possible to install event handler before existing ones.



   SEE ALSO

      ctl_remidcmphandler(), ctl_openconscreen(),
      ctl_closeconscreen()



   EXAMPLE

      __interrupt void myhandler(
                           struct ctl_csn_cwin *cc, void *mydata)
      {
        /*
         * Do something when window becomes active.
        */
      }

      ...

      struct ctl_csn_data *cd = <init screen>;
      struct ctl_csn_ient *ci;

      if ((ci = AllocVec(
          sizeof(struct ctl_csn_ient), MEMF_PUBLIC | MEF_CLEAR)))
      {
        ci->ci_idcmpev = IDCMP_ACTIVEWINDOW;

        ci->ci_idcmpcode = myhandler;

        ci->ci_idcmpdata = NULL;

        ctl_addidcmphandler(&cd->cd_cc[0], ci);

        ctl_addidcmphandler(&cd->cd_cc[1], ci);

        ...

        ctl_remidcmphandler(&cd->cd_cc[1], ci);

        ctl_remidcmphandler(&cd->cd_cc[0], ci);

        FreeVec(ci);
      }



   BUGS

      None known.



 ----------------------------------------------------------------------------