pager.c File Reference

Console/terminal paging functionality. More...

#include <windef.h>
#include <winbase.h>
#include <wincon.h>
#include <winnls.h>
#include <strsafe.h>
#include "conutils.h"
#include "stream.h"
#include "screen.h"
#include "pager.h"

Include dependency graph for pager.c:

Go to the source code of this file.

Macros
#define	UNICODE
#define	_UNICODE
#define	CON_STREAM_WRITE   ConStreamWrite
#define	CP_SHIFTJIS   932
#define	CP_HANGUL   949
#define	CP_JOHAB   1361
#define	CP_GB2312   936
#define	CP_BIG5   950
#define	IsCJKCodePage(CodePage)

Functions
static INT	GetWidthOfCharCJK (IN UINT nCodePage, IN WCHAR ch)
static BOOL	GetNextLine (IN OUT PCON_PAGER Pager, IN PCTCH TextBuff, IN SIZE_T cch)
	Retrieves a new text line, or continue fetching the current one.
static BOOL	ConPagerWorker (IN PCON_PAGER Pager, IN PCTCH TextBuff, IN DWORD cch)
	Does the main paging work: fetching text lines and displaying them.
ConWritePaging
Pages the contents of a user-specified character buffer on the screen. Parameters [in] Pager Pager object that describes where the paged output is issued. [in] PagePrompt A user-specific callback, called when a page has been displayed. [in] StartPaging Set to TRUE for initializing the paging operation; FALSE during paging. [in] szStr Pointer to the character buffer whose contents are to be paged. [in] len Length of the character buffer pointed by szStr, specified in number of characters. Returns TRUE when all the contents of the character buffer has been displayed; FALSE if the paging operation has been stopped (controlled via PagePrompt).
BOOL	ConWritePaging (IN PCON_PAGER Pager, IN PAGE_PROMPT PagePrompt, IN BOOL StartPaging, IN PCTCH szStr, IN DWORD len)
BOOL	ConPutsPaging (IN PCON_PAGER Pager, IN PAGE_PROMPT PagePrompt, IN BOOL StartPaging, IN PCTSTR szStr)
BOOL	ConResPagingEx (IN PCON_PAGER Pager, IN PAGE_PROMPT PagePrompt, IN BOOL StartPaging, IN HINSTANCE hInstance OPTIONAL, IN UINT uID)
BOOL	ConResPaging (IN PCON_PAGER Pager, IN PAGE_PROMPT PagePrompt, IN BOOL StartPaging, IN UINT uID)

Detailed Description

Console/terminal paging functionality.

Definition in file pager.c.

Macro Definition Documentation

_UNICODE

#define _UNICODE

Definition at line 18 of file pager.c.

CON_STREAM_WRITE

#define CON_STREAM_WRITE   ConStreamWrite

Definition at line 33 of file pager.c.

CP_BIG5

#define CP_BIG5   950

Definition at line 39 of file pager.c.

CP_GB2312

#define CP_GB2312   936

Definition at line 38 of file pager.c.

CP_HANGUL

#define CP_HANGUL   949

Definition at line 36 of file pager.c.

CP_JOHAB

#define CP_JOHAB   1361

Definition at line 37 of file pager.c.

CP_SHIFTJIS

#define CP_SHIFTJIS   932

Definition at line 35 of file pager.c.

IsCJKCodePage

#define IsCJKCodePage

(

CodePage

)

Value:

    ((CodePage) == CP_SHIFTJIS || (CodePage) == CP_HANGUL || \
  /* (CodePage) == CP_JOHAB || */ \
     (CodePage) == CP_BIG5     || (CodePage) == CP_GB2312)

Definition at line 42 of file pager.c.

UNICODE

#define UNICODE

Definition at line 17 of file pager.c.

Function Documentation

ConPagerWorker()

static BOOL ConPagerWorker ( IN PCON_PAGER  Pager, IN PCTCH  TextBuff, IN DWORD  cch  )

