usr/src/man/man3xcurses/overlay.3xcurses

   1 '\" te
   2 .\"  Copyright (c) 1990, 1995 by Mortice Kern Systems Inc.  All Rights Reserved  Portions Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH OVERLAY 3XCURSES "Jun 5, 2002"
   7 .SH NAME
   8 overlay, overwrite \- copy overlapped windows
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR [ \fIflag\fR... ] \fIfile\fR... \fB-I\fR /usr/xpg4/include \fB -L \fR /usr/xpg4/lib \e
  13 \fB -R \fR /usr/xpg4/lib \fB -lcurses \fR [ \fIlibrary\fR... ]
  14
  15 \fBc89\fR [ \fIflag\fR... ] \fIfile\fR... \fB-lcurses\fR [ \fIlibrary\fR... ]
  16
  17 #include <curses.h>
  18
  19 \fBint\fR \fBoverlay\fR(\fBconst WINDOW *\fR\fIsrcwin\fR, \fBWINDOW *\fR\fIdstwin\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBoverwrite\fR(\fBconst WINDOW *\fR\fIsrcwin\fR, \fBWINDOW *\fR\fIdstwin\fR);
  25 .fi
  26
  27 .SH PARAMETERS
  28 .sp
  29 .ne 2
  30 .na
  31 \fB\fIsrcwin\fR\fR
  32 .ad
  33 .RS 10n
  34 Is a pointer to the source window to be copied.
  35 .RE
  36
  37 .sp
  38 .ne 2
  39 .na
  40 \fB\fIdstwin\fR\fR
  41 .ad
  42 .RS 10n
  43 Is a pointer to the destination window to be overlayed or overwritten.
  44 .RE
  45
  46 .SH DESCRIPTION
  47 .sp
  48 .LP
  49 The \fBoverwrite()\fR and \fBoverlay()\fR functions overlay \fIsrcwin\fR on top
  50 of \fIdestwin\fR. The \fIsrcwin\fR and \fIdstwin\fR arguments do not have to be
  51 the same size; only text where the two windows overlap is copied.
  52 .sp
  53 .LP
  54 The \fBoverwrite()\fR function copies characters as though a sequence of
  55 \fBwin_wch\fR(3XCURSES) and \fBwadd_wch\fR(3XCURSES) were performed with the
  56 destination window's attributes and background attributes cleared.
  57 .sp
  58 .LP
  59 The \fBoverlay()\fR function does the same thing, except that, whenever a
  60 character to be copied is the background character of the source window,
  61 \fBoverlay()\fR does not copy the character but merely moves the destination
  62 cursor the width of the source background character.
  63 .sp
  64 .LP
  65 If any portion of the overlaying window border is not the first column of a
  66 multi-column character, then all the column positions will be replaced with the
  67 background character and rendition before the overlay is done. If the default
  68 background character is a multi-column character when this occurs, then these
  69 functions fail.
  70 .SH RETURN VALUES
  71 .sp
  72 .LP
  73 Upon successful completion, these functions return \fBOK\fR. Otherwise, they
  74 return \fBERR\fR.
  75 .SH ERRORS
  76 .sp
  77 .LP
  78 No errors are defined.
  79 .SH EXAMPLES
  80 .LP
  81 \fBExample 1 \fRImplement a pop-up dialog
  82 .sp
  83 .LP
  84 The following example demonstrates the use of \fBoverwrite()\fR to implement a
  85 pop-up dialog box.
  86
  87 .sp
  88 .in +2
  89 .nf
  90 #include <curses.h>
  91 /*
  92  *   Pop-up a window on top of curscr.  If row and/or col
  93  *   are -1 then that dimension will be centered within
  94  *   curscr.  Return 0 for success or -1 if malloc(\|) failed.
  95  *   Pass back the working window and the saved window for the
  96  *   pop-up.  The saved window should not be modified.
  97  */
  98 int
  99 popup(work, save, nrows, ncols, row, col)
 100 WINDOW **work, **save;
 101 int nrows, ncols, row, col;
 102 {
 103      int mr, mc;
 104      getmaxyx(curscr, mr, mc);
 105      /* Windows are limited to the size of curscr. */
 106      if (mr < nrows)
 107           nrows = mr;
 108      if (mc < ncols)
 109           ncols = mc;
 110      /* Center dimensions. */
 111      if (row == -1)
 112           row = (mr-nrows)/2;
 113      if (col == -1)
 114           col = (mc-ncols)/2;
 115      /* The window must fit entirely in curscr. */
 116      if (mr < row+nrows)
 117           row = 0;
 118      if (mc < col+ncols)
 119           col = 0;
 120      *work = newwin(nrows, ncols, row, col);
 121      if (*work == NULL)
 122           return (-1);
 123      if ((*save = dupwin(*work)) == NULL) {
 124           delwin(*work);
 125           return (-1);
 126      }
 127      overwrite(curscr, *save);
 128      return (0);
 129 }
 130 /*
 131  * Restore the region covered by a pop-up window.
 132  * Delete the working window and the saved window.
 133  * This function is the complement to popup(\|).  Return
 134  * 0 for success or -1 for an error.
 135  */
 136 int
 137 popdown(work, save)
 138 WINDOW *work, *save;
 139 {
 140      (void) wnoutrefresh(save);
 141      (void) delwin(save);
 142      (void) delwin(work);
 143      return (0);
 144 }
 145 /*
 146  * Compute the size of a dialog box that would fit around
 147  * the string.
 148  */
 149 void
 150 dialsize(str, nrows, ncols)
 151 char *str;
 152 int *nrows, *ncols;
 153 {
 154      int rows, cols, col;
 155      for (rows = 1, cols = col = 0; *str != '\e0'; ++str) {
 156           if (*str == '\en') {
 157                if (cols < col)
 158                    cols = col;
 159                col = 0;
 160                ++rows;
 161           } else {
 162                ++col;
 163           }
 164       }
 165       if (cols < col)
 166            cols = col;
 167       *nrows = rows;
 168       *ncols = cols;
 169 }
 170 /*
 171  * Write a string into a dialog box.
 172  */
 173 void
 174 dialfill(w, s)
 175 WINDOW *w;
 176 char *s;
 177 {
 178      int row;
 179      (void) wmove(w, 1, 1);
 180      for (row = 1; *s != '\e0'; ++s) {
 181           (void) waddch(w, *((unsigned char*) s));
 182           if (*s == '\en')
 183                wmove(w, ++row, 1);
 184      }
 185      box(w, 0, 0);
 186 }
 187 void
 188 dialog(str)
 189 char *str;
 190 {
 191      WINDOW *work, *save;
 192      int nrows, ncols, row, col;
 193      /* Figure out size of window. */
 194      dialsize(str, &nrows, &ncols);
 195      /* Create a centered working window with extra */
 196      /* room for a border. */
 197      (void) popup(&work, &save, nrows+2, ncols+2, -1, -1);
 198      /* Write text into the working window. */
 199      dialfill(work, str);
 200      /* Pause.  Remember that wgetch(\|) will do a wrefresh(\|) */
 201      /* for us. */
 202      (void) wgetch(work);
 203      /* Restore curscr and free windows. */
 204      (void) popdown(work, save);
 205      /* Redraw curscr to remove window from physical screen. */
 206      (void) doupdate(\|);
 207 }
 208 .fi
 209 .in -2
 210
 211 .SH ATTRIBUTES
 212 .sp
 213 .LP
 214 See \fBattributes\fR(5) for descriptions of the following attributes:
 215 .sp
 216
 217 .sp
 218 .TS
 219 box;
 220 c | c
 221 l | l .
 222 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 223 _
 224 Interface Stability     Standard
 225 _
 226 MT-Level        Unsafe
 227 .TE
 228
 229 .SH SEE ALSO
 230 .sp
 231 .LP
 232 \fBcopywin\fR(3XCURSES), \fBlibcurses\fR(3XCURSES), \fBwadd_wch\fR(3XCURSES),
 233 \fBwin_wch\fR(3XCURSES), \fBattributes\fR(5), \fBstandards\fR(5)