Argument#

Fully qualified name: usd_optimize::Argument

class Argument#

Generic argument class.

This class represents an argument that can configure how an operation works. It contains basic info like its name, but also more UI-specific info like its display type, things that are intended primarily to drive a user interface.

The idea is that Arguments can store enough info that all configuration for an operation can be specified within the plugin, with no extra configuration required elsewhere to build a rich user interface.

Subclassed by usd_optimize::Group

Public Functions

Argument()#: Construct an invalid argument.

Argument( const std::string &name, const std::string &displayName, const std::string &displayType, const std::string &description, const PXR_NS::JsValue &defaultValue, void *target = nullptr, )#: Construct a valid argument with primary attributes.

Argument(const Argument&) = delete#: Disable copying.

void operator=(const Argument&) = delete#

virtual ~Argument()#: Destructor.

std::string getName() const#: Returns the name of the argument.

std::string getDisplayName() const#: Returns the display name of the argument.

std::string getDisplayType() const#

Get the display type of the argument.

Some argument types may require a specific UI widget. For example, a list of strings may want be a “primPaths” widget in the UI which allows more useful controls for manipulating paths of prims (drag/drop, etc).

std::string getDescription() const#: Get the description of this argument.

PXR_NS::JsValue getDefaultValue() const#: Get the default value.

bool hasMin() const#: Returns whether this Argument has a minimum value.

float getMin() const#

Returns the minimum value for this Argument, if one is available.

Returns:: The minimum value or NaN

Argument &setMin(float minValue)#: Set the minimum value for this Argument.

bool hasMax() const#: Returns whether this Argument has a maximum value.

float getMax() const#

Returns the maximum value for this Argument, if one is available.

Returns:: The maximum value or NaN

Argument &setMax(float maxValue)#: Set the maximum value for this Argument.

bool getRejectOutOfRange() const#: Returns whether out-of-range values should be rejected instead of clamped.

Argument &setRejectOutOfRange(bool value)#

Control how values outside [min, max] are handled.

By default an out-of-range value is silently clamped into range. When this is set, such a value is instead rejected: setting arguments fails and the operation returns a failed OperationResult, so a caller cannot mistake e.g. reductionFactor=150 (clamped to a no-op “reduce to 100%”) for a successful reduction. Only meaningful together with setMin/setMax.

bool hasStep() const#

Returns whether this Argument has a step value.

Step can be used to configure stepping in a UI slider.

float getStep() const#

Returns the step value for this Argument, if one is available.

Returns:: The step value or NaN

Argument &setStep(float value)#: Set the step value for this Argument.

bool hasPrecision() const#: Returns whether this Argument has a precision value specified.

int getPrecision() const#

Gets the precision value.

Arguments can specify an optional “precision” that indicates to a user interface how many digits of precision are required. This can be used to ensure a UI can correctly display very small values, if necessary.

Returns:: The precision, or NaN

Argument &setPrecision(int precision)#: Set a precision value for this argument.

std::string getPlaceholder() const#

Get the placeholder text.

This is used by the user interface to provide a placeholder text value in some widgets. For example, in a prim paths widget this can help the user understand what adding prims to it might do.

Returns:: The placeholder text, or an empty string.

Argument &setPlaceholder(const std::string &placeholder)#

Set the placeholder text.

Sets the placeholder text to display in a UI if there is no value set.

Parameters:: placeholder – The placeholder text.
Returns:

template<typename T> inline void setEnumValues( const std::vector<std::pair<T, std::string>> &valueToNameMap, )#

Sets the mappings from enum value types to their string display name.

This info is intended to help the UI display readable names for options. Can be called using initializer list syntax: arg.setEnumValues<TestEnum>({{TestEnum::eFoo, "Foo"}, {TestEnum::eBar, "Bar"}});

Parameters:: valueToNameMap – vector of pairs that map enum value to string display name

std::vector<EnumMap> getEnumValues() const#: Get the mapping of enum values and names.

void setFloatPresets(const std::vector<FloatPreset> &presets)#

Sets the mappings from float value types to their string display name.

This info is intended to help the UI display readable names for options. Can be called using initializer list syntax: arg.setFloatPresets({{0.2, "Foo"}, {1.8, "Bar"}});

std::vector<FloatPreset> getFloatPresets() const#: Get the mapping of float values and names.

std::string getEnableIf() const#

Get the enableIf expression for this argument.

This expression is used to instruct a UI how to control the enabled state of a widget for this argument. It is expected to be a simple expression that can be eval’d by the user interface. It should evaluate to True in order to enable the widget or False in order to disable it. The expression will have access to local variables for each of the other current argument values.

The current Usd Optimize user interface is written in python, so it is assumed to be python.

For example, to enable this argument if the value of another matches some condition you would use:

otherArg > 100

Returns:: Either the expression or an empty string

Argument &setEnableIf(const std::string &expression)#: Set the enableIf expression.

std::string getVisibleIf() const#

Get the visibleIf expression for this argument.

This function is similar to getEnableIf(), but controls whether the argument is visible or hidden in the UI, rather than whether it is enabled or disabled. Otherwise it functions in the same way as enableIf.

Returns:: Either the expression or an empty string

Argument &setVisibleIf(const std::string &expression)#: Set the visibleIf expression.

bool getVisible() const#

Returns whether this argument is visible.

This controls whether a user interface should display the argument, or whether it should be hidden (for example, for internal/debug arguments).

Returns:: Whether the argument is visible

Argument &setVisible(bool value)#: Set whether the argument is visible.

Argument &setJoinNext( const std::string &name, const std::string &description, )#

Group this argument with the next argument.

For the purposes of a user interface, treat this argument and the next (and any others that continue the chain) as a group of arguments. For example, a user interface may want to group all of the arguments together, such as for individual R, G and B colors.

The first argument that specifies joinWith will have its name and description used in the UI. The following arguments should have the same join name in order to consider them a group.

Parameters:

name – The name of the group
description – An overall description for the group of arguments

Returns:

A reference to this argument for chaining functions

std::string serialize() const#: Serialize this argument to a JSON string.

virtual PXR_NS::JsValue toJson() const#: Serialize this argument to a JSON object.

void *getTarget() const#: Get the target address for populating this argument at execution time.

void setIsFloat(bool value)#

Specify this argument uses floats, not doubles.

Because JSON only supports double and not float we need to be careful to cast to the correct type when setting argument values.

bool getIsFloat() const#: Return whether this arguments data type is float rather than double.

bool getIsBool() const#: Return whether this arguments data type is bool.

bool getIsGroup() const#

Return whether this argument is a group.

Groups are for organization, so while they are “Arguments” they are treated a bit differently in various places.

void setArrayType(ArgumentArrayType type)#: Set the expected type of data an array should hold.

ArgumentArrayType getArrayType() const#: Get the type of data this arguments array is expected to hold.

Public Static Functions

static Argument *deserialize(const std::string &serialized)#: Create an Argument from a serialized representation.

Protected Attributes

Impl *pImpl#