[docs] cursing curses in python 3.1

[John Summerfield]

First, we will deal with spammers. You do not have permission to store 
this email in a public space unless my email address is expunged.

I am learning Python, and my references are Mark Summerfield's book on 
Python 3.0 and what I can find on the Internet.

I know little C, and have no prior experience of curses. I do remember 
Turbo Pascal, with Turbo Vision, fondly, it allowed one to write 
text-based applications with hot keys, buttons, menus etc, and all with 
the use of the mouse.

I am finding the documentation I find (when google turns up the right 
release - it tends to find earlier releases, even at python.org) is 
incomplete and/or lacks clarity regarding the use of the mouse.

I am using Python 3.1 on Debian Still In Development, on a Linux console 
and but for my wish to use the mouse, it would be in screen. I'm also 
using gpm.

There might be room for argument as to whether any of these problems 
might be to do with the python/curses rather than its documentation.

Here is the reference document:
http://docs.python.org/py3k/library/curses.html


The first problems I had is that, when I enabled the mouse using 
curses.mousemask(), I could not see what mask to use so I tried -1. This 
did not work, so I hunted further and eventually hit upon 
ALL_MOUSE_EVENTS. That didn't work differently.

What happened is that my first getch() returned curses.KEY_MOUSE. When I 
used curses.getmouse() to find what happened, it raised an exception.

I don't know what exception it raised, so I cannot selectively catch it. 
It might be curses.error, I hit on that after reading some source code 
(really!) and guessing. Anyway, that's what I'm catching.

The error message being returned is ERR. I don't have the foggiest idea 
what that means (except something didn't work), and the documentation 
does not help me resolve the problem.

Eventually, I tried it directly on a console and discovered, on a Linux 
console, it works. For diagnostic purposes, connected to localhost using 
ssh. It doesn't work through ssh either.

I then tried to find a method to see whether I have a working mouse 
(curses.has_mouse() perhaps?)

The crude hack I implemented is to, first, enable mouse events as above, 
and then if that errors, I disable them again.

I would like to see the documentation updated to reflect the 
circumstances where curses' mouse support does not work, and the 
recommended way to discover whether there is a functional mouse at all.

Had getch() not returned KEY_MOUSE, I would hardly have been better off, 
I would have clicked the mouse and had nothing happen. Which leads me to 
the next problem.

Having sorted that our, and having debugging messages popping out 
whenever I clicked the mouse, I set about creating some code to 
distinguish mouse events.

Of course, the first thing I wanted was code that would correctly 
identify when I clicked a button, and which one it was. The first part 
is easy, in fact, I already had that working. The second part was not. I 
printed out, in hex, the button state, but with no documentation that I 
could find, it was difficult matching the values I saw printed with the 
names in the web page.

I clicked the mouse buttons, repeatedly, and saw the events being 
reported by my debugging code. However, the names I found, such as 
BUTTON1_CLICKED did not match what I saw with my eyes. More debugging 
code, and I find matches with PRESS and RELEASE. Never a CLICK.

This behaviour needs to be documented, as does the question of how it 
works in, say, xterm. Is it different? I don't have X installed on Sid, 
nor python3 on anything that has.

The binary values of the constants' names also need to be documented; if 
they vary between platforms (I think I read that they do), then in the 
packaged documentation.


I also had some difficulty with curses windows on my Linux console. I 
discovered there were some things I needed to do before I could define a 
scrollable area or scroll the screen. I am not sure that all of the 
things I did are necessary.

I would like to see the page improved with examples of the calls needed 
to prepare a screen for curses, for creating windows, for scrolling 
areas of the windows, and of the use of the mouse. I don't propose 
turning the page into a tutorial, just some basic examples (similar to 
those in the man pages for mawk and gawk) would have saved me hours of 
time and frustration.

-- 
John Summerfield