--------------------------------------------------------------------------------
--                                                                            --
-- Copyright (C) 2004, RISC OS Ada Library (RASCAL) developers.               --
--                                                                            --
-- This library is free software; you can redistribute it and/or              --
-- modify it under the terms of the GNU Lesser General Public                 --
-- License as published by the Free Software Foundation; either               --
-- version 2.1 of the License, or (at your option) any later version.         --
--                                                                            --
-- This library is distributed in the hope that it will be useful,            --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of             --
-- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU           --
-- Lesser General Public License for more details.                            --
--                                                                            --
-- You should have received a copy of the GNU Lesser General Public           --
-- License along with this library; if not, write to the Free Software        --
-- Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA    --
--                                                                            --
--------------------------------------------------------------------------------

-- @brief Generic gadget methods and types.
-- $Author$
-- $Date$
-- $Revision$

with RASCAL.Toolbox;        use RASCAL.Toolbox;
with RASCAL.OS;             use RASCAL.OS;
with RASCAL.Utility;        use RASCAL.Utility;

with System.Unsigned_Types; use System.Unsigned_Types;
with System;                use System;

package RASCAL.ToolboxGadget Is

   Gadget_Type_Incompatible_With_Set_Value : Exception;

   type Gadget_Base_Type is new Integer;

   ActionButton_Base  : constant := 128;
   AdjusterArrow_Base : constant := 768;
   Button_Base        : constant := 960;
   DisplayField_Base  : constant := 448;
   Draggable_Base     : constant := 640;
   Label_Base         : constant := 320;
   LabelledBox_Base   : constant := 256;
   NumberRange_Base   : constant := 832;
   OptionButton_Base  : constant := 192;
   PopUp_Base         : constant := 704;
   RadioButton_Base   : constant := 384;
   ScrollList_Base    : constant := 16410;
   Slider_Base        : constant := 576;
   StringSet_Base     : constant := 896;
   TextArea_Base      : constant := 16408;
   WritableField_Base : constant := 512;
   TreeView_Base      : constant := 16#140280#;
   
   type Gadget_Type is (ActionButton_Type,AdjusterArrow_Type,Button_Type,DisplayField_Type,
                        Draggable_Type,Label_Type,LabelledBox_Type,NumberRange_Type,
                        OptionButton_Type,PopUp_Type,RadioButton_Type,ScrollList_Type,
                        ScrollBar_Type,Slider_Type,StringSet_Type,WritableField_Type,
                        TextArea_Type,Tabs_Type,TreeView_Type);

   type ActionButton_Gadget is
   record
   Text            : Address;
   Max_Text_Length : Integer;
   Click_Show      : Address;
   Event           : Integer;
   end record;
   pragma Convention (C, ActionButton_Gadget);

   type OptionButton_Gadget is
   record
   Label            : Address;
   Max_Label_Length : Integer;
   Event            : Integer;
   end record;
   pragma Convention (C, OptionButton_Gadget);

   type LabelledBox_Gadget is
   record
   Label : Address;
   end record;
   pragma Convention (C, LabelledBox_Gadget);

   type Label_Gadget is
   record
   Label : Address;
   end record;
   pragma Convention (C, Label_Gadget);

   type RadioButton_Gadget is
   record
   Group_Number     : Integer;
   Label            : Address;
   Max_Label_Length : Integer;
   Event            : Integer;
   end record;
   pragma Convention (C, RadioButton_Gadget);

   type DisplayField_Gadget is
   record
   Text            : Address;
   Max_Text_Length : Integer;
   end record;
   pragma Convention (C, DisplayField_Gadget);

   type WritableField_Gadget is
   record
   Text            : Address;
   Text_Limit      : Integer;
   Allowable       : Address;
   Allowable_Limit : Integer;
   Before          : Component_ID;
   After           : Component_ID;
   end record;
   pragma Convention (C, WritableField_Gadget);

   type Slider_Gadget is
   record
   Lower_Bound   : Integer;
   Upper_Bound   : Integer;
   Step_Size     : Integer;
   Initial_Value : Integer;
   end record;
   pragma Convention (C, Slider_Gadget);

   type Draggable_Gadget is
   record
   Text              : Address;
   Max_Text_Length   : Integer;
   Sprite            : Address;
   Max_Sprite_Length : Integer;
   end record;
   pragma Convention (C, Draggable_Gadget);

   type PopUp_Gadget is
   record
   Menu : Address;
   end record;
   pragma Convention (C, PopUp_Gadget);

   type Adjuster_Gadget is
   record
   Dummy : Integer;
   end record;
   pragma Convention (C, Adjuster_Gadget);

   type NumberRange_Gadget is
   record
   Lower_Bound   : Integer;
   Upper_Bound   : Integer;
   Step_Size     : Integer;
   Initial_Value : Integer;
   Precision     : Integer;
   Before        : Component_ID;
   After         : Component_ID;
   Display_Length: Integer;
   end record;
   pragma Convention (C, NumberRange_Gadget);

   type StringSet_Gadget is
   record
   StringSet           : Address;
   Title               : Address;
   InitialValue        : Address;
   InitialValue_Length : Integer;
   Allowable           : Address;
   Allowable_Length    : Integer;
   Before              : Component_ID;
   After               : Component_ID;
   end record;
   pragma Convention (C, StringSet_Gadget);

   type Button_Gadget is
   record
   Button_Flags   : System.Unsigned_Types.Unsigned;
   Value          : Address;
   Max_Value      : Integer;
   Validation     : Address;
   Max_Validation : Integer;
   end record;
   pragma Convention (C, Button_Gadget);

   type TextArea_Gadget is
   record
   Gadget_Type : Integer;
   Event       : Integer;
   Text        : Address;
   Foreground  : OS_Colour;
   Background  : OS_Colour;
   end record;
   pragma Convention (C, TextArea_Gadget);

   type Scrolllist_Gadget is
   record
   Event      : Integer;
   Foreground : OS_Colour;
   Background : OS_Colour;
   end record;
   pragma Convention (C, Scrolllist_Gadget);

   type ScrollBar_Gadget is
   record
   Gadget_Type : Integer;
   Event       : Integer;
   Min         : System.Unsigned_Types.Unsigned;
   Max         : System.Unsigned_Types.Unsigned;
   Value       : System.Unsigned_Types.Unsigned;
   Visible     : System.Unsigned_Types.Unsigned;
   Line_Inc    : System.Unsigned_Types.Unsigned;
   Page_Inc    : System.Unsigned_Types.Unsigned;
   end record;
   pragma Convention (C,ScrollBar_Gadget);

   type Tabs_Gadget is
   record
   ForeGround : System.Unsigned_Types.Unsigned;
   BackGround : System.Unsigned_Types.Unsigned;
   Text            : Address;
   end record;
   pragma Convention (C, Tabs_Gadget);

   type TreeView_Gadget is
   record
   Foreground : System.Unsigned_Types.Unsigned;
   Background : System.Unsigned_Types.Unsigned;
   end record;
   pragma Convention (C, TreeView_Gadget);

   type Gadget_Header_Type is
   record
   Flags          : System.Unsigned_Types.Unsigned;
   Gadget_Kind    : Gadget_Base_Type;
   BBox           : Toolbox_BBox_Type;
   Id             : Component_ID;
   Max_Help       : integer;
   Help           : Address;
   end record;
   pragma Convention (C, Gadget_Header_Type);

   type Gadget_Data(Gadget : Gadget_Type) is
   record
   case Gadget is
   when ActionButton_Type  => ActionButton  : ActionButton_Gadget;
   when AdjusterArrow_Type => AdjusterArrow : Adjuster_Gadget;
   when Button_Type        => Button        : Button_Gadget;
   when DisplayField_Type  => DisplayField  : DisplayField_Gadget;
   when Draggable_Type     => Draggable     : Draggable_Gadget;
   when Label_Type         => Label         : Label_Gadget;
   when LabelledBox_Type   => LabelledBox   : LabelledBox_Gadget;
   when NumberRange_Type   => NumberRange   : NumberRange_Gadget;
   when OptionButton_Type  => OptionButton  : OptionButton_Gadget;
   when PopUp_Type         => PopUp         : PopUp_Gadget;
   when RadioButton_Type   => RadioButton   : RadioButton_Gadget;
   when ScrollList_Type    => ScrollList    : ScrollList_Gadget;
   when ScrollBar_Type     => ScrollBar     : ScrollBar_Gadget;
   when Slider_Type        => Slider        : Slider_Gadget;
   when StringSet_Type     => StringSet     : StringSet_Gadget;
   when WritableField_Type => WritableField : WritableField_Gadget;
   when TextArea_Type      => TextArea      : TextArea_Gadget;
   when TreeView_Type      => TreeView      : TreeView_Gadget;
   when Tabs_Type          => Tabs          : Tabs_Gadget;
   end case;
   end record;
