// See COPYING for copyright and license details

// vim: set ft=asciidoc:
DWBREMOTE(1)
============
:doctype: manpage


NAME
----
dwbremote - dwb remote control

SYNOPSIS
--------
*dwbremote* ['OPTION'] <command> <arguments>

DESCRIPTION
-----------
*dwbremote* allows one to control dwb from command line. It communicates with
dwb instances by setting its XProperties. Return values will be printed to
stdout. To use dwbremote 'enable-ipc' must be enabled in the dwb instance to
communicate with. 

*dwbremote* tries to find windows depending on the options passed, if no options
are used or no windows were found it will use the environment variable
*DWB_WINID*, if it is not set it will use the last dwb window that had focus. In
userscripts executed by dwb the environment variable *DWB_WINID* will always be
set and will point to the window that executed the script. Passing more than one
option sends the command to all matching windows. 

OPTIONS
-------

*-a --all*::
    Sends a command to all windows. 

*-c --class* 'wm_class'::
    Search for window id by WM_CLASS. 

*-i --id* 'window_id'::
    Send comands to window with id 'window_id', window ids in hexadecimal format
    must start with 0x. 

*-l --list*::
    List all dwb window ids with enabled ipc.

*-n --name* 'wm_name'::
    Search for window id by WM_NAME.

*-p --pid* 'pid':: 
    Search for window id by process id 'pid'.

*-s --show-id*:: 
    Print the window id in every response, the window id will be prepended to
    the response. 

COMMANDS
--------
*add_hooks* ['hook' ...]::
    Adds a list of hooks without actually connecting to the hook, see 'hook' for
    a list of hooks and 'clear_hooks'.

*bind* 'command:shortcut' ['command:shortcut' ...]::
    Bind a shorcut or command, to bind only a commandline command without
    binding a shortcut 'command:none' must be used, to bind only a
    shortcut without binding a commandline command 'none:shortcut'.

*clear_hooks* ['hook' ...]::
    Removes a list of hooks so the will no longer be emitted. To re-enable hooks
    'add_hooks' can be sent. For a list of hooks see 'hook'.

*confirm* ['prompt message']::
    Shows a confirmation prompt. Returns 'true' if 'y' was pressed and false if
    'n' or 'Escape' was pressed.
    
*execute* 'command'::
    Executes a command, the command is parsed the same way as if executed from
    commandline. A shorthand for execute is prepending ':' to the command, i.e. 
    'dwbremote execute scroll_down' is equivalent to 'dwbremote :scroll_down'

*get* 'argument'::
    Gets miscellaneous properties

    *Arguments*:::
        *all_domains*::::
            Gets newline separated list of all domains.
        *all_hosts*::::
            Gets newline separated list of all hosts.
        *all_titles*::::
            Gets newline separated list of all titles.
        *all_uris*::::
            Gets newline separated list of all uris.
        *current_tab*::::
            Gets number of the current tab, starting at 1.
        *[n] domain*::::
            Gets the effective top level domain of the nth tab or current tab is
            n is omitted, e.g. for www.example.co.uk it will return
            example.co.uk.
        *[n] history*::::
            Gets the newline separated history list of the nth tab or current tab if
            n is omitted. The first field is the history number, negative values
            indicate back history items, positive numbers indicate forward
            history items, 0 indicates the current uri. 
        *[n] host*::::
            Gets the host of the nth tab or current tab is n is omitted.
        *ntabs*::::
            Gets total number of tabs.
        *profile*::::
            Gets the profile name.
        *session*::::
            Gets the name of the session.
        *setting <name>*::::
            Gets a setting, only the current local settings from the instance
            are received so they might differ from the settings in
            $HOME/.config/dwb/settings, e.g. if they were changed with local_set.
        *[n] title*::::
            Gets the title of the nth tab or current tab is n is omitted.
        *[n] uri*::::
            Gets the uri of the nth tab or current tab is n is omitted.

