selecting_values_in_Qlik.md

backendApi.selectValues

The Backend API is available for extension developers as this.backendApi.

Parameters

qDimNo (Number)

Dimension number. 0 = first dimension.

qValues (Array)

Array of values (qElemNumber in the matrix from the Qlik engine) to select or deselect.

Is it array of values or array of elemNumber?

qToggleMode (Boolean )

If true, values in the field are selected in addition to any previously selected items.

If false, values in the field are selected while previously selected items are deselected.

When to use

• When developing extension

extension API.selectValues

Parameters

dimNo (Number)

Dimension number (ignored if listbox)

values (Array)

Array of values to select

toggleMode (Boolean )

If true, values in the field are selected in addition to any previously selected items.

If false, values in the field are selected while previously selected items are deselected.

field API.selectValues

[ ENGINE ] Field Class.LowLevelSelect

Selects some values in a field, by entering the element numbers related to the values to select.

Parameters

qValues (Array of Integer)

Indexes (or element numbers) of the values to select.

qToggleMode (Boolean)

Set to true to keep any selections present in the list object. If this parameter is set to false, selections made before accepting the list object search become alternative. This parameter is mandatory.

qSoftLock (Boolean)

Set to true to ignore locks; in that case, locked fields can be selected. The default value is false. This parameter is optional.

[ ENGINE ] Field Class.SelectValues

Meaningless Promises

The field API's selectValues(...) returns a Promise, but there's no significance to the Promise (I think). For example, the documentation doesn't describe what the Promise does (also called what type of Promise; what the Promise is expected to return to us); the Qlik documentation only describes that there is a Promise:

Returns A promise.

Whereas other documentation describe what the promise returns; in this case, findAll returns a Promise, and the job of that Promise is to return to you an Array of Models that you asked to find:

public static findAll(options: Object): Promise<Array>

Qlik doesn't describe what it means when the Promise is resolved, what it means if the Promise is rejected, or what value is passed to the Promsie callback function.

By trial and error we see that selectValues() Promise resolves with a boolean true/false; i.e. Promise. The Javascript return value (a boolean) is consistent with the Engine / WebSocket / JSON RPC return value; result objects' qReturn property. It is also a boolean; and whatever value the Engine returns (here it is false); that is the value the Javascript will return

{"jsonrpc":"2.0","id":396,"result":{"qReturn":false}}

What's the significance of true vs false? Does it mean "was the select successful; can it be applied"? Does it mean "the select is finished applying; the UI should be showing the results". I think it means "is the select successful"

I get false in these cases I expect to get false (i.e. I expect failure)

• selecting a value in a locked field

I get true even in these cases I expect to get false:

• selecting a value in a field even though the value doesn't exist in that field
  • whether value doesnt exist literally i.e. "A" not in the field "B", "C", "D"
  • or the value doesnt exist in form i.e. "002" not in the numeric field 2, 3, 4 selecting

What would I get in these cases (i.e. TODO please experiment and note results):

• if I send SelectValues and its request is aborted
  • actually I dont think a SelectValues could be aborted? I think SelectValues is idempotent. I think only functions whose return values may change if they are recalled (i.e. non-idempotent?) would be aborted; as a signal client should try again ?

Different Techniques

selectMatch vs selectValues vs lowLevelSelect

Selection Window

i.e. BeginSelection and EndSelection

Aborting Selection Window

i.e. completing

Selection Mode

i.e. toggle or no