Positioning

There are 3 key methods to positioning items in SimpleHMI:

1. Character position
2. Pixel position (uses a "px" suffix)
3. Fractional position (uses a "%" suffix)

All of these methods may be combined with positioning relative to:

1. The left or top edge of the screen or bounding box
2. The centre of the screen or bounding box (uses a "C" prefix)
3. The right or bottom edge of the screen or bounding box (uses a negative number)

Any combination of these may be used in every instruction that takes positioning.  These concepts are succinctly explained by example.

   #HMI SetCursor( x:10, y:-2 )     ;10 chars from the left, 2 lines from the bottom

   #HMI SetCursor( x:c-2, x:c+30px );2 chars from the left of centre, 30 pixels down from centre

   #HMI SetCursor( x:-45px, y:25% ) ;45 pixels from the right, 1/4 from the top

Bounding Box

Images and buttons are positioned relative to the whole screen.  Text is drawn relative to the current bounding box which is set and cleared by the #HMI SetBounds() instruction.  The default bounding box is the whole screen.

Therefore:

• #HMI SetCursor() uses the current bounding box.
• #HMI CursorRel() uses the current bounding box.
• #HMI ButtonEvent2() uses the whole screen.
• #HMI DrawImage() uses the whole screen, but only draws the section that lies within the current bounding box (prior to V4.2 it used the whole screen).

Character positioning

Character positioning uses the dimensions of the current font.  Character positioning is performed when a position is just a number with no suffix (eg: "px" or "%").

If the font is proportional things get more complicated because characters have a varying width, so the HMI controller uses the advance of a '0' (zero) to determine the offset.  If positioning is from the right edge, it performs an initial offset of the width of the widest character.  When positioning the row, the baseline of the current font is used.

In other words, character positioning works well with non-proportional fonts such as the default system font, but works less reliably with proportional fonts.

Using the baseline means the font size can be changed and characters printed on the same line will all line up.

Examples

Print from the top left corner using a mix of font sizes.

   #HMI SetFont( "large.fon" )
   #HMI SetCursor( x:0, y:0 )    ;position using the large font to ensure there's space for it
   #HMI SetFont()                ;default font
   #HMI Print( "Normal Text " )
   #HMI SetFont( "large.fon" )
   #HMI Print( "Large Text" )
   #HMI SetFont( "small.fon" )
   #HMI Print( " and Small Text" )

Pixel Positioning

Pixel positioning uses only whole numbers and has a "px" suffix.  Some examples:

   #HMI SetCursor( x:10px, y:50px )

position the cursor 10 pixels from the left, 50 pixels from the top of the current bounds.

   #HMI SetCursor( x:-50px, y:( f(=w,3,0), "px" ) )

position the cursor 50 pixels from the right and the value in W as pixels from the top of the current bounds.

Fractional position

Fraction positioning uess a "%" suffix and is based on the current bounds.  Some examples:

   #HMI SetCursor( x:10%, y:-45.5% )

position the cursor 10% from the left, 45.5% from the bottom of the current bounds.

Left or Top Edge

A positive position number means positioning will be performed from the left or top edge.

Examples

• 2 : horizontal = 2 characters from the current left edge; vertical = 2 lines from the top.
• 25% : horizontal = 1/4 of the screen or box width from the current left edge; vertical = 1/4 of the screen or box height from the current top edge.
• 65px : horizontal = 65 pixels from the current left edge; vertical = 65 pixels from the current top edge.

Centre Relative

A horizontal or vertical position the starts with "C" means relative to the centre of the current box.

Examples

• C = from the centre of the current box.
• C-5 : horizontal = 5 characters to the left of the centre of the current box; vertical = 5 rows above the centre of the current box.
• C-15px : horizontal = 15 pixels to the left of the centre of the current box; vertical =  15 pixels above the centre of the current box.
• C+2 : horizontal = 2 characters to the right of the centre of the current box; vertical = 2 rows below the centre of the current box.
• C+10% : horizontal = 10% of the current box width to the right of centre; vertical = 10% of the current box height below centre.

   #HMI SetCursor( x:C-2.5, y:C+10px )

position the cursor left 2.5 characters from the centre, 10 pixel down from the centre of the current bounds.

   #HMI DrawImage( x:C+15px, y:( "C+", f(=q,3,0), "px" ), i:"orange.png" )

draw the image 15 pixels right of centre, the value of Q down from the centre of the current bounds.

Right Edge

A negative position number means positioning will be performed from the right or bottom edge.

Examples

• -3 : horizontal = 3 characters from the current right edge; vertical = 3 lines from the bottom.
• -10% : horizontal = 1/10 of the screen or box width from the current right edge; vertical = 1/10 of the screen or box height from the current bottom edge.
• -65px : horizontal = 65 pixels from the current right edge; vertical = 65 pixels from the current bottom edge.