vcProperty

vcProperty is a property object with its own set of properties, methods and event handlers.

Properties
Methods
Events
Examples

Properties

Name	Type	Access	Description
CalculatedValue	<Type>	R	Gets the calculated value of property. Generally, this is used to get the result of an Expression type property whose Value is an expression passed as a string. All other types, except Distribution, would return the same as Value.
ChangeOnRebuild	Boolean	RW	Defines if component geometry is rebuilt when property value is changed.
ChangeOnReconfigure	Boolean	RW	Defines if component structure is reconfigured when property value is changed.
ChangeOnUpdate	Boolean	RW	Defines if simulation world is updated when property value is changed.
Distribution	String	RW	If Distribution type property, defines an expression to use for calculating values. Available functions include: normal( u, s ) Normal distribution for mean value u, and the standard deviation s. lognormal( u, s ) Log normal distribution for mean u, and the standard deviation s. uniform( a, b ) Uniform distribution in range a <= x < b. exponential( lambda ) Exponential distribution where the mean is 1/lambda and the variance is 1/lambda^2. gamma( k, theta ) Gamma distribution with shape k and scale theta. triangular( min, mode, max ) Triangular distribution with the specified minimum, mode and maximum values. weibull( k, lambda ) Weibull distribution with shape k and scale lambda. Tip: Use RandomStream to have the distribution use a stream for seeding a value and generating the same set of random numbers during a simulation. That is, if you reset and run a simulation you should expect the same values given in the previous simulation.
Group	Integer	RW	Defines the group assignment of property. Properties are ordered by groups, and a group number is automatically assigned at the time of creation. This order can be overridden to have properties come before or after one another when listed in the GUI.
IgnoreEvents	Boolean	RW	Defines if event passing is ignored by property, for example to avoid cyclic calls.
IsVisible	Boolean	RW	Turns on/off the visibility of property in Properties panel.
IsVisibleDesignTime	Boolean	RW	Turns on/off the visibility of property in Component Cell Graph panel.
IsDesignTime	Boolean	RW	Defines if property is used for component authoring.
IsPersistent	Boolean	RW	Defines if property value is saved with component or layout.
ListValueCount	Integer	R	Gets the number of values listed in property.
ListValues	List of vcPropertyListValue	R	Gets a list of values for property.
Magnitude	Real	R	Gets the conversion factor of unit assigned to property. The conversion factor is used to convert the value of property to and from its canonical unit. For example, if the property has a Quantity of Distance with a Unit of millimeters (mm), the magnitude is 1. If Unit is meters (m), the magnitude is 1000.0. Note: You can use setUnitMagnitude() to change the unit of property based on the current unit group of its quantity. For example, a magnitude of 10 would most likely change the unit to centimeters (cm) if the quantity of property was Distance.
MaxValue	<Type>	W	If property supports a limit constraint, defines maximum value of property.
MinValue	<Type>	W	If property supports a limit constraint, defines the minimum value of property.
Name	String	RW	Defines the name of property.
Quantity	vcScalarQuantity or vcVectorQuantity	RW	Defines the quantity of property. Tip: You assign the quantity by name using a string, for example Distance, thereby the application will search for and assign a quantity matching that name.
RandomStream	Integer	RW	If Distribution type property, defines a stream used for generating pseudo-random values. Every layout has a RandomStreams layout item, which has a set of RandomSeedN properties where N is 0 to 63, which contain the seed values for each stream. A random stream can be used in distribution function, for example normal(stream,u,s) in which stream is the index of stream in the layout to use, u is mean value and s is standard deviation.
StepValues	List of <Type>	RW	If property has a step constraint, defines a list of step values for property.
SupportsTemplate	Boolean	R	Indicates if property supports the use of a templates.
Templates	List of String	R	Gets a list of names of the templates in the property.
Type	Enumeration	R	Gets the property type. See Property Constants for more information.
Unit	vcUnit	R	Gets the unit of property. Note: Use setUnitMagnitude() to change the unit of property. The magnitude should be the conversion factor of unit in the current unit group of quantity assigned to property.
Value	<Type>	RW	Gets/Sets property value.
WritableWhenConnected	Boolean	RW	Defines if property value can be set when component of property is connected to another component via interface.
WritableWhenDisconnected	Boolean	RW	Defines if property value can be set when component of property is not connected to another component via interface.
WritableWhenSimulating	Boolean	RW	Defines if property value can be set when a simulation is running.

