next up previous contents index
Next: Other Property Management Functions Up: Geometry Creation and Management Previous: Other Object Management Functions   Contents   Index

Property Management by Handles

The following functions provide an interface for working with properties.

(prpty_handle) PrptyHandle(object_handle)
This function returns a handle to the list of properties of the object referenced by the passed object handle. If the passed value is 0, the returned handle will reference the list of properties of the current cell, either the electrical or physical part depending on the display mode.

(int) PrptyNumber(prpty_handle)
This function returns the number of the property referenced by the handle.

(string) PrptyString(prpty_handle)
This function returns the string of the property referenced by the handle. The ``raw'' string is returned, meaning that if the property comes from an electrical object, all of the detail from the internal property string is returned.

(int) PrptyNext(prpty_handle)
This function causes the referenced property of the passed handle to be advanced to the next in the list. If there are no other properties in the list, the handle is closed, and 0 is returned. Otherwise, the handle (same as the argument) is returned. The number of remaining reference objects can be obtained with the HandleContent function.

(int) PrptyAdd(object_handle, number, string)
This function will create a new property using the number and string provided, on the object referenced by the handle. If the handle is 0, the property will be created in the the current cell. The object must be defined in the current cell.

In physical mode, the number argument is an integer, within the acceptable range.

Physical cell 0 - 6999, 7105 (Flags), 7198 (Template Params), 7199 (Template Script), 7300 or larger.
Physical object 0 - 6999, 7198 (Template Params), 7200 or larger.

Adding a Flags, Template Params or Template Script property will automatically remove the old property, if any. Note that pseudo-properties can be applied to physical objects.

In electrical mode, it is possible to set the name, model, value, param, other and nophys properties if the handle references an electrical device, or the same properties except for model and value if the handle references an electrical subcell, or the param and other properties in the cell. In this case, the number argument is a string, and should be a prefix of ``name'', ``model'', ``value'', ``param'', ``other'', or ``nophys''. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed. The object must be defined in the current cell, thus the mode must be electrical.

If the function succeeds, 1 is returned. otherwise 0 is returned.

(int) PrptyRemove(object_handle, number, string)
This function will remove properties matching the given number and string from the object referenced by the handle. If the handle value is 0, properties will be removed from the current cell.

In physical mode, the number argument is an integer, within the acceptable range. If the string is null or empty, only the number is used for comparison, and all properties with that number will be removed. Otherwise, if the string is a prefix of the property string and the numbers match, the property will be removed.

Physical cell 0 - 6999, 7105 (Flags), 7300 or larger.
Physical object 0 - 6999, 7300 or larger.

Note that template properties can not be removed.

In electrica mode, the name, model, value, param, other, and nophys properties can be removed from a device, and the same properties except for model and value can be removed from an electrical subcell, and param and other properties can be removed from the cell. In this case, the number argument is a string, which should be a prefix of ``name'', ``model'', ``value'', ``param'', ``other'', or ``nophys''. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed. Except for other, the string argument is ignored. For other properties, the string is used as above to identify the property to delete.

Objects must be defined in the current cell. The function returns the number of properties removed.

(prpty_handle) GetPrpHandle(number)
Since there can be arbitrarily many properties defined with the same number, a generator function is used to read properties one at a time. This function returns a handle to a list of the properties that match the number passed. This applies to the first object in the selection queue (the most recent object selected). The returned value is used by other functions to actually retrieve the property text.

If the number argument is a prefix of ``all'', then any property string will be returned. In physical mode, the number argument should otherwise be an integer. In electrical mode, the number argument is a prefix of ``name'', ``model'', ``value'', ``param'', ``other'', or ``nophys'', which is appropriate for electrical devices. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed.

(prpty_handle) GetCellPrpHandle(number)
Since there can be arbitrarily many properties defined with the same number, a generator function is used to read properties one at a time. This function returns a handle to a list of the properties that match the number passed, from the current cell. The returned value is used by other functions to actually retrieve the property text.

A prefix of the string ``all'' can be passed for the number argument, in which case the handle will reference all properties of the cell. In physical mode, the number argument should otherwise be an integer.

In electrical mode, the number argument is a prefix of ``name", ``model'', ``value'', ``param'' ``other'', or ``nophys''. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed.

(string) GetProperty(prpty_handle, number)
This function returns the string of the first property referenced by the handle that matches the number. If the number argument is a prefix of ``all'', then any property string will be returned. In physical mode, the number argument should otherwise be an integer. In electrical mode, the number argument is a prefix of ``name", ``model'', ``value'', ``param'' ``other'', or ``nophys'', which is appropriate for electrical devices. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed. The handle is set to reference the next property in the reference list, following the one returned. When there are no more properties, this function returns a null string.

If the requested property is a name property of an electrical device or subcircuit, only the name is returned (the internal property string is more complex). Otherwise the ``raw'' string is returned.

(string) GetPropertyString(object_handle, number)
This function returns the strings from properties or pseudo-properties for the object referenced by the handle, or from the current cell if the handle is 0. The function will fail if a nonzero handle argument does not reference a list of objects.

In physical mode, the function will locate a property with the given number, and return its string. If no property is found with that number, and a pseudo-property for the object matches the number, then the pseudo-property string is returned. Note that pseudo-properties are currently defined for objects, not cells. If no matching pseudo-property is found, a null string is returned. Note: objects can be modified through setting pseudo-properties using the PrptyAdd function.

In electrical mode, the number argument is a string, in which case it should be a prefix of one of ``name'', ``model'', ``value'', ``param'', ``other'', or ``nophys''. The single character string ``n'' implies name, and (additionally) ``y'' implies nophys. If the string is not recognized, other is assumed. This input is appropriate for obtaining property values from electrical devices.

If the requested property is a name property of an electrical device or subcircuit, only the name is returned (the internal property string is more complex). Otherwise the ``raw'' string is returned.


next up previous contents index
Next: Other Property Management Functions Up: Geometry Creation and Management Previous: Other Object Management Functions   Contents   Index
Stephen R. Whiteley 2006-10-23