Global settings - arklumpus/TreeViewer GitHub Wiki

The value for a global setting can be retrieved by the module by accessing the TreeViewer.GlobalSettings.Settings.AdditionalSettings dictionary. The value will be returned as an object, which then needs to be converted into the correct type. This can be done using code similar to the following snippet:

// Define the global setting
public static List<(string, string)> GetGlobalSettings()
{
    return new List<(string, string)>()
    {
        ("Huge file threshold:", "FileSize:1073741824"),
    };
}

// ...

// In some other method (e.g. PerformAction):

    // Initialise variable with the default value.
    long hugeFileThreshold = 1073741824;

    // Check whether the global setting is available and, if so, retrieve its value and store it in the hugeFileThresholdValue object.
    if (TreeViewer.GlobalSettings.Settings.AdditionalSettings.TryGetValue("Huge file threshold:", out object hugeFileThresholdValue))
    {
        // Check whether the object is of the correct type (i.e. long)
        if (hugeFileThresholdValue is long threshValue)
        {
            // If so, update the value of the variable.
            hugeFileThreshold = threshValue;
        }
        // Check whether the object is a JsonElement (this may happen if the global setting is loaded but not parsed).
        else if (hugeFileThresholdValue is JsonElement element)
        {
            // Parse the value of the object and update the variable.
            hugeFileThreshold = element.GetInt64();
        }
    }

Care should be taken to ensure that the global setting is cast back to the correct type (in this example, long) and parsed appropriately (in this example, using the element.GetInt64() method).

The following list describes all the parameter types that can be returned by the GetGlobalSettings method, as well as the correct type to which the value should be cast and the appropriate way to parse the JsonElement.

Checkbox

Syntax

"CheckBox:<default>"

Value type and parsing strategy

bool

element.GetBoolean()

Checkboxes are specified by the CheckBox keyword; the default value can be either true or false. No additional settings are available.

Example

("Test checkbox", "CheckBox:true")

Drop-down list (combo box)

Syntax

"ComboBox:<default index>[<element1>,<element2>,...]"

Value type and parsing strategy

int

element.GetInt32()

Drop-down lists (sometimes known as combo boxes) are specified by the ComboBox keyword; the default index should be the index of the item that is initially selected in the box. The additional parameters are a list of all the items in the box.

Example

("Test drop-down:", "ComboBox:1[\"Item 0\",\"Item 1\",\"Item 2\",\"Item 3\"]")

Text box

Syntax

"TextBox:<default>"

Value type and parsing strategy

string

element.GetString()

Text boxes are specified by the TextBox keyword; the default value is the initial text of the text box. No additional settings are available.

Example

("Test text box:", "TextBox:Initial text")

Number spin box

Syntax

"NumericUpDown:<default>[<minimum>,<maximum>]"
"NumericUpDown:<default>[<minimum>,<maximum>,<increment>]"
"NumericUpDown:<default>[<minimum>,<maximum>,<increment>,<format>]"

Value type and parsing strategy

double

element.GetDouble()

Numeric spin boxes are specified by the NumericUpDown keyword; the default value is the initial value of the box. Additional settings are:

<minimum>: the minimum value (required).
<maximum>: the maximum value (required).
<increment>: the amount by which the selected value is increased or decreased when the user clicks on the spin up/down buttons.
<format>: a string used to format the value of the box (see Standard numeric format strings and Custom numeric format strings).

Note that all these values (including the minimum and maximum) must be supplied as strings in the JSON array. If the value entered in the box should have no minimum or maximum bound, a maximum or minimum of "-Infinity" or "Infinity" are accepted.

If the <increment> is omitted, the default value is computed as 1% of the <maximum> - <minimum> difference. If this is not a finite number, an increment of 1 is used.

The <format> string can be used to alter the appearance of the value in the spin box, e.g. changing the number of decimal digits, showing it as a percentage, or including a measurement unit. If the format string is not provided, it is determined automatically based on the increment, using the following criteria:

If the increment is 0, it is not finite, or its absolute value is greater than 1, the format string is "0" (i.e. show the value rounded to the next integer).
Otherwise, the order of magnitude of the value is determined as $o=-\lfloor\log_10\left|x\right| \rfloor$ and the format string is "0." followed by $o$ additional zeroes.

For example, an increment of 100.123 would result in a default format string of "0", while an increment of 0.0000123 would result in a default format string of "0.00000".

Examples

("Test numeric box 1:", "NumericUpDown:1[\"0\",\"Infinity\"]")
("Test numeric box 2:", "NumericUpDown:0.5[\"0\",\"1\",\"0.01\",\"{0:P0}\"]")
("Test numeric box 3:", "NumericUpDown:90[\"0\",\"360\",\"1\",\"{0}°\"]")

File size

Syntax

"FileSize:<default>"

Value type and parsing strategy

long

element.GetInt64()

