83 lines
4.4 KiB
Plaintext
83 lines
4.4 KiB
Plaintext
Many people have admired the paged question selection facility in the
|
|
OpenDoors 5.00 EZVote example door. EZVote allows the user to choose
|
|
questions from a list of up to 200 questions, by displaying one page
|
|
of questions at a time. The user is able to page up or down in the list
|
|
of quesitons, select a question from the list, or return to the main
|
|
menu. A prompt at the bottom of the screen shows the current page
|
|
number, and a list of options that are currently available. For
|
|
instance, when displaying the first of two pages, this prompt indicates
|
|
that the user can move to the next page, but not the previous page.
|
|
|
|
This OpenDoors Tip shows a generic function that provides the same sorts
|
|
of capabilities that are seen in the EZVote example door, in a form that
|
|
can be re-used in many different programs. This function, named
|
|
PagedViewer(), can be used for displaying multi-paged messages, text
|
|
files, or for permitting selection from a potentially very long list of
|
|
items. To use the PagedViewer() in a program, you should add the
|
|
pageview.c file to your project file / makefile, and #include the
|
|
pageview.h file in any source file that calls PagedViewer().
|
|
|
|
The prototype for the PagedViewer() function is as follows:
|
|
|
|
int PagedViewer(
|
|
int nInitialLine,
|
|
int nTotalLines,
|
|
void (*pDisplayCallback)(int nLine, void *pCallbackData),
|
|
void *pCallbackData,
|
|
BOOL bAllowSelection,
|
|
char *pszTitle,
|
|
int nPageSize);
|
|
|
|
The nInitialLine parameter specifies the line to begin viewing at.
|
|
Normally this would be 0, but you may wish to pass a different value to
|
|
this function to force the viewer to begin on a page other than the
|
|
first. Using this parameter, you can have the user return to
|
|
the page they were previously viewing, rather than returning to the
|
|
first page and having to again find their original location.
|
|
|
|
The nTotalLines parameter specifies the total number of lines that can
|
|
be viewed, and can be any value greater than or equal to 0.
|
|
|
|
The pDisplayCallback parameter must be a pointer to a function that the
|
|
PagedViewer will call to display a particular line of the file at the
|
|
current location. When PagedViewer() calls your function, it will pass
|
|
the line number to be displayed, along with the value originally passed
|
|
to PagedViewer() in pCallbackData. The provided function should simply
|
|
display the text for the specified line number, without a trailing CR/LF
|
|
sequence, and then return.
|
|
|
|
The pCallbackData can point to any data that you wish PagedViewer() to
|
|
pass to your callback function, or may be NULL if you do not wish to use
|
|
this feature.
|
|
|
|
The bAllowSelection parameter should be TRUE if the user should be able
|
|
to make a selection from the list, and FALSE if they should not. If
|
|
bAllowSelection is TRUE, PagedViewer() will display a letter beside each
|
|
line, and allow the user to select a line by pressing the corresponding
|
|
letter. If you are using PagedViewer() to display a text file or
|
|
message, you will want to set bAllowSelection to FALSE. If you are using
|
|
PagedViewer() to display a list of items from which the user can select,
|
|
you will want to set bAllowSelection to TRUE.
|
|
|
|
The pszTitle parameter can point to a title to be displayed at the top
|
|
of each page, and could be something like ("Select a message"). If you
|
|
do not wish to have a title displayed, set this parameter to NULL.
|
|
|
|
The nPageSize parameter specifies the number of lines that should be
|
|
displayed on each page. If you do not wish to have the local screen
|
|
(with a two line status line) to be scrolled while displaying the list,
|
|
the maximum page size you should use is 21 if no title is being
|
|
displayed, and 19 if a title is being displayed.
|
|
|
|
The included fileview.c text file viewing program demonstrates the use
|
|
of PagedViewer(). The fileview.c door can be setup to allow the user to
|
|
view one or more files. If setup to view multiple files, the program
|
|
first displays a list of files that the user can select to view.
|
|
The fileview.c program uses PagedViewer() in two places - for providing
|
|
the list of files and for displaying the file itself. As such, the user
|
|
can page up or down in the list of files, select a file to view, and
|
|
then page up or down in the file. When the user selects quit while
|
|
viewing the file, they are returned to the list of files to possibly
|
|
select another file. When the user selects quit from the list of files,
|
|
the door returns control to the calling BBS software.
|