Programming Guide

Opens a window at a given position

int sm_d_window(char *address, int start_line, int start_column);

int sm_l_window(int lib_desc, char *name, int start_line, int start_column);

int sm_r_window(char *name, int start_line, int start_column);

address

The address of the screen in memory

lib_desc

Specifies the library in which the window is stored, where lib_desc is an integer library descriptor returned by sm_l_open. You must call sm_l_open before you read any screens from a library.

name

The name of the window.

start_line, start_column

Specifies the window's top left corner, where start_line and start_column are zero-based offsets from the physical display's top left corner. Thus, setting start_line to 1 starts the window at the screen's second line. If the window does not fit on the display at the specified location, Panther adjusts it as needed.

A negative value for start_line specifies to clear the current screen before displaying the window. The screen's contents are discarded and cannot be restored.

sm_d_window is C only

• 0 Success.

• -1 Screen file's format is incorrect.

• -2 Screen cannot be found.

• -3 Insufficient memory available to display the screen; the current screen remains displayed.

• -4 Read error occurred after the current screen was cleared and start_line is -1. Consequently, Panther cannot restore the screen.

• -5 System ran out of memory after the current screen was cleared and start_line is -1. Consequently, Panther cannot restore the screen.

• -6 Library is corrupted.

• -7 The window is larger than the physical display and there are fields that overhang the display.

Use sm_d_window, sm_l_window, or sm_r_window to display a screen as a stacked window at the specified line and column.:

• On GUI platforms such as Windows, the window is positioned relative to the GUI display. For example, in Windows, the screen is positioned in the middle of the display; on Motif, it is positioned relative to the base window's status line.

• In character mode, the window is positioned relative to the cursor position on the invoking screen, offset by one line to avoid hiding the line's current display.

The area of the display that surrounds the window remains visible. However, only the opened window is active, and only its fields are accessible to input and library functions. To change the active window, use sm_wselect.

To display a form use sm_r_form or one of its variants. Use sm_close_window to close the window.

When you use sm_r_window, Panther looks for the named screen in the following places in this order:

1. The application's memory-resident list; if found, sm_d_window is called to display the screen.
2. All open libraries; if found, sm_l_window is called to display the screen.

If the search fails and the supplied file name has no extension, Panther appends the SMFEXTENSION-specified extension to the file name and repeats the search. If all searches fail, sm_r_window displays an error message and returns.

You can save processing time by using sm_d_window to display screens that are memory-resident. Use bin2c to convert screens from disk files to program data structures that you can compile into your application.

A memory-resident screen never changes at runtime and therefore can be made sharable on systems let you share read-only data. sm_r_window can also display memory-resident screens if they are properly installed with sm_formlist. Memory-resident screens are especially useful in applications with a limited number of screens, or in environments with a slow disk.

You can also save processing time with sm_l_window to display screens from a library. A library is a single file that stores screens, JPL modules, and menus. You can assemble a library from individual screen files with formlib. Libraries let you distribute a large number of screens with an application, and can improve efficiency by reducing the number of search paths.

/* Bring up a window from a library. */
	 int ld;

	if ((ld = sm_l_open("myforms")) < 0)
	   sm_cancel();
	...
	sm_l_window(ld, "popup", 5, 22);
	...
	sm_l_close(ld);

sm_*at_cur, sm_close_window, sm_*form, sm_jwindow

---

---