Difference between revisions of "ParameterEnumeration"

Latest revision as of 17:57, 16 January 2018

ParameterEnumeration is an attribute of a function that specifies a list of possible values for a function parameter. Expression Assist displays these values, along with their descriptions, to help the user when typing in a call to the function. It has no effect impact on how a parameter is evaluated or when errors are reported.

Enumerated parameter values

Some function parameters have a list of allowed values, which we call an enumerated list. For example, the «part» parameter of the DatePart function can be "Y" to get the year, "MMM" to get the three letter abbreviation for the monthor, or "MMMM" to get the full name of the month, among many other options. Expression Assist shows the enumerated list when you are entering the parameter to show you the available codes, along with text explaining each option, for example:

You can use the mouse or arrow keys to select an option from the Expression Assist popup to insert into the definition that you are typing.

Specifying enumerated parameters for a user-defined function

When writing a User-Defined Function (UDF) with one or more enumerated parameters, you can define the possible codes and descriptions using the ParameterEnumeration attribute. If you do that, Expression Assist will use them to give popup suggestions when you or others use the function.

By default, the ParameterEnumeration attribute is not visible in the Object window or Attribute panel. So, you must first make it visible, thus:

From the Object menu, select Attributes....
In the Attributes dialog, from the Class menu, select Functions.
Double click on the Parameter Enumeration attribute to turn on a check mark next to it.
Press OK
Open the Object Window for your UDF.

The ParameterEnumeration attribute should now be visible.

When adding content to this attribute, you must adhere carefully to this syntax:

 param1Name
   val1|description
   val2|description
     ⁞
   valM|description
 param2Name
   val1|description
   val2|description
     ⁞
   valN|description
 ⁞

Each enumerated parameter name appears as a single word on a line. You list only the enumerated parameters, but you may have more than one. After each parameter is a list of possible values, each on a separate line. Each value may be a number, or a text enclosed in quotes. Each value must be followed by a pipe character (|), followed by an optional description. Here is an example for a single parameter named buttons used in the built-in Error function:

   buttons
   	0|OK only
   	1|OK and Cancel (default)
   	2|Abort, Retry and Ignore
   	3|Yes, No and Cancel
   	4|Yes and No
   	5|Retry and Cancel

Notes

After you've typed information into this attribute, it's a good idea to switch its visibility off again, since it will just be a distraction to other users who view your function.
You can see ParameterEnumeration for a built-in function, after turning on the attribute in the Attributes dialog), by selecting the function from the Definition menu.
The enumerations for built-in functions are in the Analytica.ini file, located in the Analytica install directory.

History

Introduced in Analytica 4.5.

@@ Line 1: / Line 1: @@
-[[Category: Concepts]]
+[[Category: Functions]]
-The [[ParameterEnumeration]] attribute holds the list of possible values for a function parameter that gets displayed by [[Expression Assist]]. The value does not have any impact on how a parameter is evaluated or when errors are reported -- it is used solely for providing suggestions while someone it typing an expression.
+ParameterEnumeration is an attribute of a function that specifies a list of possible values for a function parameter.   [[Expression Assist]] displays these values, along with their descriptions, to help the user when typing in a call to the function. It has no effect impact on how a parameter is evaluated or when errors are reported.
-== Enumerated values ==
+== Enumerated parameter values ==
-Some function parameters have a list of possible values that they accept. We say that such a parameter has an enumerated list of values. For example, the «part» parameter of the [[DatePart]] function can take values such as <code>"Y"</code> or <code>"MMMM"</code> that indicate what part of the date you want. [[Expression Assist]] helps you remember these by showing you suggestions
+Some function parameters have a list of allowed values, which we call an ''enumerated list''. For example, the «part» parameter of the [[DatePart]] function can be <code>"Y"</code> to get the year, <code>"MMM"</code> to get the three letter abbreviation for the monthor, or <code>"MMMM"</code> to get the full name of the month, among many other options. [[Expression Assist]] shows the enumerated list when you are entering the parameter to show you the available codes, along with text explaining each option, for example:
 :[[image:DatePartPartEnum.png]]
