------------------------------------------------------------------------------
--                                                                          --
--                An Ada2005 binding to the Qt C++ framework                --
--                                                                          --
------------------------------------------------------------------------------
--                                                                          --
-- Copyright © 2008-2010 Vadim Godunko <vgodunko@gmail.com>                 --
--                                                                          --
-- QtAda is free software;  you can  redistribute it and/or modify it under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 2,  or (at your option) any later ver- --
-- sion. QtAda is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
-- for  more details.  You should have  received  a copy of the GNU General --
-- Public License distributed with QtAda;  see file COPYING.  If not, write --
-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
-- Boston, MA 02110-1301, USA.                                              --
--                                                                          --
-- As a special exception,  if other files  instantiate  generics from this --
-- unit, or you link  this unit with other files  to produce an executable, --
-- this  unit  does not  by itself cause  the resulting  executable  to  be --
-- covered  by the  GNU  General  Public  License.  This exception does not --
-- however invalidate  any other reasons why  the executable file  might be --
-- covered by the  GNU Public License.                                      --
--                                                                          --
------------------------------------------------------------------------------
--  $Revision: 3769 $ $Date: 2010-10-24 03:16:28 +0400 (Sun, 24 Oct 2010) $
------------------------------------------------------------------------------
with System.Address_To_Access_Conversions;

with Ada.Finalization;

package Qt4_Entities is

   pragma Preelaborate;

   type Cpp_Class is limited null record;
   pragma Convention (C, Cpp_Class);

   type Cpp_Class_Access is access all Cpp_Class;

   package Conversions is new
     System.Address_To_Access_Conversions (Cpp_Class);

   type Entity_Role is (Director, Container, Wrapper);
   --  Роли в которых может выступать объект Ada:
   --   - Director  - объект является подклассом, реализованным средствами Ada;
   --   - Container - объект постоянно ассоциирован - освобождение памяти для
   --                 обоих объектов происходит одновременно. Это наиболее
   --                 часто используемый режим;
   --   - Wrapper   - объект временно ассоциирован с объектом C++ и может быть
   --                 освобождён без одновременного освобождения
   --                 ассоциированного объекта. Этот режим используется при
   --                 отсутствии необходимости или невозможности установления
   --                 постоянной ассоциации, например, для передачи события
   --                 при диспетчеризации виртуальной функции.

   type Allocation_Class is (Static, Dynamic);
   --  Класс распределённой памяти Ada объекта:
   --   - Static  - объект распределён без использования аллокатора (объявлен
   --               как член записи или как объёкт внутри пакета или
   --               подпрограммы) или с использованием аллокатора, но ссылочный
   --               тип не объявлен на уровне библиотеки. Освобождение Ada
   --               объекта в этом случае не требуется, оно будет осуществлено
   --               средствами библиотеки времени выполнения;
   --   - Dynamic - объект выделен с помощью аллокатора и ссылочный тип
   --               эквивалентен объявленному на уровне библиотеки.
   --               Освобождение Ada объекта будет произведено сразу после
   --               освобождения ассоциированного объекта C++.

   --
   --  Сущность, допускающая копирование.
   --

   type Entity is abstract new Ada.Finalization.Controlled with record
      Cpp_Object : access Cpp_Class := null;
      Role       : Entity_Role      := Wrapper;
      Class      : Allocation_Class := Static;
      Destroyed  : Boolean          := False;
   end record;

   overriding
   procedure Initialize (Self : in out Entity);

   overriding
   procedure Adjust (Self : in out Entity);

   overriding
   procedure Finalize (Self : in out Entity);

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Default_Cpp_Object
   --!    <Purpose> Возвращает ассоциируемый по умолчанию объект C++.
   --! Реализация по умолчанию возвращает нулевой указатель.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Default_Cpp_Object (Self : not null access Entity)
     return access Cpp_Class;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Copy_Cpp_Object
   --!    <Purpose> Производит создание копии ассоциированного объекта C++.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Copy_Cpp_Object (Self : not null access Entity)
     return not null access Cpp_Class
       is abstract;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Delete_Cpp_Object
   --!    <Purpose> Производит удаление ассоциированного объекта C++.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   procedure Delete_Cpp_Object (Self : not null access Entity)
     is abstract;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Cpp_Object
   --!    <Purpose> Возвращает ссылку на ассоциированный объект C++.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Cpp_Object (Self : Entity'Class) return access Cpp_Class;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Set_Dynamically_Allocated
   --!    <Purpose> Устанавливает признак динамического распределения памяти
   --! для Ada объекта. Динамически распределённый Ada объект уничтожается
   --! автоматически при уничтожении ассоциированного объекта C++ (для
   --! статически выделенных объектов Ada производится только установка
   --! признака уничтожения объекта C++).
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   procedure Set_Dynamically_Allocated
    (Self : not null access Entity'Class);

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Is_Director
   --!    <Purpose> Возвращает True если Ada объект работает в режиме
   --!  директора.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Is_Director (Self : not null access constant Entity)
     return Boolean;

   --
   --  Сущность, не допускающая копирования.
   --

   type Limited_Entity is
     abstract new Ada.Finalization.Limited_Controlled with
   record
      Cpp_Object : access Cpp_Class := null;
      Role       : Entity_Role      := Wrapper;
      Class      : Allocation_Class := Static;
      Destroyed  : Boolean          := False;
   end record;

   type Limited_Entity_Access is access all Limited_Entity'Class;
   --  XXX GNAT GCC 4.3.0 129029 workaround (finalization list corruption)

   overriding
   procedure Initialize (Self : in out Limited_Entity);

   overriding
   procedure Finalize (Self : in out Limited_Entity);

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Default_Cpp_Object
   --!    <Purpose> Возвращает ассоциируемый по умолчанию объект C++.
   --! Реализация по умолчанию возвращает нулевой указатель.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Default_Cpp_Object (Self : not null access Limited_Entity)
     return access Cpp_Class;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Delete_Cpp_Object
   --!    <Purpose> Производит удаление ассоциированного объекта C++.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   procedure Delete_Cpp_Object (Self : not null access Limited_Entity)
     is abstract;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Cpp_Object
   --!    <Purpose> Возвращает ссылку на ассоциированный объект C++.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding function Cpp_Object
    (Self : Limited_Entity'Class) return access Cpp_Class;

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Set_Dynamically_Allocated
   --!    <Purpose> Устанавливает признак динамического распределения памяти
   --! для Ada объекта. Динамически распределённый Ada объект уничтожается
   --! автоматически при уничтожении ассоциированного объекта C++ (для
   --! статически выделенных объектов Ada производится только установка
   --! признака уничтожения объекта C++).
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   procedure Set_Dynamically_Allocated
    (Self : not null access Limited_Entity'Class);

   ---------------------------------------------------------------------------
   --! <Subprogram>
   --!    <Unit> Is_Director
   --!    <Purpose> Возвращает True если Ada объект работает в режиме
   --!  директора.
   --!    <Exceptions>
   ---------------------------------------------------------------------------
   not overriding
   function Is_Director (Self : not null access constant Limited_Entity)
     return Boolean;

end Qt4_Entities;
