/*
 * ibicon
 *  proper icon bar mangement (multiple icons, etc.)
 *
 * © 1992-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel 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 General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __ibicon_h
#define __ibicon_h

#ifndef __sprite_h
  #include "sprite.h"
#endif

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

#ifndef __event_h
  #include "event.h"
#endif

#ifndef __menu_h
  #include "menu.h"
#endif

/*-----------------------------------------------------

  DOs and DON'Ts

  DO...

  + only use the functions provided for manipulating your icons

  DON'T...

  + try and use event_attachmenu() or win_register_event_handler()
    like you do for baricon.
  + delete icons without these functions

  baricon will be retained for compatibility, but it will use these
  routines rather than going it alone.

-----------------------------------------------------*/

typedef struct ibicon__ibiconstr *ibicon;

typedef enum
{
  ibicon_NOTHING,          /* Nothing interesting.  This is for use by     */
                           /* ibicon, and will NOT be passed to handlers   */
  ibicon_LEFTCLICK,        /* Click with left button                       */
  ibicon_RIGHTCLICK,       /* Click with right button                      */
  ibicon_LOAD,             /* Attempt to load file from disk               */
  ibicon_SAVE,             /* Attempt to import file                       */
  ibicon_HELP              /* Request for help about the icon              */
}
ibicon_eventType;

typedef void (*ibicon_handler)(ibicon i,ibicon_eventType e,void *handle);
typedef BOOL (*ibicon_rawHandler)(ibicon i,wimp_eventstr *e,void *handle);

/* These are places you can put your icon */

#define ibicon_LEFT -2     /* Show icon on left side (device)              */
#define ibicon_RIGHT -1    /* Show icon on right side (application)        */
#define ibicon_LEFTSEARCHLEFT -5
#define ibicon_LEFTSEARCHRIGHT -6
#define ibicon_RIGHTSEARCHLEFT -7
#define ibicon_RIGHTSEARCHRIGHT -8

/* A couple of ways of specifying odd sprite areas */

#define ibicon_WIMPAREA ((sprite_area *)1)
#define ibicon_SYSTEMAREA ((sprite_area *)0)

/*
 * ibicon ibicon_find(wimp_i icon)
 *
 * Use
 *  Return the ibicon handle of an icon.
 *
 * Parameters
 *  wimp_i icon == the icon to find
 */

ibicon ibicon_find(wimp_i icon);


/*
 * wimp_i ibicon_syshandle(ibicon i)
 *
 * Use
 *  Returns the low-level WIMP handle for the icon concerned.
 *
 * Parameters
 *  ibicon i == the icon whose handle is desired
 *
 * Returns
 *  The WIMP icon handle for the icon
 */

wimp_i ibicon_syshandle(ibicon i);

/*
 * void ibicon_setPriority(int priority)
 *
 * Use
 *  Sets the priority with which to create icons under RISC OS 3.
 *
 * Parameters
 *  int priority == the new setting
 */

void ibicon_setPriority(int priority);

/*
 * ibicon ibicon_create
 * (
 *   int where,
 *   char *spritename,
 *   sprite_area *sprarea,
 *   char *text,
 *   int maxtext
 * )
 *
 * Use
 *  Creates an icon in the icon bar.  Where is up to you.  Specify a
 *  sprite-only icon by passing 0 for text.  Use the macros to define where
 *  and what area you want the sprite from.
 *
 * Parameters
 *  int where == what part of the icon bar you want to put the icon in.
 *    Macros are defined for the RISC OS 2 possibilities.  Wait for the
 *    RISC OS 3 macros, or just pass a window handle.
 *  char *spritename == the name of the sprite to display
 *  sprite_area *sprarea == the area from which the sprite area comes.  Use
 *    the macros provided for odd things like the WIMP area.  If you have
 *    text as well, then this will be ignored anyway.
 *  char *text == the text for the icon.  May be a NULL pointer, for no
 *    text.
 *  int maxtext == the max length the text entry can be.  If 0 then the
 *    length of the text given will be used.
 *
 * Returns
 *  A handle to the icon if successful, or 0 if not.
 */

ibicon ibicon_create
(
  int where,
  char *spritename,
  sprite_area *sprarea,
  char *text,
  int maxtext
);

/*
 * void ibicon_changeSprite(ibicon i,char *newsprite)
 *
 * Use
 *  Chnage the sprite displayed in an icon
 *
 * Parameters
 *  ibicon i == the icon to change
 *  char *newsprite == the new name
 */

void ibicon_changeSprite(ibicon i,char *newsprite);

/*
 * void ibicon_changeText(ibicon i,char *newtext)
 *
 * Use
 *  Change the text of an icon.
 *
 * Parameters
 *  ibicon i == the icon to change
 *  char *text == the new text to display
 */

void ibicon_changeText(ibicon i,char *newtext);

/*
 * void ibicon_attachMenu
 * (
 *   ibicon i,
 *   menu m,
 *   menu_selectProc sel,
 *   menu_helpProc help,
 *   void *handle
 * )
 *
 * Use
 *  Attaches a menu to an icon in the icon bar
 *
 * Parameters
 *  ibicon i == the icon to attach to
 *  menu m == the menu to attach
 *  menu_selectProc sel == a handler function for the menu
 *  menu_helpProc help == a help processor for the menu
 *  void *handle == a handle passed to the handler
 */

void ibicon_attachMenu
(
  ibicon i,
  menu m,
  menu_selectProc sel,
  menu_helpProc help,
  void *handle
);


/*
 * void ibicon_attachMenuMaker
 * (
 *   ibicon i,
 *   event_menu_maker m,
 *   menu_selectProc sel,
 *   menu_helpProc help,
 *   void *handle
 * )
 *
 * Use
 *  Attaches a menu maker to an icon in the icon bar
 *
 * Parameters
 *  ibicon i == the icon to attach to
 *  event_menu_maker m == the menu maker to attach
 *  menu_selectProc sel == a handler function for the menu
 *  menu_helpProc help == a help processor for the menu
 *  void *handle == a handle passed to the handler
 */

void ibicon_attachMenuMaker
(
  ibicon i,
  event_menu_maker m,
  menu_selectProc sel,
  menu_helpProc help,
  void *handle
);

/*
 * void ibicon_removeIcon(ibicon i)
 *
 * Use
 *  Removes an icon totally from the icon bar.
 *
 * Parameters
 *  ibicon i == the icon to vape
 */

void ibicon_removeIcon(ibicon i);

/*
 * void ibicon_eventHandler(ibicon i,ibicon_handler p,void *handle)
 *
 * Use
 *  Attaches the handler to an icon.
 *
 * Parameters
 *  ibicon i == the icon to attach
 *  ibicon_handler p == the handler
 *  void *handle == a pointer to pass to the handler
 */

void ibicon_eventHandler(ibicon i,ibicon_handler p,void *handle);

/*
 * void ibicon_rawEventHandler(ibicon i,ibicon_rawHandler p,void *handle)
 *
 * Use
 *  Attaches a raw event handler.  This can 'vet' events before ibicon gets
 *  it mucky mits on them.
 *
 * Parameters
 *  ibicon i == the icon to attach
 *  ibicon_rawHandler p == the handler
 *  void *handle == a pointer to pass to the handler
 */

void ibicon_rawEventHandler(ibicon i,ibicon_rawHandler p,void *handle);

#endif