uCalc API Version: 2.1.3-preview.2 Released: 6/16/2026

Warning

uCalc API Preview Release Notice:The documentation describes the intended behavior of the API. The current preview build contains incomplete features, unoptimized performance, and is subject to breaking changes.

Focusable = [bool]

Property

Product: 

Transformer Library

Class: 

Rule

Gets or sets a flag that allows a rule's matches to be included or excluded from a filtered result set, without deactivating the rule itself.

Remarks

The Focusable property is a lightweight flag used to control the visibility of a rule's matches in the final result set. It provides a way to filter the output of a search without deactivating the rule or re-running the entire search operation.

🎯 What is Focusable?

Think of Focusable as a tag you can apply to a rule. When you retrieve matches using Transformer.Matches() with the MatchesOption::FocusableOnly flag, only the matches from rules where Focusable is true will be included.

This is highly efficient because the Find() or Transform() operation still runs all active rules, but the final filtering of the results list is a fast, in-memory operation.

Setter and Getter Behavior

This property functions as both a getter and a setter:

  • Getter: var isFocusable = myRule.@Focusable();Returns true if the rule's matches are intended to be included in a focused view; otherwise, false.

  • Setter: myRule.@Focusable(true);Sets the state. The method returns the Rule object, allowing for a fluent, chainable syntax.

Focusable(false) vs. Active(false) vs. Release()

It is crucial to understand the difference between these three methods:

MethodPurposeEffect on MatchingReversibilityPerformance Cost to Change
@Focusable(false)Hide from filtered resultsRule still runs and participates in Transform.Reversible.None. No re-scan needed.
@Active(false)Temporarily disable ruleRule does not run or produce matches.Reversible.High. Requires re-running Find()/Transform().
Release()Permanently delete ruleRule is gone and cannot run.Irreversible.High. Requires re-running Find()/Transform().

💡 Primary Use Case: UI Highlighting

Focusable is ideal for applications like code editors or log viewers where the user might want to toggle highlighting for different types of syntax. For example, a user could check a box to "Highlight all comments." Your code would simply loop through all comment-related rules and set @Focusable(true), then refresh the display using Matches(MatchesOption::FocusableOnly) without needing to re-parse the entire document.

⚖️ Comparative Analysis

In a standard Regex library, achieving similar functionality would require significant application-side logic:

  1. Run all Regex patterns against the text.
  2. Store all Match objects in a list.
  3. For each match, determine which original pattern generated it (often requiring complex group naming or separate searches).
  4. Filter this list in your application code based on external flags.

uCalc streamlines this process by integrating the Focusable flag directly into the Rule object and providing a built-in filtering mechanism with MatchesOption::FocusableOnly. This is not only cleaner and less error-prone but also more performant as the filtering logic is handled within the optimized core engine.

Examples

Succinct: A basic demonstration of toggling the Focusable flag to filter a list of matches.
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Text = "A B C";

var ruleA = t.Pattern("A").SetFocusable(true);
var ruleB = t.Pattern("B").SetFocusable(true);
var ruleC = t.Pattern("C").SetFocusable(false); // C is not focusable
t.Find();

Console.WriteLine("--- All Matches ---");
Console.WriteLine(t.GetMatches(MatchesOption.All).Text);

Console.Write("--- Focusable Matches ---");
// This list will exclude the match for 'C'.
Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
				
			
--- All Matches ---
A
B
C
--- Focusable Matches ---A
B
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Text("A B C");

   auto ruleA = t.Pattern("A").SetFocusable(true);
   auto ruleB = t.Pattern("B").SetFocusable(true);
   auto ruleC = t.Pattern("C").SetFocusable(false); // C is not focusable
   t.Find();

   cout << "--- All Matches ---" << endl;
   cout << t.GetMatches(MatchesOption::All).Text() << endl;

   cout << "--- Focusable Matches ---";
   // This list will exclude the match for 'C'.
   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
}
				
			
--- All Matches ---
A
B
C
--- Focusable Matches ---A
B
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Text = "A B C"
      
      Dim ruleA = t.Pattern("A").SetFocusable(true)
      Dim ruleB = t.Pattern("B").SetFocusable(true)
      Dim ruleC = t.Pattern("C").SetFocusable(false) '// C is not focusable
      t.Find()
      
      Console.WriteLine("--- All Matches ---")
      Console.WriteLine(t.GetMatches(MatchesOption.All).Text)
      
      Console.Write("--- Focusable Matches ---")
      '// This list will exclude the match for 'C'.
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
   End Sub
