Describe Timer Dialog API

From commit messages:

Testing code: https://github.com/Luashine/wc3-test-maps/blob/1fd3cdaed228d5906a442bab27a8a9f4ce18ca55/README.md#timerdialog-api-tests

Previously I incorrectly described the r,g,b,a color values as if they were clamped to (0,255). This is not the case. The input color value is actually normalized with "value mod 256" or something similar, like an integer division.

The result is that you get the magenta color for (-257, -256, -257) as if you entered (255,0,255). The same applies to TimerDialogSetTitleColor and probably other APIs of this kind.

Relatably, the float angles of unit facing are also normalized to be in 360 range.

Test code:

mb = CreateMultiboard()
-- yes, it's mod
MultiboardSetTitleTextColor(mb, -257, -256, -257, 255)
MultiboardSetTitleText(mb, "mboard title")
MultiboardSetRowCount(mb, 1)
MultiboardSetColumnCount(mb, 1)
MultiboardSetItemsValue(mb, "ivalue")
-- yes it's mod too
MultiboardSetItemsValueColor(mb, -257, -256, -257, 255)
MultiboardDisplay(mb, true)

Extra note for clarity about colors:

-- How do colors behave?
--> Answer: their value is normalized with modulo or similar
TimerDialogSetTitleColor(tdialog, 0, 255, 0, 0) -- 100% green
TimerDialogSetTitleColor(tdialog, 0, 382, 0, 0) -- 50% green
TimerDialogSetTitleColor(tdialog, 0, 510, 0, 0) -- 100% green

TimerDialogSetTitleColor(tdialog, 0, -1, 0, 0) -- 100%
TimerDialogSetTitleColor(tdialog, 0, -240, 0, 0) -- very dark
TimerDialogSetTitleColor(tdialog, 0, -255, 0, 0) -- black
TimerDialogSetTitleColor(tdialog, 0, -256, 0, 0) -- black
TimerDialogSetTitleColor(tdialog, 0, -257, 0, 0) -- 100%
TimerDialogSetTitleColor(tdialog, -257, -257, -257, 0) -- 100%

I will probably check the rest of jassdoc where colors were used to fix those places.

lep / jassdoc

Describe Timer Dialog API #89