User configuration

webmacs can be configured by writing Python code. The files should live in a ~/.webmacs/init directory, starting with an __init__.py file.

If this file exists, it will be loaded early in the application.

Note that you have the full power of Python in there, and as it is loaded early, you can change and adapt nearly every aspect of the webmacs behavior.

Note

Only the documented functions and objects here are considered stable (meaning they will not change without change notes and explanations). Any other API you can use is considered internal and might change without notification.

The init function

You can write a function init that would be called when webmacs is about to start. This function must take one parameter (usually named opts), that contains the result of the parsed command line. For now, there is only one useful parameter:

  • opts.url: the url given in the command line, or None

Overriding the init function does override the default init function of webmacs, though it is still accessible with webmacs.main.init(). Hello world example:

import webmacs.main


def init(opts):
    print("hello wordl")
    if opts.url:
        print("{} was given as a command line argument".format(opts.url))
    webmacs.main.init(opts)

The default webmacs.main.init function is responsible for restoring the session, or opening the given URL, for example.

Note

It is not required to create an init function in the user configuration __init__.py file. Only do so if you want to change the default webmacs initialization. Other changes can be applied early, directly at the module level, such as defining webjumps or binding keys.

Using more than one configuration file

It is possible to write more than one configuration file. The directory where the __init__.py file lives is a Python package, so it is possible to just use relative imports.

For example:

__init__.py

from . import webjumps

webjumps.py

print("definition of my custom webjumps should go there.")

Variables

It is possible to change a variable in the configuration using webmacs.variables.set():

from webmacs import variables

variables.set("webjump-default", "google")

Here is the list of the variables:

