CursesAPI Documentation

Package Documentation
Release Notes

Package Documentation

There is currently no package-specific documentation for CursesAPI. The Unix curses library is well-documented, and there are a number of books available on the subject.

CursesAPI v2.2 - Release Notes

Directories

CursesAPI installs into the following directories:

`ingen/cursesAPI/`	The base directory for CursesAPI.
`ingen/cursesAPI/curses`	CursesAPI headers and dynamic loader source.
`ingen/cursesAPI/docs`	Documentation and release notes.
`ingen/cursesAPI/lib`	Target directory for import libraries.
`ingen/cursesAPI/sample1`	Sample application 1 source.
`ingen/cursesAPI/sample2`	Sample application 2 source.
`ingen/cursesAPI/sample3`	Sample application 3 source.
`ingen/cursesAPI/utility`	Utility library and headers used by Sample3.
`ingen/cursesAPI/GSWTNET`	Georgia Softworks' evaluation telnet server.

Unimplemented Functions

The following functions have been implemented as "dummy" functions. They are included to allow applications that use them to successfully link, but they are essentially no-ops.



int delay_output(int ms);
void filter(void);
void garbagedlines(WINDOW* win, int begy, int numlines);
void idlok(WINDOW* win, bool bf);
SCREEN* newterm(char* nterm, FILE* outfp, FILE* infp);
SCREEN* set_term(SCREEN* new);
void restartterm(char* term, int fildes, int* errret);
int scr_dump(char* filename);
int scr_restore(char* filename);
int scr_init(char* filename);
TERMINAL* set_curterm(TERMINAL* nterm);
int setupterm(char* term, int fildes, int* errret);
void traceon(void);
void traceoff(void);
int typeahead(int fildes);

The handling of interaction between stdio rotuines and CursesAPI has been fixed. Before calling any stdio routine that results in output/input to/from the console (i.e. printf(), gets(), etc.), you should call endwin(). This restores the "cooked" processing mode of the console. Upon the next refresh of CursesAPI ( via wgetch(), doupdate(), wrefresh(), etc.), the CursesAPI modes will be restored and the screen automatically redrawn.

Linking Options

CursesAPI is now distributed in DLL format to allow for the greatest variety of development environments. There are two types of dynamic linking: importing and dynamic loading.

Link Loading
Link loading is done by linking to an import library that references the DLL.

To use this method of linking, you must:
- Use a linker that can read Microsoft Visual C++ 5.0 import libraries.
- Link with lib/curses_api.lib or lib/curses_apid.lib.
The included cursesAPI.mdp Visual C++ project and cursesAPI.mak Visual C++ makefile demonstrate this type of linkage for the sample applications.

Run-time Loading
Run-time loading is performed by never actually linking with the CursesAPI library. Instead, the DLL is loaded at run-time, and the CursesAPI functions are mapped through a function table. You must use this method if your linker cannot read MS Visual C++ 5.0 import libraries.

To use this method, you must:
- Define the macro __CURSES_DYNLOAD as a compile option.
- Compile and link with curses/curses_loader.c. This code module contains the routines that dynamically load the CursesAPI DLL upon the call to initscr().
Since this method defines all CursesAPI functions as macros for their function table entries, you will get compile errors if you use names ( function, variable or members ) that conflict with CursesAPI function names. We have provided a GNU compatible Makefile, Makefile.GNU, that demonstrates building an application with this method under the GNU-win32 compiler.

Remember that curses_api.dll must be in your "path" when you run an application that uses the library!

User-Defined Input Processing

CursesAPI makes it easy to define your own key mappings.

BOOL capi_setUsrKeyMapFxn( BOOL (*fxn) (WINDOW* wScr,KEY_EVENT_RECORD* pKr,int* pVal));

Call capi_setUsrKeyMapFxn() to install your own input pre-processing function. Your function should match the signature specified in the prototype, and will receive all Win32 keystroke events before any processing is performed on the events by CursesAPI.

wScr is the WINDOW* that wgetch() was called on.
pKr is a pointer to the Win32 keystroke event.
pVal is a pointer to the integer value that will be returned by wgetch()

Your function should return TRUE if has mapped the event, and CursesAPI should not do any further mapping on the event. Return FALSE to have CursesAPI map the event to a curses keystroke.

Pass NULL as the fxn argument to capi_setUsrKeyMapFxn() to uninstall your keystroke mapping routine.

Implementation Issues

Only Windows95 and WindowsNT targets are supported by CursesAPI. Win32s, the 32-bit subsystem used by 16-bit Windows 3.x, does not support the routines used by CursesAPI.
Only the x86 version of NT is released in binary format. RISC customers must purchase a source-code license to compile CursesAPI on their platform (Verified compatible with Alpha). Please email requests for other platforms to ingen@ingensoft.com.
CursesAPI implements curses in console-mode. This is fully Win32 code and implementation; it should not be confused with a DOS application. A future version of CursesAPI will allow your application to appear in a non-console-mode window.
CursesAPI maps window control events to signals.

Shutdown, logoff, and window close events are mapped to SIGTERM.
CTRL-Break is mapped to SIGINT.

CTRL-C and DELETE do not generate signals. CTRL-Break is the interrupt key.
ttyname() will return a name of the form /dev/ttypxxx. The number is assigned on a per-console basis, so applications running in separate consoles will have different pseudo-tty numbers. If you are using the Georgia Softworks telnet server, ttyname() returns the name assigned by the telnet server. If you have a program that needs to read the variable name, outside of using ttyname(), you can read the name from the environment variable INGEN_CAPI_TTY.
Mouse input is currently turned off. Mouse support will be offered in a future version of CursesAPI.

[Welcome] [What's New] [Product Info] [Ingen WWW Partners] [Write us!]

Send questions/comments to ingenweb@ingensoft.com