The param module
Also see :
| Quick Notes |
- Objects, Attributes, Methods and Functions
- dialog (newer and better alternative to param for dialog creation)
Prompting dialogs, etc. :
ClearSelection() clears the selection list so that a member that was previously selected using MemberLocate() can be selected again. When a member is selected using MemberLocate() , it is highlighted in the " Secondary selection surface color " so that the user doesn't select that member again while the same script is running or when different scripts are running.
Example 1: Here's a script that demonstrates how this function works.
# Demonstration of ClearSelection().
from param import Warning, ClearSelection
from member import MemberLocate
mem1 = MemberLocate("Select a member")
Warning("The secondary selection list will be cleared.")
ClearSelection()Example 2: Here's a more practical application for this function. When the user presses " Cancel " on the dialog, the ClearSelection() function is called, and the while loop ends ( break ), and the script stops running. In this way, the secondary selection list is cleared (all members cease to be highlighted) before the next script is Run .
# While loop for changing section sizes of members.
from param import Prompt, ResponseNotOK, ClearSelection
from member import MemberLocate
sect = "W18x40"
while sect is not None:
try:
Size = Prompt(sect, "Section size:")
except ResponseNotOK:
ClearSelection()
break
mem1 = MemberLocate("Select a member")
mem1.SectionSize = Size
mem1.update()Tip: You do not need ClearSelection() for MultiMemberLocate() or SelectionAdd() . A user can simply click (
) a blank space on screen to clear the selection made using these functions. Other than exiting Modeling , ClearSelection() is the only way to clear the selection of members that was made using MemberLocate() .
RedrawScreen() does a Redraw when the Python script is Run in Modeling .
SelectionAdd(mem) adds the member object ( mem ) to the selection.
# Selects all members with the mark of the one selected.
from param import SelectionAdd, ClearSelection
from member import MemberLocate, MemberAllocated, Member
ClearSelection()
mem1 = MemberLocate("Select a member")
for mem_num in range(MemberAllocated() + 1):
try:
mem2 = Member(mem_num)
if mem1.Piecemark == mem2.Piecemark:
SelectionAdd(mem2)
except:
passSelectionRemove(mem) removes the member object ( mem ) from the selection.
# Prints a list of selected members that are not beams.
from param import SelectionRemove
from member import MultiMemberLocate
InitialList = MultiMemberLocate("Select members")
FinalList = []
for mem in InitialList:
if mem.Type == "Beam":
SelectionRemove(mem)
else:
FinalList.append(mem)
print("Number of selected members:", len(FinalList))SelectionToggle(mem) toggles the selection state of the member object ( mem ).
# Filters out beams, prints the remaining selected piecemarks.
from member import MultiMemberLocate
from param import SelectionToggle, ClearSelection
ClearSelection()
InitialList = MultiMemberLocate("Select members")
FinalList = []
for mem in InitialList:
if mem.Type == "Beam":
SelectionToggle(mem)
else:
FinalList.append(mem)
print("These are the piecemarks of the selected members:")
for mem in FinalList:
print(mem.Piecemark,)select_multiple_files("/filefolder/subfolder") launches a file selection dialog that allows the person who is running the script to select one or more files from the folder whose path is designated in parentheses and quotes. If the user presses the " Cancel " button, an empty list is returned. If the user selects one or more files then presses the " Open " button, a list of one or more filenames are returned as full paths. If you do not specify a specific file folder -- select_multiple_files() -- the " Open " dialog shows the root directory.
Example: When the following script is Run it launches a file selection dialog that allows the user to select files from the macro folder. The script then prints the list of files that the user has selected.
# Select multiple files; print the selection as a list.
from param import select_multiple_files
list = select_multiple_files("C:/sds2_7.1/macro")
print(list)
# the C:/sds2_7.1/macro directory must existStationType() returns "Ultimate Edition" or "Drafting Edition" or "Modeling Edition" or "Basic Edition" or "Viewer Edition" depending on the module in which the Python script is Run ( read-only ). Only Ultimate Edition and the Modeling Edition can Run scripts that can add or delete members, material, holes, bolts or welds, or that can change the physical characteristics of such objects in the model.
# Prints the edition in which this parametric is Run.
from param import StationType
print(StationType())# Gives a warning in editions with restrictions for parametrics.
from param import StationType, Warning
if StationType() in ["Basic Edition", "Drafting Edition"]:
Warning("This parametric won't Run!")
else:
pass # replace pass with codeyes_or_no ("prompt string", "button 1", "button 2") returns a value or string for whichever button is pressed on the dialog box that appears when the Python script is.The first argument ( "prompt string" ) must be a string and therefore must be in quotes. The second and third arguments are optional. When there is no second or third argument, this function opens an OK-Cancel dialog that returns 1 (for " Yes ") or 0 (for " No ").
# No second or third argument entered for yes_or_no.
from param import yes_or_no
response = yes_or_no("Do you want to continue")
print(response)
|
Dialog that appears when the above script is Run . Pressing " OK " returns 1. Pressing " Cancel " returns 0. |
# Buttons in dialog are "point" and 0, 0, 0.
from param import Units, yes_or_no, dim_print
from point import PointLocate, Point
Units("feet") # sets dim_print output to ft-in frac
pt1 = PointLocate("Locate a point")
pt3 = Point(0, 0, 0)
var = yes_or_no("From point or origin?", "point", pt3)
if var is "point":
pt2 = PointLocate("Locate another point")
print(dim_print(pt1.Distance(pt2)))
else:
print(dim_print(pt1.Distance(pt3)))
|
Dialog that appears when the above script is Run . Pressing " Point " returns "point". Pressing " 0, 0, 0 " returns 0, 0, 0. |
# Updates "Member hold status" of each selected member.
from member import MemberLocate
from param import ClearSelection, yes_or_no
response = 1
mems_updated = [ ]
while response == 1:
mem1 = MemberLocate("Select a member")
mem1.MarkedForHold = "Held"
mem1.Update()
mems_updated.append(mem1)
response = yes_or_no("Mark another member as held?")
for each_mem in mems_updated:
print(each_mem.Piecemark, "[",each_mem.MemberNumber,"]")
ClearSelection()Prompt(integer, "Prompt string") defines an integer prompt dialog with a single field that requires the entry of a positive or negative whole number or zero. The first argument (in parentheses) sets the default value -- it must be an integer . Do not put this first argument in quotes, or it will be interpreted as a dimension or a string.
In the following example, the Prompt() function defines an integer prompt dialog since the first argument -- 100 -- is an integer. Pressing " OK " on the dialog returns the value entered. Pressing " Cancel " returns ResponseNotOK .
# Converts a distance entered in millimeters to inches.
from param import Prompt, ResponseNotOK
try:
mm = Prompt(100, "Enter a number of millimeters:")
inches = mm / 25.4
print("The number of mm you entered =", mm)
print("This number converted to inches =", inches)
except ResponseNotOK:
print("You pressed the Cancel button.")# Raises 2 to the power the user enters, prints the result.
from param import Prompt, ResponseNotOK
try:
power = Prompt(2, "Power to raise 2 to:")
result = 2 ** power
print("You have raised 2 to the power of", power)
print("The result is", result)
except ResponseNotOK:
print("You pressed the Cancel button.")Prompt(1.0, "Prompt string") defines an float prompt dialog with a single field that requires the entry of a number and always returns a decimal number (a float). The first argument (in parentheses) sets the default value -- it must be a floating point number . Do not put this first argument in quotes, or it will be interpreted as a dimension or a string. In the following example , the Prompt() function defines a float prompt because the first argument -- 14.25 -- is a floating point number. Pressing " OK " on the dialog returns the floating point equivalent to the numerical value that is entered, even if the user enters an integer . Pressing " Cancel " returns ResponseNotOK .
# Converts decimal inches to ft-in frac and millimeters.
from param import Prompt, ResponseNotOK, Units, dim_print
Units("feet") # sets dim_print output to ft-in frac
try:
inches = Prompt(14.25, "Enter decimal inches:")
mm = inches * 25.4
print("The value (inches) you entered =", inches)
print("The value in ft-in frac =", dim_print(inches))
print("The value in millimeters =", mm)
except ResponseNotOK: # user presses "Cancel"
passPrompt("1-0", "prompt string") defines a dimension prompt dialog with a single field that displays dimension strings and allows dimension string entries when the startup code units are Units("feet") or Units("inch") or "Units("inch-fraction") and the primary dimension " Units " match those startup code units. The "prompt string" is optional. The first argument (in parentheses) is the dimension string that sets the default value -- it must be in quotes ( "1-0" ).
In the following example, the Prompt() function defines a dimension dialog since "1-2 1/4" is the function's first argument. The value the user enters to the dialog produced by this script may be in setup's primary dimension " Units " or other units . The function dim_print(inches) returns that user-entered value that is called with the variable inches in the form ft-inches fractions since Units("feet") are the startup code units in the script. The expression mm = inches * 25.4 converts the user-entered value to millimeters. Pressing " OK " on the dialog returns the user-entered value in decimal inches since Units("feet") are the startup code units. Pressing " Cancel " returns ResponseNotOK .
# Converts an imperial dimension to millimeters.
from param import Prompt, ResponseNotOK, Units, dim_print
Units("feet") # sets dim_print output to ft-in frac
try:
inches = Prompt("1-2 1/4", "Enter a dimension:")
mm = inches * 25.4
print("This dimension in ft-in frac =", dim_print(inches))
print("This dimension in decimal inches =", inches)
print("This dimension in mm =", mm)
except ResponseNotOK: # user presses "Cancel"
pass| Please note: A dimension prompt displays the default value -- "1-2 1/4" in the above script -- in setup's primary dimension " Units ". This means that if this script were run with setup's primary dimension " Units " set to ' Metric ', the prompt would show a default value of 362 , but the dim_print value for that default would still be 1-2 1/4 since Units("feet") is specified in the script. |
Prompt("string", "prompt string") defines a string prompt dialog with a single field that requires the entry of a string . The first argument (in parentheses) sets the default string -- it must be in quotes ( "string" ). Be aware that entering numbers in the string may cause it to be interpreted as a dimension.
In the following example, the Prompt() function defines a string prompt dialog since sect is the function's first argument and sect = "W18x40" . Pressing " OK " on the dialog returns the value entered. Pressing " Cancel " returns ResponseNotOK .
# While loop for changing section sizes of members. Press "Cancel" to end the operation.
from param import Prompt, ResponseNotOK, ClearSelection
from member import MemberLocate
default = "W14x90"
while default:
try:
Size = Prompt(default, "Section size:")
except ResponseNotOK: # user presses "Cancel"
break
mem1 = MemberLocate("Select a member")
mem1.SectionSize = Size
mem1.Update()
ClearSelection()Warning("string" ) opens a read-only dialog with an "OK" button on it. Pressing the "OK" button returns no value or string. The parametric continues to run after the warning dialog is dismissed. The "string" in Warning("string") is a message to the user who Runs the parametric. The message might, for example, provide instructions to the user, so that the parametric can be Run correctly. Or it might alert the user to a potentially scary event, before that event takes place. Or it might provide read-only results, as does the example below.
|
An example of the warning dialog that is generated when, in Modeling , you Run the script shown below. |
# Displays the dimensions of the selected plate.
from mtrl_list import MtrlLocate
from rect_plate import *
from bnt_plate import *
from roll_plate import *
from plate_layout import *
from param import Warning, dim_print, Units
Units("feet") # sets dim_print output to ft-in frac
try:
plate1 = MtrlLocate("Select a plate", "Single")
if plate1.MaterialType == "Plate": # user selects a plate
Warning("Plate dimensions are:\r\r"+"Width = " + dim_print(plate1.Width)+"\rThickness = "+ dim_print((plate1.Thickness)+"\rLength = " + dim_print(plate1.OrderLength))
else: # user selects a material other than plate
print("The material you selected is not a plate.")
except AttributeError: # user selects nothing, hits Esc
print("You canceled instead of selecting a plate.")
# + operator can be used to add stringsNonBlockingWarning("string") provides functionality similar to Warning() , but does not block a process. It might be used, for example, in custom member or custom component code.
|
An example of the warning dialog that is generated when, in Modeling , you Run the script shown below. |
# A parametric that calls itself a waste of time.
import param
param.NonBlockingWarning("This parametric is a waste of your time!")Units("feet" or "metric" or "inch" or "inch-fraction" or "inch-decimal") sets whether you need to make entries in inches.decimals or millimeters.decimals when you input values to a Python script.
| Units("...") | Python Input* | Python Output | dim_print |
| Units("feet") | inch.decimal | inch.decimal | ft-in fractions |
| Units("inch") | inch.decimal | inch.decimal | inches-sixteenths |
| Units("inch-fraction") | inch.decimal | inch.decimal | inches fractions |
| Units("inch-decimal") | inch.decimal | inch.decimal | inch.decimal |
| Units("metric") | mm.decimal | mm.decimal | mm.decimal |
| * Note: Python input is input to an entry window in a text editor. It is not necessarily in the same units that the user inputs to a parametric dialog, which is controlled by the primary dimension " Units " (in Home > Project Settings > Fabricator > Drawing Presentation > the " Primary Dimension " tab > ) or by style = in a script. Tip: dim() converts dimension strings to numbers and can be used to input distances to scripts. | |||
Warning : Always include the startup code Units("...") in any script that returns distances. If you do not, the script will still Run , but it will use the Units("...") that were set by the last parametric that was Run , or by the loading of custom member plugins at the time that Modeling is started, or by using Advanced Selection .
Incorrect invocations of Units() due to an invalid string generate a warning. SDS2 software versions prior to v7.244 did not provide a warning and simply treated any invalid string as equivalent to Units('feet') . An invalid string continues, at this time, to be equivalent to Units('feet') . However, it is good practice to explicitly change the specified invalid string to a valid string so that you will still be able to Run your script in future releases, when invalid strings throw an error.
SDS2 Python Prompt >>> from param import *
>>> Units("inches")
DeprecationWarning: Invalid unit string 'inches' will be an error in a future release. To preserve existing behaviour, use 'feet'.As this next example from the Python Prompt shows, the startup code Units("...") set whether return values are in inches or millimeters. Units("feet") or Units("inch") or Units("inch-fraction") or Units"inch-decimal" all set the output to be in inches ( 12.0 in the example below). Units("metric") sets the output to be in mm ( 304.0000800001 in the example below). Also note that the Units("...") affects the output for the dim_print() function.
| SDS2 Python Prompt |
|
>>> from shape import Shape
>>> from param import Units >>> Units("feet") >>> Shape("WT12x81").NominalDepth 12.0 # a number >>> from param import dim_print >>> dim_print(Shape("WT12x81").NominalDepth) '1-0' # a string >>> dim_print(13.625) '1-1 5/8' # 1 foot 1 inch and five-eighths >>> Units("metric") >>> Shape("WT12x81").NominalDepth 304.0000800001 # a number >>> Units("inch") >>> dim_print(13.625) '13-10' # 13 inches and ten-sixteenths >>> Units("inch-fraction") >>> dim_print(13.625) '13 5/8' # 13 inches and five-eighths |
A metric parametric can be Run in a Job with imperial " Units " set in Drawing Presentation (or vice-versa). If the startup code Units("...") and the Drawing Presentation " Units " do not match, the values that you input in a parametric dialog will be in the Drawing Cosmetic " Units ," unless you have specified a specific style for the entry field. The parametric will give you accurate and reliable results.
dim("dim") - click here for more information.
dim_print() - click here for more information.
PR 34729 In parametrics, added the ability to remove parametrics without user interaction. See help(param.EraseParametric) for more details. (v2016)