/*
 *  ####             #    #     # #
 *  #   #            #    #       #          The FreeWare C library for
 *  #   #  ##   ###  #  # #     # ###             RISC OS machines
 *  #   # #  # #     # #  #     # #  #   ___________________________________
 *  #   # ####  ###  ##   #     # #  #
 *  #   # #        # # #  #     # #  #    Please refer to the accompanying
 *  ####   ### ####  #  # ##### # ###    documentation for conditions of use
 *  ________________________________________________________________________
 *
 *  File:    PopUp.h
 *  Author:  Copyright  1993 Jason Williams
 *  Version: 1.00 (20 May 1993)
 *  Purpose: Low and high-level veneers, typedefs for the PopUp system.
 *
 *  NOTE:
 *  The PopUp system requires support of 2 Wimp message numbers. These
 *  should be integrated into Wimp.h so that you can use:
 *    event->data.message.popupxxx. ...
 *
 *  However, to do this requires permanent wiring of the folowing typedefs
 *  into Wimp.h, which is undesirable if you aren't using PopUps in every
 *  .c file, as it will have a bad effect on compile time/memory use.
 *
 *  Thus, I recommend that you simply #include this file as needed, and
 *  cast the generic message data type from Wimp.h into the specific type
 *  of the message as necessary, e.g.
 *
 *  case Desk_message_POPUPSTATE:
 *  {
 *    Desk_message_popupstate *state;
 *    state = (Desk_message_popupstate *) &event->data.message.data;
 *    switch (state->handle) ...
 */


#ifndef __Desk_PopUp_h
#define __Desk_PopUp_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __Desk_Wimp_h
	#include "Desk.Wimp.h"
#endif


typedef int Desk_popup_handle;


/*  The following are defined in Wimp.h
 *    Desk_message_POPUPRQ      0x46D40
 *    Desk_message_POPUPREQUEST 0x46D40
 *    Desk_message_POPUPSTATE   0x46D41
 *    Desk_message_POPUPCLOSED  0x46D42
 */

/*
 *  PopUp flag byte: Values of flag bits
 *  Preferably, use the 'all inclusive' values below instead
 */
#define Desk_popup_ISLEAF   (0x01)
#define Desk_popup_ISSTATIC (0x02)


/*
 *  All-inclusive PopUp flag byte values
 */
#define Desk_popup_STANDALONE (0x00)
#define Desk_popup_MENULEAF   (0x01)
#define Desk_popup_STATIC     (0x02)

/*
 *  PopUp-specific data for SWI Desk_PopUp_Open and Desk_Message_PopUpState blocks...
 *  See the PopUp documents for details.
 */

typedef struct
{
  int mul, div;
  int minmul, maxmul;
  int mindiv, maxdiv;
} Desk_popup_magnify;

typedef struct
{
  char appname[32];
  char purpose[32];
  char author[32];
  char version[32];
} Desk_popup_proginfo;

typedef struct
{
  struct
  {
    unsigned int cancel     : 1;    /* Has cancel button / cancel was chosen */
    unsigned int ok         : 1;    /* Has OK button     / OK was chosen     */
    unsigned int reserved   : 6;
    unsigned int userhandle : 24;   /* Put anything you find useful here     */
  } flags;
  char oktext[12];                  /* Text for OK button (if any)           */
  char canceltext[12];              /* Text for cancel button (if any)       */
  char appname[12];                 /* Application name for window titlebar  */
  char message[188];                /* Text message to report to the user    */
} Desk_popup_report;

typedef struct
{
  char iconsprite[12];              /* Save As file icon's Iconsprite name   */
  char filename[212];               /* Default text to put into writable icn */
} Desk_popup_saveas;                     /* NOTE a different block is RETURNED... */

typedef struct
{
  struct
  {                                /* If Desk_bool_TRUE:           | If Desk_bool_FALSE:         */
    unsigned int wasdragged : 1;   /* File was dragged   | OK was 'pressed'  */
    unsigned int shiftdown  : 1;   /* SHIFT key was down | SHIFT key wasn't  */
    unsigned int reserved   : 30;
  } flags;

  int  reserved;
  char filename[212];              /* if (wasdragged) this is a leafname,
                                    * else            this is a full pathname
                                    */
} Desk_popup_saveasreturn;

typedef struct
{
  char colour;                     /* Colour 0..15 */
} Desk_popup_wimpcolour;


typedef struct
{
  unsigned int transparency : 8;
  unsigned int red          : 8;
  unsigned int green        : 8;
  unsigned int blue         : 8;
} Desk_colour_rgb;

typedef struct
{
  unsigned int value        : 8;    /* 0..255 */
  unsigned int saturation   : 8;    /* 0..255 */
  unsigned int hue          : 16;   /* 0..359 */
} Desk_colour_hsv;

typedef struct
{
  unsigned int key          : 8;
  unsigned int yellow       : 8;
  unsigned int magenta      : 8;
  unsigned int cyan         : 8;
} Desk_colour_cmyk;

/*
 *  Colour model numbers. See below for examples of use
 */
#define Desk_popuptc_RGB  0
#define Desk_popuptc_HSV  1
#define Desk_popuptc_CMYK 2

/*  Values to OR in to flag value for no transparency, 1 transparency value
 *  ('none' option) and full transparency (256 transparency levels)
 */
#define Desk_popuptc_TRANSPARENT0   0x00000
#define Desk_popuptc_TRANSPARENT1   0x10000
#define Desk_popuptc_TRANSPARENT256 0x20000