Boxes used to enter a file size are specified by the FileSize keyword; the default value is the initial value of the box in bytes. No additional settings are available.

The measurement unit is decided base on the value:

If the size is between 0 and 1024 bytes (excluded), "bytes" (B) are used.
If the size is between 1024 B and 1024 kiB (excluded), "kibibytes" (kiB) are used.
If the size is between 1024 kiB and 1024 MiB (excluded), "mebibytes" (MiB) are used.
Otherwise, "gibibytes" (GiB) are used.

Example

("Test file size:", "FileSize:26214400")

Slider

Syntax

"Slider:<default>[<minimum>,<maximum>]"
"Slider:<default>[<minimum>,<maximum>,<format>]"

Value type and parsing strategy

double

element.GetDouble()

Sliders are specified by the Slider keyword; the default value is the initial value of the slider. Additional settings are:

<minimum>: the minimum value (required).
<maximum>: the maximum value (required).
<format>: a string used to format the value of the slider (see Standard numeric format strings and Custom numeric format strings).

Note that all these values (including the minimum and maximum) must be supplied as strings in the JSON array.

The slider is shown together with a numeric spin box that shows the current value of the slider and can be used to change it with greater precision.

The increment is computed as 1% of the <maximum> - <minimum> difference. If this is not a finite number, an increment of 1 is used. The <format> string can be used to alter the appearance of the value in the spin box, e.g. changing the number of decimal digits, showing it as a percentage, or including a measurement unit. If the format string is not provided, it is determined automatically based on the increment, using the following criteria:

If the increment is 0, it is not finite, or its absolute value is greater than 1, the format string is "0" (i.e. show the value rounded to the next integer).
Otherwise, the order of magnitude of the increment is determined as $o=-\lfloor\log_10\left|x\right| \rfloor$ and the format string is "0." followed by $o$ additional zeroes.

For example, an increment of 100.123 would result in a default format string of "0", while an increment of 0.0000123 would result in a default format string of "0.00000".

Examples

("Test slider 1:", "Slider:1[\"0\",\"100\"]")
("Test slider 2:", "Slider:0.5[\"0\",\"1\",\"{0:P0}\"]")
("Test slider 3:", "Slider:90[\"0\",\"360\",\"{0}°\"]")

Font

Syntax

"Font:[<font family>,<font size>]"

Value type and parsing strategy

VectSharp.Font

JsonSerializer.Deserialize<VectSharp.Font>(element.GetRawText(), GlobalSettings.SerializationOptions);

Font selection buttons are specified by the Font keyword; the default value is provided as a JSON string array containing the name of the font family and the size in points of the font.

The font family should be one of the 12 standard PDF font families:

Helvetica
Helvetica-Bold
Helvetica-Oblique
Helvetica-BoldOblique
Times-Roman
Times-Bold
Times-Italic
Times-BoldItalic
Courier
Courier-Bold
Courier-Oblique
Courier-BoldOblique
Symbol
ZapfDingbats

Note that the default font size should also be specified as a string.

Example

("Test font:", "Font:[\"Courier-Bold\",\"18\"]")

Point

Syntax

"Point:[<X>,<Y>]"

Value type and parsing strategy

VectSharp.Point

JsonSerializer.Deserialize<VectSharp.Point>(element.GetRawText(), GlobalSettings.SerializationOptions);

Points are specified by the Point keyword; the default value is provided as a JSON number array containing the X and Y coordinates of the point.

Example

("Test point:", "Point:[10.5,15.6]")

Colour

Syntax

"Colour:[<R>,<G>,<B>,<A>]"

Value type and parsing strategy

VectSharp.Colour

JsonSerializer.Deserialize<VectSharp.Colour>(element.GetRawText(), GlobalSettings.SerializationOptions);

Colour picker buttons are specified by the Colour keyword; the default value is provided as a JSON array of integer numbers containing the red (<R>), green (<G>), blue (<B>) and alpha (<A>) components of the colour. Each component can range from 0 to 255 (inclusive). The alpha component must always be provided, even when the colour is completely opaque (in which case it should be equal to 255).

Example

("Test colour:", "Colour:[0,162,232,255]")

Dash

Syntax

"Dash:[<units on>,<units off>,<phase>]"

Value type and parsing strategy

VectSharp.Dash

JsonSerializer.Deserialize<VectSharp.Dash>(element.GetRawText(), GlobalSettings.SerializationOptions);

Dash style buttons are specified by the Dash keyword; the default value is provided as a JSON number array containing number of units in which the dash is "on", the number of units in which it is "off", and the phase (i.e. the position along the dash pattern of the starting point).

Example

("Test dash:", "Dash:[10,10,0]")

Global settings - arklumpus/TreeViewer GitHub Wiki

Checkbox

Drop-down list (combo box)

Text box

Number spin box

File size

Slider

Font

Point

Colour

Dash

⚠️ **GitHub.com Fallback** ⚠️

⚠️ GitHub.com Fallback ⚠️