welcome: please sign in
location: Diff for "UserVariables"
Differences between revisions 77 and 78
Revision 77 as of 2013-12-23 09:14:07
Size: 19840
Editor: df
Comment: Document isearch_scroll_center_vertically
Revision 78 as of 2013-12-23 09:15:22
Size: 19842
Editor: df
Deletions are marked like this. Additions are marked like this.
Line 195: Line 195:
 isearch_scroll_center_vertically  isearch_scroll_center_vertically::

User Variables

Conkeror has many behaviors that can be customized by setting certain ordinary variables in your rc. We will try to describe them all here.

NOTE: variables are not the same thing as preferences.

String color for the active hint. Default is "#88FF00".
String color for the active image hint. Default is "#88FF00".

If this is set to true, if a content buffer page calls window.close() from JavaScript and is not prevented by the normal Mozilla mechanism that restricts pages from closing a window that was not opened by a script, the buffer will be killed, deleting the window as well if it is the only buffer. Default is true.

A list of mappings from URI regular expressions to page modes. This should probably only be changed to add new page modes. See modules/page-modes/ for examples.

Duration (in milliseconds) during which an element is allowed to gain focus following a mouse click or key press, if block_content_focus_change_mode is enabled.


note: As of November 2, 2009, this variable was renamed to block_content_focus_change_duration. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS.

Time window (in milliseconds) during which a form element is allowed to gain focus following a mouse click or key press, if browser_prevent_automatic_form_focus_mode is enabled. Default is 20.


Specifies how new window requests by content pages (e.g. by window.open from JavaScript or by using the target attribute of anchor and form elements) will be handled. This will generally be OPEN_NEW_BUFFER, OPEN_NEW_BUFFER_BACKGROUND, or OPEN_NEW_WINDOW. Default is OPEN_NEW_BUFFER.


XPath expression matching elements to be selected by browser-focus-next-form-field and browser-focus-previous-form-field. Default is

  •   "//input[" + (
            //        "translate(@type,'RADIO','radio')!='radio' and " +
            //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
            //        "translate(@type,'SUBMIT','submit')!='submit' and " +
            //        "translate(@type,'REST','rest')!='reset'"
        ) +  "] | " +
            "//xhtml:input[" + (
                //        "translate(@type,'RADIO','radio')!='radio' and " +
                //        "translate(@type,'CHECKBOX','checkbox')!='checkbox' and " +
                //        "translate(@type,'SUBMIT','submit')!='submit' and " +
                //        "translate(@type,'REST','rest')!='reset'"
            ) +  "] |" +
            "//select | //xhtml:select | " +
            "//textarea | //xhtml:textarea | " +
            "//textbox | //xul:textbox"

Patterns used by follow-next and follow-previous. By default, we have

  •   browser_relationship_patterns[RELATIONSHIP_NEXT] =
         new RegExp("^>$","i"),
         new RegExp("^(>>|»)$","i"),
         new RegExp("^(>|»)","i"),
         new RegExp("(>|»)$","i"),
         new RegExp("\\bnext","i")
       browser_relationship_patterns[RELATIONSHIP_PREVIOUS] =
         new RegExp("^<$","i"),
         new RegExp("^(<<|«)$","i"),
         new RegExp("^(<|«)","i"),
         new RegExp("(<|«)$","i"),
         new RegExp("\\bprev|previous\\b","i")

Behavior of bury-buffer command with respect to buffer order. See Buffer Order.

Boolean controlling whether the kill-buffer command can kill the last buffer in a window.
Which mouse button should open links in a new buffer.
  • 0 = left, 1 = middle, 2 = right. Default is 1. (With require("clicks-in-new-buffer.js")).
How to open links in a new buffer, in the foreground or the background. Set to one the constants OPEN_NEW_BUFFER or OPEN_NEW_BUFFER_BACKGROUND. Default is OPEN_NEW_BUFFER.
  • (With require("clicks-in-new-buffer.js")).

Format string for the mode-line clock widget. It takes the same format as strftime() in C. See http://www.opengroup.org/onlinepubs/007908799/xsh/strftime.html for details. Default is "%R", which is hours and minutes in 24-hour format.


A mime type table mapping mime types to content handlers. This table will be checked for a match when a navigation event causes Conkeror to encounter a mime type which is not supported by Mozilla. If no appropriate content handler is found in this table, the user will be prompted to choose from among common actions. No handlers are registered by default. See ContentHandlers for details on how to manipulate the table.


Abbreviation for current working directory. It is used as your default download directory, and the directory for shell commands. Individual buffers and pages may have their own local cwd. The change-directory command sets the buffer-local cwd. The value must be an nsILocalFile object. The function make_file will make an nsILocalFile from a string path. The default value of cwd is your home directory.


Boolean controlling whether daemon-mode abides the quit command. Default is true.

