Blame - doc/html/man/panel.3x.html - android_external_libncurses

Amit Daniel Kachhap

e6a01f5

2011-07-20 11:45:59 +0530

[diff] [blame]

1

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">

2

<!--

3

****************************************************************************

4

5

* *

6

* Permission is hereby granted, free of charge, to any person obtaining a *

7

* copy of this software and associated documentation files (the *

8

* "Software"), to deal in the Software without restriction, including *

9

* without limitation the rights to use, copy, modify, merge, publish, *

10

* distribute, distribute with modifications, sublicense, and/or sell *

11

* copies of the Software, and to permit persons to whom the Software is *

12

* furnished to do so, subject to the following conditions: *

13

* *

14

* The above copyright notice and this permission notice shall be included *

15

* in all copies or substantial portions of the Software. *

16

* *

17

* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *

18

* OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *

19

* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *

20

* IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *

21

* DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *

22

* OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *

23

* THE USE OR OTHER DEALINGS IN THE SOFTWARE. *

24

* *

25

* Except as contained in this notice, the name(s) of the above copyright *

26

* holders shall not be used in advertising or otherwise to promote the *

27

* sale, use or other dealings in this Software without prior written *

28

* authorization. *

29

****************************************************************************

30

* @Id: panel.3x,v 1.14 2007/05/12 20:45:20 tom Exp @

-->

<HTML>

<HEAD>

<TITLE>panel 3x</TITLE>

</HEAD>

<BODY>

<H1>panel 3x</H1>

<HR>

<PRE>

43

<A HREF="panel.3x.html">panel(3x)</A> <A HREF="panel.3x.html">panel(3x)</A>

</PRE>

panel - panel stack extension for curses

</PRE>

<H2>SYNOPSIS</H2><PRE>

55

#include <panel.h>

56

57

cc [flags] sourcefiles -lpanel -lncurses

58

59

PANEL *new_panel(WINDOW *win)

60

int bottom_panel(PANEL *pan)

61

int top_panel(PANEL *pan)

62

int show_panel(PANEL *pan)

63

void update_panels();

64

int hide_panel(PANEL *pan)

65

WINDOW *panel_window(const PANEL *pan)

66

int replace_panel(PANEL *pan, WINDOW *window)

67

int move_panel(PANEL *pan, int starty, int startx)

68

int panel_hidden(const PANEL *pan)

69

PANEL *panel_above(const PANEL *pan)

70

PANEL *panel_below(const PANEL *pan)

71

int set_panel_userptr(PANEL *pan, const void *ptr)

72

const void *panel_userptr(const PANEL *pan)

73

int del_panel(PANEL *pan)

</PRE>

<H2>DESCRIPTION</H2><PRE>

78

Panels are <A HREF="ncurses.3x.html">curses(3x)</A> windows with the added feature of

79

depth. Panel functions allow the use of stacked windows

80

and ensure the proper portions of each window and the

81

curses stdscr window are hidden or displayed when panels

82

are added, moved, modified or removed. The set of cur-

83

rently visible panels is the stack of panels. The stdscr

84

window is beneath all panels, and is not considered part

85

of the stack.

86

87

A window is associated with every panel. The panel rou-

88

tines enable you to create, move, hide, and show panels,

89

as well as position a panel at any desired location in the

90

stack.

91

92

Panel routines are a functional layer added to <A HREF="ncurses.3x.html">curses(3x)</A>,

93

make only high-level curses calls, and work anywhere ter-

minfo curses does.

</PRE>

<H2>FUNCTIONS</H2><PRE>

99

new_panel(win)

100

allocates a PANEL structure, associates it with

101

win, places the panel on the top of the stack

102

(causes it to be displayed above any other

103

panel) and returns a pointer to the new panel.

104

105

update_panels()

106

refreshes the virtual screen to reflect the rela-

107

tions between the panels in the stack, but does not

108

call doupdate() to refresh the physical screen.

109

Use this function and not wrefresh or wnoutrefresh.

