/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "Licence").
 * You may not use this file except in compliance with the Licence.
 *
 * You can obtain a copy of the licence at RISC OS path @.^.LICENCE
 * or  http://www.riscosdev.com/lanman98/LICENCE.CDDL
 * See the Licence for the specific language governing permissions
 * and limitations under the Licence.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the Licence file. If applicable, add the
 * following below this CDDL HEADER, with the fields enclosed by
 * brackets "[]" replaced with your own identifying information:
 * Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */
 
/*
 *   Portions Copyright 1996 Warm Silence Software Ltd.
 */

/******************************************************/
/*                                                    */
/* Name: PGicn.h                                      */
/* Author: Paul Gardiner.                             */
/* Function:                                          */
/*   Provides a library of functions for manipulating */
/* icons, for use with the modules PGwin and PGscn.   */
/* They CANNOT be used in isolation.                  */
/*                                                    */
/******************************************************/

#ifndef _PGicn_
#define _PGicn_

#include "PGspr.h"
#include "PGwin.h"

typedef struct icn_icon_s *icn_icon;

typedef void (*icn_action)(void);

typedef char *(*icn_seed)(void);

typedef void (*icn_save)(char *);

typedef struct {int      file_type;
                icn_seed      seed;
                icn_save      save;} icn_drag;

typedef void (*icn_load)(char *);


icn_icon IcnBar(spr_sprite);
    /* Puts an icon on the right of the icon bar.   */
    /* Icon contains specified sprite, or a default */
    /* sprite if argument is NULL.                  */

icn_icon IcnBarFS(spr_sprite);
    /* Puts an icon on the left of the icon bar.   */
    /* Icon contains specified sprite, or a default */
    /* sprite if argument is NULL.                  */

icn_icon IcnBarDisc(char *sprite, char *text);
/*
Puts a sprite and text icon on the icon bar, just to the left of Apps.
*/

void IcnBarDelete(icn_icon icn);
/*
Deletes and icon from the icon bar, and destroys the associated C object.
*/

icn_icon *IcnButtons(win_window);
/*
Returns a NULL terminated array containing the icons of the specified window.
*/

void IcnSetText(icn_icon, char *);
    /* Sets the text of an icon. Presently works    */
    /* only for indirected icons.                   */

char *IcnText(icn_icon);
    /* Returns the text of an icon. Presently works */
    /* only for indirected icons.                   */

void IcnSetSel(icn_icon, int);
/*
 * Selects or deselects an icon, according to whether
 * the second argument is nonzero or zero.
 */

int IcnSel(icn_icon);
/*
 * Returns the selection status of an icon.
 */

void IcnSetGrey(icn_icon, int);
/*
 * Controls the 'greying out' of an icon, according to whether
 * the second argument is nonzero or zero.
 */

void IcnGiveFocus(icn_icon);
/*
Give the input focus to the specified icon.
*/

char *IcnSprName(icn_icon);
    /* Returns the name of an icon's sprite.        */
    /* Presently works only for icons that use      */
    /* system sprites.                              */

void IcnClickS(icn_icon, icn_action);
    /* Defines the action to be taken when the      */
    /* SELECT button is clicked over the specified  */
    /* icon. Actions initiated in this way          */
    /* are performed during calls to WinCoop or     */
    /* ScnVDU, which are defined in the modules,    */
    /* PGwin and PGscn respectively.                */

void IcnClickM(icn_icon, icn_action);
    /* As above, but for the MENU button.           */

void IcnClickA(icn_icon, icn_action);
    /* As above, but for the ADJUST button.         */

void IcnDrag(icn_icon, icn_drag);
    /* Define the action to be performed when a     */
    /* the specified icon is dragged to a filer     */
    /* window. A drag action consists of two        */
    /* functions, called the seed function and the  */
    /* save function. The seed function generates a */
    /* leaf file name for the use by the            */
    /* destination task. When the destination task  */
    /* replies with a full pathname, the save       */
    /* function is executed with the pathname as    */
    /* argument.                                    */

int IcnSafe(void);
    /* This function may be called within the 'save' */
    /* part of a drag action. The value returned     */
    /* indicates whether the save is directed to a   */
    /* filer.                                        */

void IcnSetData(icn_icon, void *);
    /* This function may be called to associate any  */
    /* data with a given icon.                       */

void *IcnGetData(icn_icon);
    /* This function returns the data associated     */
    /* with the given icon.                          */

void *IcnData(void);
    /* This function can be called at any time while */
    /* processing the result of an icon action (i.e. */
    /* inside a handler function for an Icon Click,  */
    /* or drag. It returns the data associated with  */
    /* the icon that has been operated upon.         */

icn_icon IcnCopy(icn_icon, int, int);
/*
  Create a displaced copy of an icon.
*/

#endif /* _PGicn */
