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 |
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. 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 | 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-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. |
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-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. |
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 |
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")