-The [[Expression Assist]] popup shows the possible values, along with some documentation for each value.  You can use the arrow keys to select or the mouse to click on a value in the Expression Assist popup, which inserts the value into the definition that you are typing.
+You can use the mouse or arrow keys to select an option from the  [[Expression Assist]] popup to insert into the definition that you are typing.
-== Specifying for a user-defined function ==
+== Specifying enumerated parameters for a user-defined function ==
-You may want to provide the [[ParameterEnumeration]] information for one or more parameters of your own [[User-Defined Function]] (UDF). When you do this, then [[Expression Assist]] can provide the popup suggestions for values later while you are typing a call to the function.
+When writing a [[User-Defined Function]] (UDF) with one or more enumerated parameters,  you can define the possible codes and descriptions using the [[ParameterEnumeration]] attribute. If you do that, [[Expression Assist]] will use them to give popup suggestions when you or others use the function.
-By default, the [[ParameterEnumeration]] attribute is not visible in the [[Object window]] or [[Attribute panel]]. Thus, before you can edit it, you need to make is visible using these steps:
+By default, the [[ParameterEnumeration]] attribute is not visible in the [[Object window]] or [[Attribute panel]]. So, you must first make it visible, thus:
-* From the menu, go to '''Object &rarr; Attributes... &rarr; class: Functions'''.
+* From the '''Object''' menu, select '''Attributes...'''.
-* Double click on '''Parameter Enumeration''' to turn on a check mark next to it.
+* In the [[Attributes dialog]], from the  '''Class''' menu, select '''Functions'''.
+* Double click on the '''Parameter Enumeration''' attribute to turn on a check mark next to it.
 * Press '''OK'''
 * Open the [[Object Window]] for your [[User-Defined Function|UDF]].
-The [[ParameterEnumeration]] attribute should now be visible. Since this attribute is not of direct interest to users of your model, it is best to turn off visibility of this attribute after you've finished you edits. Leaving it non-visible avoids an unnecessary distraction when others are browsing your model.
+The [[ParameterEnumeration]] attribute should now be visible.
-== Syntax ==
+When adding content to this attribute, you must adhere carefully to this syntax:
-The parameter must adhere to a strict syntax of the following form:
 <pre style="background:white; border:white; margin-left: 1em;">
@@ Line 41: / Line 40: @@
 </pre>
-You only list the parameters that are enumerated, but you may have more than one. The parameter name appears as the only word on the line, while the values that follow are always followed by a pipe character (<code>|</code>).  The description of each value is optional, but the pipe character must be there. Here is an example for a single parameter named <code>buttons</code>.
+Each enumerated parameter name appears as a single word on a line. You list only  the enumerated parameters, but you may have more than one. After each parameter is a list of possible values, each on a separate line. Each value may be a number, or a text enclosed in quotes.  Each value must be followed by a pipe character (<code>|</code>), followed by an optional description. Here is an example for a single parameter named <code>buttons</code> used in the built-in [[Error]] function:
 <pre style="background:white; border:white">
@@ Line 54: / Line 53: @@
 == Notes ==
+* After you've typed information into this attribute, it's a good idea to switch its visibility off again, since it will just be a distraction to other users who view your function.
+* You can see [[ParameterEnumeration]] for a built-in function, after turning on the attribute in the [[Attributes dialog]]), by selecting the function from the [[Definition menu]].
 * The enumerations for built-in functions are in the <code>Analytica.ini</code> file, located in the Analytica install directory.
-* Once you turn on [[ParameterEnumeration]] in the [[Object Window]], you can view the [[ParameterEnumeration]] for a given built-in function by bringing up its Object Window by selecting it from the '''Definition Menu'''.
 ==History==