reduce-historical/r37/lisp/csl/cslbase/cwin.h

/*
 * "cwin.h"                                   1995-2002, A C Norman
 *
 * This defines the public interface supported by the "cwin" window
 * interface.
 *
 */

/*
 * This code may be used and modified, and redistributed in binary
 * or source form, subject to the "CCL Public License", which should
 * accompany it. This license is a variant on the BSD license, and thus
 * permits use of code derived from this in either open and commercial
 * projects: but it does require that updates to this code be made
 * available back to the originators of the package.
 * Before merging other code in with this or linking this code
 * with other packages or libraries please check that the license terms
 * of the other material are compatible with those of this.
 */


/*
 * The code here is provides a windowed framework in which reasonably
 * ordinary C code can run.  The functions described here are the
 * interface.  Version for Windows 95 as well as win32s and Windows NT.
 */

/* Signature: 368013b1 10-Oct-2002 */

#ifndef header_cwin_h
#define header_cwin_h 1

#include <stdarg.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * The "C" code will eventually be entered at cwin_main() in what looks like a
 * normal way.  The function cwin_main() MUST return. There is no provision
 * for anything like the exit() function present in normal C libraries. The
 * reason for this uncomfortable situation is that my window manager code
 * needs to regain cotrol to close things down and tidy up at the end.
 * Furthermore conflicts between C++ exceptions and C "setjmp" appear to make
 * it hard to find a reliable way of skipping down stack frames across the
 * two languages.  So I have to insist that that user deals will all
 * necessary unwinding by hand. Apologies.
 */
extern int cwin_main(int argc, char *argv[]);

/*
 * cwin_full_program_name is a string like "d:\xxx\yyy\something.exe"  This is
 * made available so that applications can edit it to generate names of
 * resource files (eg by just altering the ".exe" bit on the end into some
 * other suffix.
 */
extern char *cwin_full_program_name;

/*
 * programName[] holds just the "something" out of cwin_full_program_name.
 */
extern char programName[64];

/*
 * Something that is SPECIAL and IMPORTANT to this code is that all the
 * code executed via cwin_main() must arrange to call
 *           cwin_poll_window_manager(0);
 * every so often.  If this does not happen the window system will become
 * unresponsive. If you are happy to be suspended (eg waiting for a keystroke)
 * you can give an arg of TRUE, otherwise give FALSE (0).
 */
extern void cwin_poll_window_manager(int waitForEvent);

/*
 * To finish off you can either return from cwin_main(), or you can go
 *        cwin_exit(n);
 * The system will forcibly close down for you if the EXIT item on
 * the FILE menu or the CLOSE item on the SYSTEM menu gets selected.  But
 * direct use of the C function "exit()" is not considered proper.
 */

extern void cwin_exit(int return_code);

/*
 * To be on the safe side I make exit() a macro for cwin_exit(). This is
 * a function that does not exist! It is declared here so that attempts to
 * call it will lead to suitable link-time diagnostics.
 */
#undef exit
#define exit(n) cwin_exit(n)
extern void cwin_exit(int n);

/*
 * If, when the program is stopping, cwin_pause_at_end has been set to
 * be non-zero (by default it will be zero) then an alert box is displayed
 * forcing the user to give positive confirmation before the main window
 * is closed.  This does not give an opportunity to cancel the exit, just to
 * read the final state of the screen...   This effect does not occur if
 * program exit is caused by selecting EXIT from the FILE menu or CLOSE
 * from the system menu. That is (deliberate in my code) because in those
 * cases the user has taken explicit interactive action to terminate the
 * program so an extra prompt seems unnecessary.
 */
extern int cwin_pause_at_end;


/*
 * cwin_minimize() indicates that the window should be shrunk to be just
 * an icon.
 */
extern void cwin_minimize(void);

/*
 * cwin_maximize() indicates that the window should be restored to
 * regular size. I do know that in Windows the term "maximize" would more
 * usually indicate expansion to fill the whole screen, and what I am
 * doing here is a "restore to normal size", but I have chosen not to
 * provide an option that explodes windows to full screen size.
 */
extern void cwin_maximize(void);

