*   Copyright (c) 2002 by Michael J. Roberts.  All Rights Reserved.

 *   

 *   Please see the accompanying license file, LICENSE.TXT, for information

 *   on using and copying this software.  

 */

/*

Name

  osgen.h - definitions for the osgen subsystem

Function

Notes

Modified

  05/19/02 MJRoberts  - Creation

*/

#ifndef OSGEN_H

#define OSGEN_H

/* ------------------------------------------------------------------------ */

/*

 *   osgen support routines.  These routines are implemented by the

 *   semi-portable osgen.c layer for use by the underlying osxxx code.  

 */

/*

 *   Initialize the osgen scrollback buffer.  Allocate the given amount of

 *   space in bytes for scrollback.

 */

void osssbini(unsigned int size);

/*

 *   Delete the scrollback buffer.  This should be called during program

 *   termination to release memory allocated by osssbini().

 */

void osssbdel(void);

/*

 *   The size, in character cells, of the ENTIRE SCREEN (or, at least, the

 *   entire part of the screen available for our use).  Note that these

 *   variables reflect the size of the entire screen - these are NOT

 *   adjusted for status lines, banners, or anything else.

 *   

 *   The system-specific "oss" code MUST initialize these variables during

 *   startup, and MUST then keep them up to date whenever the screen size

 *   changes (for example, if we're running in a terminal window, and the

 *   user resizes the window, these must be updated to reflect the new

 *   window size).  IN ADDITION, whenever the display size changes after

 *   start-up, the "oss" code MUST call osssb_on_resize_screen() to notify

 *   the osgen layer of the change.

 *   

 *   IMPORTANT: In the past, the "oss" code was responsible for initializing

 *   and maintaining the global variables G_os_linewidth and

 *   G_os_pagelength.  The "oss" code need not do this any more - in fact,

 *   the OS code MUST STOP setting G_os_pagelength and G_os_linewidth.

 *   Change these variables instead.  

 */

extern int G_oss_screen_width;

extern int G_oss_screen_height;

/* 

 *   the "oss" code MUST call this routine whenever G_os_screen_width or

 *   G_os_screen_height change (except during initialization) 

 */

void osssb_on_resize_screen(void);

#ifdef RUNTIME

/*

 *   Redraw the screen if necessary.  The oss code MUST call this routine

 *   whenever it's going to pause for a timed wait, or stop to wait for user

 *   input.  Specifically, this should be called from the OS implementation

 *   of the following routines:

 *   

 *   os_getc()

 *.  os_getc_raw()

 *.  os_waitc()

 *.  os_get_event()

 *.  os_askfile();

 *.  os_input_dialog()

 *.  os_sleep_ms()

 *.  os_yield();

 */

void osssb_redraw_if_needed(void);

/*

 *   Put the cursor at the default position.  The oss code CAN optionally

 *   call this at the start of routines that pause for input to put the

 *   cursor at the default position in the main window.  Depending on how the

 *   oss code implements text drawing, the osgen code can sometimes leave the

 *   cursor in a banner window rather than in the main window after drawing.

 *   This routine will ensure that the cursor is in the main window at the

 *   end of the main window's text.  

 */

void osssb_cursor_to_default_pos(void);

/*

 *   Determine if stdin is at end-of-file.  If possible, this should return

 *   the stdin status even if we've never attempted to read stdin.

 *   

 *   For most Unix systems, this can return feof(stdin).  With some C

 *   libraries, however, this doesn't work until after an attempt has already

 *   been made to read from stdin, so we provide this cover to allow flexible

 *   implementation on different systems.  On Windows, for example, it's

 *   necessary to use _feof(_fileno(stdin)), because the higher-level feof()

 *   doesn't recognize EOF until the handle has been read from.  

 */

int oss_eof_on_stdin(void);

#else /* RUNTIME */

/* in non-RUNTIME mode, we don't use osssb_redraw_if_needed at all */

#define osssb_redraw_if_needed()

/* in non-RUNTIME mode, we don't need to reposition the cursor */

#define osssb_cursor_to_default_pos()

#endif /* RUNTIME */

/* ------------------------------------------------------------------------ */

/*

 *   ossxxx implementation for osgen.  These routines must be defined by the

 *   OS-specific subsystem. 

 */

