sigc++/doc/API

   1
   2 Object & Handles
   3 =================
   4 In order for a signal to be connected to object, the object must
   5 have Object somewhere in its inheritence tree.
   6
   7 class virtual Object
   8   {
   9    public:
  10      bool is_dynamic();
  11      bool is_floating();
  12      Object();
  13      virtual ~Object();
  14   };
  15
  16 Objects are
  17  - Reference counted
  18  - Capable of deleting self if told to be managed.
  19
  20
  21 Handles are used for internal memory management.  They are a signature not
  22 a real class so they can incapsulate any class that has the necessary
  23 functions.
  24
  25 signature class Handle<ObjType,Policy>
  26   {
  27    public:
  28      operator ObjType*();
  29      ObjType operator *();
  30      ObjType* operator ->();
  31
  32      bool connected();
  33
  34      Handle& operator =(ObjType*);
  35      Handle& operator =(ObjType&);
  36      Handle& operator =(const Handle<O,P> &);
  37
  38      Handle(ObjType*);
  39      Handle(ObjType&);
  40      Handle(const Handle<O,P>&);
  41   };
  42
  43
  44
  45 Slots
  46 ======
  47 Slots are an encapsulation of a callable object.  A factory called slot()
  48 builds Slots from object/methods, static functions and signals.
  49
  50 class Slot#<rettype,ARGS>: public Object
  51   {
  52    public:
  53      rettype call(ARGS);
  54      Slot#()
  55      virtual ~Slot#()
  56   };
  57
  58 Slots build up in a tree to contain a wide number of connection types.
  59
  60 There is a class of functions call Adaptors.  Adaptors take a slot
  61 and alter it to a different profile.
  62
  63 Planned adaptors
  64   bind - bind callback data starting from the end.
  65   extend - add dummy arguments to the end of a slot.
  66   convert - convert the calling arguments with a function.
  67
  68 Internally slots are just handles to an internal abstract slot
  69 type called Slot#_, which is a pimple on SlotData.
  70
  71 Slots can not be duplicated as they may have a large list of internal
  72 data.  You should not reuse a slot in multiple lists.
  73
  74
  75 Signals
  76 =======
  77 A list of slots can be called with a signal.  A signal is considered a
  78 slot container.
  79
  80 class Signal#<RETURN,ARGS,Policy>
  81   {
  82    public:
  83      typedef Slot#<RETURN,ARGS> InSlotType;
  84      typedef Slot#<MARSH_RETURN,ARGS> OutSlotType;
  85
  86      OutSlotType slot();
  87      Connection connect(InSlotType& s);
  88      MARSH_RETURN emit(ARGS);
  89      MARSH_RETURN operator()(ARGS); // alias for emit
  90      Signal();
  91      Signal(InSlotType& );
  92      ~Signal();
  93   };
  94
  95 Two typedefs are specified InSlotType and OutSlotType.  InSlotType
  96 is the type taken by this signal for connections.  OutSlotType
  97 is the type of slot this function returns and is determented by
  98 the Marshaller.  In most cases InSlotType and OutSlotType match,
  99 but this is not necessarily the case.  Signals do not need to
 100 have these typedefs, but it eases building new Signal classes from
 101 them.
 102
 103 The basic methods shown there are
 104   emit - call all slots contained within.
 105   slot - give away a slot that receive incoming calls.
 106   connect - insert a slot into the call list.
 107
 108 Slots are removed by calling disconnect on their connections.
 109
 110 There is also the ablity to have a marshaller that takes care of handling
 111 signal callbacks.  This functionality is dependent on the implementation
 112 of the signal.  For the basic signal type, the marshaller is a hidden
 113 template parameter.
 114
 115 Connect() may also take optional implementation dependent arguments
 116 for specifying behavior.  For example, timeout.connect(slot(&foo),10)
 117 where the second argument it a time in seconds is a good use of
 118 optional connect flags.
 119
 120 Additional functionality may optionally be defined such as
 121 ablity to check if there are any signals attached (empty()) or
 122 remove all connected signals (clear()).  However these are
 123 not a requirement and are implementation dependent.
 124
 125
 126 Connections
 127 =============
 128 Connections are given to the user on each connect to allow individual
 129 connections to be broken or altered.
 130
 131 class Connection
 132   {
 133    public:
 134      void disconnect();
 135      Connection();
 136   };
 137
 138 They are a handle to the data, so when the last connection goes away and
 139 the slot is not yet properly held in a Signal the slot will go away.
 140
 141