/* 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        : menu.h
 * Description : C veneers to the Methods provided by the menu class
 */



#ifndef __menu_h
#define __menu_h


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

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


/****************************************************************************
 * Menu Templates                                                           *
 ****************************************************************************/

/*-- flags --*/

#define Menu_GenerateShowEvent    0x00000001
#define Menu_GenerateHideEvent    0x00000002

#define Menu_Entry_Ticked               0x00000001
#define Menu_Entry_DottedLine           0x00000002
#define Menu_Entry_Faded                0x00000100
#define Menu_Entry_IsSprite             0x00000200
#define Menu_Entry_SubMenu              0x00000400
#define Menu_Entry_GenerateSubMenuEvent 0x00000800
#define Menu_Entry_ClickShowTransient   0x00001000
#define Menu_Entry_ClickShowCentred     0x00002000
#define Menu_Entry_ClickShowAtPointer	0x00004000


/*-- templates --*/

typedef struct
{
  int           flags;
  char          *title;
  int           max_title;
  char          *help_message;
  int           max_help;
  int           show_event;
  int           hide_event;
  int           num_entries;
} MenuTemplateHeader;


typedef struct
{
  int           flags;
  ComponentId   component_id;
  char          *text;
  int           max_text;
  char          *click_show;
  char          *submenu_show;
  int           submenu_event;
  int           click_event;
  char          *help_message;
  int           max_entry_help;
} MenuTemplateEntry;


typedef struct
{
  MenuTemplateHeader  hdr;

  /* array of entries follows in memory (as defined below) */

} MenuTemplate;


/*-- access to templates --*/

#define menu_template_entry(m, i)  (((MenuTemplateEntry*)(&m->hdr + 1)) + i)


/****************************************************************************
 * Menu SWI Calls                                                           *
 ****************************************************************************/

#define Menu_SWIChunkBase    0x828c0
#define Menu_ObjectClass     Menu_SWIChunkBase
#define Menu_ClassSWI        (Menu_SWIChunkBase + 0)
#define Menu_PostFilter      (Menu_SWIChunkBase + 1)
#define Menu_PreFilter       (Menu_SWIChunkBase + 2)
#define Menu_UpdateTree      (Menu_SWIChunkBase + 3)

/****************************************************************************
 * Menu SWI and event constants                                             *
 ****************************************************************************/

#define Menu_ClickShowTransient                 0x00000001
#define Menu_AddEntryBefore                     0x00000001
#define Menu_AddEntryAtBeginning                -1
#define Menu_AddEntryAtEnd                      -2

/****************************************************************************
 * Menu Methods                                                             *
 ****************************************************************************/

#define Menu_SetTick                   0
#define Menu_GetTick                   1
#define Menu_SetFade                   2
#define Menu_GetFade                   3
#define Menu_SetEntryText              4
#define Menu_GetEntryText              5
#define Menu_SetEntrySprite            6
#define Menu_GetEntrySprite            7
#define Menu_SetSubMenuShow            8
#define Menu_GetSubMenuShow            9
#define Menu_SetSubMenuEvent          10
#define Menu_GetSubMenuEvent          11
#define Menu_SetClickShow             12
#define Menu_GetClickShow             13
#define Menu_SetClickEvent            14
#define Menu_GetClickEvent            15
#define Menu_SetHelpMessage           16
#define Menu_GetHelpMessage           17
#define Menu_SetEntryHelpMessage      18
#define Menu_GetEntryHelpMessage      19
#define Menu_AddEntry                 20
#define Menu_RemoveEntry              21
#define Menu_GetHeight                22
#define Menu_GetWidth                 23
#define Menu_SetTitle                 24
#define Menu_GetTitle                 25


/****************************************************************************
 * Menu Toolbox Events                                                      *
 ****************************************************************************/

#define Menu_AboutToBeShown     Menu_SWIChunkBase
#define Menu_HasBeenHidden      (Menu_SWIChunkBase + 1)
#define Menu_SubMenu            (Menu_SWIChunkBase + 2)
#define Menu_Selection          (Menu_SWIChunkBase + 3)