static

Does the main paging work: fetching text lines and displaying them.

Definition at line 219 of file pager.c.

{
    const DWORD PageColumns = Pager->PageColumns;
    const DWORD ScrollRows = Pager->ScrollRows;
 
    BOOL bFinitePaging = ((PageColumns > 0) && (Pager->PageRows > 0));
    LONG nTabWidth = Pager->nTabWidth;
 
    PCTCH Line;
    SIZE_T ich;
    SIZE_T ichStart;
    SIZE_T iEndLine;
    DWORD iColumn = Pager->iColumn;
 
    UINT nCodePage = GetConsoleOutputCP();
    BOOL IsCJK = IsCJKCodePage(nCodePage);
    UINT nWidthOfChar = 1;
    BOOL IsDoubleWidthCharTrailing = FALSE;
 
    /* Normalize the tab width: if negative or too large,
     * cap it to the number of columns. */
    if (PageColumns > 0) // if (bFinitePaging)
    {
        if (nTabWidth < 0)
            nTabWidth = PageColumns - 1;
        else
            nTabWidth = min(nTabWidth, PageColumns - 1);
    }
    else
    {
        /* If no column width is known, default to 8 spaces if the
         * original value is negative; otherwise keep the current one. */
        if (nTabWidth < 0)
            nTabWidth = 8;
    }
 
 
    /* Continue displaying the previous line, if any, or start a new one */
    Line = Pager->CurrentLine;
    ichStart = Pager->ichCurr;
    iEndLine = Pager->iEndLine;
 
ProcessLine:
 
    /* Stop now if we have displayed more page lines than requested */
    if (bFinitePaging && (Pager->iLine >= ScrollRows))
        goto End;
 
    if (!Line || (ichStart >= iEndLine))
    {
        /* Start a new line */
        if (!GetNextLine(Pager, TextBuff, cch))
            goto End;
 
        Line = Pager->CurrentLine;
        ichStart = Pager->ichCurr;
        iEndLine = Pager->iEndLine;
    }
    else
    {
        /* Continue displaying the current line */
    }
 
    // ASSERT(Line && ((ichStart < iEndLine) || (ichStart == iEndLine && iEndLine == 0)));
 
    /* Determine whether this line segment (from the current position till the end) should be displayed */
    Pager->iColumn = iColumn;
    if (Pager->PagerLine && Pager->PagerLine(Pager, &Line[ichStart], iEndLine - ichStart))
    {
        iColumn = Pager->iColumn;
 
        /* Done with this line; start a new one */
        Pager->nSpacePending = 0; // And reset any pending space.
        ichStart = iEndLine;
        goto ProcessLine;
    }
    // else: Continue displaying the line.
 
 
    /* Print out any pending TAB expansion */
    if (Pager->nSpacePending > 0)
    {
ExpandTab:
        while (Pager->nSpacePending > 0)
        {
            /* Print filling spaces */
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT(" "), 1);
            --(Pager->nSpacePending);
            ++iColumn;
 
            /* Check whether we are going across the column */
            if ((PageColumns > 0) && (iColumn % PageColumns == 0))
            {
                // Pager->nSpacePending = 0; // <-- This is the mode of most text editors...
 
                /* Reposition the cursor to the next line, first column */
                if (!bFinitePaging || (PageColumns < Pager->Screen->csbi.dwSize.X))
                    CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);
 
                Pager->iLine++;
 
                /* Restart at the character */
                // ASSERT(ichStart == ich);
                goto ProcessLine;
            }
        }
    }
 
 
    /* Find, within this line segment (starting from its
     * beginning), until where we can print to the page. */
    for (ich = ichStart; ich < iEndLine; ++ich)
    {
        /* NEWLINE character */
        if (Line[ich] == TEXT('\n'))
        {
            /* We should stop now */
            // ASSERT(ich == iEndLine - 1);
            break;
        }
 
        /* TAB character */
        if (Line[ich] == TEXT('\t') &&
            (Pager->dwFlags & CON_PAGER_EXPAND_TABS))
        {
            /* We should stop now */
            break;
        }
 
        /* FORM-FEED character */
        if (Line[ich] == TEXT('\f') &&
            (Pager->dwFlags & CON_PAGER_EXPAND_FF))
        {
            /* We should stop now */
            break;
        }
 
        /* Other character - Handle double-width for CJK */
 
        if (IsCJK)
            nWidthOfChar = GetWidthOfCharCJK(nCodePage, Line[ich]);
 
        /* Care about CJK character presentation only when outputting
         * to a device where the number of columns is known. */
        if ((PageColumns > 0) && IsCJK)
        {
            IsDoubleWidthCharTrailing = (nWidthOfChar == 2) &&
                                        ((iColumn + 1) % PageColumns == 0);
            if (IsDoubleWidthCharTrailing)
            {
                /* Reserve this character for the next line */
                ++iColumn; // Count a blank instead.
                /* We should stop now */
                break;
            }
        }
 
        iColumn += nWidthOfChar;
 
        /* Check whether we are going across the column */
        if ((PageColumns > 0) && (iColumn % PageColumns == 0))
        {
            ++ich;
            break;
        }
    }
 
    /* Output the pending line segment */
    if (ich - ichStart > 0)
        CON_STREAM_WRITE(Pager->Screen->Stream, &Line[ichStart], ich - ichStart);
 
    /* Have we finished the line segment? */
    if (ich >= iEndLine)
    {
        /* Restart at the character */
        ichStart = ich;
        goto ProcessLine;
    }
 
    /* Handle special characters */
 
    /* NEWLINE character */
    if (Line[ich] == TEXT('\n'))
    {
        // ASSERT(ich == iEndLine - 1);
 
        /* Reposition the cursor to the next line, first column */
        CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);
 
        Pager->iLine++;
        iColumn = 0;
 
        /* Done with this line; start a new one */
        Pager->nSpacePending = 0; // And reset any pending space.
        ichStart = iEndLine;
        goto ProcessLine;
    }
 
    /* TAB character */
    if (Line[ich] == TEXT('\t') &&
        (Pager->dwFlags & CON_PAGER_EXPAND_TABS))
    {
        /* Perform TAB expansion, unless the tab width is zero */
        if (nTabWidth == 0)
        {
            ichStart = ++ich;
            goto ProcessLine;
        }
 
        ichStart = ++ich;
        /* Reset the number of spaces needed to develop this TAB character */
        Pager->nSpacePending = nTabWidth - (iColumn % nTabWidth);
        goto ExpandTab;
    }
 
    /* FORM-FEED character */
    if (Line[ich] == TEXT('\f') &&
        (Pager->dwFlags & CON_PAGER_EXPAND_FF))
    {
        if (bFinitePaging)
        {
            /* Clear until the end of the page */
            while (Pager->iLine < ScrollRows)
            {
                /* Call the user paging function in order to know
                 * whether we need to output the blank lines. */
                Pager->iColumn = iColumn;
                if (Pager->PagerLine && Pager->PagerLine(Pager, TEXT("\n"), 1))
                {
                    /* Only one blank line displayed, that counts in the line count */
                    Pager->iLine++;
                    break;
                }
                else
                {
                    CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);
                    Pager->iLine++;
                }
            }
        }
        else
        {
            /* Just output a FORM-FEED and a NEWLINE */
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\f\n"), 2);
            Pager->iLine++;
        }
 
        iColumn = 0;
        Pager->nSpacePending = 0; // And reset any pending space.
 
        /* Skip and restart past the character */
        ichStart = ++ich;
        goto ProcessLine;
    }
 
    /* If we output a double-width character that goes across the column,
     * fill with blank and display the character on the next line. */
    if (IsDoubleWidthCharTrailing)
    {
        IsDoubleWidthCharTrailing = FALSE; // Reset the flag.
        CON_STREAM_WRITE(Pager->Screen->Stream, TEXT(" "), 1);
        /* Fall back below */
    }
 
    /* Are we wrapping the line? */
    if ((PageColumns > 0) && (iColumn % PageColumns == 0))
    {
        /* Reposition the cursor to the next line, first column */
        if (!bFinitePaging || (PageColumns < Pager->Screen->csbi.dwSize.X))
            CON_STREAM_WRITE(Pager->Screen->Stream, TEXT("\n"), 1);
 
        Pager->iLine++;
    }
 
    /* Restart at the character */
    ichStart = ich;
    goto ProcessLine;
 
 
