CreateScreen

Creates a new screen

Local Servers:blocking
Remote Servers:N/A
Classification:3.x, 4.x, 5.x, 6.x
Service:Screen Handling

Syntax

  #include <nwconio.h>  
   
  int CreateScreen  (  
     char  *screenName,   
     BYTE   attributes);

Parameters

screenName

(IN) Points to the name of the new screen.

attributes

(IN) Specifies the screen attributes.

Return Values

Returns the screen handle if successful or EFAILURE if an error occurs. If a NULL value is returned, the screen handle cannot be returned and errno is set to ENOMEM.

Remarks

A new screen is created for use by the NLM™ application. The new screen is displayed and made the current screen only if no other screens exist for the NLM when this call is made; otherwise, the current and displayed screens remain unchanged.

If a screen has the DONT_AUTO_ACTIVATE attribute set, it is not automatically displayed when it is created, even if it is the only screen for the NLM.

The supported screen attributes are:

Attribute

Description

DONT_AUTO_ACTIVATE

Prevents auto activation when screens are created and no other screens exist.

DONT_CHECK_CTRL_CHARS

Turns off Ctrl-C and Ctrl-S processing.

AUTO_DESTROY_SCREEN

Prevents the "Press any key to close" message.

POP_UP_SCREEN

Makes the screen a pop up screen.

UNCOUPLED_CURSORS

Sets distinct input and output cursors.

A popup screen automatically overlays the currently displayed screen. If the popup screen is still displayed when the DestroyScreen function or DropPopUpScreen (for the popup screen) function is called, the screen that was overlayed is redisplayed.

If screenName is "System Console" (case sensitive), a new screen is not created, rather the returned screen handle refers to the System Console Screen. In this case, the attributes should be set to zero. Input is not allowed from the System Console Screen. (All the input functions return EFAILURE with errno set to EWRNGKND.)

NOTE:If you pass a valid OS screen ID (usually obtained by other functions in this module) in the screenName parameter, CreateScreen creates a C Library screen handle from the given screen ID.

See scrhand.c.

See Also

DestroyScreen, DisplayScreen, GetCurrentScreen, __GetScreenID, GetScreenInfo, ScanScreens, SetCurrentScreen

Example

  #include <nwconio.h>  
  char   screenName[ ] = "NLM x New Screen";  
  int    screenHandle;  
  BYTE   attributes = 0;  
  screenHandle = CreateScreen(screenName, attributes);