StoreValue

Synopsis

Defun: StoreValue(
       Any, $value,
       Instance, $Instance,
       Name, $Name )
@{...} Boolean;

Description:
Stores a new value in an attribute as a dynamic rule. If the attribute exists
in an instance of a given class, you must declare the attribute as Modifiable.
If the attribute does not exist, it is created as a dynamic rule.
Any rules that were dependent on the old value are made unbound. This may result
in considerable processing behind the scenes. If unbinding dependent values is
not required, consider using ug_setCacheValue.
The new value is converted to a constant string formula that recreates the value
when evaluated. Storing list values could result in a large string, which is not
limited in length.
StoreValue does not check or compare the data type of the new value to the data
type of the target attribute. If the data types do not match, StoreValue
changes the data type of the target attribute to match the new value. When the
value has to be a number and an integer will not do, use this technique to force
it to a number.
StoreValue(1.0*newValue:, inst:, target_attr)
The new value cannot be a User datatype. You can use Instance datatypes but they
cannot be instances created from a Child List or ug_createInstance. You cannot
call StoreValue cannot from a rule that is dependent in any way on the target
attribute being modified.
StoreValue is frequently used in Knowledge Ffusion User Interface Styler
applications to control the behavior of the user interface.
This is a low-level function, which is not generally needed.
Example 1:
This example provides a technique for obtaining more control over when a rule
evaluates. Knowledge fusion first evaluates the quantity. If it is not zero,
then it evaluates the class. You have to do the storeValue() in the quantity
else no children get created since the length of FusionExpressions is zero.
See below.
#! NX/KF 4.0
Def[remove]Class: with_store_test (ug_base_part);
(Boolean) store:
@{
    ug_printmessage({"Storing"});
    StoreValue({"test1","test2"},self:,FusionExpressions);
};
(list modifiable) FusionExpressions: {};
(child list) exp:
{
#   class;      if ( store: ) then ug_expression else nullDesign;
#   quantity;   length(FusionExpressions:);
    class;      ug_expression;
    quantity;   @{ store:; length(FusionExpressions:); };
    givenname;
    @{
        ug_printmessage({"Creating Expression - " + nth(child:index:,
                          FusionExpressions:)});
        nth(child:index:, FusionExpressions:);
     };
    value; child:index:;
};
Example 2:
In this example, a UI/Style dialog exists that has a number field named OFFSET
and a toggle box named OFFSET_TOGGLE. When the toggle is checked, the user can
change the value of OFFSET. When the toggle is cleared, the OFFSET field is made
insensitive and restored to the default value. The toggle box has a "rule"
callback assigned to it in the DLG file.
# Parameters linked to the dialog
(number modifiable parameter)  offset: default_offset:;
(boolean modifiable parameter) offset_toggle: false;
# Default OFFSET value could be calculated or obtained elsewhere
(number) default_offset: 27.0;
# OFFSET field is sensitive only when toggle is checked
(boolean) offset_sens:  offset_toggle:;
# UI callback restores the default value when the toggle is cleared
(boolean) offset_toggle_vchg: if offset_toggle: then true else
          StoreValue(default_offset:, self:, offset);
Example 3:
In this example, a User Interface Styler dialog allows the user to add and remove
items from a single select list.
The dialog contains the following items:
  1. Single Select List named "LIST_BOX"
  2. String field named "NEW_ITEM"
  3. Real field named "NEW_VALUE"
  4. Push Button named "ADD_BUTTON" (Has Refresh callback)
  5. Push Button named "REMOVE_BUTTON" (Has Refresh callback)
The dialog constructor callback must be "Refresh".
#! NX/KF 4.0
DefClass: storevalue3 (ug_base_part);
# Index of the selected item
(integer parameter modifiable) list_box: 1;
# Dynamic list box contents
(list) list_box_list: loop
{
  for $item in master_list:;
  collect first($item);
};
# Master list contains data for list box and other associated data.
# Modified by the ADD and REMOVE buttons.
(list modifiable) master_list: {};
# Text box where user enters text for a new item before clicking ADD (string parameter modifiable) new_item: "";
# Number box where user enters a value before clicking ADD (number parameter modifiable) new_value: 0;
(boolean) add_button:
@{
  $new_master << sublist(master_list:, 1, list_box: - 1) +
                 {{new_item:, new_value:}} +
                 sublist(master_list:, list_box:, length(master_list:));
  StoreValue($new_master, self:, master_list); };
(boolean) remove_button:
@{
  $new_master << sublist(master_list:, 1, list_box: - 1) +
                 sublist(master_list:, list_box: + 1, length(master_list:));
  StoreValue($new_master, self:, master_list); };
Errors:
Signals an error if supplied a User datatype value to store.

Input Arguments:
value - Specify a value of any type except User.
Instance - Specify a reference chain to the instance that contains the attribute to receive the new value.
Name - Specify the name of the attribute to receive the new value.

Returns:
Boolean - Always returns true.

See Also:
self, ug_setCacheValue, UnbindSlot