GUITransform

(Engine-Level Function)

Description:	Applies a graphical transformation to all graphics in a module and returns an indication when selected by a mouse button or the <ENTER> key.
Returns:	GUI Object Return Codes
Usage:	Steady State only.
Function Groups:	Graphics, Advanced Module
Related To:	GetXformRefBox \| ImageParmSet \| NextFocusID \| Normalize \| Point \| Rotate \| Trajectory \| UnTransform \| Vertex \| VStatus \| Window
Format:	GUITransform(LeftReference, BottomReference, RightReference, TopReference, ScaleLeft, ScaleBottom, ScaleRight, ScaleTop, ScaleWhole, Trajectory, Rotation, Visibility, Options, Button, FocusID, FocusTrigger, ModuleCall)
Parameters:

LeftReference

A constant number that gives the left side reference coordinate. It must be a constant. A variable or expression is not valid here.

BottomReference

A constant number that gives the bottom side reference coordinate. It must be a constant. A variable or expression is not valid here. The top and bottom references are measured down from the top of the screen.

RightReference

A constant number that gives the right side reference coordinate. It must be a constant. A variable or expression is not valid here.

TopReference

A constant number that gives the top side reference coordinate. It must be a constant. A variable or expression is not valid here.

ScaleLeft

Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales this side from its reference position with respect to the opposite side. If it is a numeric expression, a value of 1 will place the side at its reference position. A value of 0 will place it at the opposite side reference position. Similarly, a Normalize value will scale the side between the high and low limits. If the value is at the high level, the side will be at its reference position. If the value is at the low level, the side will be at the opposite side reference position.

ScaleBottom

ScaleRight

ScaleTop

ScaleWhole

Required. Either a numeric expression, or any expression that returns a Normalize value. This parameter scales the horizontal and vertical dimensions by the specified factor before the left, bottom, right and top coordinates are scaled.

Trajectory

Required. Either a Trajectory function, a variable containing a Trajectory value, or a numeric expression. If this is a Trajectory value or function, the appropriate translation is applied to the image after the rotation is applied. If it is a valid numeric expression, the image isn't translated, but is displayed. Any other value is Invalid.

Rotation

Required. Either a Rotate function, a variable containing a Rotate value, or a numeric expression. If this is a Rotate value or function, the appropriate rotation is applied to the image before the trajectory is applied. If it is a valid numeric expression, the image is rotated clockwise the number of degrees specified. Any other value is Invalid.

Visibility

Required. Any logical expression. If true, the image is drawn normally. If false, the image is not drawn.

Options

Bit 1 (2^1) == Marks the transform as a GUIStretch. Rendering of the transform is done by stretching the content.

Bit 2 (2^2) == Transform may be dragged onto a window from the palette.

All transforms in a palette that can be dragged must have both bits set. A transform may be dragged even if its visibility flag is set to zero.

Note that only Windows with bit 22 of the Style parameter set can function as a drop-target. Windows with bit 23 of the Style parameter set are palette windows.

Button

Required. Any numeric expression giving the button combination that activates this graphic.

Value	Locator Buttons
0	No button combination will activate this graphic
1	Right button
2	Middle button
3	Right and middle buttons
4	Left button
5	Left and right buttons
6	Left and middle buttons
7	All three buttons

If the above values are multiplied by 8, the meaning for multiple buttons pressed becomes "OR" rather than "AND." For example, to accept any button on a 2 or 3 button mouse, use 56 (i.e. 8 * 7). To accept the left mouse button regardless of whether the right button is pressed, use 32 (i.e. 8 * 4).

If a 64 is added to this parameter, the function will become true when the mouse buttons are released rather than when they are pressed.

FocusID

Required. Any numeric expression from 0 to 32767 giving the focus number of this graphic. If FocusID is 0, this graphic cannot receive the input focus. This parameter's value may be used in a NextFocusID statement to force this graphic to get the focus.

FocusTrigger

Required. Any logical expression. If FocusTrigger changes from a valid false to a valid true, this graphic will attempt to obtain focus.

ModuleCall

Required. Any function containing a module call.

Comments:

This function is a layered graphics statement. See "Use Scaling to Position GUI Objects" for information about positioning a layered graphic.
The Left and Right references are interchangeable. Whichever is smaller is taken as the left and the larger of the two values will be used as the right. The same is true of the top and bottom references. Note that the 1^st 42 pixels of a VTScada application will be obscured by the title bar, if present.
This is typically used to display a module which contains an active graphics symbol.
The transformation is applied by finding the minimum area box which contains all reference box coordinates (the first 4) for all graphics active in that module. A scaling is performed on all graphics in that module to make them appear in the reference box specified in the transform.
This is typically used to make a group of objects move and scale together. For example, a module (called PumpSymbol) could draw a symbol (such as a pump). By applying a transform to this module, it can be made to appear in a certain area of the screen.
Any mouse functions contained by the transform will also be affected. For example, if the object is rotated 90 degrees XLoc will begin to behave like YLoc.

A draggable GUITransform has two renderings. The palette rendering is what is displayed in the palette and is the image attached to the mouse at the start of dragging the transform onto a drop-target window. When the mouse cursor is moved over a drop-target window, the module called by the GUITransform is rendered at the native size of the called module and displayed in its place. The rendering is scaled according to the zoom factor of the drop-target window. Moving off the drop target window again displays the palette rendering.

The relative mouse position within the graphic when the drag operation is started is maintained throughout the operation. Therefore, when the image switches from the palette rendering to the called module rendering, the mouse position within the called module rendering is over the same feature of the graphic as when the palette rendering is used.

Examples:

  GUITransform(0, 150, 100, 50 { Bounding box of object },
               1, 1, 1, 1, 1 { No scaling },
               0, 0 { No trajectory or rotation },
               1, 0 { Object is visible; reserved },
               0, 0, 0 { Graphic cannot be focused },
               Flow = PumpSymbol(1, amps) { A sample module call });

This shows a pump object in the upper left corner of the window. It cannot be focused. No extra scaling is performed, and no animation is performed.

This shows how a symbol can be defined once, and positioned in a multiple area (reused).

To use the magic formula to situate an image that reacts like a button at a position given by variables Left, Bottom, Right, Top:

[
  Left   = 100;
  Right  = 175;
  Top    = 100;
  Bottom = 135;
]

Main [
  If GUITransform(0, 1, 1, 0 { Unit bounding box },
                  1 - Left { Left scaling }, 
                  Bottom { Bottom scaling}, 
                  Right { Right scaling },
                  1 - Top { Top scaling },
                  1, 0, 0 { No overall scaling/movement },
                  1, 0 { Object is visible; default options },
                  4, 0, 0 { Respond to left-click. 
                            Graphic cannot be focused },
                  Scope(Code, "Library", TRUE)\Bitmap("Bitmaps\Symbols\Smile face.wmf"));
  [
  ...
  ]

The following displays an image that will re-size to match the Window object it is displayed within:

[
  Bottom;
  Right;
]

Main [
  Bottom = VStatus(Self(), 12); 
  Right  = VStatus(Self(), 11);
  GUITransform(0, 1, 1, 0   { Reference rectangle   },
               1- 0         { Left edge of window   },
               Bottom       { Bottom edge of window },
               Right        { Right edge of window  },
               1- 42        { Top edge of window under title bar },
               1            { No overall scaling    },
               0, 0         { Movement              },
               1, 0         { Visibility, Reserved  },
               0, 0, 0      { Selectability         },
               Scope(Code, "Library", TRUE)\Bitmap("Bitmaps\Symbols\Smile face.wmf"));
...