End:
    /*
     * We are exiting, either because we displayed all the required lines
     * (iLine >= ScrollRows), or, because we don't have more data to display.
     */
 
    Pager->ichCurr = ichStart;
    Pager->iColumn = iColumn;
    // INVESTIGATE: Can we get rid of CurrentLine here? // if (ichStart >= iEndLine) ...
 
    /* Return TRUE if we displayed all the required lines; FALSE otherwise */
    if (bFinitePaging && (Pager->iLine >= ScrollRows))
    {
        Pager->iLine = 0; /* Reset the count of lines being printed */
        return TRUE;
    }
    else
    {
        return FALSE;
    }
}

Referenced by ConWritePaging().

ConPutsPaging()

BOOL ConPutsPaging	(	IN PCON_PAGER	Pager,
		IN PAGE_PROMPT	PagePrompt,
		IN BOOL	StartPaging,
		IN PCTSTR	szStr
	)

Definition at line 646 of file pager.c.

{
    DWORD len;
 
    /* Return if no string has been given */
    if (szStr == NULL)
        return TRUE;
 
    len = wcslen(szStr);
    return ConWritePaging(Pager, PagePrompt, StartPaging, szStr, len);
}

ConResPaging()

BOOL ConResPaging	(	IN PCON_PAGER	Pager,
		IN PAGE_PROMPT	PagePrompt,
		IN BOOL	StartPaging,
		IN UINT	uID
	)