End Module
				
			
--- All Matches ---
A
B
C
--- Focusable Matches ---A
B
Focusable to toggle pattern matches
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b>");

var BoldTag = t.Pattern("<b>{text}</b>").SetFocusable(true);
var H3Tag = t.Pattern("<h3>{text}</h3>").SetFocusable(true);
t.Find();

Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
Console.WriteLine("");

BoldTag.Focusable = false;
Console.WriteLine($"BoldTag.Focusable(): {BoldTag.Focusable}");
Console.WriteLine("--------------------------");
// t.Find(); // A Find operation does not have to be executed again
Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
Console.WriteLine("");

BoldTag.Focusable = true;
Console.WriteLine($"BoldTag.Focusable(): {BoldTag.Focusable}");
Console.WriteLine("--------------------------");

//t.Find(); // A Find operation does not have to be executed again
Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
Console.WriteLine("");
				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Focusable(): False
--------------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Focusable(): True
--------------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

#define tf(IsTrue) ((IsTrue) ? "True" : "False")

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b>");

   auto BoldTag = t.Pattern("<b>{text}</b>").SetFocusable(true);
   auto H3Tag = t.Pattern("<h3>{text}</h3>").SetFocusable(true);
   t.Find();

   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
   cout << "" << endl;

   BoldTag.Focusable(false);
   cout << "BoldTag.Focusable(): " << tf(BoldTag.Focusable()) << endl;
   cout << "--------------------------" << endl;
   // t.Find(); // A Find operation does not have to be executed again
   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
   cout << "" << endl;

   BoldTag.Focusable(true);
   cout << "BoldTag.Focusable(): " << tf(BoldTag.Focusable()) << endl;
   cout << "--------------------------" << endl;

   //t.Find(); // A Find operation does not have to be executed again
   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
   cout << "" << endl;
}
				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Focusable(): False
--------------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Focusable(): True
--------------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      t.Str("<h3>Title</h3><b>Bold statement</b><h3>Title B</h3><b>Other text</b>")
      
      Dim BoldTag = t.Pattern("<b>{text}</b>").SetFocusable(true)
      Dim H3Tag = t.Pattern("<h3>{text}</h3>").SetFocusable(true)
      t.Find()
      
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
      Console.WriteLine("")
      
      BoldTag.Focusable = false
      Console.WriteLine($"BoldTag.Focusable(): {BoldTag.Focusable}")
      Console.WriteLine("--------------------------")
      '// t.Find(); // A Find operation does not have to be executed again
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
      Console.WriteLine("")
      
      BoldTag.Focusable = true
      Console.WriteLine($"BoldTag.Focusable(): {BoldTag.Focusable}")
      Console.WriteLine("--------------------------")
      
      '//t.Find(); // A Find operation does not have to be executed again
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
      Console.WriteLine("")
   End Sub
End Module
				
			
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>

BoldTag.Focusable(): False
--------------------------
<h3>Title</h3>
<h3>Title B</h3>

BoldTag.Focusable(): True
--------------------------
<h3>Title</h3>
<b>Bold statement</b>
<h3>Title B</h3>
<b>Other text</b>
Focusable to select only patterns from local transformer
				
					using uCalcSoftware;

var uc = new uCalc();
var t = uc.NewTransformer();
var FruitsXML =
"""

<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>

""";

