Skip to content

Write or clear a preference value in memory

This operation mutates the in-memory _Preferences collection only; no database write occurs until the consumer separately calls Persist preferences.

Field Value
Operation ID OP-PREF-003
Trigger Consumer code calls Add, Remove, Clear, or Delete
Inputs Key/value pairs and optional scope
Outputs Mutated in-memory _Preferences collection; no persistence occurs until Save()
Primary components clsPreferences.Add, clsPreferences.Remove, clsPreferences.Clear, clsPreferences.Delete
Entry point SAIF.Presentation\clsPreferences.vb

Steps

Add(inKey, inValue, inScope): 1. If inKey is Nothing, no-op (BR-PREF-002). 2. Find or create (if not found) a Preference group keyed by (m_Application, PageKey(scope)) (BR-PREF-001). 3. If the key already exists in PreferenceItems, remove it first (to avoid duplicate-key exceptions), then add the new (lower-cased key, string-cast value) pair.

Remove(inKey, inScope): 1. Wraps the operation in clsLogTrace.MethodBegin()/MethodEnd() trace calls. 2. Finds the matching group by application/scope and removes the key if present. - If no matching group or key is found: no-op.

Clear(inScope): 1. Finds the matching group for the given scope and clears all its PreferenceItems, leaving the group itself in _Preferences.

Delete(): 1. Iterates all groups in _Preferences (not scoped to m_Application) and clears each group's PreferenceItems — broader in effect than Clear(), and not filtered to the current application*.

Process flow

The following diagram visualizes this operation's control flow for Add.

flowchart TD
    Start([Add key/value/scope]) --> S1{Key is Nothing?}
    S1 -->|Yes| EndNoop([No-op])
    S1 -->|No| S2[Find or create Preference group by app/scope]
    S2 --> S3{Key already exists?}
    S3 -->|Yes| S4[Remove existing key]
    S3 -->|No| S5[Add new key/value pair]
    S4 --> S5
    S5 --> EndOk([In-memory group updated])

Failure and edge-case behavior

  • Delete() clears preference items across all loaded application groups for the user, not just the current application — a broader and less targeted operation than Clear(), which is scoped to the current application*.
  • None of Add, Remove, Clear, or Delete write to the database; a subsequent explicit Save() call is required for changes to persist (Persist preferences).

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • SAIF.Presentation\clsPreferences.vb