SclDragString and SclDragStringConstrained

Overview

Provide feedback to define the displacement of a string from an existing position to a new position.

Note that the actual coordinates of the string are not changed. This function just returns the difference in X,Y and Z values only.

Synopsis

SclDragString StringHandle $PromptText delx dely delz
SclDragStringConstrained StringHandle $PromptText $Constraint delx dely delz

Description

The text in the PromptText argument is displayed to instruct the user to take the necessary action required to select and drag a string to a new location.

This command is only appropriate for use in a window that contains a 3D Graphics component.

The delta values that are returned to define the change in the X,Y and Z values from the current location of the string to the location where the mouse button is released.

The constrained variant restricts the freedom of the movement to be in a particular plane or direction.

Arguments

StringHandle

Passed by reference. The unique handle to the selected string is returned in this variable. This handle may be used in subsequent Scl commands to modify the coordinates or other attributes of the string.

PromptText

Passed by value. The value of this argument is displayed in the graphics prompting region to instruct the user to perform the actions to select and move the string.

Constraint

The movement of the string to its new location may be constrained to be only in a plane of interest or to just a direction of interest. Permitted values include:

XYZ

Three degrees of freedom. Movement may be in any direction and is the same as using SclDragSegment.

XY, YZ, XZ

Two degrees of freedom. Movement will only occur in the specified plane.

X, Y, Z

One degree of freedom. Movement will only occur in the specified direction.

delx, dely, delz

Passed by reference. These variables are assigned the X, Y and Z values of change in location of the selected string.

Returns

The SclDragString and SclDragStringConstrained commands return $SCL_OK if successful and $SCL_ERROR if escape is pressed.

Examples

# Drag a string with 3 degrees of freedom
set status [SclDragString string "Drag a string to a new location" delx dely delz]
if { $status == $SCL_OK } {
  puts "String coordinates = ($delx, $dely, $delz)"
} else {
  puts "Error draging string - probably cancelled by user"
}
# Drag a string in the XY plane only
set status [SclDragStringConstrained string "Drag a string to a new location" \
XY delx dely delz]
if { $status == $SCL_OK } {
  puts "String coordinates = ($delx, $dely, $delz)"
} else {
  puts "Error draging string - probably cancelled by user"
}
# Drag a string in the Z direction only
set status [SclDragStringConstrained string "Drag a string to a new location" \
Z delx dely delz]
if { $status == $SCL_OK } {
  puts "String coordinates = ($delx, $dely, $delz)"
} else {
  puts "Error draging string - probably cancelled by user"
}