Pop-up Window Subroutines

view_buffer(char *buf, int last)   /* complete.e */

view_buf(int buf, int last)      /* complete.e */

Several commands in Epsilon display information using the view_buffer( ) subroutine. It takes the name of a buffer and displays it page by page in a pop-up window. The view_buf( ) subroutine takes a buffer number and does the same. Both take a parameter last which says whether the command is displaying the buffer as its last action.

If last is nonzero, Epsilon will create the window and then return. Epsilon's main command loop will take care of displaying the pop-up window, scrolling through it, and removing it when the user's done examining it. If the user executes a command like find-file while the pop-up window is still on the screen, Epsilon will remove the pop-up and continue with the command.

If last is zero, the viewing subroutine will not return until the user has removed the pop-up window (by pressing <Space> or Ctrl-g, for example). The command can then continue with its processing. The user won't be able to execute a prompting command like find-file while the pop-up window is still on the screen.

view_linked_buf(int buf, int last, int (*linker)()) int linker(char *link) /* linker function prototype */
Epsilon uses a variation of view_buf( ) to display some online help. The variation adds support for simple hyperlinks. The user can select one of the links in a page of displayed text and follow it to go to another page, or potentially to perform any other action. The view_linked_buf( ) subroutine shows a buffer with links.

The links are delimited with a Ctrl-a character before and a Ctrl-b character after each link. Epsilon's non-Windows documentation file edoc is in this format. (See Help Subroutines.) The view_linked_buf( ) subroutine will modify the buffer it receives, removing and highlighting the links before displaying it.

When the user follows a link, Epsilon will call the function pointer linker passed as a parameter to view_linked_buf( ). The linker function, which may have any name, will receive the link text as a parameter.

/* space at sides of viewed popup */ short _view_left = 2; short _view_top = 2; short _view_right = 2; short _view_bottom = 6; short _view_border = ALL_BORD(BSINGLE); char *_view_title; /* title for viewed popup */ int view_loop(int win)
By default, the above subroutines create a pop-up window with no title and a single-line border, almost filling the screen. The window begins two columns from the left border and stops two columns from the right, and extends two lines from the top of the screen to six lines from the bottom. You can alter any of these values by setting the variables _view_title, _view_border, _view_left, _view_top, _view_right, and _view_bottom. Preserve the original default value using the save_var keyword. For example, this code fragment shows a buffer in a narrow window near the right edge of the screen labeled "Results" (surrounding a title with spaces often makes it more attractive):

save_var _view_left = 40; save_var _view_title = " Results "; save_var _view_border = ALL_BORD(BDOUBLE); view_buffer(buf, 1);
A command that displays a pop-up window may want more control over the creation and destruction of the pop-up window than view_buf( ) and similar subroutines provide. A command can instead create its pop-up window itself, and call view_loop( ) to handle user interaction. The view_loop( ) subroutine takes the handle of the pop-up window to work with. The pop-up window may be a part of a dialog. (See the display_dialog_box( ) primitive described in Windowed Dialogs.)

The view_loop( ) subroutine lets the user scroll around in the window and watches for an unrecognized key (an alphabetic key, for example) or a key that has a special meaning. It returns when the user presses one of these keys or when the user says to exit. By default, the user can scroll off either end of the buffer and this subroutine will return. Set the paging-retains-view variable nonzero to prevent this. The view_loop( ) subroutine returns an INP_ code from eel.h to indicate which user action made it exit. See that file for more information. The function that called view_loop( ) may choose to call view_loop( ) again, or to destroy the pop-up window and continue.

error_if_input(int abort) /* complete.e */ remove_final_view() /* complete.e */
If the user is entering a response to some prompt and gives another command that also requires a response, Epsilon aborts the command to prevent confusion. Such commands should call error_if_input( ), which will abort if necessary. The subroutine also removes a viewed buffer, as described above, by calling remove_final_view( ) if necessary. If its abort parameter is nonzero, it will attempt to abort the outer command as well, if aborting proves necessary.

Previous Up Next
Pop-up Windows Primitives and EEL Subroutines Window Attributes