The purpose of Task is to handle Wimp task initialisation, finalisation, event
dispatching and communications with other tasks.

Task_Task
=========

Task initialisation.

- Calls Wimp_Initialise.
- Initialises event handler lists, window list, clipboard handler, menu handler
- Reads current screen info (resolution, scale factors, ...)
- Loads Sprites, Messages and Templates from
  subdirectory Resources.<configured territory number>

Task_NotTask
============

Task destructor.

- Releases the clipboard.
- Releases memory, etc.
- Calls Wimp_CloseDown
- Terminates the application.

Task_MainLoop
=============

A forever Wimp Poll loop with event dispatching.

Task_PollIdle
=============

- Calls Wimp_Poll or Wimp_PollIdle
- Gets mouse info
- returns wimp event

Task_ProcessEvent
=================

Events and messages dispatching. Can be used on events returned by Wimp_Poll
or directly on events that we generate internally to the task.

- Scans known event/messages types for a window id and do some preliminary work.
- Call event handlers in the following order until one tells us that it as
  processed the event:
  - global preprocessing event handlers
  - if a window id is known, the window event handlers attached to that window
  - global event handlers
  - internal default handler (includes sending of clipboard data to other apps)
- Reopens menus on right button clicks

Task_ProcessEventModal
======================

Preprocess some events for application (not system) wide modal boxes
Calls Task_ProcessEvent for the remaining events

Task_SubLoop
============

This call allows to write routines such as Task_PostAndWaitForReply.

- Registers a global PreEventHandler.
- Wimp_Poll loops with event dispatching until the PreEventHandler is removed.

Task_WaitReply_Handler
======================

PreEventHandler for Task_PostAndWaitForReply.

- Checks event and returns false if it is not a reply/bounce to our message.
- Unregisters itself from the list of PreEventHandler.
- Keeps track of the reply/bounce and return true.

Task_PostAndWaitForReply
========================

Posts a message to a task, returns the reply or NULL if the message bounced.
Polling occurs during that call, with normal event dispatching but it allows
you to write your code sequentially. However, beware here that if it's code from
our own task who replies that it doesn't itself uses Task_PostAndWaitForReply
or your're in trouble.

- Posts the message
- Calls Task_SubLoop to Wimp_Poll until we get a reply/bounce.

Task_WPostAndWaitForReply
========================

Posts a message to a window, returns the reply or NULL if the message bounced.

Task_RegisterEventHandler
=========================

Registers a global PreEventHandler or a normal EventHandler.

Task_DeRegisterEventHandler
===========================

Unregisters a global PreEventHandler or a normal EventHandler.

...
===

Explicit calls.

Clipboard_ClaimCaret
====================

Clipboard_Claim
===============

Store data onto the clipboard.

- Tells other tasks that they don't own the clipboard anymore.
- Clears the contents of the clipboard if we already owned it.
- Fill the contents of the clipboard with new data.

Clipboard_Release
=================

Clears the contents of the clipboard if we owned it.

Clipboard_Paste
===============

Ask for the content of the clipboard to be send to us.

- Broadcasts a message requesting the clipboard owner to
  initiate a data save via Message_DataSave to a given window,
  handle (icon or other) and mouse position in one of the
  fileformats from the list.
- Returns the reference of our message as the Message_DataSave
  will use this reference.

Clipboard_AllowPaste
====================

Checks that there is some data available in the appropriate format into the
clipboard. If our task owns the clipboard this call sends a Message_DataRequest 
and Wimp_Polls for the answer. This leads to problems while processing
a Message_MenuWarning because the Wimp expects you to open the submenu before
the next Wimp_Poll. To go around this, call Clipboard_AllowPaste before opening
the main menu with send = true to let the framework memorise the return value
when the clipboard is owned by another task. Then on Message_MenuWarning only
call Clipboard_AllowPaste with send = false which will return the memorised
value if you don't own the clipboard (the value will be updated correctly if
you choosed Cut/Copy in the menu with a right button click and became owner
of the clipboard in between the successive displays of the submenu).