Using the Display Manager
5.4. Creating Subsequent Pads in Window Panes
Once you have started your process on the user's display (either by associating your process with the user's pads, or creating your own pads, as described in Section 5.3), you can associate other pads, window panes and frames with it. This section describes how to create window panes.
Section 5.7 describes how to create frames.
Most often, you will want to associate an input pad with your program's transcript pad. You might also want to divide your window into separate window panes, or you might want to create a frame to hold two-dimensional output.
You can have any number of window panes associated with the original transcript window, up to the Display Manager's limit of 40 pads and 60 windows. Just how many pads and panes you want depends on how many different kinds of output you want displayed concurrently.
You create subsequent pads and window panes within a window with the PAD _$CREATE system call, which we described in Section 5.3.2. You can create a pane of anyone of the
• PAD $INPUT
• PAD $EDIT
• $PAD $READ EDIT
• PAD $ TRANSCRIPT.
The following sections describe how to use PAD _ $CREATE to create the three types of window panes.
5.4.1. Creating Input Pads in Window Panes
You will want to create an input pad to get input from the keyboard user. To create an input pad, use the PAD _ $ CREATE call, specifying PAD _ $INPUT as the third argument. This call creates an input pad (and a window pane to view it), and associates it with a previously created transcript pad. (You must create a transcript pad before the associated input pad.)
NOTE: You do NOT need to create an input pad if you are using the transcript pad for GPR direct mode graphics only.
You can have only one input pad for each transcript pad, and it must be located on the bottom of the pad. Example 5-3 shows how to create an input pad with PAD $CREATE. An explanation of each argument follows the example.
pad $create (' { Null pathname for input pad } 0, { Null namelength for input pad } pad_$input. { Type of pad }
stream_out, { Stream ID of related transcript pad } pad_$bottom, { Input pads always go on bottom }
[L
{ Pane size is relative to transcript pad } 20, { New pad takes up 20% of related window } input_stream, { Stream ID of this input pad }status ); { Completion status }
Example 5-3. Creating an Input Pad in a Window Pane
You must specify a null pathname and namelength when creating an input pad.
PAD _ $INPUT indicates that the type of window pane you are creating is an input pad.
Stream_ out is the stream ID, in STREAM_ $ID _ T format, of a previously created transcript pad to which this pad is related. (In this case, the transcript pad is stream_ out. )
PAD _ $BOTTOM indicates that the new window pane will be positioned at the bottom of its related transcript pad. You ~ specify the bottom when creating an input pad. If you create additional transcript and edit window panes in a transcript window pane, the input window remains at the bottom of its associated transcript pane.
An empty set of brackets, [ ], indicates the default pane _ options attribute. The value of this argument determines, among other things, the interpretation of the next argument, pane _ size.
Pane size specifies the height of the new window pane. The value of pane_size is the
maximum height the input window pane will ever be. All input pads start out to hold a single line of text in the current font. However, in cases where the user types input before the program is ready to read it, there may be more lines of input waiting for action. To accommodate this, you specify a larger window pane size for an input pad. A common value for the pane size is 20.
When PAD _ $CREATE creates an input pad, it returns the stream ID of an input stream. Your program can read any keyboard input the user types into this pane. The Display Manager usually echoes the input into the related transcript pad. If you do not want the input to be echoed, you can specify the pane _ options attribute [PAD _ $INIT _ RAW] . PAD _ $INIT _ RAW indicates that the input will be processed in raw mode, which prevents the system from preprocessing the input. Raw mode processing is described in the section below, 5.8.2.
Input _ stream is the stream ID of the new window pane, in STREAM _ $ID _ T format, returned by this call. Status is the completion status returned by this call.
5.4.2. Creating Transcript Pads in Window Panes
You can associate other transcript window panes on top of the original transcript pad. To create a transcript pane, use the PAD $CREATE call, specifying PAD $TRANSCRIPT as the third argument.
Example 5-4 shows how to create a transcript pad with PAD _$CREATE. An explanation of each argument follows the example.
('transpathname' • namelength.
pad_$transcript.
stream_out.
pad_$right.
[pad_$abs_size] • 30.
trans_stream.
status );
{ Pathname } { Namelength}
{ Type of pad }
{ Stream IO of related transcript pad }
{ Side of original pad that new pad is located } { Pane size is absolute value }
{ New pad is 30 lines high (scaled) } { Stream IO of this transcript pad } { Completion status }
Example 5-4. Creating a Transcript Pad in a Window Pane
You can specify either null, or a pathname and namelength when creating a transcript pad and pane. If you specify null, the transcript pad is a temporary file, which goes away when the program ends.
If you specify the pathname of an existing file for a transcript pad, the Display Manager positions the pad at the beginning of the file, but scrolls down to the bottom of the file the first time the user writes to the pad. Creating a transcript window pane whose pad is an existing file is a convenient way for your program to display prepared text or graphics, such as menus. The Display Manager can call an existing file to the screen faster than your program can create it.
If you create a transcript window pane with a pathname that does not refer to an existing pad, the Display Manager creates a new permanent file. Thus, the program dialogue is a permanent record that you can refer to after the program terminates.
PAD _ $RIGHT indicates that the new pad will be at the right side of the associated pad. You
PAD _ $ABS _ SIZE indicates that the next argument, pane_size, will be an absolute value, according to the current scale factor. That is, pane_size will be 30 lines high in the current font, if the scale factors are set to the default, 0,0. For details on scale factors, see Section 5.5.7. By specifying an absolute size, the Display Manager attempts to keep the pane at that size, even if its related window grows or shrinks. However, the window pane can never be larger than its related window, so that if the window shrinks below the size of the window pane, the window pane must also shrink. You can also specify the default relative value with empty brackets, [ ]. This makes the new pad's size a percentage of the original pad.
Trans_stream is the stream ID of the new window pane, in STREAM $ID T format, returned by this call. Status is the completion status returned by this call.
5.4.3. Creating Edit Pads in Window Panes
An edit window pane is a window pane where the user can type or edit text with the usual Display Manager text-editing commands. If your program requires a large amount of input from them, you can create an edit window pane for users to enter their data.
To create an edit pad, use the PAD _ $CREATE call, specifying PAD _ $EDIT as the third argument. This call creates an edit pad (and a window pane to view it) and associates it with a previously created transcript pad.
Example 5-5 shows how to create an edit pad with PAD _ $CREATE. An explanation of each argument follows the example.
(' edi tpathname' . namelength.
pad_$edit.
stream out.
pad $top.
[pad_$abs_size] . 30.
edit_stream.
status );
{ Pathname } { Namelength}
{ Type of pad }
{ Stream ID of related transcript pad }
{ Side of original pa.d that new pad is located } { Pane size is absolute value }
{ New pad is 30 lines high ( scaled ) } { Stream ID of this transcript pad } { Completion status }
Example 6-6. Creating an Edit Pad in a Window Pane
You can specify a pathname and name length when creating an edit pad. If you give a pathname of an existing file, the user sees and can edit that file. If you give anew pathname, the user's input goes into anew, permanent file. If you supply no pathname for the edit file, the user's input goes away when the stream closes.
PAD _ $TOP indicates that the edit pad is located at the top of the associated pad. You can place the edit pad anywhere on the pad, and can specify any of the following sides:
PAD_$TOP, PAD_$BOTTOM, PAD_$RIGHT, PAD_$LEFT.
PAD _ $ABS _ SIZE indicates that the next argument, pane _size, will be an absolute value, according to the current scale factor. (That is, pane_size will be 30 lines high.) By specifying an absolute size, the Display Manager attempts to keep the pane at that size, even if its related window grows or shrinks. However, the window pane can never be larger than its related window, so that if the window shrinks below the size of the window pane, the window pane must also shrink. You can also specify the default relative value with empty brackets, [ ]. This makes the new pad's size a percentage of the original pad.
Edit _ stream is the stream 10 of the new window pane, in STREAM _ $10 _ T format, returned by this call. Status is the· completion status returned by this call.
Mter you create an edit window pane, you can then call PAD _$EDIT _ WAIT. This suspends the process until the user terminates the edit session in the edit pane with a CRTL/Y, CTRL/N, EXIT, or ABORT ( WC or WC -Q) command. The process then gains control, closes the window, thereby allowing your program to access the information.
Mter an editing session, the program has different access privileges to the edited file depending on when the file was created. If the file is a temporary file, specified by a null pathname in PAD _ $ CREATE , the program has read and write access to it. However, if the file is a pre-existing file, specified as the pathname in PAD _ $ CREATE , your program has only read access to it. You can change the file access, if necessary by using the STREAM _ $REDEFlNE system call described in Chapter 4.
5.4.4. Creating Read- Only Edit Pads in Window Panes
A read-only edit pad is a file that users can read but not modify. To create a read-only edit pad, use the PAD _ $CREATE call, specifying PAD _ $READ _EDIT as the third argument. This call creates a read-only edit pad (and a window pane to view it) and associates it with a previously created transcript pad. For a description of the call, see Section 5.4.3, Creating Edit Window Panes.
Note that once you create an edit pad as read-only, the user cannot change it into an edit pad.
The Display Manager command that turns a read-only edit pad into an edit pad does not work when the window pane is created with PAD _ $ CREATE. A read-only edit pad must refer to an existing file.
5.4.5. Closing Windows and Window Panes
A pad closes when its associated stream closes; the stream closes when your program makes a STREAM _ $CLOSE system call, or when your program terminates, regardless of whether the termination is normal or unexpected. It is good practice to use the STREAM_$CLOSE system call to close any opened I/O streams before you conclude your program.
You should close the streams in the reverse order that you created them, so that you close the original transcript pad last. You can close an edit pad stream while the user is still editing. This denies your program further access to the file, but allows the user to· finish editing it. Even though a pad closes when your program ends, some types of windows or window panes associated with these pads do not close automatically when their associated streams close. These include
• Transcript windows (not panes).
• Edit windows and panes.
• Read/edit windows (not panes).
If you want these windows or panes to close when their related streams close, use the read/ edit panes, because they go away automatically when their associated streams close.
5.4.6. Sample Program: Creating and Closing Windows and Window Panes
Example, 5-6 is a program that shows how to use PAD calls to create an original transcript pad
Example 5- 6. Creating and Closing Windows and Window Panes
{* *************************************************************************** *}
{* Procedure CHECK_STATUS to check for errors. It prints an error message, *}
{* and exits on bad status. *}
{* *************************************************************************** *}
PROCEDURE check_status;
BEGIN
IF status.all <> status $ok THEN BEGIN error $print( status);
pgm $exit;
END;
END; {check_status}
{* *************************************************************************** *}
{* Procedure HOLD_DISPLAY to suspend program to demonstrate how calls work. *}
{* *************************************************************************** *}
{ This internal procedure calls TIME $WAIT to suspend the process for 3 seconds so you can see how each call works~ }
PROCEDURE hold_display;
VAR
rel time
BEGIN { hold display}
cal $sec-to clock ( 3, rel_time); {Convert secs to UTC value}
time_$wait ( time_$relative, rel time, status );
check status;
, END; {hold display }
{ Time to wait}
{* *************************************************************************** *}
BEGIN {Main}
{ Set position of future window. } window. top - 150;
window. left - 150;
window. width - 450;
window. height - 450;
{ Create original transcript pad and window. }
0,
pad_$transcript, display_unit, window,
source_stream, status);
{ No pathname for transcript pad } { No namelength for transcript pad } { Type of pad }
{ Number of display unit}
{ Position of window}
{ Returns stream ID } { Completion status }
Example 5-6. Creating and Closing Windows and Window Panes (Cont.)
{ Close window when stream closes. } pad_$set_auto_close ( source_stream, window_count,
pad_$create ( pathname, name length, pad_$set_auto_close ( edit_stream,
Window_count,
Example 5-6. Creating and Closing Windows and Window Panes (Cont.)
{ Close the streams. }
stream_$close( edit_stream. status );
cheek_status;
stream_$close( input_stream. status );
check_status;
stream_$close( source_stream. status );
check_status;
Example 5- 6. Creating and Closing Windows and Window Panes (Cont.)