Current Transform

(int) SetTransform(angle_or_string, reflection, magnification)
This function sets the ``current transform'' to the values provided. It is similar in action to the controls in the Current Transform panel. The first argument can be a floating point angle that will be snapped to the nearest multiple of 45 degrees in physical mode, 90 degrees in electrical mode. If bit 1 of reflection is set, a reflection of the x-axis is specified. If bit 2 of reflection is set, a reflection of the y-axis is specified. The magnification sets the scaling applied to transformed objects, and is accepted only while in physical mode. It is ignored if less than or equal to zero.

The first argument can alternatively be a string, in the format as returned from GetTransformString. The string will be parsed, and if no error the transform will be set. The two remaining arguments are ignored, but must be given (0 can be passed for both).

The return value is 1 on success, 0 otherwise.

Examples:

Set rotation 180, mirror the X axis:
SetTransform(180, 1, 1) or SetTransform("R180MX", 0, 0)
Set rotation 180, mirror the Y axis:
SetTransform(180, 2, 1) or SetTransform("R180MY", 0, 0)
Set rotation 180, mirror both X,Y axes:
SetTransform(180, 3, 1) or SetTransform("R180MYMX", 0, 0)

(int) StoreTransform(register)
This function will save the current transform settings into a register, which can be recalled with RecallTransform. The argument is a register number 0-5. These correspond to the ``last'' and registers 1-5 in the Current Transform pop-up. This function returns 1 on success, 0 if the argument is out of range.

(int) RecallTransform(register)
This function will restore the transform settings previously saved with StoreTransform. The argument is a register number 0-5. These correspond to the ``last'' and registers 1-5 in the Current Transform pop-up. This function returns 1 on success, 0 if the argument is out of range.

(string) GetTransformString()
Return a string describing the current transform, an empty string will indicate the identity transform. The string is a sequence of tokens and contains no white space. It is the same format used to indicate the current transform in the Xic status line. The tokens are:

[Rang][MY][MX][Mmagn]

The square brackets indicate that each token is optional and do not appear in the string. If the rotation angle is nonzero, the first token will appear, where ang is the angle in degrees. This is an integer multiple of 45 degrees in physical mode, 90 degrees in electrical mode, larger than zero and smaller than 360.

If reflection of Y or X is in force, one or both of the mext two tokens will appear. These are literal. If the magnification is not unity, the final token will appear, with magn being a real number in the range 0.001 through 1000.0.

The order of the tokens must be as shown.

The returned string, or one in the same format, can be passed to the first argument of SetTransform.

(int) GetCurAngle()
This returns the rotation angle of the current transform, in degrees. This will be 0, 45, 90, 135, 180, 225, 270, 315 in physical mode, or 0, 90, 180, 270 in electrical mode. The SetTransform function can be used to set the rotation angle.

(int) GetCurMX()
This returns 1 if the current transform mirrors the x-axis, 0 otherwise. The SetTransform function can be used to set the mirror transformations.

(int) GetCurMY()
This returns 1 if the current transform mirrors the y-axis, 0 otherwise. The SetTransform function can be used to set the mirror transformations.

(real) GetCurMagn()
This returns the magnification component of the current transform. The SetTransform function can be used to set the magnification.

(int) UseTransform(enable, x, y)
This command enables and disables use of the current transform in the ShowGhost function, as well as the functions that create objects: Box, Polygon, Arc, Wire, and Label. The functions Move, Copy, Logo, and Place naturally use the current transform and are unaffected by this function.

All arguments are numeric. If the first argument is nonzero, the current transformation will be used in subsequent calls to the functions listed above. If the first argument is zero, the current transform is ignored by these functions. The remaining arguments provide the translation applied to the object being created, before the current transform is applied.

If UseTransform(1, ...) has been given, ShowGhost will apply the current transform to the list of objects to display, using the pointer location as the translation rather than the x, y supplied to UseTransform, which are ignored. The other functions listed above will create the object after applying the current transform, using x, y.

In some scripts, it will be necessary to call UseTransform(1, ...) twice, once to enable ShowGhost, and again after the location for the new object is obtained. In particular, if Point is used to obtain the coordinate, UseTransform should be called before Point (so the ghost drawing will be accurate) and again with the coordinates returned from Point before the new object is created.

The Box function will actually create a polygon if the current transform is being used and the rotation angle is 45 degrees or one of the other non-Manhattan angles. The Polygon function will actually create a box if the rotated figure can be so represented. The Polygon function will never create boxes unless use of the current transform is enabled.

Below is an example script that will place boxes on the current layer where the user clicks. Note that the size and rotation angle of the box can be changed while in the script through the Transform Menu.

ShowPrompt("Click to place boxes")
PushGhostBox(0, 0, 1, 1)
UseTransform(1, 0, 0)
while (1)
    ShowGhost(8)
    a[2]
    if !Point(a)
        ShowPrompt("")
        Exit()
    end
    ShowGhost(0)
    UseTransform(1, a[0], a[1])
    Box(0, 0, 1, 1)
    Commit()
end