tutorial.html

Urwid is a Python library for making text console applications. It has many features including fluid

			cols, rows = ui.get_cols_rows()

ui.run_wrapper( run )</pre>

The <a href="reference.html#Screen-get_input">get_input</a> function will
return "window resize" among keys pressed when the window is resized.  It
is a good idea to check for uppercase and lowercase letters on input
to avoid confusing users.

<div class="shot"><pre><span style="color:black;background:#0000c0">                     </span>
<span style="color:black;background:#0000c0">                     </span>
<span style="color:black;background:#0000c0">                     </span>
<span style="color:black;background:#c00000">    </span><span style="color:black;background:silver"> Hello World </span><span style="color:black;background:#c00000">    </span>
<span style="color:black;background:#0000c0">                     </span>
<span style="color:black;background:#0000c0">                     </span>
<span style="color:black;background:#0000c0">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#c00000">  </span><span style="color:black;background:silver"> Hello</span><span style="color:black;background:#c00000">  </span>
<span style="color:black;background:#c00000">  </span><span style="color:black;background:silver">World </span><span style="color:black;background:#c00000">  </span>
<span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#0000c0">          </span>
<span style="color:black;background:#0000c0">          </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:#0000c0">                              </span>
<span style="color:black;background:#c00000">         </span><span style="color:black;background:silver"> Hello World </span><span style="color:black;background:#c00000">        </span>
<span style="color:black;background:#0000c0">                              </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:#c00000"> </span><span style="color:black;background:silver"> Hello World </span><span style="color:black;background:#c00000"> </span>
<span style="color:black;background:#0000c0">               </span>
</pre></div>

<br clear="left">
<br>

<h2>2. Conversation Example</h2>

<h3><a name="edit">2.1. Edit Widgets</a>
<span class="back">[<a href="#top">back to top</a>]</span></h3>

This program asks for your name then responds "Nice to meet you, (your name)."

<pre class="code">import urwid.curses_display
import urwid

ui = urwid.curses_display.Screen()

def run():
	cols, rows = ui.get_cols_rows()

	ask = urwid.Edit(&quot;What is your name?\n&quot;)
	fill = urwid.Filler( ask )
	reply = None

	while True:
		canvas = fill.render( (cols, rows), focus=True )
		ui.draw_screen( (cols, rows), canvas )

		keys = ui.get_input()
		for k in keys:
			if k == &quot;window resize&quot;:
				cols, rows = ui.get_cols_rows()
				continue
			if reply is not None:
				return
			if k == &quot;enter&quot;:
				reply = urwid.Text( &quot;Nice to meet you,\n&quot;+
					ask.edit_text+&quot;.&quot; )
				fill.body = reply
			if fill.selectable():
				fill.keypress( (cols, rows), k )

ui.run_wrapper( run )</pre>

<ul>
<li>An <a href="reference.html#Edit">Edit</a> widget is created with the
caption "What is your name?". A newline at the end of the caption makes
the user input start on the next row.
<li>A <a href="reference.html#Filler">Filler</a> widget is created to wrap
the edit widget. Its <a href="reference.html#Filler-render">render</a>
function is called to create the canvas. The render function is called with
the optional parameter "focus" set to True. This parameter allows the
wrapped Edit widget to render its cursor.
<li>Keys are processed one at a time. Most keys are sent to the Filler widget's
<a href="reference.html#Filler-keypress">keypress</a> function which will
call the Edit widget's <a href="reference.html#Edit-keypress">keypress</a>
function to handle the key.
<li>Once the ENTER key is pressed the wrapped object in the Filler widget
is changed to a reply text.
<li>Any keypress then causes the program to exit.
</ul>

The Edit widget has many capabilities. It lets you make corrections and move
the cursor around with the HOME, END and arrow keys. It is based on the Text
widget so it supports the same wrapping and alignment modes.