Definition at line 681 of file pager.c.

{
    return ConResPagingEx(Pager, PagePrompt, StartPaging,
                          NULL /*GetModuleHandleW(NULL)*/, uID);
}

Referenced by ConOutResPaging().

ConResPagingEx()

BOOL ConResPagingEx	(	IN PCON_PAGER	Pager,
		IN PAGE_PROMPT	PagePrompt,
		IN BOOL	StartPaging,
		IN HINSTANCE hInstance	OPTIONAL,
		IN UINT	uID
	)

Definition at line 663 of file pager.c.

{
    INT Len;
    PCWSTR szStr = NULL;
 
    Len = K32LoadStringW(hInstance, uID, (PWSTR)&szStr, 0);
    if (szStr && Len)
        return ConWritePaging(Pager, PagePrompt, StartPaging, szStr, Len);
    else
        return TRUE;
}

Referenced by ConResPaging().

ConWritePaging()

BOOL ConWritePaging	(	IN PCON_PAGER	Pager,
		IN PAGE_PROMPT	PagePrompt,
		IN BOOL	StartPaging,
		IN PCTCH	szStr,
		IN DWORD	len
	)

Definition at line 549 of file pager.c.

{
    CONSOLE_SCREEN_BUFFER_INFO csbi;
    BOOL bIsConsole;
 
    /* Parameters validation */
    if (!Pager)
        return FALSE;
 
    /* Get the size of the visual screen that can be printed to */
    bIsConsole = ConGetScreenInfo(Pager->Screen, &csbi);
    if (bIsConsole)
    {
        /* Calculate the console screen extent */
        Pager->PageColumns = csbi.dwSize.X;
        Pager->PageRows = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
    }
    else
    {
        /* We assume it's a file handle */
        Pager->PageColumns = 0;
        Pager->PageRows = 0;
    }
 
    if (StartPaging)
    {
        if (bIsConsole && (Pager->PageRows >= 2))
        {
            /* Reset to display one page by default */
            Pager->ScrollRows = Pager->PageRows - 1;
        }
        else
        {
            /* File output, or single line: all lines are displayed at once; reset to a default value */
            Pager->ScrollRows = 0;
        }
 
        /* Reset the internal data buffer */
        Pager->CachedLine = NULL;
        Pager->cchCachedLine = 0;
 
        /* Reset the paging state */
        Pager->CurrentLine = NULL;
        Pager->ichCurr = 0;
        Pager->iEndLine = 0;
        Pager->nSpacePending = 0;
        Pager->iColumn = 0;
        Pager->iLine = 0;
        Pager->lineno = 0;
    }
 
    /* Reset the reading index in the user-provided source buffer */
    Pager->ich = 0;
 
    /* Run the pager even when the user-provided source buffer is
     * empty, in case we need to flush any remaining cached line. */
    if (!Pager->CachedLine)
    {
        /* No cached line, bail out now */
        if (len == 0 || szStr == NULL)
            return TRUE;
    }
 
    while (ConPagerWorker(Pager, szStr, len))
    {
        /* Prompt the user only when we display to a console and the screen
         * is not too small: at least one line for the actual paged text and
         * one line for the prompt. */
        if (bIsConsole && (Pager->PageRows >= 2))
        {
            /* Reset to display one page by default */
            Pager->ScrollRows = Pager->PageRows - 1;
 
            /* Prompt the user; give him some values for statistics */
            // FIXME: Doesn't reflect what's currently being displayed.
            if (!PagePrompt(Pager, Pager->ich, len))
                return FALSE;
        }
 
        /* If we display to a console, recalculate its screen extent
         * in case the user has redimensioned it during the prompt. */
        if (bIsConsole && ConGetScreenInfo(Pager->Screen, &csbi))
        {
            Pager->PageColumns = csbi.dwSize.X;
            Pager->PageRows = csbi.srWindow.Bottom - csbi.srWindow.Top + 1;
        }
    }
 
    return TRUE;
}