/*

 *   Get extended system information.  This checks to see if the ossxxx

 *   implementation handles the system information code.  If the osxxx layer

 *   doesn't want to handle the code, it can return false so that the osgen

 *   layer will provide a default interpretation.

 *   

 *   Currently, the following codes should be handled by the oss layer:

 *   

 *   SYSINFO_TEXT_COLORS - return the level of color support on this

 *   platform.  Because the ossxxx color interface that osgen uses is limited

 *   to the ANSI colors, this should normally return one of the ANSI support

 *   levels if color is supported, or the unsupported level if color isn't

 *   supported.  Note that if the platform uses a fixed color scheme that

 *   cannot be controlled via the ossxxx routines, this should usually return

 *   the "highlighting only" or "parameterized colors" level.

 *   

 *   SYSINFO_TEXT_HILITE - indicate whether or not highlighted text is

 *   rendered in a distinctive appearance.  

 */

int oss_get_sysinfo(int code, void *param, long *result);

/*

 *   Translate a portable color specification to an oss-style color code.

 *   This returns a color code suitable for use in ossclr(), ossdsp(), and

 *   the other ossxxx() routines defined here that take color codes as

 *   parameters; this color code is opaque to the caller.

 *   

 *   The purpose of this routine is to translate from the portable interface

 *   to color to the hardware-specific or OS-specific color coding used in

 *   the ossxxx layer, so that a caller given a color specified via the

 *   portable interface can send the appropriate ossxxx color code to the

 *   lower-level routines.

 *   

 *   'fg', 'bg', and 'screen_color' are OSGEN_COLOR_xxx values.  'attrs' is a

 *   combination of OS_ATTR_xxx values (defined in osifc.h).  This routine

 *   should combine the colors specified by the combination of these values

 *   to yield an appropriate color code for use in the ossxxx routines.

 *   

 *   Note that the 'bg' color can be OSGEN_COLOR_TRANSPARENT.  If this is the

 *   case, the 'screen_color' value should be used to determine the

 *   background color, if possible.  'fg' should never be transparent.  If

 *   'bg' is not transparent, then screen color is usually ignored.

 *   

 *   COLOR SUPPORT IS OPTIONAL, but this routine must be implemented if

 *   osgen.c is to be used.  If the platform does NOT support explicit color

 *   settings, this routine should still return an appropriate code that can

 *   be used with ossclr, etc.  For example, the Unix oss implementation, at

 *   the time of this writing, used an internal color scheme to select from a

 *   fixed set of parameterized colors (normal, highlighted, reverse), so the

 *   Unix implementation could simply return its appropriate internal code,

 *   largely ignoring the requested colors.  Note, however, that a platform

 *   with only parameterized colors might still want to inspect the 'fg' and

 *   'bg' colors for the OSGEN_COLOR_xxx parameterized colors

 *   (OSGEN_COLOR_TEXT, OSGEN_COLOR_STATUSBG, etc), and return its internal

 *   code corresponding to the selected parameter color when possible.  

 */

int ossgetcolor(int fg, int bg, int attrs, int screen_color);

/*

 *   Translate a key event from "raw" mode to processed mode.  This takes an

 *   event of type OS_EVT_KEY, and converts the keystroke encoded in the

 *   event from the raw keystroke to a CMD_xxx code, if appropriate.

 *   

 *   In effect, this routine converts the event returned from os_get_event()

 *   to the corresponding command code that would be returned from os_getc().

 *   

 *   This routine is defined at the "oss" level because the osgen layer is

 *   semi-portable, and thus needs to be aloof from the details of key

 *   mappings, which vary by system.  

 */

void oss_raw_key_to_cmd(os_event_info_t *evt);

/*

 *   Clear an area of the screen.  The color code is opaque to callers; it is

 *   meaningful only to the ossxxx implementation.  

 */

void ossclr(int top, int left, int bottom, int right, int color);

/*

 *   Display text at a particular location in a particular color.

 */

void ossdsp(int line, int column, int color, const char *msg);

/*

 *   Move the cursor 

 */

void ossloc(int line, int column);

/*

 *   Scroll a region of the screen UP one line. 

 */

void ossscu(int top_line, int left_column, int bottom_line,

            int right_column, int blank_color);

