'\" t
.\"     Title: dwbremote
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 03/07/2014
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "DWBREMOTE" "1" "03/07/2014" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dwbremote \- dwb remote control
.SH "SYNOPSIS"
.sp
\fBdwbremote\fR [\fIOPTION\fR] <command> <arguments>
.SH "DESCRIPTION"
.sp
\fBdwbremote\fR 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 \fIenable\-ipc\fR must be enabled in the dwb instance to communicate with\&.
.sp
\fBdwbremote\fR 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 \fBDWB_WINID\fR, if it is not set it will use the last dwb window that had focus\&. In userscripts executed by dwb the environment variable \fBDWB_WINID\fR 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\&.
.SH "OPTIONS"
.PP
\fB\-a \-\-all\fR
.RS 4
Sends a command to all windows\&.
.RE
.PP
\fB\-c \-\-class\fR \fIwm_class\fR
.RS 4
Search for window id by WM_CLASS\&.
.RE
.PP
\fB\-i \-\-id\fR \fIwindow_id\fR
.RS 4
Send comands to window with id
\fIwindow_id\fR, window ids in hexadecimal format must start with 0x\&.
.RE
.PP
\fB\-l \-\-list\fR
.RS 4
List all dwb window ids with enabled ipc\&.
.RE
.PP
\fB\-n \-\-name\fR \fIwm_name\fR
.RS 4
Search for window id by WM_NAME\&.
.RE
.PP
\fB\-p \-\-pid\fR \fIpid\fR
.RS 4
Search for window id by process id
\fIpid\fR\&.
.RE
.PP
\fB\-s \-\-show\-id\fR
.RS 4
Print the window id in every response, the window id will be prepended to the response\&.
.RE
.SH "COMMANDS"
.PP
\fBadd_hooks\fR [\fIhook\fR \&...]
.RS 4
Adds a list of hooks without actually connecting to the hook, see
\fIhook\fR
for a list of hooks and
\fIclear_hooks\fR\&.
.RE
.PP
\fBbind\fR \fIcommand:shortcut\fR [\fIcommand:shortcut\fR \&...]
.RS 4
Bind a shorcut or command, to bind only a commandline command without binding a shortcut
\fIcommand:none\fR
must be used, to bind only a shortcut without binding a commandline command
\fInone:shortcut\fR\&.
.RE
.PP
\fBclear_hooks\fR [\fIhook\fR \&...]
.RS 4
Removes a list of hooks so the will no longer be emitted\&. To re\-enable hooks
\fIadd_hooks\fR
can be sent\&. For a list of hooks see
\fIhook\fR\&.
.RE
.PP
\fBconfirm\fR [\fIprompt message\fR]
.RS 4
Shows a confirmation prompt\&. Returns
\fItrue\fR
if
\fIy\fR
was pressed and false if
\fIn\fR
or
\fIEscape\fR
was pressed\&.
.RE
.PP
\fBexecute\fR \fIcommand\fR
.RS 4
Executes a command, the command is parsed the same way as if executed from commandline\&. A shorthand for execute is prepending
\fI:\fR
to the command, i\&.e\&.
\fIdwbremote execute scroll_down\fR
is equivalent to
\fIdwbremote :scroll_down\fR
.RE
.PP
\fBget\fR \fIargument\fR
.RS 4
Gets miscellaneous properties
.PP
\fBArguments\fR
.RS 4
.PP
\fBall_domains\fR
.RS 4
Gets newline separated list of all domains\&.
.RE
.PP
\fBall_hosts\fR
.RS 4
Gets newline separated list of all hosts\&.
.RE
.PP
\fBall_titles\fR
.RS 4
Gets newline separated list of all titles\&.
.RE
.PP
\fBall_uris\fR
.RS 4
Gets newline separated list of all uris\&.
.RE
.PP
\fBcurrent_tab\fR
.RS 4
Gets number of the current tab, starting at 1\&.
.RE
.PP
\fB[n] domain\fR
.RS 4
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\&.
.RE
.PP
\fB[n] history\fR
.RS 4
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\&.
.RE
.PP
\fB[n] host\fR
.RS 4
Gets the host of the nth tab or current tab is n is omitted\&.
.RE
.PP
\fBntabs\fR
.RS 4
Gets total number of tabs\&.
.RE
.PP
\fBprofile\fR
.RS 4
Gets the profile name\&.
.RE
.PP
\fBsession\fR
.RS 4
Gets the name of the session\&.
.RE
.PP
\fBsetting <name>\fR
.RS 4
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\&.
.RE
.PP
\fB[n] title\fR
.RS 4
Gets the title of the nth tab or current tab is n is omitted\&.
.RE
.PP
\fB[n] uri\fR
.RS 4
Gets the uri of the nth tab or current tab is n is omitted\&.
.RE
.RE
.RE
.PP
\fBhook\fR \fIhook\fR [\fIhook\fR \&...]
.RS 4
Connect to a list of hooks\&.
.PP
\fBHooks\fR
.RS 4
.PP
\fBchange_mode\fR
.RS 4
Emitted when the mode changes, return format:
\fIchange_mode <mode>\fR
.PP
\fBmode\fR
.RS 4
The new mode, can be one of
\fInormal\fR,
\fIinsert\fR,
\fIhint\fR,
\fIcommand\fR
or
\fIcaret\fR
.RE
.RE
.PP
\fBclose_tab\fR
.RS 4
Emitted when a tab is closed, return format:
\fIclose_tab <n>\fR
.PP
\fBn\fR
.RS 4
Number of tab that was closed
.RE
.RE
.PP
\fBdocument_finished\fR
.RS 4
Emitted when the DOM document load has been finished for a frame, return format:
\fIdocument_finished <n> <mainframe>\fR
.PP
\fBn\fR
.RS 4
Number of the tab
.RE
.PP
\fBmainframe\fR
.RS 4
\fItrue\fR
if it is the DOM document of the mainframe has been finshed loading,
\fIfalse\fR
if the DOM document of a subframe has been finshed\&.
.RE
.RE
.PP
\fBdownload_finished\fR
.RS 4
Emitted when a download has been finished, return format:
\fIdownload_finished <destination_uri>\fR
.PP
\fBdestination_uri\fR
.RS 4
The destination uri of the download, e\&.g\&.
file:///tmp/download\&.pdf
.RE
.RE
.PP
\fBexecute\fR
.RS 4
Emitted when a command is executed, return format:
\fIexecute <command> <argument> <n>\fR
.PP
\fBcommand\fR
.RS 4
Command that is executed
.RE
.PP
\fBargument\fR
.RS 4
Argument if it is a commandline command with argument or
\fInone\fR
.RE
.PP
\fBn\fR
.RS 4
Numerical modifier or \-1
.RE
.RE
.PP
\fBfocus_tab\fR
.RS 4
Emitted when a tab gets focus, return format:
\fIfocus_tab <n>\fR
.PP
\fBn\fR
.RS 4
Number of tab that gets focus
.RE
.RE
.PP
\fBhook\fR
.RS 4
Emitted when the command
\fIhook\fR,
\fIadd_hooks\fR
or
\fIclear_hooks\fR
is executed, return format:
\fIhook <action> <hooks>\fR
.PP
\fBaction\fR
.RS 4
Either
\fIadd\fR
if add_hooks or hook is executed,
\fIclear\fR
if clear_hooks is executed
.RE
.PP
\fBhooks\fR
.RS 4
List of hooks\&.
.RE
.RE
.PP
\fBload_committed\fR
.RS 4
Emitted when new page load has been committed, return format:
\fIload_committed <n> <uri>\fR
.PP
\fBn\fR
.RS 4
Number of the tab
.RE
.PP
\fBuri\fR
.RS 4
Uri that will be loaded
.RE
.RE
.PP
\fBload_finished\fR
.RS 4
Emitted when a page load has finished, return format:
\fIload_finished <n> <uri>\fR
.PP
\fBn\fR
.RS 4
Number of the tab
.RE
.PP
\fBuri\fR
.RS 4
Uri that will be loaded
.RE
.RE
.PP
\fBnavigation\fR
.RS 4
Emitted when a tab or a frame in a tab requests a new page load, return format:
\fInavigation <n> <mainframe> <uri>\fR
.PP
\fBn\fR
.RS 4
Number of the tab
.RE
.PP
\fBmainframe\fR
.RS 4
\fItrue\fR
if it is the mainframe,
\fIfalse\fR
if it is a subframe that requests the new page load
.RE
.PP
\fBuri\fR
.RS 4
Uri that will be loaded
.RE
.RE
.PP
\fBnew_tab\fR
.RS 4
Emitted when new tab is created, return format:
\fInew_tab <n>\fR
.PP
\fBn\fR
.RS 4
Number of the new tab
.RE
.RE
.PP
\fBquit\fR
.RS 4
Emitted when dwb is closed\&. The response will be empty
.RE
.RE
.RE
.PP
\fBprompt\fR \fIpromptmessage\fR
.RS 4
Shows a prompt dialog\&.
.RE
.PP
\fBpwd_prompt\fR \fIpromptmessage\fR
.RS 4
Shows a password dialog\&. Note that using password prompt is not save\&.
.RE
.SH "EXAMPLES"
.PP
Executing commands
.RS 4
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    dwbremote :tabopen example\&.com
    dwbremote \-pid 1234 execute 2close
.fi
.if n \{\
.RE
.\}
.PP
Getting properties
.RS 4
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    uri="$(dwbremote \-id 0x1000001 get uri)"
    title="$(dwbremote \-id 0x1000001 get 2 title)"
    scripts_enabled="$(dwbremote \-class foo setting enable\-settings)"
.fi
.if n \{\
.RE
.\}
.PP
User/Password prompt
.RS 4
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    username="$(dwbremote prompt Username:)"
    if [ "$username" ]; then
        password="$(dwbremote pwd_prompt Password:)"
    fi
.fi
.if n \{\
.RE
.\}
.PP
Multiple hooks with one dwbremote instance
.RS 4
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    #!/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)
.fi
.if n \{\
.RE
.\}
.PP
Binding multiple shortcuts
.RS 4
.RE
.sp
.if n \{\
.RS 4
.\}
.nf
    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)
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBdwb\fR(1)