Referenced by ConPrintfVPaging(), ConPutsPaging(), ConResPagingEx(), and wmain().

GetNextLine()

static BOOL GetNextLine ( IN OUT PCON_PAGER  Pager, IN PCTCH  TextBuff, IN SIZE_T  cch  )

static

Retrieves a new text line, or continue fetching the current one.

Remarks

Manages setting Pager's CurrentLine, ichCurr, iEndLine, and the line cache (CachedLine, cchCachedLine). Other functions must not modify these values.

Definition at line 68 of file pager.c.

{
    SIZE_T ich = Pager->ich;
    SIZE_T ichStart;
    SIZE_T cchLine;
    BOOL bCacheLine;
 
    Pager->ichCurr = 0;
    Pager->iEndLine = 0;
 
    /*
     * If we already had an existing line, then we can safely start a new one
     * and getting rid of any current cached line. Otherwise, we don't have
     * a current line and we may be caching a new one, in which case, continue
     * caching it until it becomes complete.
     */
    // INVESTIGATE: Do that only if (ichStart >= iEndLine) ??
    if (Pager->CurrentLine)
    {
        // ASSERT(Pager->CurrentLine == Pager->CachedLine);
        if (Pager->CachedLine)
        {
            HeapFree(GetProcessHeap(), 0, (PVOID)Pager->CachedLine);
            Pager->CachedLine = NULL;
            Pager->cchCachedLine = 0;
        }
 
        Pager->CurrentLine = NULL;
    }
 
    /* Nothing else to read if we are past the end of the buffer */
    if (ich >= cch)
    {
        /* If we have a pending cached line, terminate it now */
        if (Pager->CachedLine)
            goto TerminateLine;
 
        /* Otherwise, bail out */
        return FALSE;
    }
 
    /* Start a new line, or continue an existing one */
    ichStart = ich;
 
    /* Find where this line ends, looking for a NEWLINE character.
     * (NOTE: We cannot use strchr because the buffer is not NULL-terminated) */
    for (; ich < cch; ++ich)
    {
        if (TextBuff[ich] == TEXT('\n'))
        {
            ++ich;
            break;
        }
    }
    Pager->ich = ich;
 
    cchLine = (ich - ichStart);
 
    //
    // FIXME: Impose a maximum string limit when the line is cached, in order
    // not to potentially grow memory indefinitely. When the limit is reached,
    // terminate the line.
    //
 
    /*
     * If we have stopped because we have exhausted the text buffer
     * and we have not found an end-of-line character, this may mean
     * that the text line spans across different text buffers. If we
     * have been told so, cache this line: we will complete it during
     * the next call(s) and only then, display it.
     * Otherwise, consider the line to be terminated now.
     */
    bCacheLine = ((Pager->dwFlags & CON_PAGER_CACHE_INCOMPLETE_LINE) &&
                  (ich >= cch) && (TextBuff[ich - 1] != TEXT('\n')));
 
    /* Allocate, or re-allocate, the cached line buffer */
    if (bCacheLine && !Pager->CachedLine)
    {
        /* We start caching, allocate the cached line buffer */
        Pager->CachedLine = HeapAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY,
                                      cchLine * sizeof(TCHAR));
        Pager->cchCachedLine = 0;
 
        if (!Pager->CachedLine)
        {
            SetLastError(ERROR_NOT_ENOUGH_MEMORY);
            return FALSE;
        }
    }
    else if (Pager->CachedLine)
    {
        /* We continue caching, re-allocate the cached line buffer */
        PVOID ptr = HeapReAlloc(GetProcessHeap(), HEAP_ZERO_MEMORY,
                                (PVOID)Pager->CachedLine,
                                (Pager->cchCachedLine + cchLine) * sizeof(TCHAR));
        if (!ptr)
        {
            HeapFree(GetProcessHeap(), 0, (PVOID)Pager->CachedLine);
            Pager->CachedLine = NULL;
            Pager->cchCachedLine = 0;
 
            SetLastError(ERROR_NOT_ENOUGH_MEMORY);
            return FALSE;
        }
        Pager->CachedLine = ptr;
    }
    if (Pager->CachedLine)
    {
        /* Copy/append the text to the cached line buffer */
        RtlCopyMemory((PVOID)&Pager->CachedLine[Pager->cchCachedLine],
                      &TextBuff[ichStart],
                      cchLine * sizeof(TCHAR));
        Pager->cchCachedLine += cchLine;
    }
    if (bCacheLine)
    {
        /* The line is currently incomplete, don't proceed further for now */
        return FALSE;
    }
 
TerminateLine:
    /* The line should be complete now. If we have an existing cached line,
     * it has been completed by appending the remaining text to it. */
 
    /* We are starting a new line */
    Pager->ichCurr = 0;
    if (Pager->CachedLine)
    {
        Pager->iEndLine = Pager->cchCachedLine;
        Pager->CurrentLine = Pager->CachedLine;
    }
    else
    {
        Pager->iEndLine = cchLine;
        Pager->CurrentLine = &TextBuff[ichStart];
    }
 
    /* Increase only when we have got a NEWLINE */
    if ((Pager->iEndLine > 0) && (Pager->CurrentLine[Pager->iEndLine - 1] == TEXT('\n')))
        Pager->lineno++;
 
    return TRUE;
}

Referenced by ConPagerWorker().

GetWidthOfCharCJK()

static INT GetWidthOfCharCJK ( IN UINT  nCodePage, IN WCHAR  ch  )

inlinestatic

Definition at line 48 of file pager.c.

{
    INT ret = WideCharToMultiByte(nCodePage, 0, &ch, 1, NULL, 0, NULL, NULL);
    if (ret == 0)
        ret = 1;
    else if (ret > 2)
        ret = 2;
    return ret;
}

Referenced by ConPagerWorker().