*hook* 'hook' ['hook' ...]::
    Connect to a list of hooks.

    *Hooks*:::

        *change_mode*;; 
            Emitted when the mode changes, return format: 'change_mode <mode>'
            *mode*:::: 
                The new mode, can be one of 'normal', 'insert', 'hint', 'command'
                or 'caret'
        *close_tab* ;;
            Emitted when a tab is closed, return format: 'close_tab <n>'
            *n*::::
                Number of tab that was closed
        *document_finished* ;;
            Emitted when the DOM document load has been finished for a frame,
            return format: 'document_finished <n> <mainframe>'
            *n*::::
                Number of the tab 
            *mainframe*::::
                'true' if it is the DOM document of the mainframe has been
                finshed loading, 'false' if the DOM document of a subframe has
                been finshed.
        *download_finished* ;;
            Emitted when a download has been finished, return format: 'download_finished <destination_uri>'
            *destination_uri*::::
                The destination uri of the download, e.g. file:///tmp/download.pdf
        *execute* ;;
            Emitted when a command is executed, return format: 'execute <command> <argument> <n>'
            *command*::::
                Command that is executed
            *argument*::::
                Argument if it is a commandline command with argument or 'none'
            *n*::::
                Numerical modifier or -1
        *focus_tab*;;
            Emitted when a tab gets focus, return format: 'focus_tab <n>'
            *n*::::
                Number of tab that gets focus
        *hook*;;
            Emitted when the command 'hook', 'add_hooks' or 'clear_hooks' is
            executed, return format: 'hook <action> <hooks>'
            *action*::::
                Either 'add' if add_hooks or hook is executed, 'clear' if
                clear_hooks is executed
            *hooks*::::
                List of hooks.
        *load_committed*;;
            Emitted when new page load has been committed, return format: 'load_committed <n> <uri>'
            *n*::::
                Number of the tab 
            *uri*::::
                Uri that will be loaded
        *load_finished*;;
            Emitted when a page load has finished, return format: 'load_finished <n> <uri>'
            *n*::::
                Number of the tab 
            *uri*::::
                Uri that will be loaded
        *navigation*;;
            Emitted when a tab or a frame in a tab requests a new page load, 
            return format: 'navigation <n> <mainframe> <uri>'
            *n*::::
                Number of the tab 
            *mainframe*::::
                'true' if it is the mainframe, 'false' if it is a subframe that
                requests the new page load
            *uri*::::
                Uri that will be loaded
        *new_tab*;;
            Emitted when new tab is created, return format: 'new_tab <n>'
            *n*::::
                Number of the new tab
        *quit*;; 
            Emitted when dwb is closed. The response will be empty

*prompt* 'promptmessage'::
    Shows a prompt dialog.
        
*pwd_prompt* 'promptmessage'::
    Shows a password dialog. Note that using password prompt is not save.


EXAMPLES
--------
    Executing commands::
    +
----
    dwbremote :tabopen example.com
    dwbremote -pid 1234 execute 2close
----

    Getting properties::
    +
----
    uri="$(dwbremote -id 0x1000001 get uri)"
    title="$(dwbremote -id 0x1000001 get 2 title)"
    scripts_enabled="$(dwbremote -class foo setting enable-settings)"
----
    User/Password prompt::
    +
----
    username="$(dwbremote prompt Username:)"
    if [ "$username" ]; then 
        password="$(dwbremote pwd_prompt Password:)"
    fi
----


    Multiple hooks with one dwbremote instance::
    +
-----
    #!/bin/bash 

    if [ "$DWB_WINID" ]; then 
        DWBRC=dwbremote
    else
        DWBRC="dwbremote -class foo"
    fi

    while read -a array; do 
        hook="${array[0]}"
        case "$hook" in 
            navigation) 
                ...
                ;;
            load_finished) 
                ...
                ;;
            close_tab) 
                ...
                ;;
        esac
    done < <("$DWBRC" hook navigation load_finished close_tab)
-----
    Binding multiple shortcuts::
    +
-----
    while read -a array; do 
        bind="${array[0]}"
        case "$bind" in
            none:xx) 
                ...
                ;;
            foobar:gx) 
                ...
                ;;
        esac
    done < <(dwbremote -pid 1234 bind none:xx foobar:gx)
-----



SEE ALSO
--------
*dwb*(1)
