--------------------------------------------------------------------------------
--                                                                            --
-- 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 Toolbox Window related types and methods.
-- $Author$
-- $Date$
-- $Revision$

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

with RASCAL.Utility;                  use RASCAL.Utility;
with RASCAL.ToolboxKeyboardShortcut;  use RASCAL.ToolboxKeyboardShortcut;
with RASCAL.Toolbox;                  use RASCAL.Toolbox;
with RASCAL.ToolboxGadget;            use RASCAL.ToolboxGadget;
with RASCAL.OS;                       use RASCAL.OS;
with RASCAL.WimpWindow;               use RASCAL.WimpWindow;

package RASCAL.ToolboxWindow is

   No_Toolbox_Window          : Exception;
   Enumeration_Buffer_Overrun : Exception;
   Too_Many_Gadgets           : Exception;
   
   type Toolbox_Toolbar_Type is (Internal_Bottom_Left,Internal_Top_Left,
                                 External_Bottom_Left,External_Top_Left);

   type Gadget_List_Type    is array(integer range <>) of Component_ID;
   type Gadget_List_Pointer is access Gadget_List_Type;

   type WindowTemplate is
   record
   Flags                  : System.Unsigned_Types.Unsigned;
   Help_Message           : Address;
   Max_Help               : Integer;
   Pointer_Shape          : Address;
   Max_Pointer_Shape      : Integer;
   Pointer_X_Hot          : Integer;
   Pointer_Y_Hot          : Integer;
   Menu                   : Address;
   Num_Keyboard_Shortcuts : Integer;
   KeyboardShortcut       : Shortcutlist_Pointer;
   Num_Gadgets            : Integer;
   Gadget                 : Gadgets_Pointer;
   Default_Focus          : Component_ID;
   Show_Event             : Integer;
   Hide_Event             : Integer;
   toolbar_ibl            : Address;
   toolbar_itl            : Address;
   toolbar_ebl            : Address;
   toolbar_etl            : Address;
   Window                 : Wimp_Window_Block_Type;
   end record;
   pragma Convention (C, WindowTemplate);

   -- Flags
   Window_Generate_About_To_Be_Shown  : constant := 16#1#;
   Window_Auto_Open                   : constant := 16#2#;
   Window_Auto_Close                  : constant := 16#4#;
   Window_Generate_Dialogue_Completed : constant := 16#8#;
   Window_Is_Tool_Bar                 : constant := 16#10#;
   Window_No_Focus                    : constant := 16#1#;
   Window_Set_Focus_To_Window         : constant := 16#2#;
   Action_Window_About_To_Be_Shown    : constant := 16#82880#;
   Action_Window_Dialogue_Completed   : constant := 16#82890#;
   Window_Tool_Bar_Ibl                : constant := 16#1#;
   Window_Tool_Bar_Itl                : constant := 16#2#;
   Window_Tool_Bar_Ebl                : constant := 16#4#;
   Window_Tool_Bar_Etl                : constant := 16#8#;
   Window_Click_Adjust                : constant := 16#1#;
   Window_Click_Menu                  : constant := 16#2#;
   Window_Click_Select                : constant := 16#4#;
   Window_Click_Not_Toolbox           : constant := 16#100#;

   --
   -- This event is raised just before the Window object is shown.
   --Type lacks union.
   --
   type Toolbox_Window_AboutToBeShown is
   record
   Header    : Toolbox_Event_Header;
   Show_Type : Integer;
   Info      : Window_Position_Type(Full_Spec);
   end record;
   pragma Convention (C, Toolbox_Window_AboutToBeShown);

   type Toolbox_Window_AboutToBeShown_Pointer is access Toolbox_Window_AboutToBeShown;

   type ATEL_Toolbox_Window_AboutToBeShown is abstract
        new Toolbox_EventListener(Toolbox_Event_Window_AboutToBeShown,-1,-1) with

   record
   Event : Toolbox_Window_AboutToBeShown_Pointer;
   end record;

   --
   -- This event is raised after the Window object has been hidden.
   --
   type Toolbox_Window_HasBeenHidden is
   record
   Header  : Toolbox_Event_Header;
   end record;
   pragma Convention (C, Toolbox_Window_HasBeenHidden);

   type Toolbox_Window_HasBeenHidden_Pointer is access Toolbox_Window_HasBeenHidden;

   type ATEL_Toolbox_Window_HasBeenHidden is abstract
        new Toolbox_EventListener(Toolbox_Event_Window_HasBeenHidden,-1,-1) with

   record
   Event : Toolbox_Window_HasBeenHidden_Pointer;
   end record;

   --
   -- This event is raised when the gadget looses the input focus.
   --
   type Toolbox_Window_GadgetLostFocus is
   record
   Header  : Toolbox_Event_Header;
   end record;
   pragma Convention (C, Toolbox_Window_GadgetLostFocus);

   type Toolbox_Window_GadgetLostFocus_Pointer is access Toolbox_Window_GadgetLostFocus;

   type ATEL_Toolbox_Window_GadgetLostFocus is abstract
        new Toolbox_EventListener(Toolbox_Event_Window_GadgetLostFocus,-1,-1) with

   record
   Event : Toolbox_Window_GadgetLostFocus_Pointer;
   end record;

   --
   -- Returns a pointer to a block of memory suitable for use with Window_AddGadget.
   --
   procedure Extract_GadgetInfo (Template : in Address;
                                 Gadget   : in Component_ID;
                                 Block    : out Address;
                                 BlockSize: out Integer;
                                 Flags    : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Provides the icon numbers for all Toolbox components and sub icons of one component.
   --
   function Enumerate_Gadgets (Window : in Object_ID;
                               Flags  : in System.Unsigned_Types.Unsigned := 0) return Gadget_List_Type;

   --
   -- Plots a gadget in a redraw loop.
   --
   procedure Plot_Gadget (Gadget : in Address;
                          Flags  : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Adds the gadget to the window.
   --
   procedure Add_Gadget (Window : in Object_ID;
                         Gadget : in Address;
                         Flags  : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Removes the gadget from the window.
   --
   procedure Remove_Gadget (Window    : in Object_ID;
                            Component : in Component_ID;
                            Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Sets the objectId of the Menu that will be displayed when MENU is pressed over the window.
   --
   procedure Set_Menu (Window  : in Object_ID;
                       Menu    : in Object_ID;
                       Flags   : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the objectId of the Menu that will be displayed when MENU is pressed over the window.
   --
   function Get_Menu (Window : in Object_ID;
                      Flags  : in System.Unsigned_Types.Unsigned := 0) return Object_ID;

   --
   -- Sets the name of the pointer sprite to be used in the specified window.
   --
   procedure Set_Pointer (Window     : in Object_ID;
                          SpriteName : in string;
                          X_Hotspot  : in integer;
                          Y_Hotspot  : in integer;
                          Flags      : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the name of the pointer sprite to be used in the specified window.
   --
   procedure Get_Pointer (Window    : in Object_ID;
                          SpriteName: out UString;
                          X_Hotspot : out integer;
                          Y_Hotspot : out integer;
                          Flags     : in System.Unsigned_Types.Unsigned := 0);
                         
   --
   -- Sets the interactive help message of the specified window object.
   --
   procedure Set_Help  (Window : in Object_ID;
                        Help   : in String;
                        Flags  : in System.Unsigned_Types.Unsigned := 0);

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

   --
   -- Sets the title of the window.
   --
   procedure Set_Title  (Window : in Object_ID;
                         Title  : in String;
                         Flags  : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the title of the window.
   --
   function Get_Title (Window : in Object_ID;
                       Flags  : in System.Unsigned_Types.Unsigned := 0) return String;

   --
   -- Set the ComponentID of the gadget which the cursor appears in when the specified window is opened.
   --
   procedure Set_DefaultFocus (Window    : in Object_ID;
                               Component : in Component_ID;
                               Flags     : in System.Unsigned_Types.Unsigned := 0);

   --
   -- Returns the ComponentID of the gadget which the cursor appears in when the specified window is opened.
   --
   function Get_DefaultFocus (Window : in Object_ID;
                              Flags  : in System.Unsigned_Types.Unsigned := 0) return Component_ID;

   --
   -- Sets the size of the specified window.
   --
   procedure Set_Extent (Window : in Object_ID;
                         BBox   : in Toolbox_BBox_Type;
                         Flags  : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Returns the size of the specified window.
   --
   function Get_Extent (Window : in Object_ID;
                        Flags  : in System.Unsigned_Types.Unsigned := 0) return Toolbox_BBox_Type;
 
   --
   -- Forces a redraw of the area of the window given by the bounding box.
   --
   procedure Force_Redraw (Window : in Object_ID;
                           BBox   : in Toolbox_BBox_Type;
                           Flags  : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Sets the ObjectIDs of the toolbars that are attached to the specified window.
   --
   procedure Set_Toolbars (Window  : in Object_ID;
                           Toolbar : in Object_ID;
                           Bar_Type: in Toolbox_Toolbar_Type);
 
   --
   -- Returns the ObjectIDs of the toolbars that are attached to the specified window.
   --
   function Get_Toolbars (Window   : in Object_ID;
                          Bar_Type : in Toolbox_Toolbar_Type) return Object_ID;

   --
   -- Returns true if the window is open.
   --
   function Is_Open (Window : in Object_ID) return Boolean;

   --
   -- Returns the ObjectID and ComponentId if the pointer is over a Toolbox window.
   --
   procedure Get_PointerInfo(Flags : in System.Unsigned_Types.Unsigned := 0;
                             X_Pos : out Integer;
                             Y_Pos : out Integer;
                             State : out Integer;
                             Object: out Integer;
                             Gadget: out Integer);

   --
   -- Return Top_left coordinates of window in OS units.
   --
   procedure Get_Position (Window : in Object_ID;
                           X_Pos  : out Integer;
                           Y_Pos  : out Integer);
                                 
   --
   -- Returns the WIMP handle of the toolbox window.
   --
   function Get_WimpHandle (Window : in Object_ID;
                            Flags  : in System.Unsigned_Types.Unsigned := 0) return Wimp_Handle_Type;

   --
   -- Returns the ObjectID and ComponentID of the object that contains the icon specified.
   --
   procedure Wimp_To_Toolbox (Window    : in Wimp_Handle_Type;
                              Icon      : in Icon_Handle_Type;
                              Object    : out Object_ID;
                              Component : out Component_ID;
                              Flags     : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Adds keyboard shortcuts to the window object.
   --
   procedure Add_KeyboardShortcuts (Window    : in Object_ID;
                                    Shortcuts : in KeyboardShortcutList_Type;
                                    Flags     : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Removes keyboard shortcuts from window object.
   --
   procedure Remove_KeyboardShortcuts (Window    : in Object_ID;
                                       Shortcuts : in KeyboardShortcutList_Type;
                                       Flags     : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Registers a new gadget type with the window module.
   --
   procedure Register_External(Gadget_Type : in Integer;
                               Handler_SWI : in Integer;
                               Flags       : in System.Unsigned_Types.Unsigned := 0);
 
   --
   -- Deregisters a gadget type from the window module.
   --
   procedure DeRegister_External(Gadget_Type : in Integer;
                                 Handler_SWI : in Integer;
                                 Flags       : in System.Unsigned_Types.Unsigned := 0);

   --
   --Returns an unused gadgetid.
   --
   function Get_UnusedGadget (Window : in Object_ID) return Component_ID;

end RASCAL.ToolboxWindow;
