Function Attributes

Vocola supports three .NET attributes, which may appear before an extension function to declare something about its properties. In addition to the VocolaFunction attribute declaration used to identify extension functions, Vocola supports the attribute declarations ClearDictationStack and CallEagerly.

Most extension developers won't need these additional attributes, but they are useful in some cases.

The 'ClearDictationStack' attribute

This attribute relates to Vocola dictation. Note that Vocola modifies the just-dictated phrase by first sending enough "backspace" keystrokes to remove it, so modification will not work correctly if the insertion point moves from the end of the just-dictated phrase. To be conservative Vocola disables modification of the just-dictated phrase (by clearing the internal stack of dictated phrases) after any function call which might move the insertion point or switch the window focus. Extension functions may indicate the desired behavior via the ClearDictationStack attribute.

By default Vocola assumes that an extension function which returns a value has no side effects, and so will preserve the dictation stack. Conversely Vocola assumes that an extension function which returns void does have side effects, and so will clear the dictation stack. You may use the ClearDictationStack attribute for exceptional cases. Use the declaration:

    [ClearDictationStack(false)]

for extension functions which return void but should preserve the dictation stack. For example, the library function Wait uses this declaration because it returns void but does not affect the insertion point. Or, use the declaration:

    [ClearDictationStack(true)]

for extension functions which return a value but should clear the dictation stack. This is less-commonly needed.

The 'CallEagerly' attribute

This attribute controls the timing of function calls. If a function performs computation, calls to that function should be evaluated eagerly so the return value is available to be passed to other functions or concatenated in a keystroke sequence. But if a call performs actions which affect the state of an application or the operating system, calls to that function should be evaluated lazily so that actions are performed in the proper sequence. Extension functions may indicate the desired behavior via the CallEagerly attribute.

By default, extension functions which return a value are called eagerly and extension functions which return void are called lazily. You may use the CallEagerly attribute for exceptional cases. Use the declaration:

    [CallEagerly(false)]

for extension functions which return a value but should be called lazily. For example, the library function Clipboard.GetText uses this declaration; otherwise action sequences such as

    {Ctrl+c} Clipboard.GetText()

would not behave as intended since the clipboard contents would be retrieved by an eager call before being set by the keystroke {Ctrl+c}. Or, use the declaration:

    [CallEagerly(true)]

for extension functions which return void but should be called eagerly. This is less-commonly needed.

See Action Evaluation for more information about how Vocola evaluates function calls and other actions.