// List names of fruit within comment, not the whole comment as well
t.Text = FruitsXML;
var CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false);
var CommentedFruitsTr = CommentedFruits.LocalTransformer;
CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable = true;

t.Filter();
Console.WriteLine("With Focusable()");
Console.WriteLine("----------------");
Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text);
Console.WriteLine("");

// Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
Console.WriteLine("Without Focusable()");
Console.WriteLine("-------------------");
Console.WriteLine(t.Matches.Text);
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
				
					#include <iostream>
#include "uCalc.h"

using namespace std;
using namespace uCalcSoftware;

int main() {
   uCalc uc;
   auto t = uc.NewTransformer();
   auto FruitsXML =
   R"(
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>
)";

   // List names of fruit within comment, not the whole comment as well
   t.Text(FruitsXML);
   auto CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false);
   auto CommentedFruitsTr = CommentedFruits.LocalTransformer();
   CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable(true);

   t.Filter();
   cout << "With Focusable()" << endl;
   cout << "----------------" << endl;
   cout << t.GetMatches(MatchesOption::FocusableOnly).Text() << endl;
   cout << "" << endl;

   // Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
   cout << "Without Focusable()" << endl;
   cout << "-------------------" << endl;
   cout << t.Matches().Text() << endl;
}
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
				
					Imports System
Imports uCalcSoftware
Public Module Program
   Public Sub Main()
      Dim uc As New uCalc()
      Dim t = uc.NewTransformer()
      Dim FruitsXML =
      "
<Fruits>
  <Fruit CommonName='Apple' ScientificName='Malus domestica' />
  <Fruit CommonName='Banana' ScientificName='Musa acuminata' />
  <Fruit CommonName='Orange' ScientificName='Citrus × sinensis' />
  <!-- <Fruit CommonName='Grapes' ScientificName='Vitis vinifera' /> -->
  <Fruit CommonName='Strawberry' ScientificName='Fragaria × ananassa' />
  <Fruit CommonName='Pineapple' ScientificName='Ananas comosus' />
  <!-- <Fruit CommonName='Mango' ScientificName='Mangifera indica' /> -->
  <Fruit CommonName='Blueberry' ScientificName='Vaccinium corymbosum' />
  <!-- <Fruit CommonName='Rambutan' ScientificName='Nephelium lappaceum' /> -->
  <Fruit CommonName='Salak (Snake Fruit)' ScientificName='Salacca zalacca' />
  <Fruit CommonName='Jabuticaba' ScientificName='Plinia cauliflora' />
  <!-- <Fruit CommonName='Watermelon' ScientificName='Citrullus lanatus' /> -->
</Fruits>
"
      
      '// List names of fruit within comment, not the whole comment as well
      t.Text = FruitsXML
      Dim CommentedFruits = t.Pattern("<!-- {comment} -->").SetFocusable(false)
      Dim CommentedFruitsTr = CommentedFruits.LocalTransformer
      CommentedFruitsTr.FromTo("CommonName={@string:text}", "{text}").Focusable = true
      
      t.Filter()
      Console.WriteLine("With Focusable()")
      Console.WriteLine("----------------")
      Console.WriteLine(t.GetMatches(MatchesOption.FocusableOnly).Text)
      Console.WriteLine("")
      
      '// Note: The displayed Fruit element is modified by CommentedFruitsTr.FromTo()
      Console.WriteLine("Without Focusable()")
      Console.WriteLine("-------------------")
      Console.WriteLine(t.Matches.Text)
   End Sub
End Module
				
			
With Focusable()
----------------
Grapes
Mango
Rambutan
Watermelon

Without Focusable()
-------------------
<!-- <Fruit Grapes ScientificName='Vitis vinifera' /> -->
Grapes
<!-- <Fruit Mango ScientificName='Mangifera indica' /> -->
Mango
<!-- <Fruit Rambutan ScientificName='Nephelium lappaceum' /> -->
Rambutan
<!-- <Fruit Watermelon ScientificName='Citrullus lanatus' /> -->
Watermelon
Previous
Next