/* Copyright 1997 Acorn Computers Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/****************************************************************************
 * This source file was written by Acorn Computers Limited. It is part of   *
 * the toolbox library for writing desktop applications in C. It may be     *
 * used freely in the creation of programs for RISC OS.                     *
 *                                                                          *
 * Copyright  Acorn Computers Ltd, 1994                                    *
 *                                                                          *
 ***************************************************************************/



/*
 * Name        : window.h
 * Description : C veneers to the Methods provided by the window class
 */



#ifndef __window_h
#define __window_h


#ifndef __kernel_h
#include "kernel.h"
#endif

#ifndef __toolbox_h
#include "toolbox.h"
#endif

#ifndef __gadgets_h
#include "gadgets.h"
#endif

#ifndef __wimp_h
#include "wimp.h"
#endif



/****************************************************************************
 * Window templates                                                         *
 ****************************************************************************/


/*-- template definition --*/

typedef struct
{
  unsigned int  flags;
  int           wimp_key_code;
  int           key_event;
  char          *key_show;
} KeyboardShortcut;


#define KeyboardShortcut_ShowAsTransient    0x00000001


typedef struct
{
  GadgetHeader hdr;
  union
  {
    ActionButton      action_button;
    OptionButton      option_button;
    LabelledBox       labelled_box;
    Label             label;
    RadioButton       radio_button;
    DisplayField      display_field;
    WritableField     writable_field;
    Slider            slider;
    Draggable         draggable;
    PopUp             popup;
    Adjuster          adjuster;
    NumberRange       number_range;
    StringSet         string_set;
    Button            button;
  } data;
} Gadget;


typedef struct
{
  unsigned int        flags;
  char                *help_message;
  int                 max_help;
  char                *pointer_shape;
  int                 max_pointer_shape;
  int                 pointer_x_hot;
  int                 pointer_y_hot;
  char                *menu;
  int                 num_keyboard_shortcuts;
  KeyboardShortcut    *keyboard_shortcuts;
  int                 num_gadgets;
  Gadget              *gadgets;
  ComponentId         default_focus;
  int                 show_event;
  int                 hide_event;
  char                *toolbar_ibl;
  char                *toolbar_itl;
  char                *toolbar_ebl;
  char                *toolbar_etl;
  WimpWindow          window;
} WindowTemplate;


#define Window_GenerateAboutToBeShown        0x00000001
#define Window_AutoOpen                      0x00000002
#define Window_AutoClose                     0x00000004
#define Window_GenerateHasBeenHidden         0x00000008
#define Window_IsToolBar                     0x00000010


/****************************************************************************
 * Window Methods                                                           *
 ****************************************************************************/

#define Window_GetWimpHandle            0
#define Window_AddGadget                1
#define Window_RemoveGadget             2
#define Window_SetMenu                  3
#define Window_GetMenu                  4
#define Window_SetPointer               5
#define Window_GetPointer               6
#define Window_SetHelpMessage           7
#define Window_GetHelpMessage           8
#define Window_AddKeyboardShortcuts     9
#define Window_RemoveKeyboardShortcuts 10
#define Window_SetTitle                11
#define Window_GetTitle                12
#define Window_SetDefaultFocus         13
#define Window_GetDefaultFocus         14
#define Window_SetExtent               15
#define Window_GetExtent               16
#define Window_ForceRedraw             17
#define Window_SetToolBars             18
#define Window_GetToolBars             19

/****************************************************************************
 * Window Events                                                            *
 ****************************************************************************/

#define Window_AboutToBeShown          (Window_SWIChunkBase + 0)
#define Window_HasBeenHidden           (Window_SWIChunkBase + 16)


typedef struct
{
  BBox                visible_area;          /* visible area coords */
  int                 xscroll,
                      yscroll;               /* scroll offsets */
  int                 behind;                /* handle to open window behind */
  /* The following are only used with the extended Toolbox_ShowObject
   * method (when Toolbox_ShowObject_AsSubWindow is set in flags) */
  unsigned int        window_flags;
  int                 parent_window_handle;
  unsigned int        alignment_flags;
} WindowShowObjectBlock;


typedef struct
{
  ToolboxEventHeader  hdr;
  int                 show_type;
  union
  {
    TopLeft                 top_left;
    WindowShowObjectBlock   full_spec;
  } info;
} WindowAboutToBeShownEvent;


typedef struct
{
  ToolboxEventHeader  hdr;
} WindowHasBeenHiddenEvent;



/****************************************************************************
 * Window SWIs                                                              *
 ****************************************************************************/

#ifndef Window_SWIChunkBase
#define Window_SWIChunkBase    0x82880
#endif

