i3menu.1

.nh
.TH I3MENU  1 2022-05-19 budlabs "User Manuals"
.SH NAME
.PP
i3menu - Adds more features to rofi when used in i3wm

.SH SYNOPSIS
.PP
.RS

.nf
i3menu     [--theme THEME] [--layout|-a LAYOUT] [--include|-i INCLUDESTRING] [--top|-t TOP] [--xpos|-x INT] [--xoffset INT] [--ypos|-y INT] [--yoffset INT] [--width|-w INT] [--options|-o OPTIONS] [--prompt|-p PROMPT]  [--filter|-f FILTER] [--show MODE] [--modi MODI] [--target TARGET] [--orientation ORIENTATION] [--anchor INT] [--height INT] [--fallback FALLBACK] [--no-auto-position] 
i3menu     [--verbose] [--dryrun] 
i3menu     [--list-directory DIRECTORY] 
i3menu     --help|-h
i3menu     --version|-v

.fi
.RE

.SH OPTIONS
.PP
.RS

.nf
--anchor               INT           | Sets the "*anchor*" point of the menu.  
--dryrun                             | Do not execute any i3-msg commands  
--fallback             FALLBACK      | DEPRECATED
-f, --filter           FILTER        | Sets initial inputbox text
--height               INT           | Overrides the calculated height of the menu.  
-h, --help                           | print help and exit  
-i, --include          INCLUDESTRING | combination of p e l  
-a, --layout           LAYOUT        | mouse, window, titlebar, tab, A, B, C, D  
--list-directory       DIRECTORY     | content of DIRECTORY will be list  
--modi                 MODI          | set rofi -modi option 
--no-auto-position                   | don't autoposition menu if its outside the workspace  
-o, --options          OPTIONS       | extra rofi options  
--orientation          ORIENTATION   | vertical\\|horizontal  
-p, --prompt           PROMPT        | Sets the prompt of the menu to PROMPT 
--show                 MODE          | short hand for the rofi option `-show`  
--target               TARGET        | target window, passed to i3list  
--theme                THEME         | change appearance of the menu  
-t, --top              TOP           | put TOP at the top of the list  
--verbose                            | Print additional information to STDERR 
-v, --version                        | print version info and exit  
-w, --width            INT           | Changes the width of the menu  
--xoffset              INT           | offsets the menu on the x axis  
-x, --xpos             INT           | absolute X position of the menu  
--yoffset              INT           | offsets the menu on the y axis   
-y, --ypos             INT           | absolute Y position of the menu  

.fi
.RE

.SS --anchor               INT
.PP
The default is \fB1\fP\&. \fB1\fP means the top left
corner, \fB9\fP means the bottom right corner.
Corner in this context doesn't refer to the
corners of the screen, but the corners of the
menu. If the anchor is \fItop left\fP (\fB1\fP), the
menu will \fIgrow\fP from that point.

.SS --fallback             FALLBACK
.PP
The functionality has been removed.

.SS -i, --include          INCLUDESTRING
.PP
INCLUDESTRING can be set to force which elements of the menu to include.
INCLUDESTRING can be one or more of the following character:

.TS
allbox;
l l 
l l .
\fB\fCchar\fR	\fB\fCelement\fR
\fBp\fP	prompt
\fBe\fP	entrybox
\fBl\fP	list
.TE

.PP
\fB\fCecho "list" | i3menu --include le --prompt "enter a value: "\fR
.br
The command above will result in a menu without the \fBprompt\fP element.

.PP
\fB\fCi3menu --include pe --prompt "enter a value: "\fR
.br
The command above will result in a menu without a \fBlist\fP element. (just an inputbox).

.PP
It's also worth mentioning that \fBi3menu\fP adapts to the objects it knows before creating the menu. This means that if no input stream (list) exist, no list element will be included, the same goes for the prompt.

.SS -a, --layout           LAYOUT
.PP
This is where \fBi3menu\fP differs the most from normal \fBrofi\fP behavior and is the only option that truly depends on \fB\fCi3\fR, \fB\fCi3list\fR (and \fBi3fyra\fP if the value is A|B|C|D). If this option is not set, the menu will default to a single line (\fIdmenu like\fP) menu at the top of the screen. If however a value to this option is one of the following:

