/*
 * tearoff.h
 *
 * Tearoff menu handling
 *
 * © 1994-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 __tearoff_h
#define __tearoff_h

/*----- Constants and exported types --------------------------------------*/

/* --- Event type codes --- */

typedef enum
{
  tearoff_SELECTION,
  tearoff_CLOSE,
  tearoff_SUBMENU,
  tearoff_HELP
}
tearoff_message;

/* --- Left-side adornments for menu items --- */

typedef enum
{
  tearoff_NONE,
  tearoff_TICKED,
  tearoff_RADIOED
} tearoff_selectType;

/* --- Event handler interface --- */

typedef void (*tearoff_selectProc)(tearoff_message m,int hit,void *handle);

/* --- What a tearoff menu looks like --- */

typedef struct tearoff__str *tearoff;

/*----- Exported functions ------------------------------------------------*/

/* --- tearoff_create --- *
 *
 * Arguments
 *
 * char *title == title for the menu
 * char *items == text and properties of the menu items.  See above for
 *                syntax.
 * BOOL tearoff == whether to display the tearoff bar along the top
 * tearoff_selectProc proc == an event handler for the menu
 * int max == maximum height of the menu (OS units) or 0 for no maximum
 * void *handle == a `this' pointer for the event handler.
 *
 * Return value
 *
 * A handle to the newly created menu, or 0 if it failed.
 */

tearoff tearoff_create(char *title,char *items,BOOL tearoff,
                       tearoff_selectProc proc, int max, void *handle);

/* --- tearoff_attachSubMenu --- *
 *
 * Arguments
 *
 * tearoff to == a handle for the tearoff to which we must attach the submenu
 * int itm == the index (numbered from 1) of the item to attach to.  The item
 *            must exist in tearoff to.
 * tearoff sub == a handle to the (to be) submenu
 */

void tearoff_attachSubMenu(tearoff to,int itm,tearoff sub);

/* --- tearoff_destroy --- *
 *
 * Arguments
 *
 * tearoff t == handle to a tearoff to get rid of. This call does
 * 	     	not recursively destroy sub menus.
 */

void tearoff_destroy(tearoff t);

/* --- tearoff_displayMenu --- *
 *
 * Arguments
 *
 * tearoff t == handle to the tearoff to display on the screen. It
 * 	     	is opened as a sub menu if one is expected.
 * void *handle == Handle to be returned to handler function. If
 * 		   it is 0 then the old value is used.
 */

BOOL tearoff_displayMenu(tearoff t,void *handle);

/* --- tearoff_init --- *
 *
 * Make sure you call this before any of the other tearoff functions.  The
 * results are undefined in the traditional manner if you don't.
 */

void tearoff_init(void);

/* --- tearoff_selectItem --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff containing the item to select
 * int item == the item (indexed from 1) to select (or not)
 * tearoff_selectType type == how to select the item
 */

void tearoff_selectItem(tearoff t, int item, tearoff_selectType type);

/* --- tearoff_shadeItem --- *
 *
 * Arguments
 *
 * tearoff t == the menu
 * int item == the item to (un)shade
 * BOOL shaded == whether to shade the item or not
 */

void tearoff_shadeItem(tearoff t, int item, BOOL shaded);

/* --- tearoff_closeMenu --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff to close
 */

void tearoff_closeMenu(tearoff t);

/* --- tearoff_changeItemText --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff menu
 * int item == the item to change (indexed from 1)
 * char *text == the new text message. Control key shortcuts must be
   	      	 regiven if they are still wanted.
 */

void tearoff_changeItemText(tearoff t,int item,char *text);

/* --- tearoff_extendMenu --- *
 *
 * Arguments
 *
 * tearoff t == the menu to extend
 * char *items == the items to add in the same syntax as for tearoff_create.
 * 	       	  The results are unpleasent if the menu is open
 *
 * Return Value
 *
 * A new pointer to the tearoff menu, or NULL if it could not be extended.
 */

tearoff tearoff_extendMenu(tearoff t,char *items);

/* --- tearoff_changeTitle --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff menu
 * char *title == the new title - the menu changes size if nessesary
 */

void tearoff_changeTitle(tearoff t,char *title);

/* --- tearoff_displayAt --- *
 *
 * Arguments
 *
 * tearoff t == the menu to open
 * void *handle == Handle to be returned to handler function. If
 *                 it is 0 then the old value is used
 * int x == the x coordinate to open left of menu
 * int y == the y coordinate to open top of menu
 */

void tearoff_displayAt(tearoff t,void *handle,int x,int y);

/* --- tearoff_height --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff menu to find height of
 *
 * Return value
 *
 * The height of the menu - not including the title bar
 */

int tearoff_height(tearoff t);

/* --- tearoff_attachMenu --- *
 *
 * Arguments
 *
 * wimp_w w == the window the attach menu to
 * tearoff t == the menu to attach
 * void *handle == the handle to pass to the handler function,
 *                 if it is 0 then the old value is used.
 *
 * Return value
 *
 * TRUE if successful
 */

BOOL tearoff_attachMenu(wimp_w w,tearoff t,void *handle);

/* --- tearoff__isShaded --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff in question
 * int item == the item to be questioned
 *
 * Return value
 *
 * TRUE if the item is shaded
 */

BOOL tearoff_isShaded(tearoff t,int item);

/* --- tearoff_howSelected --- *
 *
 * Arguments
 *
 * tearoff t == the tearoff in question
 * int item == the item to be questioned
 *
 * Return value
 *
 * How the item has been selected
 */

tearoff_selectType tearoff_howSelected(tearoff t,int item);

#endif