Technical Reference: Base Operating System and Extensions , Volume 2

derwin, newwin, or subwin Subroutine

Purpose

Window creation subroutines.

Library

Curses Library (libcurses.a)

Syntax

#include <curses.h>
 
WINDOW *derwin(WINDOW *orig,
int nlines,
int ncols,
int begin_y,
int begin_x);
 
WINDOW *newwin(int nlines,
int ncols,
int begin_y,
 int begin_x);
 
WINDOW *subwin(WINDOW *orig,
int nlines,
int ncols,
int begin_y,
int begin_x);

Description

The derwin subroutine is the same as the subwin subroutine except that begin_y and begin_x are relative to the origin of the window orig rather than absolute screen positions.

The newwin subroutine creates a new window with nlines lines and ncols columns, positioned so that the origin is at (begin_y, begin_x). If nlines is zero, it defaults to LINES - begin_y; if ncols is zero, it defaults to COLS - begin_x.

The subwin subroutine creates a new window with nlines lines and ncols columns, positioned so that the origin is at (begin_y, begin_x). (This position is an absolute screen position, not a position relative to the window orig.) If any part of the new window is outside orig, the subroutine fails and the window is not created.

Parameters

Return Values

Upon successful completion, these subroutines return a pointer to the new window. Otherwise, they return a null pointer.

Examples

For the derwin and newwin subroutines:

1. To create a new window, enter:

   WINDOW *my_window;
    
   my_window = newwin(5, 10, 20, 30);
   

   my_window is now a window 5 lines deep, 10 columns wide, starting at the coordinates y = 20, x = 30. That is, the upper left corner is at coordinates y = 20, x = 30, and the lower right corner is at coordinates y = 24, x = 39.

2. To create a window that is flush with the right side of the terminal, enter:

   WINDOW *my_window;
    
   my_window = newwin(5, 0, 20, 30);
   

   my_window is now a window 5 lines deep, extending all the way to the right side of the terminal, starting at the coordinates y = 20, x = 30. The upper left corner is at coordinates y = 20, x = 30, and the lower right corner is at coordinates y = 24, x = lastcolumn.

3. To create a window that fills the entire terminal, enter:

   WINDOW *my_window;
    
   my_window = newwin(0, 0, 0, 0);
   

   my_window is now a screen that is a window that fills the entire terminal's display.

For the subwin subroutine:

1. To create a subwindow, use:
   WINDOW *my_window, *my_sub_window;
   my_window = newwin (derwin, newwin, or subwin Subroutine)
   (5, 10, 20, 30);
   my_sub_window is now a subwindow 2 lines deep, 5 columns wide, starting at the same coordinates of its parent window my_window. That is, the subwindow's upper-left corner is at coordinates y = 20, x = 30 and lower-right corner is at coordinates y = 21, x = 34.
2. To create a subwindow that is flush with the right side of its parent, use
   WINDOW *my_window, *my_sub_window;
   my_window =
   newwin (derwin, newwin, or subwin Subroutine)(5, 10, 20, 30);
   my_sub_window = subwin(my_window, 2, 0, 20, 30);
   my_sub_window is now a subwindow 2 lines deep, extending all the way to the right side of its parent window my_window, and starting at the same coordinates. That is, the subwindow's upper-left corner is at coordinates y = 20, x = 30 and lower-right corner is at coordinates y = 21, x = 39.
3. To create a subwindow in the lower-right corner of its parent, use:
   WINDOW *my_window, *my_sub_window
   my_window = newwwin (derwin, newwin, or subwin Subroutine)
   (5, 10, 20, 30);
   my_sub_window = subwin(my_window, 0, 0, 22, 35);
   my_sub_window is now a subwindow that fills the bottom right corner of its parent window, my_window, starting at the coordinates y = 22, x = 35. That is, the subwindow's upper-left corner is at coordinates y = 22, x = 35 and lower-right corner is at coordinates y = 24, x = 39.

Implementation Specifics

These subroutines are part of Base Operating System (BOS) Runtime.

Related Information

The endwin (endwin Subroutine), initscr (initscr and newterm Subroutine) subroutines.

Curses Overview for Programming, List of Curses Subroutines, Windows in the Curses Enviroment in AIX 5L Version 5.1 General Programming Concepts: Writing and Debugging Programs.