GNU Info

(sawfish.info)Customization

---

Next: Window Frames Prev: Windows Up: Top

---

Enter node , (file) or (file)node

Customization
*************

   Sawfish provides two levels of configuration:

  1. "customization": setting variables to change the behavior of
     existing features of the window manager, and,

  2. "extensibility": the ability to add entirely new features to the
     window manager through the creation of new Lisp modules.

   Obviously the first of these requires a lot less specialized
knowledge than the second. But even then, the user has to edit startup
files containing the Lisp forms setting the variables. To remove this
need for hand-editing, Sawfish has a specialized system allowing all
customizations to be made through a GUI, and then automatically
reloaded each time that the window manager is started.

 - Command: customize &optional group
     Invoke the user-customization GUI. GROUP defines the class of
     customization variables to configure, or all classes if GROUP is
     undefined.

   The `sawfish-ui' program can be used to invoke the GUI manually; if
GNOME is being used, then the GNOME Control Center can also be used to
customize certain classes.

   In order to provide these customization options however, an extra
requirement is placed on the Lisp programmer. Instead of just using the
`defvar' special form to declare variables, the `defcustom' macro must
be used. This augments the variable with extra information for the GUI,
including such things as its required data type.

   Customization options are organized into groups. Each group has a
name and contains a set of related options. Currently, it is not
possible for groups to contain sub-groups.

 - Macro: defgroup group real-name &rest keys
     Declares a new customization group whose name is defined by the
     symbol GROUP. The string REAL-NAME is the title of the group as
     seen by the user.

     KEYS is a list, defining the properties of the group. The members
     of the list are grouped into pairs of elements, the first element
     names the property, the second defines its value. Currently the
     only property is `:widget', defining a function to create the
     group's UI widget.

     This macro also creates an interactive function named
     `customize:GROUP' allowing the GUI to be invoked to configure the
     new group.

 - Macro: defcustom variable value documentation &rest keys
     The first three arguments are analogous to the `defvar' special
     form, they declare a special variable stored in the symbol
     VARIABLE, whose value is set to VALUE if the variable is currently
     unbound, with a documentation string DOCUMENTATION.

     All other parameters are key-value pairs as with `defgroup'. The
     possible pairs are as follows:

    `:group GROUP'
          Specifies the customization group that this variable is a
          member of.

    `:type TYPE'
          Specifies the required type of the variable. The current
          possibilities are `boolean', `number', `string', `file-name',
          `program-name', `font', `color', `frame-style', `keymap' and
          `(set SYMBOLS...)'.

          The `boolean' type assures a value of either `nil' or `t',
          the `set' type allows the user to choose from one of the
          symbols in the list.

    `:require FEATURE'
          Denotes that the feature FEATURE must be loaded if the
          variable is set to a non-`nil' value by user customizations.
          This is necessary because customization options are loaded on
          startup, possibly before the modules that define them.

    `:allow-nil BOOL'
          Specifies whether the variable may be `nil', instead of a
          member of its actual type. This is only supported by the
          `string', `set', `font' and `color' types.

    `:set FUNCTION'
          Specifies that the variable must be set by calling FUNCTION
          instead of the default `custom-set-variable'. The function
          should accept three arguments: `(VARIABLE VALUE &optional
          REQUIRE)'.

          The usual action of this function is to translate the value
          into the correct type, then call `custom-set-variable'. This
          translation is necessary since many of the UI widgets accept
          strings representing more complex types (i.e. a color's name,
          instead of the actual object)

    `:get FUNCTION'
          Provides a function for reading the current value of the
          variable.  Should return a value that's acceptable to the UI
          widget associated with the variable. Called with a single
          argument, the symbol containing the variable.

    `:before-set FUNCTION'
    `:after-set FUNCTION'
          Functions called both immediately before and after setting
          the value of the variable. Called with a single parameter:
          the variable itself.

    `:range (MIN . MAX)'
          The allowed range for numeric variables. If MIN is `nil' the
          the default minimum allowed value is zero; if MAX is `nil'
          then the default maximum is unbounded.


   Note that where necessary the types themselves define default
`:set', `:get' and `:widget' values that may be overridden by values in
the `defcustom' call. Usually, however, this will not be necessary.

   Consider the following example:

     (defgroup move "Move/Resize")
     
     (defcustom move-outline-mode 'opaque
       "The method of drawing windows being moved interactively."
       :type (set opaque box)
       :group move)
     
     (defcustom move-snap-epsilon 8
       "Proximity in pixels before snapping to a window edge."
       :group move
       :type number
       :range (0 . 64))

This defines a group and two customization options.