<div class="shot"><pre><span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">What is your name?   </span>
<span style="color:silver;background:black"> </span><span style="color:black;background:silver">                    </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">What is your name?   </span>
<span style="color:black;background:silver">Arthur, King of the  </span>
<span style="color:black;background:silver">Britons</span><span style="color:silver;background:black"> </span><span style="color:black;background:silver">             </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">Nice to meet you,    </span>
<span style="color:black;background:silver">Arthur, King of the  </span>
<span style="color:black;background:silver">Britons.             </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>

<br clear="left">
<br>

<h3><a name="frlb">2.2. Frame and ListBox Widgets</a>
<span class="back">[<a href="#top">back to top</a>]</span></h3>

This program asks for your name and responds "Nice to meet you, (your name)"
<i>while</i> you type your name.  F8 exits.

<pre class="code">import urwid.curses_display
import urwid

class Conversation(object):
	def __init__(self):
		self.items = urwid.SimpleListWalker(
			[self.new_question()])
		self.listbox = urwid.ListBox(self.items)
		instruct = urwid.Text(&quot;Press F8 to exit.&quot;)
		header = urwid.AttrWrap( instruct, 'header' )
		self.top = urwid.Frame(self.listbox, header)

	def main(self):
		self.ui = urwid.curses_display.Screen()
		self.ui.register_palette([
			('header', 'black', 'dark cyan', 'standout'),
			('I say', 'default', 'default', 'bold'),
			])
		self.ui.run_wrapper( self.run )
	
	def run(self):
		size = self.ui.get_cols_rows()

		while True:
			self.draw_screen( size )
			keys = self.ui.get_input()
			if &quot;f8&quot; in keys:
				break
			for k in keys:
				if k == &quot;window resize&quot;:
					size = self.ui.get_cols_rows()
					continue
				self.top.keypress( size, k )
			if keys:
				name = self.items[0].edit_text
				self.items[1:2] = [self.new_answer(name)]
	
	def draw_screen(self, size):
		canvas = self.top.render( size, focus=True )
		self.ui.draw_screen( size, canvas )

	def new_question(self):
		return urwid.Edit(('I say',&quot;What is your name?\n&quot;))

	def new_answer(self, name):
		return urwid.Text(('I say',&quot;Nice to meet you, &quot;+name+&quot;\n&quot;))

Conversation().main()</pre>

<ul>
<li>In the __init__ function a list called self.items is created. It 
contains an Edit widget with the caption "What is your name?".
<li>A <a href="reference.html#ListBox">ListBox</a> widget called 
self.listbox is created that is passed the self.items list.
This ListBox widget will display and scroll through the widgets in that list.
ListBox widgets default to using the first item in the list as the focus.
<li>A <a href="reference.html#Frame">Frame</a> widget called self.top
is created that contains self.listbox and some header text. Frame widgets
wrap around a box widget and may have header and footer flow widgets.
The header and footer are always displayed. The contained box widget uses the
remaining space in between.
<li>When a key is pressed the reply text is inserted or updated in 
self.items.  This updated text will be displayed by self.listbox.
</ul>

When changing the contents of ListBox widgets remember to use in-place 
editing operations on the list, eg. "list = list + [something]" will not work,
use "list += [something]" instead.  The former code will create a new list
but the ListBox will still be displaying the old list.

