16.5.9 Preferences support in custom files

16.5.9.1 Creating new preferences

GPS has a number of predefined preferences to configure its behavior and its appearance. They are all customizable through the Edit->Preferences menu.

However, you might wish to add your own kind of preferences for your extension modules. This can easily be done through the usual GPS customization files. Preferences are different from project attributes (see Defining project attributes), in that the latter will vary depending on which project is loaded by the user, whereas preferences are always set to the same value no matter what project is loaded.

Such preferences are created with the <preference> tag, which takes a number of attributes.

name (mandatory)

This is the name of the preference, used when the preference is saved by GPS in the $HOME/.gps/preferences file, and to query the value of a preference interactively through the GPS.Preference class in the GPS shell or python. There are a few limitation to the form of these names: they cannot contain space or underscore characters. You should replace the latter with minus signs for instance.

page (optional, default is "General")

The name of the page in the preferences editor where the preference can be edited. If this is the name of a non-existing page, GPS will automatically create it. If this is the empty string (""), the preference will not be editable interactively. This could be used to save a value from one session of GPS to the next, without allowing the user to alter it.

Subpages are references by separating pages name with colons (':').

default (optional, default depends on the type of the preference)

The default value of the preference, when not set by the user. This is 0 for integer preferences, the empty string for string preferences, True for boolean values, and the first possible choice for choice preferences.

tip (optional, default is "")

This is the text of the tooltip that appears in the preferences editor dialog.

label (mandatory)

This is the name of the preference as it appears in the preferences editor dialog

type (mandatory)

This is the type of the preference, and should be one of:

• "boolean"

  The preference can be True or False.

• "integer"

  The preference is an integer. Two optional attributes can be specified for <preference>, "minimum" and "maximum", which define the range of valid values for that integer. Default values are 0 and 10 respectively.

• "string"

  The preference is a string, which might contain any value

• "color"

  The preference is a color name, in the format of a named color such as "yellow", or a string similar to "#RRGGBB", where RR is the red component, GG is the green component, and BB is the blue component

• "font"

  The preference is a font

• "choices"

  The preference is a string, whose value is chosen among a static list of possible values. Each possible value is defined in a <choice> child of the <preference> node.

Here is an example that defines a few new preferences:

     <?xml version="1.0"?>
     <custom>
        <preference name="my-int"
                    page="Editor"
                    label="My Integer"
                    default="30"
                    minimum="20"
                    maximum="35"
                    page="Manu"
                    type="integer" />
     
        <preference name="my-enum"
                    page="Editor:Fonts &amp; Colors"
                    label="My Enum"
                    default="1"
                    type="choices" >
          <choice>Choice1</choice>
          <choice>Choice2</choice>  <!--  The default choice -->
          <choice>Choice3</choice>
        </preference>
     </custom>

The values of the above preferences can be queries in the scripting languages:

• GPS shell

            Preference "my-enum"
            Preference.get %1
  

• Python

            val = GPS.Preference ("my-enum").get ()
            val2 = GPS.Preference ("my-int").get ()
  

16.5.9.2 Setting preferences values

You can force specific default values for the preferences in the customization files through the <pref> tag. This is the same tag that is used by GPS itself when it saves the preferences edited through the preferences dialog.

This tag requires on attribute:

name

This is the name of the preference of which you are setting a default value. Such names are predefined when the preference is registered in GPS, and can be found by looking at the $HOME/.gps/preferences file for each user, or by looking at one of the predefined GPS themes.

It accepts no child tag, but the value of the <pref> tag defines the default value of the preference, which will be used unless the user has overridden it in his own preferences file.

Any setting that you have defined in the customization files will be overridden by the user's preferences file itself, unless the user was still using the default value of that preference.

This <pref> tag is mostly intended for use through the themes (see Creating themes).