.RS
.IP \(bu 2
mouse
.br
At the mouse position (requires \fB\fCxdotool\fR)
.IP \(bu 2
window
.br
The currently active window.
.IP \(bu 2
titlebar
.br
The titlebar of the currently active window.
.IP \(bu 2
tab
.br
The tab (or titlebar if it isn't tabbed) of the currently active window.
.IP \(bu 2
A,B,C or D
.br
The \fBi3fyra\fP container of the same name if it is visible. If target container isn't visible the menu will be displayed at the default location.

.RE

.PP
titlebar and tab LAYOUT will be displayed as a single line (\fIdmenu like\fP) menu, and the other LAYOUTS will be of vertical (\fIcombobox\fP) layout with the prompt and entrybox above the list.

.PP
The position of the menu can be further manipulated by using \fB\fC--xpos\fR,\fB\fC--ypos\fR,\fB\fC--width\fR,\fB\fC--height\fR,\fB\fC--orientation\fR,\fB\fC--include\fR\&.

.PP
\fB\fC$ echo "list" | i3menu --prompt "select: " --layout window --xpos -50 --ypos 30\fR
.br
The command above would create a menu with the same size and position as the current window, but place it 50px to the left of the window, and 30px below the \fIlower\fP of the window.

.SS --list-directory       DIRECTORY
.PP
This option will list filenames in DIRECORY. The
selected item will be returned with the full path.

.SS --modi                 MODI
.PP
This is a short hand for the \fBrofi\fP option \fB\fC-modi\fR\&. So instead of doing this:
.br
\fB\fC$ i3menu -o '-modi run,drun -show run'\fR , you can do this:
.br
\fB\fC$ i3menu --modi run,drun --show run\fR

.SS -o, --options          OPTIONS
.PP
The argument is a string of aditional options to pass to \fBrofi\fP\&.

.PP
\fB\fC$ i3menu --prompt "Enter val: " --options '-matching regex'\fR
.br
will result in a call to rofi looking something like this:
.br
\fB\fCrofi -p "Enter val: " -matching regex -dmenu\fR

.PP
Note that the \fBrofi\fP options: \fB\fC-p, -filter, -show, -modi\fR \fIcould be\fP entered to as arguments to \fB\fCi3menu --options\fR, but it is recommended to use: \fB\fC--prompt\fR, \fB\fC--filter\fR, \fB\fC--show\fR and \fB\fC--modi\fR instead, since this will make i3menu optimize the layout better.

.SS --orientation          ORIENTATION
.PP
This forces the layout of the menu to be either vertical or horizontal. If \fB\fC--layout\fR is set to \fBwindow\fP, the layout will always be \fB\fCvertical\fR\&.

.SS --target               TARGET
.PP
TARGET is a string containing additional options passed to \fBi3list\fP\&.
This can be used to change the target window when \fB\fC--layout\fR is set to:
\fB\fCwindow\fR,\fB\fCtitlebar\fR or \fB\fCtab\fR\&.

.SS --theme                THEME
.PP
If a \fB\&.rasi\fP file with same name as THEME exist in \fB\fCI3MENU_DIR/themes\fR, it's content will get appended to theme file before showing the menu.

.PP
\fB\fC$ echo "list" | i3menu --theme red\fR
.br
this will use the the file: \fB\fCI3MENU_DIR/themes/red.rasi\fR

.PP
If no matching themefile is found, \fB\fCI3MENU_DIR/themes/default.rasi\fR will be used
(and created if it doesn't exist).

.SS -t, --top              TOP
.PP
If TOP is set, the input stream (LIST) will get matched against TOP.
Lines in LIST with an exact MATCH of those in TOP will get moved to the TOP of LIST before the menu is created.

.PP
\fB\fC$ printf '%s\\n' one two three four | i3menu --top "$(printf '%s\\n' two four)"\fR

.PP
will result in a list looking like this:
.br
\fB\fCtwo four one three\fR

.SS -w, --width            INT
.PP
If the argument to \fB\fC--width\fR ends with a \fB\fC%\fR
character the width will be that many percentages
of the screenwidth. Without \fB\fC%\fR absolute width in
pixels will be set.

.SS --xoffset              INT
.PP
If \fB\fC--layout\fR is set to \fB\fCwindow\fR and \fB\fC--xpos\fR
is set to \fB\fC-50\fR, the menu will be placed 50 pixels
to the left of the active window but have the same
dimensions as the window.

.SH USAGE
.PP
\fB\fCi3menu\fR wraps the options i use the most with \fB\fCrofi\fR
and make it easy to set different color schemes
and positions for the menu.

.PP
Every line in \fB\fCstdin\fR will be displayed as a menu item.
The order will be the same as entered if not \fB\fC--top\fR is set.

.PP
The foundation for the appearance of the menus are the themefiles
\fBi3menu.rasi\fP,\fBthemevars.rasi\fP, found in I3MENU_DIR (defaults to $XDG_CONFIG_HOME/i3menu), but depending on the options
passed to \fB\fCi3menu\fR certain values of the themefiles
will get overwritten.


.SH ENVIRONMENT
.SH I3MENU_DIR
.PP
Path to config directory.

.SH CONTACT
.PP
Send bugs and feature requests to:
.br
https://github.com/budlabs/i3ass/issues

.SH COPYRIGHT
.PP
Copyright (c) 2018-2022, budRich of budlabs
.br
SPDX-License-Identifier: MIT