[rfc] developer documentation on user interaction

[Martin Pool]

2009/9/25 John Arbash Meinel <john at arbash-meinel.com>:
>> This actually highlights an interesting direction which is that access
>> to stdout could be mediated by the UIFactory providing a "I want to
>> provide some bulk output" operation that returns a file-like object.
>> On the terminal this could cause it to synchronize with the progress
>> bar, and in a GUI it could send it into a specific output window that
>> shows for example a text-mode diff.  I'm not sure if that's actually
>> useful, but it might be.
>>
>
> Well, we currently also have the "Command.outf" functionality. Which is
> still always bound to stdout but sometimes has unicode encoding/decoding
> enabled.

I would question whether the Command object is really the right place
for it vs the UI, and I think if it has to be explicitly passed from
the command down to whatever code actually writes, people are likely
to cheat and use stdout.

It's not very consistently used and that to me indicates it's probably
not the right interface.
>
> If we went to put something like this onto ui_factory, I'd like to see
> an object that was smarter than .write(bytes).
>
> Possibly a minimal api would be something like:
>  .write(bytes)
>  .write_unicode(Unicode)
>  (arguably you could go so far as .write_path(), .write_url()...)
>
> I think internally we know when we are writing something like a Log
> message, that should be in Unicode locally, and translated for the
> screen. Versus writing the diff output ('log -p').
>
> I believe Mercurial does this by passing a 'ui' object to most of their
> commands. Which is a bit ugly because you have to pass it through all
> the layers. Doing it as a ui_factory is nicer in that aspect, though it
> introduces global state, and makes things non-threadsafe.
>
> At the moment, we try to have functions that want to do output take a
> 'to_file' style parameter. (show_tree_status, for example), which is the
> same thing as above, only you have a simple file object, rather than
> something richer.

I think some of those methods should still take a to_file parameter.
For diff, for instance, it's quite reasonable that a gui or loggerhead
would want to generate a diff to be sent somewhere else.

> I honestly feel that Gui's should be interacting with an object model,
> and never interacting via a stdout pipe. Though qbzr's policy of
> interacting via a subprocess (to preserve interactivity in the main
> thread, IIRC) means that this is difficult.

I agree, though I think it still makes sense for the UIModel to map
some library-driven interactions onto the GUI, so that when you have
code that hasn't been rewritten as a specific GUI application it will
still do something sane, rather than writing to stdout.

-- 
Martin <http://launchpad.net/~mbp/>