[ python-Bugs-1484978 ] Doc for new_panel() missing scope info

[SourceForge.net]

Bugs item #1484978, was opened at 2006-05-09 20:06
Message generated for change (Comment added) made by gbrandl
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1484978&group_id=5470

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Documentation
Group: Python 2.5
>Status: Closed
>Resolution: Fixed
Priority: 5
Submitted By: Troels Therkelsen (troelst)
Assigned to: Nobody/Anonymous (nobody)
Summary: Doc for new_panel() missing scope info

Initial Comment:
The (current) documentation for curses.panel.new_panel
() does not explain that if the panel object returned 
by the function goes out of scope, or is explicitly 
deleted, the associated panel is immediately 
destroyed and removed from the panel stack.  Since 
this is distinctly different from how normal curses 
windows work (text printed to a destroyed window 
doesn't go away).

Maybe the documentation could read something like: 

----

new_panel(win) 

Returns a panel object, associating it with the given 
window win.  Be aware that you need to keep the 
returned panel object referenced explicitly.  If you 
don't, the panel object is garbage collected and 
removed from the panel stack.

----

Of course, one could argue that since there's no 
functions for deleting panels, that it's obvious it's 
handled via normal Python scoping rules, but I got 
stumped by this and it was only by looking into the 
examples in Demo/curses that I figured out what was 
going on.

----------------------------------------------------------------------

>Comment By: Georg Brandl (gbrandl)
Date: 2006-05-10 16:12

Message:
Logged In: YES 
user_id=849994

Thanks for reporting, I applied your new wording in rev.
45952, 45953(2.4).

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=1484978&group_id=5470