/*

 *   Scroll a region of the screen DOWN one line. 

 */

void ossscr(int top_line, int left_column, int bottom_line,

            int right_column, int blank_color);

/* ------------------------------------------------------------------------ */

/*

 *   osgen attribute names - these are simply substitutes for the regular

 *   osifc attribute names; they map directly to the corresponding osifc

 *   attributes.  

 */

#define OSGEN_ATTR_BOLD OS_ATTR_BOLD

/* ------------------------------------------------------------------------ */

/*

 *   osgen colors.  We don't use full RGB values in the osgen

 *   implementation, but use a simpler color scheme involving the

 *   parameterized colors (from the osifc layer), plus the eight ANSI colors

 *   (black, white, red, green, blue, yellow, cyan, magenta), each in a

 *   "low-intensity" and "high-intensity" version.

 *   

 *   If an underlying platform supports some colors but not all of the ANSI

 *   colors defined here, it should simply map each OSGEN_COLOR_xxx color to

 *   the closest available system color.

 *   

 *   Some systems use color intensity to render the "hilite" ("bold")

 *   attribute.  On these systems, it's obviously not possible for the

 *   caller to select both boldness and the full range of colors

 *   independently, because that would leave no way to render bold text for

 *   the brighter half of the range of colors.  Such systems should simply

 *   treat the high-intensity and low-intensity version of a given color as

 *   equivalent, and select the high- or low-intensity version according to

 *   the boldness attribute.  For reference, here's the correspondence

 *   between the low- and high-intensity versions of the colors:

 *   

 *   low <-> high

 *.  black <-> gray

 *.  maroon <-> red

 *.  green <-> lime

 *.  navy <-> blue

 *.  teal <-> cyan

 *.  purple <-> magenta

 *.  olive <-> yellow

 *.  silver <-> white

 *   

 *   The comment for each absolute color gives the approximate RGB value we

 *   expect for the color (given as hex triplets on 00-FF intensity scale).  

 */

/* the parameterized colors, mapped to single-byte values for osgen's use */

#define OSGEN_COLOR_TRANSPARENT ((char)((OS_COLOR_P_TRANSPARENT) >> 24))

#define OSGEN_COLOR_TEXT        ((char)((OS_COLOR_P_TEXT) >> 24))

#define OSGEN_COLOR_TEXTBG      ((char)((OS_COLOR_P_TEXTBG) >> 24))

#define OSGEN_COLOR_STATUSLINE  ((char)((OS_COLOR_P_STATUSLINE) >> 24))

#define OSGEN_COLOR_STATUSBG    ((char)((OS_COLOR_P_STATUSBG) >> 24))

#define OSGEN_COLOR_INPUT       ((char)((OS_COLOR_P_INPUT) >> 24))

/* "low-intensity" versions of the ANSI colors */

#define OSGEN_COLOR_BLACK       0x70                            /* 00 00 00 */

#define OSGEN_COLOR_MAROON      0x71                            /* 80 00 00 */

#define OSGEN_COLOR_GREEN       0x72                            /* 00 80 00 */

#define OSGEN_COLOR_NAVY        0x73                            /* 00 00 80 */

#define OSGEN_COLOR_TEAL        0x74                            /* 00 80 80 */

#define OSGEN_COLOR_PURPLE      0x75                            /* 80 00 80 */

#define OSGEN_COLOR_OLIVE       0x76                            /* 80 80 00 */

#define OSGEN_COLOR_SILVER      0x77                            /* C0 C0 C0 */

/* "high-intensity" versions of the ANSI colors */

#define OSGEN_COLOR_GRAY        0x78                            /* 80 80 80 */

#define OSGEN_COLOR_RED         0x79                            /* FF 00 00 */

#define OSGEN_COLOR_LIME        0x7A                            /* 00 FF 00 */

#define OSGEN_COLOR_BLUE        0x7B                            /* 00 00 FF */

#define OSGEN_COLOR_CYAN        0x7C                            /* 00 FF FF */

#define OSGEN_COLOR_MAGENTA     0x7D                            /* FF 00 FF */

#define OSGEN_COLOR_YELLOW      0x7E                            /* FF FF 00 */

#define OSGEN_COLOR_WHITE       0x7F                            /* FF FF FF */