T_VIEW

Control view through a text window

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
xcall T_VIEW(window_id, [col_id], [help_id][, unmapped_key])

window_id

The ID of the text window to view. (n)

col_id

(optional) The ID of the view-control menu column. (n)

help_id

(optional) The help identifier. (a)

unmapped_key

(optional) Returned with the decimal value of any pressed key not mapped to a function code. (n)

Discussion

T_VIEW enables the user to move the view of a text window using a view-control menu column. It performs the following actions:

On Windows, T_VIEW does not display a scroll bar by default. However, you can enable the scroll bars by calling the W_BRDR windowing subroutine. For more information, see Synergy Windowing API. The text window can also be navigated using arrow keys by setting the g_plc_col_args flag to true. (See g_plc_col_args for information.)

The col_ids are, by default, ignored when running on Windows. These columns usually contain reserved menu entries that are automatically supported by the Windows environment. Additionally, the excessive placing and removing of columns causes a Windows menu bar to “flicker.”

If there’s more than one line in the text window, there will be unusable space at the bottom of the window. The amount of unusable space depends on the number of lines of text and is caused by leading that’s added as a result of the mapping from the native Windows edit control (used under the hood for text windows) to the rows of the Toolkit window used to display the text. This added leading causes the text window to be larger than it needs to be to display the rows, resulting in the unusable space. If the text window is part of a tab set, however, you may be able to work around this by making the text window larger than the tab set. This allows the extra rows to be used by T_VIEW because the tab set container stretches the window’s display area to encompass that size.

On Windows, T_VIEW recognizes the following menu entries: E_CLEAR, E_COPY, E_CUT, E_MARK, E_PASTE. These perform the associated Windows functionality, if applicable. See Appendix B: Reserved Menu Entries for information on reserved menu entries.

On Unix and OpenVMS, T_VIEW assumes that the column identified by col_id will contain one or more of the menu entries for scrolling listed below:

T_LINUP

T_RSIDE

T_TOP

T_LINDWN

T_LSIDE

T_BOTTOM

T_SCRUP

T_PAGUP

T_SCRLFT

T_SCRDWN

T_PAGDWN

T_SCRRT

The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in tkctl.def. See g_plc_col_args for details.

In all environments, if the internal name of a selected menu entry begins with “U_,” the EUTILS_METHOD subroutine is called and the input is redone. If the internal name of the selected menu entry is “O_HELP,” the EHELP_METHOD subroutine is called, with help_id as its argument.

If a selection is made that is neither a T_VIEW entry, a utility entry, a help entry, nor one of the E_ menu entries listed above for Windows, control returns to the calling subroutine with g_select set to true and g_entnam containing the name of the selected entry in uppercase. You must clear g_select after you satisfy the event.

If unmapped_key is passed, when the user presses a key that is not mapped to a function code, the decimal value of the corresponding ASCII character will be returned in this argument. If passed and the user presses Enter, unmapped_key returns zero. Passing unmapped_key may be useful if you want to test for a certain ASCII character and provide alternative processing if the test is true. For example, you could allow the user to press Enter to exit the view function, even though you can’t define the Enter key as a regular shortcut. If you omit unmapped_key, any unmapped key the user presses will ring the terminal bell, but T_VIEW will continue viewing.

Creating the view-control column

Use the menu column script file commands .COLUMN and .ENTRY to create the view-control column and its entries. The following command creates a menu column named “text_view” whose text in the menu bar is “Scrolling.”

.column text_view, Scrolling

To enable scrolling on Unix or OpenVMS, the view-control column must contain some subset of the menu entries listed above. Your script file commands will look something like this:

.entry t_linup, "Up 1 line", key(up)
.entry t_lindwn, "Down 1 line", key(down)

Examples

This code fragment shows the three steps required to view a text window. The window is loaded with U_LDWND and converted to a text window with T_SETUP. Next, a menu column that lists view commands is loaded but not placed on the menu bar. The view column is placed by T_VIEW in this example. T_VIEW only returns when a non-view command is selected.

xcall u_ldwnd(wndid, g_utlib, "intro_text")
xcall t_setup(wndid)
xcall m_ldcol(vcolid, g_utlib, "view_ctl", D_NOPLC)
do
  begin
    xcall t_view(wndid, vcolid)
    if(g_select)
     case(g_entnam) of
      begincase
"ENTRY1": call ENTRYONE    one of these subroutines will 
"ENTRY2": call ENTRYTWO    set the done flag
"ENTRY3": call ENTRYTHREE
      endcase
  end
until(done)