.\" Copyright (c) 2023, Sebastian Geiger (lanoxx@gmx.net)
.\"
.\" Copyright (c) 2012, Davide Truffa <davide@catoblepa.org>
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of
.\" this manual under the conditions for verbatim copying, provided that
.\" the entire resulting derived work is distributed under the terms of
.\" a permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume.
.\" no responsibility for errors or omissions, or for damages resulting.
.\" from the use of the information contained herein.  The author(s) may.
.\" not have taken the same level of care in the production of this.
.\" manual, which is licensed free of charge, as they might when working.
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.TH "TILDA" "1" "Jan 2024" "tilda 2.0.0" "User Commands"
.SH "NAME"
tilda \- a highly configurable terminal emulator
.SH "SYNOPSIS"
tilda [\fB\-b|\-\-background\-color\fR \fIcolor\fR] [\fB\-c|\-\-command\fR \fIcommand\fR] [\fB\-h|\-\-hidden\fR] [\fB\-f|\-\-font\fR \fIfont\fR] [\fB\-g|\-\-config-file\fR \fIfile\fR] [\fB\-l|\-\-lines\fR \fIfile\fR] [\fB\-s|\-\-scrollbar\fR] [\fB\-w|\-\-working\-dir\fR \fIdir\fR] [\fB\-x|\-\-x\-pos\fR \fIx_pos\fR] [\fB\-y|\-\-y\-pos\fR \fIy_pos\fR] [\fB\-t|\-\-background\-alpha\fR \fIalpha\fR] [\fB\-C|\-\-config\fR] [\fB\-\-display\fR \fIdisplay\fR]
.PP
tilda \fB\-\-dbus\fR
.PP
tilda \fB\-T|\-\-toggle\-window [instance_id]
.PP
tilda \fB\-\-version\fR
.PP
tilda \fB\-\-help\fR
.PP
tilda \fB\-\-help-all\fR
.SH "DESCRIPTION"
.BR Tilda
is a terminal emulator which is highly configurable. The main distinguishing feature of tilda is that it
uses a configurable shortcut to show and hide the tilda window. This allows users to quickly switch between tilda
and other windows only through keyboard shortcuts. When tilda is hidden it will move
outside of the screen until the pull/toggle shortcut is pressed again to show the tilda window. The behaviour of
tilda can be configured using the preferences dialog that is available via the context menu. A subset of the options
can also be configured from the command line as documented below.
.PP
Please note that currently command line options override the settings in the configuration file and
are persisted into the configuration file.
.PP
On Xorg-based desktops, Tilda is using an X11 filter function to register its
hotkeys. On Wayland, this method only works while other X11-based programs are
active but we cannot send hotkeys to tilda while native Wayland applications
have the focus. Therefore, on Wayland desktops tilda needs to be started with
D-Bus support (i.e., with \fB\-\-dbus\fR) and a global shortcut key must be
registered using the desktop environment settings to send a D-Bus action to
show or hide the Tilda window.
.PP
.SH "OPTIONS"
.SS "Help Options:"
.TP
\fB\-?\fR, \fB\-\-help\fR
Show help options
.TP
\fB\-\-help-all\fR
Show all help options, including D-Bus and GTK options.
.SS "Application Options:"
.TP
\fB\-b\fR, \fB\-\-background\-color\fR \fIcolor\fR
Set the background \fIcolor\fR. The value can be either a standard color name from X11 or a hexadecimal value (i.e., #rgb, #rrggbb, etc.).
.TP
\fB\-c\fR, \fB\-\-command\fR \fIcommand\fR
Run a \fIcommand\fR at startup instead of the default shell.
.TP
\fB\-h\fR, \fB\-\-hidden\fR
Start Tilda hidden.
.TP
\fB\-f\fR, \fB\-\-font\fR \fIfont\fR
Set the font to the Pango FontDescription specified in \fIfont\fR. Defaults to "Monospace 11".
.TP
\fB\-l\fR, \fB\-\-lines\fR \fIlines\fR
The the scrollback buffer size to a maximum of \fIlines\fR.
.TP
\fB\-s\fR, \fB\-\-scrollbar\fR
Show a scrollbar at the side of the terminal.
.TP
\fB\-v\fR, \fB\-\-version\fR
Print the version, then exit.
.TP
\fB\-w\fR, \fB\-\-working\-dir\fR \fIdir\fR
Set initial working directory to \fIdir\fR.
.TP
\fB\-x\fR, \fB\-\-x\-pos\fR \fIx_pos\fR
Set the X position of the tilda terminal window to \fIx_pos\fR.
.TP
\fB\-y\fR, \fB\-\-y\-pos\fR \fIy_pos\fR
Set the Y position of the tilda terminal window to \fIy_pos\fR.
.TP
\fB\-t\fR, \fB\-\-background-alpha\fR \fIalpha\fR
Set the terminal windows transparency to \fIalpha\fR (i.e., 0\-100%). Higher values
increase the level of transparency.
.TP
\fB\-C\fR, \fB\-\-config\fR
Show the configuration wizard.
.TP
\fB\-\-display\fR=\fIDISPLAY\fR
Set the X display to use (i.e., :0, :0.0, etc.).
.SS "D-Bus Options:"
.TP
\fB\-\-dbus\fR
Enables D-Bus support (see \fID-Bus\fR).
.TP
\fB\-T\fR, \fB\-\-toggle\-window\fR \fI[instance_id]\fR
Toggle a Tilda window with \fIinstance_id\fR and exit. If \fIinstance_id\fR is
not specified it will default to instance 0. This option provides a convenient
way to toggle tilda windows on Wayland environments and is equivalent to the
longer \fIdbus-send\fR command documented below. It can be used to setup a
Keyboard shortcut on a Wayland-based desktop environment which will then toggle
the Tilda window. Note, that this option is affected by the
"Non-Focus Pull Up Behaviour" setting.
.SH "NOTES"
.SS D-Bus
If D-Bus is enabled, then Tilda offers a method on D-Bus to toggle the Tilda Window.
Each Tilda process registers its own D-Bus name, so it is possible to
run multiple tilda processes each with their own config file and control
them separately via D-Bus. When D-Bus is enabled, then the pull down
shortcut is not registered as an Xorg filter function, and a suitable
global shortcut needs to be configured in the desktop environment (see
\-\-toggle\-window). You may optionally clear the pull shortcut in the settings,
if D-Bus support is enabled.
.PP
Each Tilda instance registers itself using a dynamically generated
bus name and object path using its instance number. The first Tilda
instance will be on the bus name:
.TP
    com.github.lanoxx.tilda.Actions0
.PP
with object path:
.TP
    /com/github/lanoxx/tilda/Actions0
.PP
The interface name is always:
.TP
    com.github.lanoxx.tilda.Actions
.PP
To toggle the tilda window you can use the \fB\-T|\-\-toggle\-window\fR option
of tilda:
.TP
.EX
    tilda -T    # toggle default instance (i.e., 0)
.EE
.TP
.EX
    tilda -T 0  # explicitly toggle the specified instance (i.e., 0)
.EE
.PP
Alternatively, you can also use the \fBdbus-send\fR command.
.TP
.EX
    dbus-send --session --type=method_call \\
       --dest=com.github.lanoxx.tilda.Actions0 \\
       /com/github/lanoxx/tilda/Actions0 \\
       com.github.lanoxx.tilda.Actions.Toggle
.EE
.PP
For each additional tilda instance the bus name and object path will
be incremented by one (e.g. Actions1, Actions2, etc.).
.PP
You can use one of the above commands to register a global hotkey in your Wayland
session. Under Gnome, this can be done under Settings -> Keyboard
-> Keyboard Shortcuts.
.SS "FILES"
.PP
Tilda creates its configuration files under \fB~/.config/tilda/\fR. For each instance
it will create a config file named \fBconfig_<N>\fR, where \fB<N>\fR starts at 0 and is
incremented for each additional process that is started.
.PP
Tilda also creates a cache directory under \fB~/.cache/tilda/locks\fR, where it will create
a global lock file named \fBlock_0_0\fR and additional instance specific lock files
named \fBlock_<PID>_<N>\fR, where \fB<PID>\fR is the process id and \fB<N>\fR is the
instance id.
.PP
You may optionally create a file named \fBstyle.css\fR and place it into the
tilda config directory if you want to customize the look of tilda.
.SH "BUGS"
Please report bugs via Github at https://github.com/lanoxx/tilda/issues
.SH "SEE ALSO"
For further information visit the project repository or have a look at the
wiki: https://github.com/lanoxx/tilda/wiki