/*
 * !tpluslib.tplus.h - basic library
 *
 * provides msgs and werr like library functionality plus
 * error raising mechanism, also various toolbox specific useful
 * procedures.
 *
 * Library is  Risc User 1996, portions of this code are
 *  Tony Howat 1996,  Andy Armstrong 1994,  Acorn Computers Ltd 1992
 *
 * The TPlus library is *not* freeware and should not be distributed by
 * anyone other than Risc User. Those with an official copy of TPlus
 * (on a Risc User Magazine Disc, Special Disc, CD-ROM etc)
 * have an unlimited licence to link the library with their own progams.
 */

#ifndef __tplus_h
#define __tplus_h

#include "kernel.h"
#include "swis.h"
#include "toolbox.h"
#include "gadgets.h"

#ifndef BOOL
#define BOOL int
#define TRUE 1
#define FALSE 0
#endif

#ifdef __cplusplus
  extern "C" {
#endif

/* ------------------------------ raise_error ------------------------------
 *
 * Description:   Raise a _kernel_oserror, displaying a standard wimp error
 *                box.
 *
 * Parameters:    _kernel_oserror *e -- pointer to standard RISC-OS error
 *                block.
 * Returns:       void.
 * Other Info:    This routine looks for a taskname by attempting to look
 *                up _TaskName in the messages file descriptor mfd (an
 *                external variable)
 *
 */

void raise_error(_kernel_oserror *e);

/* -------------------------------- werr -----------------------------------
 *
 * Description:   Display a (possibly fatal) error message in a pop-up
 *                dialogue box.
 *
 * Parameters:    int fatal -- non-zero indicates fatal error
 *                char *format -- printf-style format string
 *                ... -- variable arg list of message to be printed
 * Returns:       void.
 * Other Info:    Program exits if fatal is non-zero
 *                Pointer is restricted to displayed dialogue box to stop
 *                user continuing until he has clicked on "OK" buton.
 *                The message should be divided into at most three lines,
 *                each of 40 characters or less.
 *
 */

void werr(int fatal, char* format, ...);


/* ---------------------------- msgs_lookup --------------------------------
 * Description:   Find the text message associated with a given tag.
 *
 * Parameters:    char * tag_and_default -- the tag of the message, and
 *                                          an optional default message (to
 *                                          be used if tagged message not
 *                                          found).
 * Returns:       pointer to the message text (if all is well)
 * Other Info:    If the caller just supplies a tag, he will receive a
 *                pointer to its associated message (if found). A default
 *                message can be given after the tag (separated by a colon)
 *                Typical use would be:
 *                      werr(1, msgs_lookup("error1"))
 *                or    werr(1, msgs_lookup("error1:Not enough memory").
 *
 */

char *msgs_lookup(char *token);

/* ---------------------------- msgs_flookup -------------------------------
 * Description:   Find the text message associated with a given tag.
 *
 * Parameters:    char * tag_and_default -- the tag of the message, and
 *                                          an optional default message (to
 *                                          be used if tagged message not
 *                                          found).
 * Returns:       pointer to the message text (if all is well)
 * Other Info:    If the caller just supplies a tag, he will receive a
 *                pointer to its associated message (if found). A default
 *                message can be given after the tag (separated by a colon)
 *                Typical use would be:
 *                      werr(1, msgs_lookup("error1"))
 *                or    werr(1, msgs_lookup("error1:Not enough memory").
 *
 */

void msgs_flookup (char *token, char *buffer, int buffer_size, char *par1, \
                  char *par2, char *par3, char *par4, char **new_buffer, \
                  int *new_buffer_size);


/* ---------------------------- fade_gadget -------------------------------
 * Description:   Fade a toolbox gadget
 *
 * Parameters:    ObjectId win        - window the gadget is in
 *                ComponentId gadget  - id of the gadget to fade/unfade
 *                int fade            - 1 to fade, 0 to unfade
 * Returns:       void.
 *
 */

void fade_gadget(ObjectId win, ComponentId gadget, int fade);

/* --------------------------- window_front -------------------------------
 * Description:   Move a window object to the top of the window stack,
 *                shifting toolbars accordingly.
 *
 * Parameters:    ObjectId win        - window to move
 * Returns:       void.
 *
 */

void window_front(ObjectId win);

/* -------------------------- window_centre -------------------------------
 * Description:   Move a window object to the centre of the screen, shifting
 *                toolbars accordingly.
 *
 * Parameters:    ObjectId win        - window to move
 * Returns:       void.
 *
 */

void window_centre(ObjectId win);

/* ---------------------- window_force_onscreen ----------------------------
 * Description:   Move a window object to the centre of the screen, shifting
 *                toolbars accordingly.
 *
 * Parameters:    ObjectId win        - window to move
 * Returns:       void.
 *
 */

void window_force_onscreen(ObjectId win);

/* ------------------------- window_open_centre ---------------------------
 * Description:   Use instead of toolbox_show_object to open a window
 *                object in the centre of the screen.
 *
 * Parameters:    int flags           - bit 0 set means open using the
 *                                      semantics of wimp_createmenu
 *                                      bit 1 set means open using the
 *                                      semantics of wimp_createsubmenu
 *                ObjectId win        - window to centre
 *                ObjectId pid        - id of the parent object
 *                ComponentId pco     - id of the parent component
 * Returns:       _kernel_oserror *   - pointer to any error which may have
 *                                      occured.
 *
 */

_kernel_oserror *window_open_centre(int flags,ObjectId win,ObjectId pid,ComponentId pco);


#ifdef __cplusplus
  }
#endif

#endif
