UrwidManual

= Urwid Display Modules =

== Introduction ==

Urwid's display modules provide a layer of abstraction for drawing
to the screen and reading user input.  The display module you choose
will depend on how you plan to use Urwid.

[[Image(display_modules.png)]]

Typically you will select a display module
by passing it to your MainLoop constructor, eg:

{{{
loop = MainLoop(widget, ..., screen=urwid.curses_display.Screen())
}}}

If you don't specify a display module MainLoop will use `raw_display.Screen` by default

{{{
# These are the same
loop = MainLoop(widget, ...)
loop = MainLoop(widget, ..., screen=urwid.raw_display.Screen())
}}}

== Console Display Modules `raw_display` and `curses_display` ==

Urwid has two display modules for displaying to terminals or the console.

The `raw_display` module is a pure-python display module with no external
dependencies.  It sends and interprets terminal escape sequences directly.
This is the default display module used by MainLoop.

The `curses_display` module uses the curses or ncurses library provided
by the operating system.  The library does some optimization of screen updates
and uses termcap to adjust to the user's terminal.

The (n)curses library will disable colors if it detects a monochrome terminal, 
so a separate set of attributes should be given for monochrome mode 
when registering a palette with `curses_display`.  High colors will not be used
by the `curses_dislpay` module.  See [#SettingaPalette setting a palette] below.

This table summarizes the differences between the two modules:

||                                || `raw_display` || `curses_display` ||
|| optimized C code               || no            || YES ||
|| compatible with any terminal   || no            || YES ^*^ ||
|| UTF-8 support                  || YES           || YES ^**^ ||
|| bright foreground without bold || YES ^***^     || no ||
|| 88- or 256-color support       || YES           || no || 
|| mouse dragging support         || YES           || no ||
|| external event loop support    || YES           || no ||


^*^if the termcap entry exists and TERM environment variable is set correctly[[BR]]
^**^if python is linked against the wide version of ncurses [[BR]]
^***^when using xterm or gnome-terminal

[http://excess.org/urwid/reference.html#raw_display.Screen raw_display.Screen reference]

[http://excess.org/urwid/reference.html#curses_display.Screen curses_display.Screen reference]

== AJAX-based Web Display Module `web_display` ==

The `web_display` module lets you run your application as a CGI script
under Apache instead of running it in a terminal.  

This module is a proof of concept.
There are security and responsiveness issues that need to be resolved before 
this module is recommended for production use.  

The [source:tour.py tour.py] and 
[source:calc.py calc.py] example programs demonstrate use of this module.

[http://live.excess.org/ live demo of web_display module]

[http://excess.org/urwid/reference.html#web_display.Screen web_display.Screen reference]

== Screenshot Display Module `html_fragment` ==

Screenshots of Urwid interfaces can be rendered in plain HTML.
The `html_fragment` display module lets you do this by simulating user input and capturing the
screen as fragments of HTML each time `draw_screen()` is called.  

These fragments may be included in HTML documents.  They will be rendered properly by any 
browser that uses a monospaced font for text that appears in <pre> tags.  HTML screenshots have
text that is searchable and selectable in a web browser, and they will shrink and grow when a
user changes their browser's text size.

The [http://excess.org/urwid/examples.html example screenshots] are generated with this display module.

[http://excess.org/urwid/reference.html#html_fragment.Screen html_fragment.Screen reference]

= Setting a Palette =

The MainLoop constructor takes a `palette` parameter that it passes to the 
[http://excess.org/urwid/reference.html#Screen-register_palette register_palette() method] of your
display module.

A palette is a list of palette entry names, called "attributes" and foreground and background
settings.  Display modules may be run in monochrome, normal or high color modes and you can
set different foregrounds and backgrounds for each mode as part of your palette.  eg:

{{{
loop = MainLoop(widget, palette=[
    ('headings',  'white,underline', 'black',       'bold,underline'), # bold text in monochrome mode
    ('body_text', 'dark cyan',       'light gray'),
    ('buttons',   'yellow',          'dark green',  'standout'),
    ('section_text', 'body_text'),  # alias to body_text      
    ])
}}}

The DisplayAttributes section of this manual describes all the options available.