/*
 *  ####             #    #     # #
 *  #   #            #    #       #          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 message_POPUPSTATE:
 *  {
 *    message_popupstate *state;
 *    state = (message_popupstate *) &event->data.message.data;
 *    switch (state->handle) ...
 */


#ifndef __dl_popup_h
#define __dl_popup_h

#ifdef __cplusplus
extern "C" {
#endif


#ifndef __dl_wimp_h
#include "Wimp.h"
#endif


typedef int popup_handle;


/*  The following are defined in Wimp.h
 *    message_POPUPRQ      0x46D40
 *    message_POPUPREQUEST 0x46D40
 *    message_POPUPSTATE   0x46D41
 *    message_POPUPCLOSED  0x46D42
 */

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


/*
 *  All-inclusive PopUp flag byte values
 */
#define popup_STANDALONE (0x00)
#define popup_MENULEAF   (0x01)
#define popup_STATIC     (0x02)

/*
 *  PopUp-specific data for SWI PopUp_Open and Message_PopUpState blocks...
 *  See the PopUp documents for details.
 */

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

typedef struct
{
  char appname[32];
  char purpose[32];
  char author[32];
  char version[32];
} 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    */
} popup_report;

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

typedef struct
{
  struct
  {                                /* If TRUE:           | If 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
                                    */
} popup_saveasreturn;

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


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

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

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

/*
 *  Colour model numbers. See below for examples of use
 */
#define popuptc_RGB  0
#define popuptc_HSV  1
#define 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 popuptc_TRANSPARENT0   0x00000
#define popuptc_TRANSPARENT1   0x10000
#define popuptc_TRANSPARENT256 0x20000

/*  Examples:
 *  'Draw' style colour:   colourmodel  = popuptc_RGB | popuptc_TRANSPARENT1;
 *  Full transparency HSV: colour model = popuptc_HSV | popuptc_TRANSPARENT256;
 */

typedef struct
{
  int colourmodel;                /* eg: popuptc_RGB + popuptc_TRANSPARENCY1 */
  union
  {
    colour_rgb  rgb;
    colour_hsv  hsv;
    colour_cmyk cmyk;
  } colour;
  
  int transparency;                 /* 0..255 */
} popup_truecolour;


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


typedef union
{
  popup_magnify    magnify;
  popup_proginfo   proginfo;
  popup_report     report;
  popup_saveas     saveas;
  popup_wimpcolour wimpcolour;
  popup_truecolour truecolour;
} popup_data;                               /* Data to send to popup manager */


typedef struct
{
  popup_magnify    magnify;
  popup_report     report;
  popup_saveas     saveasreturn;
  popup_wimpcolour wimpcolour;
  popup_truecolour truecolour;
} popup_returndata;                     /* Data recieved in a PopUpState msg */


typedef struct
{
  window_handle window;                /* Pass this data directly to         */
  wimp_point    openpos;               /* Wimp_CreateSubMenu. Do not pass GO */
} message_popuprequest;


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


typedef struct
{
  popup_header header;
  popup_data   data;
} popup_block;                                /* Block to send to PopUp_Open */



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

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


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


extern popup_handle PopUp_ShowMenuLeaf(char *name, popup_data *definition,
                                       message_menuwarn *msg);
 /*
  *  Higher level interface to 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 message_MENUWARN:
  *    switch(event->data.message.data.menuwarn.selection[0])
  *    {
  *      case 3: |* Save => menu item *|
  *      {
  *        popup_data pud;
  *
  *        strcpy(pud.saveas.iconsprite, "file_aff");   |* iconsprite name   *|
  *        strcpy(pud.saveas.filename, "DrawFile");     |* Default file name *|
  *        PopUp_ShowMenuLeaf("SaveAs", &pud,
  *                            &event->data.message.datamenuwarn);
  */


extern popup_handle PopUp_ShowPtr(char *name, BOOL isstatic,
                                  popup_data *definition);
 /*
  *  Higher level interface to 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 "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 PopUp_ShowStandalone(N, D) PopUp_ShowPtr(N, 0, D)
/*
 *  These macros simply make 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 PopUp_ShowStatic(N, D) PopUp_ShowPtr(N, 1, D)
/*
 *  These macros simply make 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
