AlarmScreenNg 0.9.9
Filter completers

In some cases the list of possible values (strings) for particular alarm property is fixed, and can be even known in advance. The individual filter for such property can use apriori known list of possible values in two ways:

  • Use combo box where user can only select one of possible values
  • Use the completer for text field where user can type the criteria. This appears as a list of proposed completions for string entered by user

In either case, for this to work, the filter widget shal know possible values for this particular alarm property. In sumple cases list of possible values can be just hardcoded in plugin that builds widgets for structured filter (see FilterWidget). Example can be a boolean property with possible values YES/NO.

However, there are cases where list of possible values is not known until runtime. The example of such list is JCOP device types, which can differ from one project to another. In order to support building completions list at run time, AS EWO uses dedicated items in basic configuration. This sections of document describes briefly the way filter completers can be built at run time.

Completion types

There are two major types of filter completers, which affect the way the lists for completion shall be built:

  • Master completers: the list of possible values for this alarm property is fixed, in a sense that possible values do not depend on setting of filter for another alarm property. The example can be device types in the project, which is just fixed.
  • Slave completers: the list of possible values for this alarm property depends on filter setting for another property. Imagine configuration where alarm property include the rack, where device controller is placed, and the building where that rack is located. If both building and rack appear in filter widgets, then it looks natural to perform filtering in two steps:
    • First select particular building - from the list of known buildings
    • Then select one of racks in selected building
    In such situation list of possible racks for filtering shall depend on what building was selected, and the list of racks shall be refreshed every time new building is selected.
    Such 'hierarchical' selection may contain more than just 2 levels - one can imagine that particular controller in rack is also alarm property, and filter on controller is added. Then list of controllers for selection filter shall (may?) depend on selected rack.

The basic configuration contains different CTRL functions for building the lists of possible values for these two types of completers. The functions are supposed to be written in CTRL language and placed in some CTRL library (the name of library is also a part of configuration). These CTRL functions will be called directly from C++ code of AS EWO when EWO needs to build a completions list for certain filter. One can not expect that functions will be called only once (for example, when UI start) - they can be called at any moment during EWO's lifecycle.

The following secions describe API and expected functionalify for these two functions. There are constants AS_FILTER_COMPLETION_KEY_xxx declared in CTRL library AlarmScreenNg.ctl and enum FilterCompletionsType declared in the same library.

Completions list for master

The CTRL function to get a list of possible completions for master completer must have the following signature:

mapping function(string sPropName, const dyn_string &dsSelectedSystems);

Two arguments are passed to this functions:

  • sPropName: the name of alarm property for which completions are requested.
  • dsSelectedSystems: The list of system names to which AS EWO is now connected. In principle, the list of completions may depend on connected systems, for example: the list of available device types can be different in different systems. It is responsability of this function to decide if returned list of completions shall depend on connected systems or not, AS EWO itself doesn't make any assuptions on usage of this argument.

The function must return mapping with the following keys of type string (see constants AS_FILTER_COMPLETION_KEY_xxx declared in CTRL library AlarmScreenNg.ctl):

  • type: the value must be int containing the type of result, see enum FilterCompletionsType declared in the same CTRL library. This key must always be present in returned result, it determines what other keys are expected to appear in returned mapping and how AS EWO shall interpet the values for those other keys.
  • list: the value must be dyn_string. This key in mapping must be present for two possible values of type member, but content and interpretation of result by AS EWO are completely different for these cases:
    • If type member of mapping is Static (value 1), then the list is intepreted as ready to use list of completions for filter widget.
    • If f type member of mapping is Dynamic (value 2), then the returned value is interpred as 'in order to find completions for filter on this property, I need to know seeting(s) of filter(s) for other properties'. The returned strings are interpreted by AS EWO as names of other alarm properties, whose filter settings are required to find the result. In such case AS EWO will call another function with settings for requested filter(s).
  • map: the value must be mapping; this key is expected in result of function call if type member of mapping is SysRelated (value 3). The mapping is expected to contain:
    • keys are strings: names of systems
    • values are dyn_string: list of completions that shall be shown when this system is connected
    This type of result is used in situation when the list of completions shall depend on connected systems, but the list for every system is known, even if that system is not connected now (see dsSelectedSystems argument).
Note
If the value of type key in returned mapping is None (value 0), then other keys are ignored by AS EWO, even if they are present in returned result.

Completions list for slave

The CTRL function to get a list of possible completions for slave completer must have the following signature:

mapping function(string sPropName, const mapping &mFilters);

Two arguments are passed to this function:

  • sPropName: the name of alarm property for which completions are requested.
  • mFilters: the values of filters for all alarm properties, which 'masters' for filter on this alarm property. The mappng contains:
    • key: string with the name of alarm property that was returned by previous functions as a name of master.
    • value: string with current value of filter for this property
    It is not guaranteed that filters for all alarm properties, returned by call to previous function, are present in this mapping. It is not guaranteed that values for all filters in this mapping are not empty. The AS EWO just passes to this function all the information it knows at this moment, then it is responsability of this function to decide what to do with (potentially) incomplete input argument.

The mapping, returned by this function, must containe the only key of type string: list. The value for this key must be dyn_string, containing possible completions for filter.