#165 TTooltip overhaul

[Vidar Hasfjord]

While TTooltip has been improved over the years, it is still awkward to use.

I propose we change that and thoroughly overhaul it for usability and safety.

• Functions like TToolInfo::GetRect should return the result in the function return value, not take output parameters. Also, where applicable, we should use exceptions instead of error return value.

• TTooltip should minimise the use of the complex TToolInfo parameter package, and instead use explicit overloads with the parameters needed. TToolInfo should ideally be used only for returning packaged information about a tool. For simple enquires, such as GetText, a simple string should be returned instead. TToolInfo, with its internal text buffer, should be made safe to copy, and slicing issues should be prevented, i.e. operations that leaves the base structure separated from the buffer.

• Iterating over the registered tools and accessing individual tools should be made simpler. I propose TTooltip::GetTools, returning a range that can be iterated over in the standard ways (e.g. with a range-based for-loop). And GetTool (int toolIndex), to complement GetToolCount.

• All functions, that need to identify the tool operated on, should support all ways of identifying a tool, i.e. by index, by tool window and ID (for rectangle tools) and by tool parent window and child window (for control tools). Due to the confusing multitude of options here, the documentation must be clear. E.g. a "tool window" is a window containing tools (rectangles or controls), not a control tool (even if a control is a tool and a window). Perhaps a clearer term would be "tool container".

• Missing functions (relative to the Windows API) should be added, e.g. TTooltip::SetTitle encapsulating TTM_SETTITLE.

• Awkward and brittle functions should be relegated to OWL5_COMPAT mode or removed, e.g. TToolInfo::GetToolWindow (misleading).

• Documentation should be improved, with links into the Windows API documentation where applicable.
  
  

[Vidar Hasfjord]

I've started working on this in [r5168].

[Vidar Hasfjord]

All the remaining requested features and changes have now been implemented in [r5201]. The changes have been merged into Owlet [r5170] [r5324].

[Vidar Hasfjord]

A regression was introduced in [r5201], causing crash in TGadget::Moved in certain tool tip related cases. It has been fixed in [r6143], and the fix has been merged into Owlet [r6144].

Another regression in the same revision [r5201], causing buffer overflow in TTooltip::GetTool, was fixed in [r6333], and the fix has been merged into Owlet [r6334].

A small improvement in the exception handling of TTooltip::GetTitle was made in [r6335] and merged into Owlet [r6336].

Corrections and improvements to the documentation was made in [r6337], and the deprecated class TToolInfo was declared [[deprecated]] in [r6338][r6340]. These changes were merged into Owlet in [r6339][r6341].

A regression triggering [bugs:#303] was fixed in [r6342], and the fix has been merged into Owlet [r6343].

The deprecated alias TTooltipHitTestInfo was declared [[deprecated]] in [r6345], and this change has been merged into Owlet [r6346].

Overlooked TTooltip::Popup was added in [r6870] along with some fixes to the new code for GetTitle, ModifyFlags and SetFlags. Documentation for GetMargin and SetMargin was improved in r[r6875]. And [bugs:#570] "Tooltip is explicitly disabled" was fixed in [r6877]. These revisions have been merged into Owlet [r6918].

Additional changes were made in Owlet [r6916] to TTooltip::TToolIterator to enable compatibility with C++20 ranges, and a minor fix to the example code was made in [r6919]. These changes have been merged into the trunk [r6922].