/* Copyright 1998 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, 1998                                    *
 *                                                                          *
 ***************************************************************************/



/*
 * Name        : scrolllist.h
 * Description : C veneers to the Methods provided by the ScrollList gadget
 */



#ifndef __scrolllist_h
#define __scrolllist_h


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

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

#ifndef __window_h
#include "window.h"
#endif


/****************************************************************************
 * ScrollList Templates                                                     *
 ****************************************************************************/

/*-- gadget flags --*/

#define ScrollList_SingleSelections	0x00000000
#define ScrollList_MultipleSelections	0x00000001

#define ScrollListValidFlags	        0xC0000001

/*-- templates --*/

typedef struct
{
    GadgetHeader	hdr;
    int			event;
    unsigned int	foreground;
    unsigned int	background;
} ScrollList;


/*-- ScrollList methods --*/

#define ScrollList_Base		0x401A
#define ScrollList_Type		(sizeof(ScrollList)) << 16 | ScrollList_Base
#define ScrollList_SWIBase	0x140182

#define ScrollList_GetState	(ScrollList_Base + 0)
#define ScrollList_SetState	(ScrollList_Base + 1)
#define ScrollList_AddItem	(ScrollList_Base + 2)
#define ScrollList_DeleteItems	(ScrollList_Base + 3)
#define ScrollList_SelectItem	(ScrollList_Base + 4)
#define ScrollList_DeselectItem	(ScrollList_Base + 5)
#define ScrollList_GetSelected	(ScrollList_Base + 6)
#define ScrollList_MakeVisible	(ScrollList_Base + 7)
#define ScrollList_SetColour	(ScrollList_Base + 8)
#define ScrollList_GetColour	(ScrollList_Base + 9)
#define ScrollList_SetFont	(ScrollList_Base + 10)
#define ScrollList_GetItemText	(ScrollList_Base + 11)
#define ScrollList_CountItems   (ScrollList_Base + 12)
#define ScrollList_SetItemText  (ScrollList_Base + 13)


/*-- ScrollList button events --*/

#define ScrollList_Selection	(0x140180 + 1)

#define ScrollList_Selection_Flags_Set		(1<<0)
#define ScrollList_Selection_Flags_DoubleClick	(1<<1)
#define ScrollList_Selection_Flags_AdjustClick	(1<<2)

typedef struct
{
    ToolboxEventHeader	hdr;
    unsigned int	flags;
    int			item;
} ScrollListSelectionEvent;


/*-- ScrollList SWI method constants --*/

#define ScrollList_DesktopColours		(1<<0)

/*-- method flags for select_item, deselect_item, delete_items --*/

#define ScrollList_SelectionChangingMethod_SendEvent (1u<<0)
#define ScrollList_SelectionChangingMethod_OnAll     (1u<<1)

/*-- method flags for add_item and delete_items --*/

#define ScrollList_AddItem_MakeVisible               (1u<<3)
#define ScrollList_DeleteItems_DoNotJumpToTop        (1u<<1)


/****************************************************************************
 * The following functions provide veneers to the methods that are          *
 * associated with this particular class.  Please read the C Release 5      *
 * user guide for more detailed information on their functionality.         *
 ****************************************************************************/


#ifdef __cplusplus
  extern "C" {
#endif


/*
 * Name        : scrolllist_select_item
 * Description : Selects the given item from the specified scrolllist
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               int index
 * Out         : None
 * Returns     : pointer to error block
 *
 * To receive a ScrollList_Selection event indicating the item that
 * was selected with any mouse button related flags cleared, set the
 * ScrollList_SelectionChangingMethod_SendEvent bit of the flags.
 * This will be sent even if the item you specify was already
 * selected before the function call was made.
 *
 * To select all items, call with the flags bit
 * ScrollList_SelectionChangingMethod_OnAll set. In this case, the
 * value set in 'index' is irrelevant. If using the flags to get a
 * ScrollList_Selection event as well (see above), the item number
 * in the event will be zero.
 */

extern _kernel_oserror *scrolllist_select_item ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId scrolllist,
                                                 int index
                                               );