Name description default
adblock-urls-rules A list of urls to get rules for ad-blocking (using the Adblock format). The default urls are taken from the easylist site https://easylist.to. [’https://easylist.to/easylist/easylist.txt’, ‘https://easylist.to/easylist/fanboy-annoyance.txt’]
auto-buffer-modes List of tuple of regexes and mode name to automatically associate web pages to some mode. If nothing matches the url, standard-mode is used. ()
clipboard-copy Where to copy text. Allowed values are ‘primary’, ‘selection’ or ‘both’ Defaults to primary, which is the global clipboard. selection is for clipboard mouse selection, and both will copy to both clipboards. ‘primary’
close-buffer-close-window Policy to close a window when the last available buffer is closed. If never, closing a buffer will never close a window. If all, closing a buffer can close a window, even the last one ( and so it will exit the application). Finally, all-but-last is like all but the last window will never be closed. ‘never’
default-download-dir Change the default download dir. ‘’
enable-javascript Enable the running of javascript programs. Default to True. True
enable-pdfviewer Specifies that PDF documents will be opened in the internal PDF viewer. Default to False False
external-editor-command command to open an external editor. You must use the {file} placeholder in the command, as it will be used to open the temporary file. “emacsclient -c -a ‘’ {file}”
hint-alphabet-characters Which characters to use for alphabet hinting. ‘asdfghjkl’
hint-method Method to hint things in web buffers. ‘filter’
hint-node-style The style to apply to the hint div. Note that it is a dict of JavaScript style property names to values. See https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style. {‘whiteSpace’: ‘nowrap’, ‘overflow’: ‘hidden’, ‘padding’: ‘1px 3px 0px 3px’, ‘background’: ‘linear-gradient(to bottom, #fc3232 0%,#990000 100%)’, ‘border’: ‘solid 1px #c32222’, ‘borderRadius’: ‘3px’, ‘boxShadow’: ‘0px 3px 7px 0px rgba(0, 0, 0, 0.3)’, ‘color’: ‘white’, ‘fontWeight’: ‘bold’, ‘fontSize’: ‘13px’, ‘textShadow’: ‘1px 1px 0 rgba(0, 0, 0, 0.6)’}
home-page Defines the url to use when webmacs starts. If set to the empty string, the last session will be loaded. You can set it to ‘about:blank’ if you want an empty page. ‘’
home-page-in-new-window Use the home page when creating a new window with make-window. Default to False. False
keep-temporary-download-dir If set to True, the download dir proposed will be the last used one. False
log-to-disk-max-files Maximum number of log files to keep. Log files are stored in ~/.webmacs/logs. Setting this to 0 will deactivate file logging completely. 0
minibuffer-flash-color Color for the minibuffer flash animation. Should be given as an hexadecimal string. ‘#ff0000’
minibuffer-flash-count How many flashes should be displayed during the minibuffer flash animation. 2
minibuffer-flash-duration Total duration in seconds of the minibuffer flash animation. 0.3
minibuffer-height The height in pixel of the minibuffer. 25
minibuffer-right-label Format for displaying some information in right label of minibuffer. ‘{loading}{mode}: {local_keymap} [{buffer_current}/{buffer_count}]’
password-manager Which password manager to use. - none: no password manager - passwordstore: the standard unix password manager. ‘none’
revive-buffers-limit The maximum number of killed buffers that can be revived. If set to a -1, there is no limit. Default to 10. 10
spell-checking-dictionaries List of dictionaries to use for spell checking. ()
switch-buffer-current-color The color to use for the current buffer in the switch-buffer list. Set to an empty string if you don’t want a special color. ‘#c0d5f7’
visited-links-display-limit Limit the number of history elements displayed in the visited-links-history command. 2000
webjump-default The default webjump ‘google’
webview-stylesheet stylesheet associated to the webviews. ‘[single=false][current=true] {n border-top: 1px solid black;n padding: 1px;n background-color: red;n}n[single=false][current=false] {n border-top: 1px solid white;n padding: 1px;n}’
window-toolbar-on-startup If set to True, the main window(s) will have the navigation toolbar visible on startup. False

Modes

Modes are used to bind keymaps to a web buffer, by assigning the buffer a given mode. By default, all buffers use the “standard-mode”.

Here is the list of the pre-defined modes:

Name Description
no-keybindings no-keybindings navigation mode
standard-mode standard navigation mode

Automatically assign modes depending on the url

You can use the auto-buffer-modes variable.

Example:

 from webmacs import variables

 variables.set("auto-buffer-modes", [
    (".*www.gnu.org.*", "no-keybindings"),
    ("https://mail.google.com/.*", "no-keybindings")
])

Binding keys

In webmacs, like in Emacs, it is possible to bind a key to a command on a given keymap.

Keymaps

Here is the list of available keymaps. Note that you can see them live (with their associated key bindings) in webmacs by running the command describe-bindings.

Name Description
bookmarks-list Local keymap activated while looking into bookmarks.
buffer-list Local keymap activated while looking into buffers.
caret-browsing Local keymap activated when you are navigating the webbuffer with a caret.
empty  
global The global keymap is always active. It act as a fallback to other keymaps, which are considered local. Only one local keymap can be active at a time. A binding is first searched in the currently active local keymap, and if not found the global keymap is used. Only bindings with modifiers should be bound to it, else it will be impossible to edit text inside the browser.
hint Local keymap used when hinting.
i-search Local keymap used in incremental search.
minibuffer Local keymap activated when input is in the minibuffer line edit.
video-fullscreen Local Keymap activated when a video is played full screen.
visited-links-list Local keymap activated while looking into visited links.
webbuffer Local keymap activated when a web buffer is focused. A web buffer is focused when there is no text editing, no caret browsing, or when the minibuffer input is not shown… It is enabled when no other local keymap is enabled.
webcontent-edit Local keymap activated when a webcontent field (input, textarea, …) is focused.
webjump Local keymap activated while using webjumps.
yes-no  

A keymap object in user configuration is retrieved with webmacs.keymaps.keymap().

Commands

Here is the list of the currently available commands:

Command description
M-x Prompt for a command name to execute.
bookmark-add Create or rename a bookmark for the current url.
bookmark-open Prompt to open a bookmark. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
bookmark-open-new-buffer Prompt to open a bookmark in a new buffer.
bookmark-open-new-window Prompt to open a bookmark in a new window.
bookmarks-delete-highlighted Deletes from the database the currently highlighted bookmark.
buffer-escape Clear selection or menus in the current buffer. The implementation clears the selection in the buffer if there is any, else it sends the Escape key which usually closes whatever takes the focus.
buffer-history Prompt to navigate in the local buffer history.
buffer-list-delete-highlighted Close currently highlighted buffer.
buffer-set-mode Change the mode of the current buffer.
buffer-unselect Unselect selection in the current web buffer.
caret-browsing-backward-char Move the caret one character backward.
caret-browsing-backward-paragraph Move the caret to the previous paragraph (TODO FIXME not working yet)
caret-browsing-backward-word Move the caret one word backward.
caret-browsing-beginning-of-document Move the caret to the beginning of the document.
caret-browsing-beginning-of-line Move the caret to the beginning of the current line.
caret-browsing-cut Cut the current caret selection.
caret-browsing-down Move the caret down a line.
caret-browsing-end-of-document Move the caret to the end of the document.
caret-browsing-end-of-line Move the caret to the end of the current line.
caret-browsing-forward-char Move the caret one character forward.
caret-browsing-forward-paragraph Move the caret to the next paragraph (TODO FIXME not working yet)
caret-browsing-forward-word Move the caret one word forward.
caret-browsing-init Init caret browsing in the current buffer.
caret-browsing-shutdown Shutdown caret browsing in current buffer.
caret-browsing-toggle-mark Set or unset (toggle) the mark where the point is.
caret-browsing-up Move the caret up a line.
close-buffer Close the current buffer.
close-other-buffers Close all but one buffer.
close-other-windows Close all windows except the current one.
close-view Close the current view.
close-window Close the current window, unless there is only one left.
content-edit-backward-char Move one character backward in browser text field.
content-edit-backward-word Move one word backward in browser text field.
content-edit-beginning-of-line Move to the beginning of the line in browser text field.
content-edit-cancel If a mark is active, clear that but keep the focus. If there is no active mark, then just unfocus the editable js object.
content-edit-capitalize-forward-word Capitalize the word forward in browser text field.
content-edit-copy Copy browser text field selection to the clipboard.
content-edit-cut Cut browser text field selection to the clipboard.
content-edit-delete-backward-word Delete one word backward in browser text field.
content-edit-delete-forward-char Delete one character forward in browser text field.
content-edit-delete-forward-word Delete one word forward in browser text field.
content-edit-downcase-forward-word Downcase the word forward in browser text field.
content-edit-end-of-line Move to the end of the line in browser text field.
content-edit-forward-char Move one character forward in browser text field.
content-edit-forward-word Move one word forward in browser text field.
content-edit-kill Kill from the cursor to end of line to the clipboard.
content-edit-open-external-editor Open an external editor to change the text field content.
content-edit-redo Redo the last editing action.
content-edit-select-all Select all text of the current input.
content-edit-set-mark Set or clear the mark in browser text field.
content-edit-undo Undo the last editing action.
content-edit-upcase-forward-word Upcase the word forward in browser text field.
copy-current-buffer-title Copy the title of the current buffer to the clipboard.
copy-current-buffer-url Copy the URL of the current buffer to the clipboard.
copy-current-link Copy the current link to the clipboard.
copy-link Hint links in the buffer to copy them.
current-instance Show the current instance name.
describe-bindings Display current bindings in the current buffer or in a new buffer.
describe-command Prompt for a command name to describe.
describe-commands Display commands in the current buffer or in a new buffer.
describe-key Retrieve the command called by the given binding.
describe-key-briefly Display in the minibuffer the command name called by the given binding.
describe-variable Prompt for a variable name to describe.
describe-variables Display variables in the current buffer or in a new buffer.
downloads Display information about the current downloads.
follow Hint links in the buffer and follow them on selection. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
follow-new-buffer Hint links in the buffer and follow them on selection in a new buffer.
follow-new-window Hint links in the buffer and follow them on selection in a new window.
go-backward Navigate backward in history for the current buffer.
go-forward Navigate forward in history for the current buffer.
go-to Prompt to open a URL or a webjump. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
go-to-alternate-url Prompt to open an alternative URL from the current one. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
go-to-alternate-url-new-buffer Prompt to open an alternative URL from the current one in a new buffer.
go-to-alternate-url-new-window Prompt to open an alternative URL from the current one in a new window.
go-to-new-buffer Prompt to open a URL or a webjump in a new buffer.
go-to-new-window Prompt to open a URL or a webjump in a new window.
hint-abort Abort current hint session.
hint-next Select the next hint.
hint-prev Select the previous hint.
i-search-abort Abort incremental search.
i-search-backward Begin an incremental search (backward).
i-search-forward Begin an incremental search (forward).
i-search-next Highlight next match in incremental search mode.
i-search-prev Highlight previous match in incremental search mode.
i-search-validate Validate current match in incremental search mode.
is-off-the-record Print wether browsing is off the record.
make-window Create a new window and focus it.
maximise-view Close all the views in the current window except the current one.
minibuffer-abort Abort edition of the minibuffer.
minibuffer-backward-char Move one character backward.
minibuffer-backward-word Move one word backward.
minibuffer-beginning-of-line Move cursor to the beginning of the line.
minibuffer-copy Copy selected text in the minibuffer.
minibuffer-cut Cut selected text in the minibuffer.
minibuffer-delete-backward-word Delete the word backward.
minibuffer-delete-forward-char Delete forward character.
minibuffer-delete-forward-word Delete forward word.
minibuffer-end-of-line Move cursor to the end of the line.
minibuffer-forward-char Move one character forward.
minibuffer-forward-word Move one word forward.
minibuffer-history-next Insert next history value.
minibuffer-history-prev Insert previous history value.
minibuffer-mark Set or unset the edit mark.
minibuffer-paste Paste text in the minibuffer.
minibuffer-redo Redo in the minibuffer.
minibuffer-select-all Select all text in the minibuffer.
minibuffer-select-complete Complete completion.
minibuffer-select-first Select first completion entry.
minibuffer-select-last Select last completion entry.
minibuffer-select-next Select next completion entry.
minibuffer-select-next-page Move one page down in completion entry list.
minibuffer-select-prev Select previous completion entry.
minibuffer-select-prev-page Move one page up in completion entry list.
minibuffer-undo Undo in the minibuffer.
minibuffer-validate Validate input in minibuffer.
next-buffer Cycle to the next buffer in the current view.
open-dev-tools Opens a dev tool page for a buffer.
open-off-the-record Opens a new webmacs instance with off-the-record enabled.
other-view Focus on the next view.
other-window Switch to the next window.
password-manager-fill-buffer Fill the current buffer inputs using password manager data.
previous-buffer Cycle to the previous buffer in the current view.
print-buffer Opens a dialog to select the printer and prints the current buffer.
quit Quit the application.
raise-instance Raise the current window of the selected instance.
reload-buffer Reload the current buffer.
reload-buffer-no-cache Reload the current buffer bypassing any cache.
restore-session Restore windows and buffers from the previous sessions.
revive-buffer Revive a previously killed buffer in the current view.
scroll-bottom Scroll the current buffer to the bottom.
scroll-down Scroll the current buffer down a bit.
scroll-page-down Scroll the current buffer one page down.
scroll-page-up Scroll the current buffer one page up.
scroll-top Scroll the current buffer to the top.
scroll-up Scroll the current buffer up a bit.
search-default Prompt to open a URL with the default webjump. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
search-default-new-buffer Prompt to open a URL with the default webjump in a new buffer.
search-default-new-window Prompt to open a URL with the default webjump in a new window.
select-buffer-content Select all content in the buffer.
send-key-down Send a key down event.
send-key-left Send a key left event.
send-key-right Send a key right event.
send-key-up Send a key up event.
split-view-bottom Create a new view below the current one.
split-view-right Create a new view on the right of the current one.
switch-buffer Prompt to select a buffer to display in the current view.
switch-recent-buffer Prompt to select a buffer to display in the current view.
text-zoom-in Zom in (text only) in the buffer.
text-zoom-out Zom out (text only) in the buffer.
text-zoom-reset Reset the zoom (text only) in the buffer.
toggle-ad-block Toggle ad-blocking on or off.
toggle-fullscreen Toggle fullscreen state of the current window.
toggle-maximized Toggle maximised state of the current window.
toggle-toolbar Toggle the main window toolbar on or off.
version Display version information.
visited-links-delete-highlighted Deletes from the database the currently highlighted visited link.
visited-links-history Prompt to open a link previously visited. You can use <C-u> as a prefix to open in a new buffer, or <C-u C-u> to open in a new window.
visited-links-history-new-buffer Prompt to open a link previously visited in a new buffer.
visited-links-history-new-window Prompt to open a link previously visited in a new window.
webcontent-copy Copy the selection in the current buffer.
webcontent-cut Cut the selection in the current buffer.
webcontent-paste Paste the selection in the current buffer.
webjump-complete Complete webjump name in the minibuffer.
where-is Print short notice of where a command is bound
zoom-in Zoom-in in the buffer.
zoom-normal Zoom-normal in the buffer.
zoom-out Zoom-out in the buffer.

Binding a command to a keymap

You should use webmacs.keymaps.Keymap.define_key(). Here is an example:

from webmacs import keymaps

global_map = keymaps.keymap("global")
global_map.define_key("C-c |", "split-view-right")
global_map.define_key("C-c _", "split-view-bottom")

buffer_keymap = keymaps.keymap("webbuffer")
buffer_keymap.define_key("x", "close-buffer")

Note

The global buffer should not define single letter keychords, as you won’t be able to type that letter in editable fields; though, this is possible in the webbuffer keymap.

Webjumps

Here is the implementation of the google webjump:


def complete_google():
    def url_fn(text):
        if not text:
            return None
        return (
            "https://www.google.com/complete/search?client=firefox&q="
            + str(QUrl.toPercentEncoding(text), "utf-8"))

    return WebJumpRequestCompleter(
        url_fn,
        lambda response: json.loads(str(response, "utf-8"))[1]
    )


define_webjump("google",
               "https://www.google.com/search?q=%s&ie=utf-8&oe=utf-8",
               "Google Search",
               complete_fn=complete_google)

The list of defined webjumps in webmacs:

Name url description
duckduckgo https://www.duckduckgo.com/?q=%s Duckduckgo Search
file file://%s Local uris
google https://www.google.com/search?q=%s&ie=utf-8&oe=utf-8 Google Search
http http://%s web sites
https https://%s secure web sites
webmacs webmacs://%s webmacs internal pages

You can implement your own webjumps, or override the existing ones. See webmacs.commands.webjump.define_webjump() and the example above.

Pressing the s key will call the command search-default, wich will, by default, use the Google webjump. To change this default, change the value of the variable webjump-default.

It is also possible to define an alias to an existing webjump, without duplicating its implementation.

from webmacs.commands.webjump import define_webjump_alias

define_webjump_alias("g", "google")