docs: Explaining the grid layout used by TfpgRect

vs the grid layout used by Types.TRect used by the RTL.

1 files changed, 68 insertions, 3 deletions

diff --git a/docs/xml/corelib/fpg_base.xml b/docs/xml/corelib/fpg_base.xml
index 3a2600b8..ccb599d5 100644
--- a/docs/xml/corelib/fpg_base.xml
+++ b/docs/xml/corelib/fpg_base.xml
@@ -2678,10 +2678,75 @@ it is shown for the first time.</short>
       </element>
       <!-- object Visibility: default -->
       <element name="TfpgRect">
-        <short>A rectangle structure used throughout fpGUI.</short>
-        <descr>Note that this structure is not a class, so static allocations are 
+        <short>A graphical (pixel based) rectangle structure used throughout fpGUI.</short>
+        <descr><p>Note that this structure is not a class, so static allocations are 
 allowed. This makes it much easier to use in Widgets and in fpGUI internal
-messages.
+messages.</p>
+<p>
+Think of the pixel screen/grid like the grid of a spreadsheet (or as a magnified look of the top corner of your screen).
+</p>
+<pre>.
+     0   1
+   +---+---+---
+0  | x |   |
+   +---+---+---
+1  |   |   |
+   +---+---+---
+2  |   |   |
+   +---+---+---
+   |   |   |
+</pre>
+<p>
+x is at (0,0). A pixel is always 1x1, you don't get smaller (we are not using sub-pixels like on LCD screens, because they don't apply to all screens).  
+</p>
+<p>
+So with that example, Width = 1 pixel and Height = 1 pixel. In the case of 
+Classes.Bounds() the Right and Bottom values are (1,1) which looking at the 
+above image will be wrong, the pixel only covers one block, so in a screen/pixel 
+environment, Right, Bottom is also (0,0), the same as Top/Left. This is what
+TfpgRect.Right and TfpgRect.Bottom will report.
+</p>
+<pre>.
+     0   1
+   +---+---+---
+0  | x | x |
+   +---+---+---
+1  | x | x |
+   +---+---+---
+2  |   |   |
+   +---+---+---
+   |   |   |
+</pre>
+<p>
+In this example we have a rectangle. Top/Left = (0,0) and Bottom/Right = (1,1). 
+This means Width = 2 pixels and Height = 2 pixels. Clearly visible in the image 
+above.
+</p>
+<p>
+But if we call Classes.Bounds(0,0,2,2) it reports Bottom/Right as (2,2) which 
+is wrong (again looking at the image above as reference). This is my point. 
+Bounds() cannot be used in this case in a graphical environment.
+</p>
+<p>
+The reason I don't use a grid layout as shown below, is 
+because if the mouse is over the rectangle containing x, the OS (graphics system) reports its 
+position as (0,0). You don't have to have the mouse pointer over the intersecting 
+lines at (0,0) as indicated in the image below. The whole square containing 
+the x is referenced as (0,0), hence the grid layout as show in the images above,
+and what fpGUI uses. The same grid layout as used in TfpgStringGrid or any 
+Spreadsheet program etc.
+</p>
+<pre>.
+   0   1
+0  +---+---+---
+   | x |   |
+1  +---+---+---
+   |   |   |
+2  +---+---+---
+   |   |   |
+3  +---+---+---
+   |   |   |
+</pre>
 </descr>
         <errors/>
         <seealso/>