#define Window_ObjectClass     Window_SWIChunkBase
#define Window_ClassSWI        (Window_SWIChunkBase + 0)
#define Window_PostFilter      (Window_SWIChunkBase + 1)
#define Window_PreFilter       (Window_SWIChunkBase + 2)
#define Window_GetPointerInfo  (Window_SWIChunkBase + 3)
#define Window_WimpToToolbox   (Window_SWIChunkBase + 4)

#define Window_ExtractGadgetInfo     (Window_SWIChunkBase + 62)

/****************************************************************************
 * Window SWI constants                                                     *
 ****************************************************************************/

#define Window_InternalBottomLeftToolbar      1
#define Window_InternalTopLeftToolbar         2
#define Window_ExternalBottomLeftToolbar      4
#define Window_ExternalTopLeftToolbar         8
#define Window_GetPointerAdjust               0x00000001
#define Window_GetPointerMenu                 0x00000002
#define Window_GetPointerSelect               0x00000004
#define Window_GetPointerNotToolboxWindow     0x00000100

/****************************************************************************
 * The following functions provide veneers to the methods that are          *
 * associated with this particular class.  Please read the User Interface   *
 * Toolbox manual for more detailed information on their functionality.     *
 ****************************************************************************/



#ifdef __cplusplus
  extern "C" {
#endif

/*
 * Name        : window_extract_gadget_info
 * Description : Extracts a gadget from a template definition
 * In          : unsigned int flags
 *               const ObjectTemplateHeader *templ
 *               ComponentId gadget
 * Out         : void **desc
 *               int *size
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_extract_gadget_info ( unsigned int flags,
                                             const ObjectTemplateHeader *templ,
                                             ComponentId gadget,
                                             void **desc,
                                             int *size
                                             );

/*
 * Name        : window_wimp_to_toolbox
 * Description : Gets the object handle and component id that contains the
 *               specified icon
 * In          : unsigned int flags
 *               int window_handle
 *               int icon_handle
 * Out         : ObjectId *object
 *               ComponentId *component
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_wimp_to_toolbox ( unsigned int flags,
                                                 int window_handle,
                                                 int icon_handle,
                                                 ObjectId *object,
                                                 ComponentId *component
                                               );


/*
 * Name        : window_get_pointer_info
 * Description : gets the ObjectId's and CompontentId's if the
 *               pointer is over a toolbox window (similar to Wimp_GetPointerInfo)
 * In          : unsigned int flags
 * Out         : int *x_pos
 *               int *y_pos
 *               int *buttons
 *               ObjectId *window
 *               ComponentId *component
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_pointer_info ( unsigned int flags,
                                                  int *x_pos,
                                                  int *y_pos,
                                                  int *buttons,
                                                  ObjectId *window,
                                                  ComponentId *component
                                                );


/*
 * Name        : window_get_tool_bars
 * Description : returns the toolbars that are attached to a window
 * In          : unsigned int flags
 *               ObjectId window
 * Out         : ObjectId *ibl
 *               ObjectId *itl
 *               ObjectId *ebl
 *               ObjectId *etl
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_tool_bars ( unsigned int flags,
                                               ObjectId window,
                                               ObjectId *ibl,
                                               ObjectId *itl,
                                               ObjectId *ebl,
                                               ObjectId *etl
                                             );


/*
 * Name        : window_set_tool_bars
 * Description : Sets the toolbars attached to a window
 * In          : unsigned int flags
 *               ObjectId window
 *               ObjectId ibl
 *               ObjectId itl
 *               ObjectId ebl
 *               ObjectId etl
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_tool_bars ( unsigned int flags,
                                               ObjectId window,
                                               ObjectId ibl,
                                               ObjectId itl,
                                               ObjectId ebl,
                                               ObjectId etl
                                             );


/*
 * Name        : window_set_menu
 * Description : Sets the menu that will be displayed when MENU is clicked over window object
 * In          : unsigned int flags
 *               ObjectId window
 *               ObjectId menu_id
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_menu ( unsigned int flags,
                                          ObjectId window,
                                          ObjectId menu_id
                                        );


/*
 * Name        : window_remove_gadget
 * Description : Removes a gadget for the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId gadget
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_remove_gadget ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId gadget
                                             );


/*
 * Name        : window_add_gadget
 * Description : Adds a gadget to the list of gadgets for the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               Gadget *gadget
 * Out         : ComponentId *gadget_component
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_add_gadget ( unsigned int flags,
                                            ObjectId window,
                                            const Gadget *gadget,
                                            ComponentId *gadget_component
                                          );


/*
 * Name        : window_get_wimp_handle
 * Description : Gets the underlying Wimp handle for the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 * Out         : int *window_handle
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_wimp_handle ( unsigned int flags,
                                                 ObjectId window,
                                                 int *window_handle
                                               );


/*
 * Name        : window_get_menu
 * Description : Gets the menu that will be displayed when MENU us clicked over window object
 * In          : unsigned int flags
 *               ObjectId window
 * Out         : ObjectId *menu_id
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_menu ( unsigned int flags,
                                          ObjectId window,
                                          ObjectId *menu_id
                                        );


/*
 * Name        : window_set_pointer
 * Description : Sets the pointer shape that will be used when pointer enters window object
 * In          : unsigned int flags
 *               ObjectId window
 *               const char *sprite_name
 *               int x_hot_spot
 *               int y_hot_spot
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_pointer ( unsigned int flags,
                                             ObjectId window,
                                             const char *sprite_name,
                                             int x_hot_spot,
                                             int y_hot_spot
                                           );


/*
 * Name        : window_get_pointer
 * Description : Gets the pointer shape that is shown when the pointer enters the window object
 * In          : unsigned int flags
 *               ObjectId window
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 *               int *x_hot_spot
 *               int *y_hot_spot
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_pointer ( unsigned int flags,
                                             ObjectId window,
                                             char *buffer,
                                             int buff_size,
                                             int *nbytes,
                                             int *x_hot_spot,
                                             int *y_hot_spot
                                           );


/*
 * Name        : window_set_help_message
 * Description : Sets the help message that is associated with the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               const char *message_text
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  const char *message_text
                                                );


/*
 * Name        : window_get_help_message
 * Description : Gets the help message that is associated with the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               char *buffer
 *               int buff_len
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_help_message ( unsigned int flags,
                                                  ObjectId window,
                                                  char *buffer,
                                                  int buff_len,
                                                  int *nbytes
                                                );


/*
 * Name        : window_add_keyboard_shortcuts
 * Description : Adds the number of keyboard shortcuts to the list for this window object
 * In          : unsigned int flags
 *               ObjectId window
 *               int no_shortcuts
 *               KeyboardShortcut *shortcuts
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_add_keyboard_shortcuts ( unsigned int flags,
                                                        ObjectId window,
                                                        int no_shortcuts,
                                                        const KeyboardShortcut *shortcuts
                                                      );


/*
 * Name        : window_remove_keyboard_shortcuts
 * Description : Removes a number of keyboard shortcuts from the list for the window obj
 * In          : unsigned int flags
 *               ObjectId window
 *               int no_remove
 *               KeyboardShortcut *shortcuts
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_remove_keyboard_shortcuts ( unsigned int flags,
                                                           ObjectId window,
                                                           int no_remove,
                                                           const KeyboardShortcut *shortcuts
                                                         );


/*
 * Name        : window_set_title
 * Description : Sets the title for the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               const char *title
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_title ( unsigned int flags,
                                           ObjectId window,
                                           const char *title
                                         );


/*
 * Name        : window_get_title
 * Description : Gets the title for the specified window object
 * In          : unsigned int flags
 *               ObjectId window
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_title ( unsigned int flags,
                                           ObjectId window,
                                           char *buffer,
                                           int buff_size,
                                           int *nbytes
                                         );


/*
 * Name        : window_set_default_focus
 * Description : Sets the component that gets the input focus for the specified window
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId focus
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_default_focus ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId focus
                                                 );


/*
 * Name        : window_get_default_focus
 * Description : Gets the id of the component that has the input focus for the specified window
 * In          : unsigned int flags
 *               ObjectId window
 * Out         : ComponentId *focus
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_default_focus ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId *focus
                                                 );


/*
 * Name        : window_set_extent
 * Description : Sets the extent of the specified window
 * In          : unsigned int flags
 *               ObjectId window
 *               const BBox *extent
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_set_extent ( unsigned int flags,
                                            ObjectId window,
                                            const BBox *extent
                                          );


/*
 * Name        : window_get_extent
 * Description : Gets the extent of the specified window
 * In          : unsigned int flags
 *               ObjectId window
 *               BBox *extent
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_get_extent ( unsigned int flags,
                                            ObjectId window,
                                            BBox *extent
                                          );


/*
 * Name        : window_force_redraw
 * Description : Forces a redraw of the supplied area for the specified window
 * In          : unsigned int flags
 *               ObjectId window
 *               const BBox *redraw_box
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *window_force_redraw ( unsigned int flags,
                                              ObjectId window,
                                              const BBox *redraw_box
                                            );


#ifdef __cplusplus
  }
#endif






#endif