/*
 * Name        : scrolllist_set_font
 * Description : Set the font for the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               const char *font_name
 *               unsigned int width
 *               unsigned int height
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_set_font ( unsigned int flags,
                                              ObjectId window,
                                              ComponentId scrolllist,
                                              const char *font_name,
                                              unsigned int width,
                                              unsigned int height
                                            );


/*
 * Name        : scrolllist_get_colour
 * Description : Gets the colours currently being used for the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 * Out         : unsigned int *foreground
 *               unsigned int *background
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_get_colour ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId scrolllist,
                                                unsigned int *foreground,
                                                unsigned int *background
                                              );


/*
 * Name        : scrolllist_set_colour
 * Description : Sets the colours for the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               unsigned int foreground
 *               unsigned int background
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_set_colour ( unsigned int flags,
                                                ObjectId window,
                                                ComponentId scrolllist,
                                                unsigned int foreground,
                                                unsigned int background
                                              );


/*
 * Name        : scrolllist_get_item_text
 * Description : Gets the text of the specified scrolllist item.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               char *buffer
 *               int size
 *               int index
 * Out         : int *nbytes
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_get_item_text ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId scrolllist,
                                                   char *buffer,
                                                   int size,
                                                   int index,
                                                   int *nbytes
                                                 );

/*
 * Name        : scrolllist_set_item_text
 * Description : Sets the text of the specified scrolllist item.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               const char *new_text
 *               int index
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_set_item_text ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId scrolllist,
                                                   const char *new_text,
                                                   int index
                                                 );


/*
 * Name        : scrolllist_set_state
 * Description : Sets the state of the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               unsigned int state
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_set_state ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId scrolllist,
                                               unsigned int state
                                             );


/*
 * Name        : scrolllist_get_state
 * Description : Gets the state of the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 * Out         : unsigned int *state
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_get_state ( unsigned int flags,
                                               ObjectId window,
                                               ComponentId scrolllist,
                                               unsigned int *state
                                             );


/*
 * Name        : scrolllist_add_item
 * Description : Adds an item to the specified scrolllist
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               const char *text
 *               const void *sprite_area
 *               const char *sprite_name
 *               int index
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_add_item ( unsigned int flags,
                                              ObjectId window,
                                              ComponentId scrolllist,
                                              const char *text,
                                              const void *sprite_area,
                                              const char *sprite_name,
                                              int index
                                            );


/*
 * Name        : scrolllist_delete_items
 * Description : Deletes the items from the specified scrolllist
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               int start
 *               int end
 * Out         : None
 * Returns     : pointer to error block
 *
 * To be sent a ScrollList_Selection event after the function completes,
 * set the ScrollList_SelectionChangingMethod_SendEvent bit of the flags.
 * The event you receive merely notifies you of completion; the actual
 * selection may not have changed. Note that an item number of '-1' will
 * be present in the event received.
 */

extern _kernel_oserror *scrolllist_delete_items ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId scrolllist,
                                                  int start,
                                                  int end
                                                );


/*
 * Name        : scrolllist_get_selected
 * Description : Gets the selected items from the specified scrolllist.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               int offset
 * Out         : int *new_offset
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_get_selected ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId scrolllist,
                                                  int offset,
                                                  int *new_offset
                                                );


/*
 * Name        : scrolllist_make_visible
 * Description : Forces the given item of the specified scrolllist to be visible.
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               int index
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_make_visible ( unsigned int flags,
                                                  ObjectId window,
                                                  ComponentId scrolllist,
                                                  int index
                                                );


/*
 * Name        : scrolllist_deselect_item
 * Description : Deselects the specified item from the specified scrolllist
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               int index
 * Out         : None
 * Returns     : pointer to error block
 *
 * To receive a ScrollList_Selection event indicating the item that
 * was deselected with any mouse button related flags cleared, set the
 * ScrollList_SelectionChangingMethod_SendEvent bit of the flags. This
 * will be sent even if the item you specify was already deselected
 * before the function call was made.
 *
 * To deselect all items, call with the flags bit
 * ScrollList_SelectionChangingMethod_OnAll set. In this case, the value
 * given in 'index' is irrelevant.
 */

extern _kernel_oserror *scrolllist_deselect_item ( unsigned int flags,
                                                   ObjectId window,
                                                   ComponentId scrolllist,
                                                   int index
                                                 );


/*
 * Name        : scrolllist_count_items
 * Description : Returns the number of items in the scrolllist
 * In          : unsigned int flags
 *               ObjectId window
 *               ComponentId scrolllist
 *               unsigned int *items
 * Out         : None
 * Returns     : pointer to error block
 */

extern _kernel_oserror *scrolllist_count_items ( unsigned int flags,
                                                 ObjectId window,
                                                 ComponentId scrolllist,
                                                 unsigned int *items
                                               );

#ifdef __cplusplus
  }
#endif




#endif
