Home | History | Annotate | Download | only in library 
      1 :mod:`curses.panel` --- A panel stack extension for curses
      2 ==========================================================
      3 
      4 .. module:: curses.panel
      5    :synopsis: A panel stack extension that adds depth to  curses windows.
      6 
      7 .. sectionauthor:: A.M. Kuchling <amk (a] amk.ca>
      8 
      9 --------------
     10 
     11 Panels are windows with the added feature of depth, so they can be stacked on
     12 top of each other, and only the visible portions of each window will be
     13 displayed.  Panels can be added, moved up or down in the stack, and removed.
     14 
     15 
     16 .. _cursespanel-functions:
     17 
     18 Functions
     19 ---------
     20 
     21 The module :mod:`curses.panel` defines the following functions:
     22 
     23 
     24 .. function:: bottom_panel()
     25 
     26    Returns the bottom panel in the panel stack.
     27 
     28 
     29 .. function:: new_panel(win)
     30 
     31    Returns a panel object, associating it with the given window *win*. Be aware
     32    that you need to keep the returned panel object referenced explicitly.  If you
     33    don't, the panel object is garbage collected and removed from the panel stack.
     34 
     35 
     36 .. function:: top_panel()
     37 
     38    Returns the top panel in the panel stack.
     39 
     40 
     41 .. function:: update_panels()
     42 
     43    Updates the virtual screen after changes in the panel stack. This does not call
     44    :func:`curses.doupdate`, so you'll have to do this yourself.
     45 
     46 
     47 .. _curses-panel-objects:
     48 
     49 Panel Objects
     50 -------------
     51 
     52 Panel objects, as returned by :func:`new_panel` above, are windows with a
     53 stacking order. There's always a window associated with a panel which determines
     54 the content, while the panel methods are responsible for the window's depth in
     55 the panel stack.
     56 
     57 Panel objects have the following methods:
     58 
     59 
     60 .. method:: Panel.above()
     61 
     62    Returns the panel above the current panel.
     63 
     64 
     65 .. method:: Panel.below()
     66 
     67    Returns the panel below the current panel.
     68 
     69 
     70 .. method:: Panel.bottom()
     71 
     72    Push the panel to the bottom of the stack.
     73 
     74 
     75 .. method:: Panel.hidden()
     76 
     77    Returns true if the panel is hidden (not visible), false otherwise.
     78 
     79 
     80 .. method:: Panel.hide()
     81 
     82    Hide the panel. This does not delete the object, it just makes the window on
     83    screen invisible.
     84 
     85 
     86 .. method:: Panel.move(y, x)
     87 
     88    Move the panel to the screen coordinates ``(y, x)``.
     89 
     90 
     91 .. method:: Panel.replace(win)
     92 
     93    Change the window associated with the panel to the window *win*.
     94 
     95 
     96 .. method:: Panel.set_userptr(obj)
     97 
     98    Set the panel's user pointer to *obj*. This is used to associate an arbitrary
     99    piece of data with the panel, and can be any Python object.
    100 
    101 
    102 .. method:: Panel.show()
    103 
    104    Display the panel (which might have been hidden).
    105 
    106 
    107 .. method:: Panel.top()
    108 
    109    Push panel to the top of the stack.
    110 
    111 
    112 .. method:: Panel.userptr()
    113 
    114    Returns the user pointer for the panel.  This might be any Python object.
    115 
    116 
    117 .. method:: Panel.window()
    118 
    119    Returns the window object associated with the panel.
    120 
    121