Start a Window (QsnStrWin) API
Required Parameter:
1 | Window handle | Input | Binary(4) |
Omissible Parameter Group:
2 | Save screen | Input | Char(1) |
3 | Error code | I/O | Char(*) |
Returned Value:
Return code | Output | Binary(4) |
Default Public Authority: *USE
Service Program: QSNAPI
Threadsafe: No
The Start a Window (QsnStrWin) API starts a window created with the Create a Window (QsnCrtWin) API. This causes the window to be displayed on the screen and added to the active window list. If specified, the Draw Window exit routine is called immediately before the window is drawn.
Authorities and Locks
None
Required Parameter
- Window handle
- INPUT; BINARY(4)
A handle for the window to be started.
Omissible Parameter Group
- Save screen
- INPUT; CHAR(1)
Indicates if the underlying display image should be saved prior to drawing the window. This option should be used only if the window will not be moved or resized over an existing display image. Performance can be improved by not saving the display image. However, doing this limits the overlapping nature of the window. If an attempt is made to move or resize a window for which the display image was not saved, the screen is cleared and all windows are redrawn prior to moving the window.
The possible values for this parameter are:
0 Do not save the underlying display image when the window is started. 1 Save the underlying display image when the window is started. This is the default.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.
Returned Value
- Return code
- OUTPUT; BINARY(4)
A return code indicating the result of the operation. The value returned will be 0 if the operation was successful, or -1 otherwise.
Error Messages
Message ID | Error Message Text |
---|---|
CPF24B4 E | Severe error while addressing parameter list. |
CPF3CF1 E | Error code parameter not valid. |
CPF3CF2 E | Error(s) occurred during running of &1 API. |
CPFA318 E | Error calling exit routine. |
CPFA31E E | Required parameter &1 omitted. |
CPFA343 E | Output operation not done. |
CPFA344 E | The file &2 in library &3 is not valid. |
CPFA345 E | The invite active flag is not valid. |
CPFA3AA E | Window handle incorrect. |
CPFA3AB E | The value for &1 must be '0' or '1'. |
Performance Considerations
You can improve the performance of window operations by doing the following:
- Do not save or restore the underlying screen image when a window is started or ended with the Start a Window (QsnStrWin) or End a Window (QsnEndWin) API, respectively. See pages Start a Window (QsnStrWin) API and End a Window (QsnEndWin) API.
- For non-GUI windows, use the same color for current and noncurrent boundaries.
- Use a display station attached to a control unit that supports an enhanced interface for a nonprogrammable work station, even if you are not using GUI windows.
- Use GUI window support when the underlying control unit supports this.
Creating/Manipulating Windows Example
The sample program in Creating and Manipulating Windows shows how to create and manipulate several windows with exit routines. The program creates three windows- Window 1, Window 2, and Window 3. Each time Enter is pressed, the next window is made current; in which case, the Draw Window exit routine for that window is called. If the user presses F4=Move or F5=Resize, the current window is moved or resized and the Draw Window exit routine is called again. The resulting screen output is shown in Display Screen.
Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.
Creating and Manipulating Windows
#include <stddef.h> #include <stdlib.h> #include <string.h> #include <stdio.h> #include "qsnapi.h" void GenericDraw(const Qsn_Cmd_Buf_T *cbuf, const Qsn_Win_T *win) { char *msg1 = "F3: quit F4: move F5: resize"; char *msg2 = "text no attribute"; QsnWrtDta(msg2, strlen(msg2), 0, 2, 1, QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, QSN_NO_SA, *cbuf, *win, NULL); QsnWrtDta(msg1, strlen(msg1), 0, -1, 1, QSN_SA_HI, QSN_SA_NORM, QSN_SA_RED, QSN_SA_NORM, *cbuf, *win, NULL); } void Draw1(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) { char *txt = "window 1 (ul/blue)"; GenericDraw(cbuf, win); QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM, QSN_SA_BLU, QSN_SA_NORM, *cbuf, *win, NULL); } void Draw2(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) { char *txt = "window 2 (ul/red)"; GenericDraw(cbuf, win); QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM, QSN_SA_RED, QSN_SA_NORM, *cbuf, *win, NULL); } void Draw3(const Qsn_Win_T *win, const Qsn_Cmd_Buf_T *cbuf) { char *txt = "window 3 (ul/pink)"; GenericDraw(cbuf, win); QsnWrtDta(txt, strlen(txt), 0, 5, 5, QSN_SA_UL, QSN_SA_NORM, QSN_SA_PNK, QSN_SA_NORM, *cbuf, *win, NULL); } int main (void) { int i; char text[100]; Qsn_Win_T win1, win2, win3, cur; Qsn_Win_Desc_T win_desc; Qsn_Win_Ext_Inf_T ext = { NULL, NULL, NULL, NULL, NULL, NULL }; Q_Bin4 win_desc_length = sizeof(win_desc); char aid; QsnInzWinD(&win_desc, win_desc_length, NULL); win_desc.GUI_support = '0'; /* define and start window 1 */ win_desc.top_row = 3; win_desc.left_col = 5; win_desc.num_rows = 13; win_desc.num_cols = 40; ext.draw_fp = Draw1; win1 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext), '1', NULL, 0, NULL, NULL); QsnGetAID(NULL, 0, NULL); /* define and start window 2 */ win_desc.top_row = 10; win_desc.left_col = 10; win_desc.num_rows = 10; win_desc.num_cols = 30; ext.draw_fp = Draw2; win2 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext), '1', NULL, 0, NULL, NULL); QsnGetAID(NULL, 0, NULL); /* define and start window 3 */ win_desc.top_row = 5; win_desc.left_col = 20; win_desc.num_rows = 15; win_desc.num_cols = 50; ext.draw_fp = Draw3; win3 = QsnCrtWin(&win_desc, win_desc_length, &ext, sizeof(ext), '1', NULL, 0, NULL, NULL); cur = win3; for ( ;; ) { if (( (aid=QsnGetAID(NULL, 0, NULL)) == QSN_F3)) break; else if (aid == QSN_F4) QsnMovWinUsr(cur, NULL); else if (aid == QSN_F5) QsnRszWinUsr(cur, NULL); else { /* switch current window to next window */ if (cur == win1) { QsnSetCurWin(win2, NULL); cur = win2; } else if (cur == win2) { QsnSetCurWin(win3, NULL); cur = win3; } else { QsnSetCurWin(win1, NULL); cur = win1; } } } }
Display Screen
+--------------------------------------------------------------------------------+ Command Entry RCHASD0I Request level: 1 Pr ............................................ : : : text no attr ...................................................... : : : : : text no attribute : : window 1 : : : : : : ......... : window 3 (ul/pink) : : : : : : : text no : : : : : : : : : : : F3 : win : : : : : : ottom Ty :... : : : ===> ca : : : : F3: qui : F3: quit F4: move F5: resize : : : : :........ :....................................................: F3=Exit F4=Prompt F9=Retrieve F10=Include detailed messages F11=Display full F12=Cancel F13=Information Assistant F24=More keys +--------------------------------------------------------------------------------+
API introduced: V2R3
[ Back to top | Dynamic Screen Manager APIs | APIs by category ]