<div class="shot"><pre><span style="color:black;background:teal">Press F8 to exit.    </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">   </span>
<span style="color:silver;background:black"> </span><span style="color:black;background:silver">                    </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:teal">Press F8 to exit.    </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">   </span>
<span style="color:black;background:silver">Tim t</span><span style="color:silver;background:black"> </span><span style="color:black;background:silver">               </span>
<span style="color:black;background:silver">Nice to meet you, Tim</span>
<span style="color:black;background:silver">t</span><span style="color:black;background:silver">                    </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:teal">Press F8 to exit.    </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">   </span>
<span style="color:black;background:silver">Tim the Ench</span><span style="color:silver;background:black"> </span><span style="color:black;background:silver">        </span>
<span style="color:black;background:silver">Nice to meet you, Tim</span>
<span style="color:black;background:silver">the Ench</span><span style="color:black;background:silver">             </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>
<div class="shot"><pre><span style="color:black;background:teal">Press F8 to exit.    </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">   </span>
<span style="color:black;background:silver">Tim the Enchanter</span><span style="color:silver;background:black"> </span><span style="color:black;background:silver">   </span>
<span style="color:black;background:silver">Nice to meet you, Tim</span>
<span style="color:black;background:silver">the Enchanter</span><span style="color:black;background:silver">        </span>
<span style="color:black;background:silver">                     </span>
<span style="color:black;background:silver">                     </span>
</pre></div>

<br clear="left">
<br>

<h3><a name="lbcont">2.3. Modifying ListBox Content</a>
<span class="back">[<a href="#top">back to top</a>]</span></h3>

This program asks for your name and responds "Nice to meet you, (your name)."
It then asks again, and again. Old values may be changed and the responses
will be updated when you press ENTER. F8 exits.
<br><br>
Update the <a href="#frlb">previous program</a> with this code:
<pre class="code">	def run(self):
		size = self.ui.get_cols_rows()

		while True:
			self.draw_screen( size )
			keys = self.ui.get_input()
			if &quot;f8&quot; in keys:
				break
			for k in keys:
				if k == &quot;window resize&quot;:
					size = self.ui.get_cols_rows()
					continue
				self.keypress( size, k )

	def keypress(self, size, k):
		if k == &quot;enter&quot;:
			widget, pos = self.listbox.get_focus()
			if not hasattr(widget,'get_edit_text'):
				return

			answer = self.new_answer( widget.get_edit_text() )

			if pos == len(self.items)-1:
				self.items.append( answer )
				self.items.append( self.new_question() )
			else:
				self.items[pos+1:pos+2] = [answer]

			widget.set_edit_pos(0)
			self.listbox.set_focus( pos+2, coming_from='above' )
		else:
			self.top.keypress( size, k )</pre>

<ul>
<li>In this version only the ENTER key receives special attention. When the
user presses ENTER:
  <ul>
  <li>The widget in focus and its current position is retrieved by calling the
  <a href="reference.html#ListBox-get_focus">get_focus</a> function.
  <li>If the widget in focus does not have an edit_text attribute, then it
  is not one of the Edit widgets we are interested in. 
  One of the Text widgets might receive focus
  if it covers the entire visible area of the ListBox widget and there is
  no Edit widget to take focus. While this is unlikely, it should be handled
  or the program will fail when trying to call 
  <a href="reference.html#Edit-get_edit_text">get_edit_text</a>.
  <li>If the current position is at the end of the list, a response is 
  appended followed by a new question. If the current position is not at the
  end then a previous response is replaced with an updated one.
  <li>The cursor position is moved to the far left by calling 
  <a href="reference.html#Edit-set_edit_pos">set_edit_pos</a>.
  <li>Finally, the focus is moved down two positions to the next question 
  by calling
  <a href="reference.html#ListBox-set_focus">set_focus</a>.
  </ul>
<li>All other keys are passed to the top widget to handle. The ListBox widget
does most of the hard work:
  <ul>
  <li>UP and DOWN will change the focus and/or scroll the widgets in the list
  box.
  <li>PAGE UP and PAGE DOWN will try to move the focus one screen up or down.
  <li>The cursor's column is maintained as best as possible when moving
  from one Edit widget to another.
  </ul>
</ul>

<div class="shot"><pre><span style="color:black;background:teal">Press F8 to exit.      </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">     </span>
<span style="color:black;background:silver">Abe                    </span>
<span style="color:black;background:silver">Nice to meet you, Abe</span><span style="color:black;background:silver">  </span>
<span style="color:black;background:silver">                       </span>
<span style="color:black;background:silver">What is your name?</span><span style="color:black;background:silver">     </span>