/*  Examples:
 *  'Draw' style colour:   colourmodel  = Desk_popuptc_RGB | Desk_popuptc_TRANSPARENT1;
 *  Full transparency HSV: colour model = Desk_popuptc_HSV | Desk_popuptc_TRANSPARENT256;
 */

typedef struct
{
  int colourmodel;                /* eg: Desk_popuptc_RGB + Desk_popuptc_TRANSPARENCY1 */
  union
  {
    Desk_colour_rgb  rgb;
    Desk_colour_hsv  hsv;
    Desk_colour_cmyk cmyk;
  } colour;
  
  int transparency;                 /* 0..255 */
} Desk_popup_truecolour;


typedef struct
{
  char       name[12];              /* PopUp type name, eg "SaveAs"          */
  Desk_wimp_point openpos;               /* Position (top left) to open window at */
  char       flags;                 /* menuleaf/standalone/static popup?     */
  char       reserved1, reserved2, reserved3;
} Desk_popup_header;


typedef union
{
  Desk_popup_magnify    magnify;
  Desk_popup_proginfo   proginfo;
  Desk_popup_report     report;
  Desk_popup_saveas     saveas;
  Desk_popup_wimpcolour wimpcolour;
  Desk_popup_truecolour truecolour;
} Desk_popup_data;                               /* Data to send to popup manager */


typedef struct
{
  Desk_popup_magnify    magnify;
  Desk_popup_report     report;
  Desk_popup_saveas     saveasreturn;
  Desk_popup_wimpcolour wimpcolour;
  Desk_popup_truecolour truecolour;
} Desk_popup_returndata;                     /* Data recieved in a PopUpState msg */


typedef struct
{
  Desk_window_handle window;                /* Pass this data directly to         */
  Desk_wimp_point    openpos;               /* Desk_Wimp_CreateSubMenu. Do not pass GO */
} Desk_message_popuprequest;


typedef struct
{
  Desk_popup_handle     handle;                /* PopUp handle                    */
  char             name[12];              /* PopUp type nam, e.g. "ProgInfo" */
  Desk_popup_returndata data;                  /* Returned state data             */
} Desk_message_popupstate;


typedef struct
{
  Desk_popup_header header;
  Desk_popup_data   data;
} Desk_popup_block;                                /* Block to send to Desk_PopUp_Open */



/* --------------------------------------------------------------------------
 *  Functions
 * --------------------------------------------------------------------------
 */

extern Desk_popup_handle Desk_PopUp_Open(Desk_popup_block *params);
  /*
   *  Straight SWI veneer for Desk_PopUp_Open swi.
   *  (You shouldn't have to call this function - use PopUpShowXXXX, below)
   */


extern void Desk_PopUp_Close(Desk_popup_handle handle);
  /*
   *  Straight SWI veneer for Desk_PopUp_Close swi.
   *  This will close any PopUp, given the handle as returned by other
   *  PopUp calls (Desk_PopUp_Open, Desk_PopUp_Show)
   *  Note that this is only necessary for STATIC PopUps, and that illegal
   *  calls (popup isn't open, etc) will be ignored.
   */


extern Desk_popup_handle Desk_PopUp_ShowMenuLeaf(char *name, Desk_popup_data *definition,
                                       Desk_message_menuwarn *msg);
 /*
  *  Higher level interface to Desk_PopUp_Open, which will show a MENU-LEAF PopUp
  *  given the PopUp type name and popup-specific data, plus the "menuwarn"
  *  message that induced your desire to open the PopUp in the first place.
  *
  *  'name'       is the PopUp type name (e.g. "FontSelect")
  *  'definition' is the popup-specific description.
  *
  *  Hypothetical example of use:
  *  case Desk_message_MENUWARN:
  *    switch(event->data.message.data.menuwarn.selection[0])
  *    {
  *      case 3: |* Save => menu item *|
  *      {
  *        Desk_popup_data pud;
  *
  *        strcpy(pud.saveas.iconsprite, "Desk_file_aff");   |* iconsprite name   *|
  *        strcpy(pud.saveas.filename, "DrawFile");     |* Default file name *|
  *        Desk_PopUp_ShowMenuLeaf("SaveAs", &pud,
  *                            &event->data.message.datamenuwarn);
  */


extern Desk_popup_handle Desk_PopUp_ShowPtr(char *name, Desk_bool isstatic,
                                  Desk_popup_data *definition);
 /*
  *  Higher level interface to Desk_PopUp_Open, which will open a STANDALONE MENU
  *  or STATIC PopUp by filling in the position to open at (over the pointer)
  *  and other header data for you, and open the PopUp as defined by the
  *  passed in "Desk_popup_data" block.
  *
  *  'name'       is the PopUp type name (e.g. "FontSelect")
  *  'isstatic'   indicates if the PopUp should be a static or menu PopUp.
  *  'definition' is the popup-specific description.
  *
  *  Rather than calling ShowPtr directly, use the macros that follow...
  */


#define Desk_PopUp_ShowStandalone(N, D) Desk_PopUp_ShowPtr(N, 0, D)
/*
 *  These macros simply make Desk_PopUp_ShowPtr nicer to use without causing more
 *  code bulk. They are used to show a standalone-menu or a static (permanent
 *  window) PopUp respectively. Prototypes:
 */

#define Desk_PopUp_ShowStatic(N, D) Desk_PopUp_ShowPtr(N, 1, D)
/*
 *  These macros simply make Desk_PopUp_ShowPtr nicer to use without causing more
 *  code bulk. They are used to show a standalone-menu or a static (permanent
 *  window) PopUp respectively. Prototypes:
 */

#ifdef __cplusplus
}
#endif
  

#endif