Delay (in milliseconds) after the most recent key stroke before auto-completing. Default is 150.
If this is set to true (the default), temporary files downloaded to run a command on them will be deleted once the command completes. If not, the file will stay around forever unless deleted outside the browser.

Target for download buffers created by open_download_buffer_automatically. The default is OPEN_NEW_WINDOW.

Minimum interval (in milliseconds) between updates in download progress buffers. Lowering this interval will increase the promptness of the progress display at the cost of using additional processor time. Default is 2000 (ms).

Delay (in milliseconds) before a download buffer is opened for temporary downloads. This variable takes effect only if open_download_buffer_automatically is in download_added_hook, as it is by default. Default is 500.


Default is "txt". File extension for the temp files created by edit-current-field-in-external-editor. Obsolete Dec 31, 2010. See external_editor_extension_overrides.


Shell command used to invoke an external editor. Default is the value of the environment variable EDITOR. It is used as part of a shell command in the following two ways:

  •     <editor_shell_command> <file>
        <editor_shell_command> +<line> <file>

Windows users should reference ConkerorSpawnHelper and include a trailing .exe on any executables set here. Non-null run_external_editor_function overrides this setting. Default is

  •   getenv("VISUAL") || getenv("EDITOR") || "emacs"
A mime-type table containing associations of mime types to programs that can handle content of that type. Used by commands and actions that entail running an external program on content. The default contents of the table are:
  •   {
          "*": getenv("EDITOR"),
          text: { "*": getenv("EDITOR") },
          image: { "*": "feh" },
          video: { "*": "mplayer" },
          audio: { "*": "mplayer" },
          application: {
              pdf: "evince",
              postscript: "evince",
              "x-dvi": "evince"

See ContentHandlers for more information about manipulating the table.

Mime-type table giving file extensions for temp files used in external editing. The contents of this table are for overrides only. Defaults are gotten from the mime service.
A setting for the eye-guide commands. Context size in pixels for eye-guide-scroll-down and eye-guide-scroll-up. Default is 50.
A setting for the eye-guide commands. When true, the new part of the view is highlighted instead of the old. Default is false.
A setting for the eye-guide commands. Interval during which the eye guide is visible (in ms). When 0, the eye guide will remain visible. Default is 800.
Maximum (pixel) width and height of an image document that is considered for use as a favicon. Default is 1024.
An alist mapping url regexps to charsets.

A function called by suggest_file_name which sanitizes a filename prior to saving. The default is a function appropriate to the current OS. This variable can be customized in order to impose additional sanitization rules on filenames, for example, if you wanted to always convert spaces to underscores or the like.

String color name for hints. Default is "yellow".

Null or a string of the digits to use as the counting base for hint numbers, starting with the digit that represents zero and ascending. If null, base 10 will be used with the normal hindu-arabic numerals. Default is null. See Hinting.

Delay (in milliseconds) after the most recent key stroke before the first of an ambiguous match is automatically selected. If this is set to 0, automatic selection in ambiguous matches is disabled. Default is 0.
Delay (in milliseconds) after the most recent key stroke before a sole matching element is automatically selected. If this is set to 0, automatic selection is disabled. Default is 0.
Default url for content buffers.
String color for image hints. Default is "yellow".

A directory (instance of nsILocalFile) for storing the index files corresponding to index webjumps; the index data can be downloaded from the index URL using webjump-get-index. If the index file is available for an index webjump then the webjump will provide completions for the indexed URLs.

A command to run on the downloaded index. The xulrunner parser is quite fussy and specifically requires xhtml (or other xml). Running something like html tidy can avoid parser problems.
Default is false. When true, the selection will always be left visible after completing an isearch.
When an isearch causes scrolling, the result is normally scrolled into view at the bottom of the screen. If this variable is set to true it will be centered vertically instead. Only available since XULRunner 12, when the SCROLL_CENTER_VERTICALLY flag was added.

When true, the state of capslock will be overridden for key combos that contain characters. If shift was pressed with the character, the character will be forced to upper-case, and otherwise forced to lower-case. This only affects keys bound to commands. Capslock will still work as normal when typing in input fields. The default value of this variable is false.

Delay (in milliseconds) before the current key sequence prefix is displayed in the minibuffer. Default is 0.

Default is false. When true, the command cut-to-end-of-line will also cut the newline character at the end, when point is at the beginning of a line.


Array of URL prefixes searched in order when loading a module. Each entry must end in a slash, and should begin with file:// or chrome://.

Regular expression used by the default media scraper to match URIs for embedded media in the page source code. Defaults to
  •   new RegExp("(?:http://[a-zA-Z0-9.\\-]+/)?(?!://)[^=&<>\"'|\\s]+\\.(?:aiff|au|avi|flv|mid|mov|mp3|mpg|mpeg|ogg|ra|rm|spl|wav|wma|wmv)(?!\\w)", "ig")

Function (or coroutine) to use to scrape the current buffer for embedded media. Default is [media_scrape_default] (see media.js).


note: this variable was removed as of October 12, 2009. The documentation for it will be left up for a reasonable amount of time in order to be available to people running an older version of Conkeror from their OS. This variable was replaced by external_content_handlers. See ContentHandlers for details.

An array of two element arrays, associating mime type patterns with handler programs. The patterns are regular expressions. When conkeror looks for an external handler, the program corresponding to the first matching pattern will be used. The default value of mime_type_external_handlers is:

  • [[/^text\/.*$/, getenv("EDITOR")],
     [/^image\/.*$/, "feh"],
     [/^video\/.*$/, "mplayer"],
     [/^audio\/.*$/, "mplayer"],
     [/^application\/pdf$/, "evince"],
     [/^application\/postscript$/, "evince"],
     [/^application\/x-dvi$/, "evince"],
     [/^.*$/, getenv("EDITOR")]]

    An API exists for manipulating this array; see MimeTypeHandlers for details.


Boolean specifying whether to auto-complete by default. The user variable minibuffer_auto_complete_preferences overrides this. Default is false.

Number of rows in the minibuffer completion display. Default is 8.
Maximum number of minibuffer history entries stored.Older history entries are truncated after this limit is reached. Default is 100.
Time duration (in milliseconds) to flash minibuffer messages while in minibuffer input mode. Default is 1000.
Specifies whether a URL presented in the minibuffer for editing should be selected. This affects find-alternate-url. Defaults to true.

Insertion position of a new buffer with no opener or with an opener that is not a buffer in the same window. See Buffer Order.


Insertion position of a new buffer whose opener is a buffer in the same window. See Buffer Order.

Paths to search for opensearch description files. Default list includes the subdirectory called 'search-engines' in your profile directory and the Conkeror installation directory.

Boolean which controls whether read_buffer should display buffer icons. Default is false. Note, simply setting this variable alone does not cause Conkeror to fetch favicons. See Favicons for the full story.

A list of handler functions which transform a typed url into a valid url or webjump. If the typed input is not valid then each function on this list is tried in turn. The handler function is called with a single string argument and it should return either a string or null. The result of the first function on the list that returns a string is used in place of the input. Example:
  •   read_url_handler_list = [read_url_make_default_webjump_handler("google")];

Coroutine function called to invoke an external editor. If this variable is set to a function, it is used to invoke an external editor in place of editor_shell_command. It is called with the filename as the first argument, and optionally the boolean keyword argument $temporary specifying whether the file should be deleted after the editor is closed, and optionally the keyword argument $line specifying a line number to display. The create_external_editor_launcher function is convenient for generating a function suitable for use as the value of this variable.

When true, access order of buffers is preserved in sessions. Default is false.

Gives the default sort order for history and bookmark completion. The value is given as a string, and the available options include: 'none', 'title_ascending', 'date_ascending', 'uri_ascending', 'visitcount_ascending', 'keyword_ascending', 'dateadded_ascending', 'lastmodified_ascending', 'tags_ascending', and 'annotation_ascending'. For every 'ascending' option, there is a corresponding 'descending' option. Additionally, with XULRunner 6 and later, the options 'frecency_ascending' and 'frecency_descending' are available. See also https://developer.mozilla.org/en/NsINavHistoryQueryOptions#Sorting_methods. The default order is "visitcount_descending".


Boolean Default is true. Controls whether bookmarks will be included in the completion list when prompting the user for an url, for example, with the open-url command.


Boolean Default is false. Controls whether urls in the browse history will be included in the completion list when prompting the user for an url, for example, with the open-url command.


Boolean. Default is true. Controls whether webjumps will be included in the completion list when prompting the user for an url, for example, with the open-url command.


"Url remoting" is the term for invoking Conkeror with an url (for example, from a command line) when a Conkeror process is already running. The new invocation is said to "remote" the url to the already running process. The variable url_remoting_fn is a function to dispatch on urls remoted into Conkeror. The default value is load_url_in_new_window. Though you can easily write your own url remoting function, obvious ones are already included in conkeror:

  • load_url_in_new_window

  • load_url_in_new_buffer

  • load_url_in_current_buffer


May be set to a user-defined function for viewing source code. The function should accept an nsILocalFile of the filename as its one positional argument, and it will also be called with the keyword $temporary, whose value will be true if the file is considered temporary, and therefore the function must take responsibility for deleting it.


When true, the view-source command will send its document to your external editor. Default is false.

Default is true. When entering a url, if the input is not a webjump, but would uniquely complete to a webjump, then accept that webjump only if this is true.
Default is false. When true, xkcd-mode will scrape the alt text from the xkcd comic and insert it into the page below the comic.

Conkeror.org: UserVariables (last edited 2013-12-23 09:15:22 by df)