typedef struct
{
  ToolboxEventHeader hdr;
  int                show_type;
  TopLeft            pos;
} MenuAboutToBeShownEvent;

typedef struct
{
  ToolboxEventHeader hdr;
} MenuHasBeenHiddenEvent;

typedef struct
{
  ToolboxEventHeader hdr;
  TopLeft            pos;
} MenuSubMenuEvent;

typedef struct
{
  ToolboxEventHeader hdr;
} MenuSelectionEvent;




/****************************************************************************
 * 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        : menu_get_title
 * Description : Gets the title for the specified menu object
 * In          : unsigned int flags
 *               ObjectId menu
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_title ( unsigned int flags,
                                         ObjectId menu,
                                         char *buffer,
                                         int buff_size,
                                         int *nbytes
                                       );


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

extern _kernel_oserror *menu_set_title ( unsigned int flags,
                                         ObjectId menu,
                                         const char *title
                                       );


/*
 * Name        : menu_get_width
 * Description : Gets the width of a menu if OS units
 * In          : unsigned int flags
 *               ObjectId menu
 * Out         : int *width
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_width ( unsigned int flags,
                                         ObjectId menu,
                                         int *width
                                       );


/*
 * Name        : menu_get_height
 * Description : Get the height of a menu in OS units
 * In          : unsigned int flags
 *               ObjectId menu
 * Out         : int *height
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_height ( unsigned int flags,
                                          ObjectId menu,
                                          int *height
                                        );


/*
 * Name        : menu_remove_entry
 * Description : Removes an entry from a menu object
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_remove_entry ( unsigned int flags,
                                            ObjectId menu,
                                            ComponentId entry
                                          );


/*
 * Name        : menu_add_entry
 * Description : Adds an entry to a menu object
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId at_entry
 *               const char *entry_description
 * Out         : ComponentId *new_entry
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_add_entry ( unsigned int flags,
                                         ObjectId menu,
                                         ComponentId at_entry,
                                         const char *entry_description,
                                         ComponentId *new_entry
                                       );


/*
 * Name        : menu_get_help_message
 * Description : Gets the help message for a menu object
 * In          : unsigned int flags
 *               ObjectId menu
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_help_message ( unsigned int flags,
                                                ObjectId menu,
                                                char *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );


/*
 * Name        : menu_set_help_message
 * Description : Sets the help message for a menu object
 * In          : unsigned int flags
 *               ObjectId menu
 *               const char *help_message
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_help_message ( unsigned int flags,
                                                ObjectId menu,
                                                const char *help_message
                                              );


/*
 * Name        : menu_get_entry_help_message
 * Description : Gets the help message for a menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_entry_help_message ( unsigned int flags,
                                                      ObjectId menu,
                                                      ComponentId entry,
                                                      char *buffer,
                                                      int buff_size,
                                                      int *nbytes
                                                    );


/*
 * Name        : menu_set_entry_help_message
 * Description : Sets the help message for a menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               const char *help_message
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_entry_help_message ( unsigned int flags,
                                                      ObjectId menu,
                                                      ComponentId entry,
                                                      const char *help_message
                                                    );


/*
 * Name        : menu_get_click_event
 * Description : Gets the event that will be raised when the menu entry is clicked
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : int *toolbox_event
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_click_event ( unsigned int flags,
                                               ObjectId menu,
                                               ComponentId entry,
                                               int *toolbox_event
                                             );


/*
 * Name        : menu_set_click_event
 * Description : Sets the event that will be raised when the menu entry is clicked
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               int toolbox_event
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_click_event ( unsigned int flags,
                                               ObjectId menu,
                                               ComponentId entry,
                                               int toolbox_event
                                             );


/*
 * Name        : menu_get_click_show
 * Description : Gets the id of the object that will be shown when the menu entry is clicked
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : ObjectId *object
 *               int *show_flags
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_click_show ( unsigned int flags,
                                              ObjectId menu,
                                              ComponentId entry,
                                              ObjectId *object,
                                              int *show_flags
                                            );


/*
 * Name        : menu_set_click_show
 * Description : Set the id of the object that will be shown when the menu entry is clicked
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               ObjectId object
 *               int show_flags
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_click_show ( unsigned int flags,
                                              ObjectId menu,
                                              ComponentId entry,
                                              ObjectId object,
                                              int show_flags
                                            );


/*
 * Name        : menu_get_sub_menu_event
 * Description : Gets the event to be raised when the pointer is moved over the sub menu arrow
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : int *toolbox_event
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_sub_menu_event ( unsigned int flags,
                                                  ObjectId menu,
                                                  ComponentId entry,
                                                  int *toolbox_event
                                                );


/*
 * Name        : menu_set_sub_menu_event
 * Description : Sets the event to be raised when the pointer is moved over sub menu arrow
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               int toolbox_event
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_sub_menu_event ( unsigned int flags,
                                                  ObjectId menu,
                                                  ComponentId entry,
                                                  int toolbox_event
                                                );


/*
 * Name        : menu_get_sub_menu_show
 * Description : Gets the id of the object to be shown when pointer moves over sub menu arrow
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : ObjectId *sub_menu
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_sub_menu_show ( unsigned int flags,
                                                 ObjectId menu,
                                                 ComponentId entry,
                                                 ObjectId *sub_menu
                                               );


/*
 * Name        : menu_set_sub_menu_show
 * Description : Sets the id of the object to be shown when pointer is moved over sub menu arrow
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               ObjectId sub_menu
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_sub_menu_show ( unsigned int flags,
                                                 ObjectId menu,
                                                 ComponentId entry,
                                                 ObjectId sub_menu
                                               );


/*
 * Name        : menu_get_entry_sprite
 * Description : Gets the sprite name for a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_entry_sprite ( unsigned int flags,
                                                ObjectId menu,
                                                ComponentId entry,
                                                char *buffer,
                                                int buff_size,
                                                int *nbytes
                                              );


/*
 * Name        : menu_set_entry_sprite
 * Description : Sets the sprite name of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               const char *sprite_name
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_entry_sprite ( unsigned int flags,
                                                ObjectId menu,
                                                ComponentId entry,
                                                const char *sprite_name
                                              );


/*
 * Name        : menu_get_entry_text
 * Description : Gets the text of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               char *buffer
 *               int buff_size
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_entry_text ( unsigned int flags,
                                              ObjectId menu,
                                              ComponentId entry,
                                              char *buffer,
                                              int buff_size,
                                              int *nbytes
                                            );


/*
 * Name        : menu_set_entry_text
 * Description : Sets the text of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               const char *text
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_entry_text ( unsigned int flags,
                                              ObjectId menu,
                                              ComponentId entry,
                                              const char *text
                                            );


/*
 * Name        : menu_get_fade
 * Description : Gets the faded state of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : int *faded
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_fade ( unsigned int flags,
                                        ObjectId menu,
                                        ComponentId entry,
                                        int *faded
                                      );


/*
 * Name        : menu_set_fade
 * Description : Sets the fade state of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               int fade
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_fade ( unsigned int flags,
                                        ObjectId menu,
                                        ComponentId entry,
                                        int fade
                                      );


/*
 * Name        : menu_get_tick
 * Description : Gets the tick state of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 * Out         : int *ticked
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_get_tick ( unsigned int flags,
                                        ObjectId menu,
                                        ComponentId entry,
                                        int *ticked
                                      );


/*
 * Name        : menu_set_tick
 * Description : Sets the tick state of a specific menu entry
 * In          : unsigned int flags
 *               ObjectId menu
 *               ComponentId entry
 *               int tick
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *menu_set_tick ( unsigned int flags,
                                        ObjectId menu,
                                        ComponentId entry,
                                        int tick
                                      );


#ifdef __cplusplus
  }
#endif



#endif