110

update_panels() may be called more than once before

111

a call to doupdate(), but doupdate() is the func-

112

tion responsible for updating the physical screen.

113

114

del_panel(pan)

115

removes the given panel from the stack and deallo-

116

cates the PANEL structure (but not its associated

window).

hide_panel(pan)

removes the given panel from the panel stack and

121

thus hides it from view. The PANEL structure is not

122

lost, merely removed from the stack.

123

124

panel_hidden(pan)

125

returns TRUE if the panel is in the panel stack,

126

FALSE if it is not. If the panel is a null

pointer, return ERR.

show_panel(pan)

makes a hidden panel visible by placing it on top

131

of the panels in the panel stack. See COMPATIBILITY

below.

top_panel(pan)

puts the given visible panel on top of all panels

136

in the stack. See COMPATIBILITY below.

137

138

bottom_panel(pan)

139

puts panel at the bottom of all panels.

140

141

move_panel(pan,starty,startx)

142

moves the given panel window so that its upper-left

143

corner is at starty, startx. It does not change

144

the position of the panel in the stack. Be sure to

145

use this function, not mvwin(), to move a panel

146

window.

147

148

replace_panel(pan,window)

149

replaces the current window of panel with window

150

(useful, for example if you want to resize a panel;

151

if you're using ncurses, you can call replace_panel

152

on the output of <A HREF="wresize.3x.html">wresize(3x)</A>). It does not change

153

the position of the panel in the stack.

154

155

panel_above(pan)

156

returns a pointer to the panel above pan. If the

157

panel argument is (PANEL *)0, it returns a pointer

158

to the bottom panel in the stack.

159

160

panel_below(pan)

161

returns a pointer to the panel just below pan. If

162

the panel argument is (PANEL *)0, it returns a

163

pointer to the top panel in the stack.

164

165

set_panel_userptr(pan,ptr)

166

sets the panel's user pointer.

167

168

panel_userptr(pan)

169

returns the user pointer for a given panel.

170

171

panel_window(pan)

172

returns a pointer to the window of the given panel.

</PRE>

<H2>DIAGNOSTICS</H2><PRE>

177

Each routine that returns a pointer returns NULL if an

178

error occurs. Each routine that returns an int value

179

returns OK if it executes successfully and ERR if not.

</PRE>

<H2>COMPATIBILITY</H2><PRE>

184

Reasonable care has been taken to ensure compatibility

185

with the native panel facility introduced in SVr3.2

186

(inspection of the SVr4 manual pages suggests the

187

programming interface is unchanged). The PANEL data

188

structures are merely similar. The programmer is cau-

189

tioned not to directly use PANEL fields.

190

191

The functions show_panel() and top_panel() are identical

192

in this implementation, and work equally well with dis-

193

played or hidden panels. In the native System V implemen-

194

tation, show_panel() is intended for making a hidden panel

195

visible (at the top of the stack) and top_panel() is

196

intended for making an already-visible panel move to the

197

top of the stack. You are cautioned to use the correct

198

function to ensure compatibility with native panel

libraries.

</PRE>

In your library list, libpanel.a should be before libn-

205

curses.a; that is, you want to say `-lpanel -lncurses',

206

not the other way around (which would usually give a link-

error).

</PRE>

<H2>FILES</H2><PRE>

panel.h interface for the panels library

213

214

libpanel.a the panels library itself

</PRE>

<A HREF="ncurses.3x.html">curses(3x)</A>

220

221

This describes ncurses version 5.6 (patch 20081011).

</PRE>

<H2>AUTHOR</H2><PRE>

Originally written by Warren Tucker <wht@n4hgf.mt-

227

park.ga.us>, primarily to assist in porting u386mon to

228

systems without a native panels library. Repackaged for

229

ncurses by Zeyd ben-Halim.

<A HREF="panel.3x.html">panel(3x)</A>

</PRE>

<HR>

Man(1) output converted with

</ADDRESS>

</BODY>

</HTML>