Modify dialogs to allow for async usage.

[freakboy3742]

Modifies dialogs to allow for async usage.

This is primarily driven by the Android use case, which doesn't have a synchronous mode of dialog presentation; however, it also allows for simplification of dialogs on other platforms (like iOS) which require some gymnastics to support async.

This allows for both async and sync usage of dialogs. i.e., the following are all legal

# Synchronous call; but app won't wait for a response
self.main_window.info_dialog("hello", "hello world")

# Async call; app will wait for a response
await self.main_window.info_dialog("hello", "hello world")

# Asynchronous usage handling a response
if await self.main_window.question_dialog("hello", "hello world"):
    ... # process a Yes response

# Synchronous usage, handling a response
def on_result(dialog, result):
    ... # process a Yes response

self.main_window.question_dialog("hello", "hello world", on_result=on_result)

# ERROR: Synchronous usage of something that has a response
# THIS WILL RAISE AN EXCEPTION, and is a backwards incompatible API change.
if self.main_window.question_dialog("hello", "hello world"):
    ... # process a Yes response

Builds on:

• Add async Android text dialogs #987 (Thanks @paulproteus)
• Async Cocoa dialogs #1040 (Thanks @samschott)

PR Checklist:

• All new features have been tested
• All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[t-arn]

The open_file_dialog and the select_folder_dialog do not exist in Android's window.py which will probably raise an error when called. We should add these methods with a "not implemented" code or implement my file/folder chooser PR. Implementing my file/folder chooser might be problematic because we get back an URI and not a file path.

[freakboy3742]

@t-arn Totally aware of this; My intention is to merge #1158 as well, but we need to get a good handle on exactly how we're handling files, paths, permissions, etc. That will probably come after this PR, as there's a lot of other moving pieces to consider.

[codecov]

Codecov Report

Merging #1464 (ff89491) into master (581e67b) will decrease coverage by 0.01%.
The diff coverage is 95.45%.

Impacted Files	Coverage Δ
src/core/toga/window.py	98.97% <95.45%> (-1.03%)	⬇️

[samschott]

An elegant solution. Though my first instinct was: what black magic makes this work, how can a dialog be both awaitable and return a result in a regular call?

In the end, the effect of being able to await to get the result, or to set a on_result handler, works well. The doc strings however mislead me with their "Returns" documentation. In fact, the toga.Window dialog methods all return awaitables...