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. ()
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. ‘’
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. {‘background’: ‘linear-gradient(to bottom, #fc3232 0%,#990000 100%)’, ‘boxShadow’: ‘0px 3px 7px 0px rgba(0, 0, 0, 0.3)’, ‘border’: ‘solid 1px #c32222’, ‘borderRadius’: ‘3px’, ‘fontSize’: ‘13px’, ‘whiteSpace’: ‘nowrap’, ‘fontWeight’: ‘bold’, ‘padding’: ‘1px 3px 0px 3px’, ‘textShadow’: ‘1px 1px 0 rgba(0, 0, 0, 0.6)’, ‘color’: ‘white’, ‘overflow’: ‘hidden’}
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}]’
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. Only usable on Qt >= 5.8 ()
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  
buffer-list  
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  
i-search  
minibuffer  
video-fullscreen Local Keymap activated when a video is played full screen.
visited-links-list  
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-minibuffer  
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.
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-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-open-external-editor Open an external editor to change the text field content.
content-edit-redo Redo the last editing action.
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-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.
i-search-backward Begin an incremental search (backward).
i-search-forward Begin an incremental search (forward).
make-window Create a new window and focus it.
maximise-view Close all the views in the current window except the current one.
next-buffer Cycle to the next buffer in the current view.
open-dev-tools Opens a dev tool page for a buffer.
other-view Focus on the next view.
other-window Switch to the next window.
previous-buffer Cycle to the previous buffer in the current view.
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-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.
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")