3. Customizing MMM Mode

This chapter explains how to customize the appearance and functioning of MMM Mode however you want.

3.1 Customizing Region Coloring

By default, MMM Mode highlights all submode regions with a background color. There are three levels of this decoration, controlled by the following variable:

User Option: mmm-submode-decoration-level

This variable controls the level of coloring of submode regions. It should be one of the integers 0, 1, or 2, representing (respectively) none, low, and high coloring.

No coloring means exactly that. Submode regions have the same background as the rest of the text. This produces the minimal interference with font-lock coloration. In particular, if you want to use background colors for font-lock, this may be a good idea, because the submode highlight, if present, overrides any font-lock background coloring.

Low coloring uses the same background color for all submode regions. This color is specified with the face mmm-default-submode-face (see section `Faces' in The Emacs Manual) which can be customized, either through the Emacs "customize" interface or using direct Lisp commands such as set-face-background. Of course, other aspects of the face can also be set, such as the foreground color, bold, underline, etc. These are more likely to conflict with font-lock, however, so only a background color is recommended.

High coloring uses multiple background colors, depending on the function of the submode region. The recognized functions and their meanings are as follows:

`init'

Code that is executed at the beginning of (something), as initialization of some sort.

`cleanup'

Code that is executed at the end of (something), as some sort of clean up facility.

`declaration'

Code that provides declarations of some sort, perhaps global or local arguments, variables, or methods.

`comment'

Text that is not executed as code, but instead serves to document the code around it. Submode regions of this function often use a mode such as Text Mode rather than a programming language mode.

`output'

An expression that is evaluated and its value interpolated into the output produced.

`code'

Executed code not falling under any other category.

`special'

Submode regions not falling under any other category, such as component calls.

The different background colors are provided by the faces mmm-function-submode-face, which can be customized in the same way as mmm-default-submode-face.

3.2 Preferred Major Modes

Certain of the supplied submode classes know only the language that certain sections are written in, but not what major mode you prefer to use to edit such code. For example, many people prefer CPerl mode over Perl mode; you may have a special mode for Javascript or just use C++ mode. This variable allows you to tell submodes such as Mason (see section 4.1 Mason: Perl in HTML) and Embedded Javascript (see section 4.4 Javascript in HTML) what major mode to use for the submodes:

User Option: mmm-major-mode-preferences

The elements of this list are cons cells of the form (language . mode). language should be a symbol such as perl, html-js, or java, while mode should be the name of a major mode such as perl-mode, cperl-mode, javascript-mode, or c++-mode.

You probably won't have to set this variable at all; MMM tries to make intelligent guesses about what modes you prefer. For example, if a function called javascript-mode exists, it is chosen, otherwise c++-mode is used. Similarly for jde-mode and java-mode.

If you do need to change the defaults, you may find the following function convenient.

Function: mmm-set-major-mode-preferences language mode &optional default

Set the preferred major mode for LANGUAGE to MODE. If there is already a mode specified for LANGUAGE, and DEFAULT is nil or unsupplied, then it is changed. If DEFAULT is non-nil, then any existing mode is unchanged. This is used by packages to ensure that some mode is present, but not override any user-specified mode. If you are not writing a submode class, you should ignore the third argument.

Thus, for example, to use my-java-mode for Java code, you would use the following line:

(mmm-set-major-mode-preferences 'java 'my-java-mode)

3.3 Customizing the Mode Line Display

By default, when in a submode region, MMM Mode changes the section of the mode line (see section `Mode Line' in The Emacs Manual) that normally displays the major mode name--for example, `HTML'---to instead show both the dominant major mode and the currently active submode--for example, `HTML[CPerl]'. You can change this format, however.

User Option: mmm-submode-mode-line-format

The value of this variable should be a string containing one or both of the escape sequences `~M' and `~m'. The string displayed in the major mode section of the mode line when in a submode is obtained by replacing all occurrences of `~M' with the dominant major mode name and `~m' with the currently active submode name. For example, to display only the currently active submode, set this variable to `~m'. The default value is `~M[~m]'.

The MMM minor mode also normally displays the string `MMM' in the minor mode section of the mode line to indicate when it is active. You can customize or disable this as well.

User Option: mmm-mode-string

This string is displayed in the minor mode section of the mode line when the MMM minor mode is active. If nonempty, it should begin with a space to separate the MMM indicator from that of other minor modes. To eliminate the indicator entirely, set this variable to the empty string.

3.4 Customizing the MMM Mode Key Bindings

The default MMM Mode key bindings are explained in 2.1.2 Key Bindings in MMM Mode, and in 2.4 Inserting new submode regions. There are a couple of ways to customize these bindings.

User Option: mmm-mode-prefix-key

The value of this variable (default is C-c %) should be a key sequence to use as the prefix for the MMM Mode keymap. Minor modes typically use C-c followed by a punctuation character, but you can change it to any user-available key sequence. To have an effect, this variable should be set before MMM Mode is loaded.

User Option: mmm-use-old-command-keys

When this variable is nil, MMM Mode commands use the control modifier and insertion keys no modifier. Any other value switches the two, so that mmm-parse-buffer, for example, is bound to C-c % b, while perl-section insertion in the Mason class is bound to C-c % C-p. This variable should be set before MMM Mode is loaded to have an effect.

When MMM is loaded, it uses the value of mmm-use-old-command-keys to set the values of the variables mmm-command-modifiers and mmm-insert-modifiers, so if you prefer you can set these variables instead. They should each be a list of key modifiers, such as (control) or (). The Meta modifier is used in some of the command and insertion keys, so it should not be used, and the Shift modifier is not particularly portable between Emacsen--if it works for you, feel free to use it. Other modifiers, such as Hyper and Super, are not universally available, but are valid when present.

3.5 Changing Saved Local Variables

A lot of the functionality of MMM Mode--that which makes the major mode appear to change--is implemented by saving and restoring the values of local variables, or pseudo-variables. You can customize what variables are saved, and how, with the following variable.

Variable: mmm-save-local-variables

At its simplest, this is a list each of whose elements is a buffer-local variable whose value is saved and restored for each major mode. Each elements can also, however, be a list whose first element is the variable symbol and whose subsequent elements specify how and where the variable is to be saved. The second element of the list, if present, should be one of the symbols global, buffer, or region. If not present, the default value is global. The third element, if present, should be a list of major mode symbols in which to save the variable. In the list form, the variable symbol itself can be replaced with a cons cell of two functions, one to get the value and one to set the value. This is called a "pseudo-variable".

Globally saved variables are the same in all (MMM-controlled) buffers and submode regions of each major mode listed in the third argument, or all major modes if it is t or not present. Buffer-saved variables are the same in all submode regions of a given major mode in each buffer, and region-saved variables can be different for each submode region.

Pseudo-variables are used, for example, to save and restore the syntax table (see section `Syntax' in The Emacs Manual) and mode keymaps (see section `Keymaps' in The Emacs Manual).

3.6 Changing the Supplied Submode Classes

If you need to use MMM with a syntax for which a submode class is not supplied, and you have some facility with Emacs Lisp, you can write your own; see 5. Writing Submode Classes. However, sometimes you will only want to make a slight change to one of the supplied submode classes. You can do this, after that class is loaded, with the following functions.

Function: mmm-set-class-parameter class param value

Set the value of the keyword parameter param of the submode class class to value. See section 5. Writing Submode Classes, for an explanation of the meaning of each keyword parameter. This creates a new parameter if one is not already present in the class.

Function: mmm-get-class-parameter class param

Get the value of the keyword parameter param for the submode class class. Returns nil if there is no such parameter.

3.7 Hooks Provided by MMM Mode

MMM Mode defines several hook variables (see section `Hooks' in The Emacs Manual) which are run at different times. The most often used is mmm-major-mode-hook which is described in 2.7.1 The Major Mode Hook, but there are a couple others.

Variable: mmm-mode-hook

This normal hook is run whenever MMM Mode is enabled in a buffer.

Variable: mmm-major-mode-hook

This is actually a whole set of hook variables, a different one for every major mode. Whenever MMM Mode is enabled in a buffer, the corresponding hook variable for the dominant major mode is run.

Variable: mmm-submode-submode-hook

Again, this is a set of one hook variable per major mode. These hooks are run whenever a submode region of the corresponding major mode is created in any buffer, with point at the start of the new submode region.

Variable: mmm-class-class-hook

This is a set of one hook variable per submode class. These hooks are run when a submode class is first applied to a given buffer.

Submode classes also have a :creation-hook parameter which should be a function to run whenever a submode region is created with that class, with point at the beginning of the submode region. This can be set for supplied submode classes with mmm-set-class-parameter; 3.6 Changing the Supplied Submode Classes.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.