Methods

Name	Return Type	Parameters	Description
addValueFromTemplate	vcPropertyListValue	String prop	Adds value from template to property.
deleteValue	None	Integer index	If property has step constraint, deletes a value at a given index from property.
getValue	vcPropertyListValue	Integer index	If property has step constraint, gets value at a given index from property.
setUnitMagnitude	None	Real magnitude	Sets the unit of property based on the given magnitude. The magnitude is the conversion factor of unit you want to assign to property. The unit should belong to the current unit group of quantity assigned to property.

Events

Name	Parameters	Description
OnChanged	vcProperty property	Triggered when value of property is changed.

Examples

Example. Define min and max values of properties

from vcScript import *

comp = getComponent()

##Real property - supports limit constraint, thereby min and max range values
p = comp.getProperty("Test_Real")
if not p:
p = comp.createProperty(VC_REAL, "Test_Real", VC_PROPERTY_LIMIT)

p.MinValue = 0x00000A
p.MaxValue = 0144
p.Value = 0b00110010
print p.MinValue, p.MaxValue, p.Value
#prints 10.0 100.0 50.0

##Integer property - supports limit constraint, must pass integer values
p = comp.getProperty("Test_Integer")
if not p:
p = comp.createProperty(VC_INTEGER, "Test_Integer", VC_PROPERTY_LIMIT)

p.MinValue = int(45.5)
p.MaxValue = int(940.457)
p.Value = int(468.319)
print p.MinValue, p.MaxValue, p.Value
#prints 45 940 468

Example. Get calculated value of properties

from vcScript import *

comp = getComponent()

##Expression property - Value is the expression to be evaluated; CalculatedValue is result of expression
p = comp.getProperty("Test_Expression")
if not p:
  p = comp.createProperty(VC_EXPRESSION, "Test_Expression")

p.Value = "2+2"
print p.Value, " = ", p.CalculatedValue
#prints 2 + 2 = 4

##Real property - CalculatedValue and Value return same values
p = comp.getProperty("Test_Real")
if not p:
  p = comp.createProperty(VC_REAL, "Test_Real")

p.Value = 2+2
print p.Value, " = ", p.CalculatedValue
#prints 4.0 = 4.0

##Distribution property - CalculatedValue and Value return different values
p = comp.getProperty("Test_Distribution")
if not p:
  p = comp.createProperty(VC_DISTRIBUTION, "Test_Distribution")

p.Distribution = "normal(100.0,5.0)"
print p.Value
print p.CalculatedValue
print p.Value
#each call returns, most likely, different pseudo-random value; so printed results will vary

Example. Using a real distribution with a random stream

from vcScript import *

comp = getComponent()

prop = comp.getProperty("Test_Distribution")
if not prop:
  prop = comp.createProperty(VC_DISTRIBUTION, "Test_Distribution")

#prop.Distribution = "normal(100.0, 5.0)"
#prop.RandomStream = 4
prop.Distribution = "normal(4, 100.0, 5.0)"

def OnRun():
    count = 0
    while count < 5:
      delay(1)
      count += 1
      print prop.Value

Example. Using OnChange event

from vcScript import *

def myActionFunction(arg): #function arguments need to match with event parameters
print arg.Value

comp = getComponent()

# get handle to a property (in this example a component property)
myprop = comp.getProperty('MyParameter')
# this property needs to be a global so events registered to this stay alive
# for example -- > global myprop

myprop.OnChanged = myActionFunction #register a custom function to an event

Example. Add different types of properties to a component

from vcScript import *
comp = getComponent()

# create a new property, this returns None if property with same name already exists
prop1 = comp.createProperty(VC_REAL, 'Fever')
prop1.Value = 36.8

# another new property with step values
prop2 = comp.createProperty(VC_STRING, 'MyLocationParam', VC_PROPERTY_STEP)

# polulate drop-down menu with pre-defined values
prop2.StepValues = ['Europe', 'America', 'Asia', 'Africa', 'Australia']
# set value: option1
comp.MyLocationParam = 'Asia'
# set value: option2 --> prop2.Value = 'Asia'