/*
 * Rather than using putchar() and printf(), here are the calls
 * the can be made to get output onto the screen.  NOTE that cwin_puts()
 * is more like fputs than puts in that it just dumps the characters in its
 * string to the screen [it does not add an extra newline in the way that
 * puts does].
 * These functions support printable ASCII characters.
 * I have not thought too hard about TAB and FormFeed here... yet.
 * Some control codes may be used to change fonts and colours, but at
 * present I will not document that here.
 */
extern void cwin_putchar(int c);
extern void cwin_puts(const char *s);
extern void 
#ifdef _MSC_VER
            __cdecl
#endif
            cwin_printf(const char *fmt, ...);
extern void cwin_vfprintf(const char *fmt, va_list a);

/*
 * cwin_linelength holds the number of normal-sized (ie the basic
 * fixed-pitch font being used) characters that fit across the screen.
 * Its value can change at any time. When the screen is minimized its value
 * will remain at the pre-minimized value. An attempt is made to create
 * the initial window to make this have the value 80.
 */
extern int cwin_linelength;

#ifdef SOMETIME_LATER_ON
/* Transliteration between Roman and Greek alphabets */
extern char latinOf[26];
#endif /* SOMETIME_LATER_ON */

/*
 * ensure_screen() causes the display to catch up with whatever else has
 * been going on.
 */
extern void cwin_ensure_screen(void);

/*
 * cwin_getchar() behaves rather as one might expect getchar() to - it
 * grabs a character from the keyboard input buffer.
 */
extern int cwin_getchar(void);

/*
 * cwin_getchar_nowait() is just like cwin_getchar() except that if
 * no character is immediately available it returns EOF instead of
 * waiting.
 */
extern int cwin_getchar_nowait(void);

/*
 * If any characters had already been typed and were waiting to be
 * read, this abandons them.
 */
extern void cwin_discard_input(void);

/*
 * cwin_set_prompt() tells cwin what string (of up to 32 characters)
 * should be used as a prompt.
 */
extern void cwin_set_prompt(const char *s);

/*
 * The following is just for use by REDUCE. It adjusts menu entries
 * to support loading packages and setting/clearing REDUCE switches.
 */
extern void cwin_menus(char **modules, char **switches);

/*
 * cwin_interrupt_pending can be set by the "interrupt" menu and is intended
 * to be used to halt calculations in the main program. It gets set to 1
 * on "INTERRUPT" and to 3 on "BACKTRACE".
 */
extern int cwin_interrupt_pending;

/*
 * Short messages can be displayed at the left middle and right of the
 * main title-ribbon of your window.  These functions set the text to be
 * displayed there.  If there is not much room then only the middle one
 * will remain visible.  Each message should be limited to around 30 chars
 * (and will be best if kept shorter than that).  The default position was
 * once that the left position displayed the time & date (but it is
 * now left blank), the middle one the name of the program being run and
 * the right one is blank. cwin_report_left(NULL) or cwin_report_mid(NULL)
 * re-instate the default display. Use cwin_report_left("") is a yet clearer
 * way of indicating that blank info to the left is required.
 */
extern void cwin_report_left(const char *msg);
extern void cwin_report_mid(const char *msg);
extern void cwin_report_right(const char *msg);

/*
 * The following four strings may be updated (but PLEASE keep within the
 * length limit) to make the display in the "ABOUT" box reflect your
 * particular application.
 */
extern char about_box_title[32];       /* "About XXX";           */
extern char about_box_description[32]; /* "XXX version 1.1";     */
                                       /* <icon appears here>    */
extern char about_box_rights_1[32];    /* "Copyright Whoever";   */
extern char about_box_rights_2[32];    /* "Date or whatever";    */

/*
 * The HELP drop-down menu in cwin always has some basic items on it, but
 * the user can add more by calling cwin_setHelpFile() where arg 1 is the
 * text to appear on the menu and arg 2 identifies the help file that will be
 * opened if the menu item is selected. Specifying NULL as the second item
 * removes the key. The information about help keys is kept in the registry
 * not in any file that CSL has direct access to, and the new help items may
 * not be visible until the user exits from CSL and re-starts it.
 */
extern void cwin_set_help_file(const char *key, const char *path);

#ifdef __cplusplus
}
#endif

#endif /* header_cwin_h */

/* end of "cwin.h" */