--   pragma Unchecked_Union(Gadget_Data);
   pragma Convention (C, Gadget_Data);

   type Gadget is
   record
   Header : Gadget_Header_Type;
   Data   : Gadget_Data(Button_Type);
   end record;
   pragma Convention (C, Gadget);

   type Gadgets_Type is array(Natural range <>) of Gadget;
   type Gadgets_Pointer is access Gadgets_Type;

   type Icon_List_Type is array(Natural range <>) of Icon_Handle_Type;
   type Icon_List_Pointer is access Icon_List_Type;

   --
   -- Returns the size of the gadget's text buffer. 
   --
   function Get_BufferSize (Object    : in Object_ID;
                            Component : in Component_ID) return Integer;


   --
   -- Generic method to read the text value of a gadget.
   --(WritableField,DisplayField,ActionButton,OptionButton,RadioButton).
   --
   function Get_Value (Object    : in Object_ID;
                       Component : in Component_ID;
                       Flags     : in System.Unsigned_Types.Unsigned := 0) return String;

   --
   --  Generic method to read the integer value of a gadget.
   --(number range, slider).
   --
   function Get_Value (Object    : in Object_ID;
                       Component : in Component_ID;
                       Flags     : in System.Unsigned_Types.Unsigned := 0) return Integer;

   --
   -- Generic method to set the text value of a gadget.
   --(WritableField,DisplayField,ActionButton,OptionButton,RadioButton).
   --
   procedure Set_Value (Window    : in Object_ID;
                        Component : in Component_ID;
                        Value     : in String;
                        Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Generic method to set the integer value of a gadget.
   --(number range, slider).
   --
   procedure Set_Value (Window    : in Object_ID;
                        Component : in Component_ID;
                        Value     : in Integer;
                        Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   --  Generic method to set the text value of a gadget.
   --(WritableField,DisplayField,ActionButton,OptionButton,RadioButton).
   --The text is truncated to the size of the gadget and an ellipsis is added.
   --
   procedure Set_TruncatedValue (Window    : in Object_ID;
                                 Component : in Component_ID;
                                 New_Value : in String;
                                 Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the bounding box of the gadget.
   --
   function Get_BBox (Window    : in Object_ID;
                      Component : in Component_ID;
                      Flags     : in System.Unsigned_Types.Unsigned := 0) return Toolbox_BBox_Type;

   --
   -- Sets the flags of the gadget.
   --
   procedure Set_Flags (Window    : in Object_ID;
                        Component : in Component_ID;
                        New_Flags : in System.Unsigned_Types.Unsigned;
                        Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the flags of the specified gadget.
   --
   function Get_Flags (Window    : in Object_ID;
                       Component : in Component_ID;
                       Flags     : in System.Unsigned_Types.Unsigned := 0) return integer;

   --
   -- Returns the type of the gadget.
   --
   function Get_Type (Window    : in Object_ID;
                      Component : in Component_ID;
                      Flags     : in System.Unsigned_Types.Unsigned := 0) return Gadget_Base_Type;

   --
   -- Returns the interactive help message of the gadget.
   --
   function Get_Help (Window    : in Object_ID;
                      Component : in Component_ID;
                      Flags     : in System.Unsigned_Types.Unsigned := 0) return String;

   --
   -- Sets the interactive help message of the gadget.
   --
   procedure Set_Help  (Window    : in Object_ID;
                        Component : in Component_ID;
                        Help      : in String;
                        Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the list if Wimp icons making up the gadget.
   --
   function Get_IconList (Window    : in Object_ID;
                          Component : in Component_ID;
                          Flags     : in System.Unsigned_Types.Unsigned := 0) return Icon_List_Type;

   --
   -- Fade gadget.
   --
   procedure Fade (Window    : in Object_ID;
                   Component : in Component_ID;
                   Flags     : in System.Unsigned_Types.Unsigned := 0);
   
   --
   -- Unfade gadget.
   --
   procedure UnFade (Window    : in Object_ID;
                     Component : in Component_ID;
                     Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Sets the gadget which will receive the inout focus when the window gets it.
   --
   procedure Set_Focus (Window    : in Object_ID;
                        Component : in Component_ID;
                        Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Moves an already created gadget to another location.
   --
   procedure Move  (Window    : in Object_ID;
                    Component : in Component_ID;
                    BBox      : in Toolbox_BBox_Type;
                    Flags     : in System.Unsigned_Types.Unsigned := 0);
   
End RASCAL.ToolboxGadget;
