Window handles

Features of the handle

In the past window handles have always been related to the internal window structure by a known algorithm. As of Wimp 5.93, this algorithm will no longer be used. There should be no clients which access the internal Wimp structures, so this should not be an issue.

Features of the previous algorithm were used by certain clients for their internal functioning, although this was never documented. For completeness, the following is true of the new algorithm and the old :

  • Bit 0 will always be set.

This feature can be used in traversing menu structures. A menu pointer with bit 0 set is actually a window handle.

  • Bit 31 will never be set.

This feature has been used to check that the window handle is valid by never being negative.

  • The handle will never be 0, -1, -2, or -3.

These values may be safely used by clients to indicate the non-existance of a window internally. The special values -1, -2 and -3 are used by some interfaces to indicate iconbar, top, bottom and hidden windows. These values actually fall into the above two categories, but are explicitly documented here for clarity.

Despite being documented here, clients should not rely on the window handle having any meaning where possible.

This documentation is copyright 3QD Developments Ltd 2013 and may not be reproduced or published in any form without the copyright holders permission. RISC OS is subject to continuous development and improvement as such all information is reproduced by 3QD Developments Ltd in good faith and is believed to be correct at the time of publication E&OE. 3QD Developments Ltd cannot accept any liability for any loss or damage arising from the use of any information provided as part of the RISC OS Documentation.

HTML document version 1.03 3rd November 2015