docs/content/programming-guide/custom-actor.h

   1 /*! \page custom-actor Custom Actor
   2  * The Dali::CustomActor is used as a base class for UI controls.  It is a proxy object to enable derived classes access
   3  * to a subset of the methods defined in the internal Actor class.
   4  *
   5  * Classes deriving from Custom Actor should follow the same design principle as the rest of the Dali API.
   6  *
   7  * One class of the new UI control should inherit from Dali::CustomActor, while a second should inherit
   8  * Dali::CustomActorImpl.  This implementation class contains a number of pure virtual methods that enable the new UI
   9  * control to respond to a variety of events such as touch and notification of being added to the stage.
  10  *
  11  * For example, if creating a new button widget called myNewButton, the user would create two classes, myNewButton which
  12  * derives from Dali::CustomActor and an implementation part myNewButtonImpl which would derive from Dali::CustomActorImpl.
  13  *
  14  * In the New() method for the myNewButton class, the user should then create a new instance of the myNewButtonImpl class
  15  * and pass this to the constructor of the myNewButton object.  Internally the connection will be made
  16  * between the new widget actor and Dali, thus allowing messages such as OnSizeSet to be received by the new actor.
  17  *
  18  * It is the responsibility of the implementation of the new UI control to implement the method bodies for the inherited
  19  * pure virtual methods from Dali::CustomActorImpl.  Obviously the application won't compile if the methods are not
  20  * overidden, but the user does not need to fill in the code for methods they don't want or need to use.
  21  *
  22  * The following code shows the static New() method from the implementation part of the TextView UI control:
  23  * \code
  24  * Dali::Toolkit::TextView TextView::New()
  25  * {
  26  *   // Create the implementation, temporarily owned on stack
  27  *   boost::intrusive_ptr< TextView > textView = new TextView;
  28  *
  29  *   // Pass ownership to CustomActor
  30  *   Dali::Toolkit::TextView handle( *textView );
  31  *
  32  *   // Second-phase init of the implementation
  33  *   // This can only be done after the CustomActor connection has been made...
  34  *   textView->Initialize();
  35  *
  36  *   return handle;
  37  * }
  38  * \endcode
  39  *
  40  * After the implementation object is created it is passed back to the basic Text View through the constructor,the
  41  * constructor uses this passed in object to initialise the internal implementation objects.
  42  *
  43  * After both the objects are created it calls an init method on the implementation which is used to initialise
  44  * objects.  THis is the preferred way to do things so to avoid errors in the constructors.
  45  *
  46  * If desired, the user can then use the myNewButtonImpl implementation class to handle only the callback message
  47  * handler methods, and do all the rest of their widget processing the the main myNewButton class.  Access to the
  48  * implementation class can be gained using the GetImpl(*this) method.  For example:
  49  *
  50  * \code
  51  * void TextView::SetFont(const Font newFont)
  52  * {
  53  *  GetImpl(*this).SetFont(newFont);
  54  * }
  55  * \endcode
  56  */