HELP.C

/*  help.c - constant help screens
*
*   Author:
*	Benjamin W. Slivka
*	(c) 1987,1988
*	Microsoft Corporation
*
*   History:
*	18-Aug-1987 bws Use keyboard queue for keystrokes
*	08-Oct-1987 bws Signal handling modifications
*	19-Oct-1987 bws Added delay time to command line
*	20-Oct-1987 bws Fix usage display
*	19-Feb-1988 bws Add explanation screens
*	27-Feb-1988 bws Improved SysSem explanation screen
*	01-Sep-1988 bws Rev number for FMT speedup
*/

#include <stddef.h>
#include <malloc.h>
#include <memory.h>
#include <string.h>
#include "asrt.h"   /* assertion checking */
#include "vio.h"
#include "os2.h"
#include "queue.h"
#include "ps.h"
#include "vars.h"

#include "os2def.h"

extern qu_t    *pQu;		/* ptr to keyboard queue */

char *ExplainLibScreen[] = {
    "ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Libraries ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
    "º                                                                    º",
    "º            PID - Process ID of program                             º",
    "º           SGID - Screen Group ID of program                        º",
    "º           Name - Name of program module                            º",
    "º   Library List - Directed, Acyclic Graph of modules imported by    º",
    "º                  the program module.                               º",
    "º                                                                    º",
    "º                  * = indicates a cycle in the graph                º",
    "º                                                                    º",
    "ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_EXPLIB	(sizeof(ExplainLibScreen)/sizeof(char *))

char *ExplainMemScreen[] = {
    "ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Shared Memory ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
    "º                                                                    º",
    "º     owner hndl - Internal ID of shared memory segment              º",
    "º            sel - LDT selector of shared memory segment             º",
    "º            ref - Number of references to shared memory segment     º",
    "º           name - Name of shared memory segment                     º",
    "º                                                                    º",
    "ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_EXPMEM	(sizeof(ExplainMemScreen)/sizeof(char *))

char *ExplainProcScreen[] = {
    "ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Processes and Threads ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
    "º                                                                      º",
    "º      PID - Process ID                   TID - Thread ID              º",
    "º     SGID - Screen Group ID              Pri - Thread priority        º",
    "º     Name - Name of program module                                    º",
    "º     Nest - Parent/child nesting level.  1 is top-level process.      º",
    "º    State - Thread state:                                             º",
    "º                zombie  - Waiting for parent to finish CWAIT          º",
    "º                ready   - Ready for CPU                               º",
    "º                block   - Waiting for I/O completion or a resource    º",
    "º                froze   - Waiting to come foreground (usually 3xBox)  º",
    "º                critsec - Blocked by other thread in DosEnterCritSec  º",
    "º                boost   - Just received I/O boost                     º",
    "º  BlockID - When state is 'block', ID of event being waited upon      º",
    "º                                                                      º",
    "ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_EXPPROC	(sizeof(ExplainProcScreen)/sizeof(char *))

char *ExplainSemScreen[] = {
    "ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ System Semaphores ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
    "º                                                                      º",
    "º    name,PID,TID - Name, PID, and TID of process owning semaphore     º",
    "º    flags/status - waiters      - thread(s) are waiting for sem       º",
    "º                   muxwaiters   - thread(s) are muxwaiting for sem    º",
    "º                   process died - process owning semaphore died       º",
    "º                   exclusive    - exclusive semaphore                 º",
    "º                   cleanup      - semaphore is being cleaned up       º",
    "º                   thread died  - thread owning semaphore died        º",
    "º                   exit owner   - exitlist thread owns semaphore      º",
    "º             ref - Count of processes referencing semaphore           º",
    "º            want - Count of processes waiting for semaphore           º",
    "º            hndl - Internal semaphore handle                          º",
    "º            name - System semaphore name                              º",
    "º                                                                      º",
    "ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_EXPSEM	(sizeof(ExplainSemScreen)/sizeof(char *))


char *helpScreen[] = {
"ÉÍÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÍÍÍÍ͵ Help ÆÍÍÍÍÍÍÍÍÍÍÍÍËÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
"º 01 Sep 1988 º         Process Status         º Version 1.13 º",
"ÌÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÊÍÍÍÍÍÍÍÍÍÍÍÍÍ͹",
"º                                                             º",
"º  Window Scrolling: \x18      - Scroll Window UP                º",
"º                    \x19      - Scroll Window DOWN              º",
"º                    PgUp   - Scroll Window UP one PAGE       º",
"º                    PgDn   - Scroll Window DOWN one PAGE     º",
"º                                                             º",
"º  Menu Selection:   \x1A      - Move Cursor RIGHT               º",
"º                    \x1B      - Move Cursor LEFT                º",
"º                    Enter  - Do cursor item                  º",
"º                    Space  - Do cursor item                  º",
"º                  <letter> - Do item starting with <letter>  º",
"º                                                             º",
"º  Use EXPLAIN to get explanation of screen data.             º",
"º                                                             º",
"º  Use -? flag to see command line flags.                     º",
"º                                                             º",
"ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_HELP	(sizeof(helpScreen)/sizeof(char *))

char *optHelpScreen[] = {
    "ÉÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Options - HELP ÆÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ»",
    "º                                                     º",
    "º  Moving Between Fields:                             º",
    "º      \x18       - UP to previous field                 º",
    "º      \x19       - DOWN to next field                   º",
    "º                                                     º",
    "º  Field WITH cursor:                                 º",
    "º      \x1A       - Move cursor RIGHT                    º",
    "º      \x1B       - Move cursor LEFT                     º",
    "º      Del     - Delete character at cursor           º",
    "º      Home    - Move cursor to LEFT edge of field    º",
    "º      BS      - Delecte character to left of cursor  º",
    "º      <other> - Insert character, if valid           º",
    "º                                                     º",
    "º  Field WITHOUT cursor:                              º",
    "º      \x1A       - Change field to NEXT value           º",
    "º      \x1B       - Change field to PREVIOUS value       º",
    "º                                                     º",
    "ÈÍÍÍÍÍÍÍÍÍÍÍÍÍÍÍ͵ Press Esc to return ÆÍÍÍÍÍÍÍÍÍÍÍÍÍͼ"
};
#define     H_OPTION	(sizeof(optHelpScreen)/sizeof(char *))


typedef struct {
    int     scNScreen;	    /* Number of rows in screen */
    int     scWidth;	    /* Width of screen in columns */
    char  **scScreen;	    /* Screen screen */
} screen_t;

screen_t screen[] = {
    {H_EXPLIB,	    0,	ExplainLibScreen},
    {H_EXPMEM,	    0,	ExplainMemScreen},
    {H_EXPPROC,     0,	ExplainProcScreen},
    {H_EXPSEM,	    0,	ExplainSemScreen},
    {H_HELP,	    0,	helpScreen},
    {H_OPTION,	    0,	optHelpScreen}
};
#define nScreen  (sizeof(screen)/sizeof(screen_t))

#define iExpLib     0	    /* index of library explanation screen */
#define iExpMem     1	    /* index of memory explanation screen */
#define iExpProc    2	    /* index of process explanation screen */
#define iExpSem     3	    /* index of semaphore explanation screen */
#define iHelp	    4	    /* index of main help screen */
#define iOption     5	    /* index of option help screen */


/***	helpInit - initialize help control structures
*
*/
helpInit ()
{
    int i;

    for (i=0; i<nScreen; i++)
	screen[i].scWidth = strlen(screen[i].scScreen[0]);
}


/***	PopUpStart - Prepare for "pop-up"
*
*	We allocate buffer large enough for screen memory, then copy
*	screen memory to buffer.  This allows for the "appearance" of
*	a "pop-up", since we can write to the screen, then later copy
*	this saved image back, thus "bringing down" the "pop-up".  This
*	is not to be confused with VioPopUp.  PopUpEnd does the restore
*	and frees the buffer.
*/
char *PopUpStart ()
{
    unsigned	size;
    char       *buf;

    size = N_of_Rows*N_of_Cols*2;
    if (buf = malloc(size))
	VioReadCellStr ((FPCe)buf, (FPI)&size, 0, 0, VioHandle);
    return buf;
}


/***	PopUpEnd - Restore screen after pop-up
*
*/
PopUpEnd (buf)
char *buf;
{
    int     size;

    size = N_of_Rows*N_of_Cols*2;
    VioWrtCellStr ((FPCe)buf, size, 0, 0, VioHandle);
    free(buf);
}


/***	doPopUp - Do pop-up processing for specified text "window"
*
*	EXIT	FALSE, normal exit
*		TRUE, kill requested
*/
BOOL doPopUp (i)
int i;
{
    int     height,width;
    int     row,col;
    int     hRow,hCol;
    Attr    a;
    char    *buf;
    word    key;
    BOOL    fDie=FALSE;

    if (buf=PopUpStart()) {
	height = screen[i].scNScreen;
	width = screen[i].scWidth;

	hRow = (N_of_Rows - height)/2;
	hCol = (N_of_Cols - width)/2;

	a = color[helpC];
	for (row=0; row<height; row++)
	    VioWrtCharStrAtt ((FPC)screen[i].scScreen[row], width,
			      row+hRow,hCol, (FPAt)&a, VioHandle);
	do {
	    key = (word)QueueRead(pQu);
	    if (key == NULL) {
		key = escKey;	/* Change kill into exit command */
		fDie = TRUE;
	    }
	} while (key != escKey);    /* wait for Esc key */

	PopUpEnd(buf);
    }
    return (fDie);
}


/***	showHelp - pop-up help window
*
*/
void showHelp (i)
int i;
{
    doPopUp(iHelp);
}


/***	showExplain - pop-up an explanation window
*
*/
void showExplain (i)
int i;
{
    doPopUp(i);
}


/***	helpOption - pop-up help window for Option window
*
*	EXIT	FALSE, normal exit
*		TRUE, kill requested
*/
BOOL helpOption (i)
int i;
{
    return ( doPopUp(iOption) );
}