git.subgeniuskitty.com - xmenu/.git/blame_incremental

... / ...

Commit	Line	Data
	1	.TH XMENU 1
	2	.SH NAME
	3	xmenu \- menu utility for X
	4	.SH SYNOPSIS
	5	.B xmenu
	6	.RB [ \-iw ]
	7	.RB [ -p
	8	.IR position ]
	9	.RI [ title ]
	10	.SH DESCRIPTION
	11	.B xmenu
	12	is a menu for X,
	13	it reads a list of newline-separated items from stdin,
	14	shows a menu for the user to select one of the items,
	15	and outputs the item selected to stdout.
	16	.PP
	17	The options are as follows:
	18	.TP
	19	.B -i
	20	Disable icons.
	21	This makes xmenu loading faster when not using icons.
	22	.TP
	23	.BI -p " position"
	24	Set the position to spawn xmenu.
	25	Without this option, xmenu spawns next to the cursor.
	26	.I position
	27	is a string of the form
	28	.BR INTxINT[:MONITOR] ,
	29	where the first INT is the x position and the second INT is the y position.
	30	The monitor part between brackets is optional.
	31	.B MONITOR
	32	can be a number from 0 to the number of monitors minus 1;
	33	or it can be a string like
	34	.B current
	35	or
	36	.BR cursor .
	37	If present, the monitor specifies that the position is relative to the upper left corner
	38	of that monitor.
	39	If
	40	.B monitor
	41	is
	42	.B current
	43	or
	44	.BR cursor ,
	45	the monitor to be used is that where the cursor is in.
	46	For example,
	47	.B -p 0x0:cursor
	48	specifies that
	49	.B xmenu
	50	must spawn at the position 0x0 of the monitor where the cursor is in.
	51	And
	52	.B -p 100x500:0
	53	specifies that
	54	.B xmenu
	55	must spawn at the position 100x500 of the monitor 0.
	56	.TP
	57	.B -w
	58	Asks the window manager to draw a border around the menus.
	59	This option may be buggy in some window managers,
	60	specially tiled ones that do not respect window hints.
	61	.PP
	62	Each item read from stdin has the following format:
	63	.IP
	64	.EX
	65	ITEM := [TABS] [[IMAGE TABS] LABEL [TABS OUTPUT]] NEWLINE
	66	.EE
	67	.PP
	68	That means that each item is composed by
	69	tabs, followed by an optional image specification, followed by tabs
	70	followed by a label, followed by more tabs, followed by an output,
	71	and ended by a newline. Brackets group optional elements.
	72	.IP
	73	The initial tabs indicate the menu hierarchy:
	74	items indented with a tab is shown in a submenu of the preceding item not indented.
	75	An item without initial tabs is a top-level item.
	76	.IP
	77	The image is a string of the form "IMG:/path/to/image.png".
	78	It specifies a image to be shown as icon at the left of the entry.
	79	.IP
	80	The label is the string that will be shown as a item in the menu.
	81	An item without label is considered a separator and is drawn as a thin line in the menu
	82	separating the item above from the item below.
	83	.IP
	84	The output is the string that will be output after selecting the item.
	85	If an item does not have an output, its label is used as its output.
	86	.IP
	87	The newline terminates the item specification.
	88	.PP
	89	If the argument
	90	.I title
	91	is given, the title of the menu window is set to it.
	92	.SH USAGE
	93	.B xmenu
	94	is controlled by the mouse,
	95	but can also be controlled by the keyboard.
	96	Items can be selected using the arrow keys,
	97	Tab (with and without Shift),
	98	Enter and Esc.
	99	.TP
	100	.BR Down ", " Tab
	101	Cycle through the items in the regular direction.
	102	.TP
	103	.BR Up ", " Shift-Tab
	104	Cycle through the items in the reverse direction.
	105	.TP
	106	.BR Right ", " Enter
	107	Select the highlighted item.
	108	.TP
	109	.B Left
	110	Go to the menu above.
	111	.TP
	112	.B Esc
	113	Go to the menu above or exit xmenu.
	114	.SH RESOURCES
	115	.B
	116	xmenu
	117	understands the following X resources.
	118	.TP
	119	.B xmenu.font
	120	The font in which the labels should be drawn.
	121	Multiple fonts can be added as fallback fonts;
	122	they must be separated by a comma.
	123	.TP
	124	.B xmenu.background
	125	The background color of non-selected items in the menu.
	126	.TP
	127	.B xmenu.foreground
	128	The color of the label text of non-selected items in the menu.
	129	.TP
	130	.B xmenu.selbackground
	131	The background color of selected items in the menu.
	132	.TP
	133	.B xmenu.selforeground
	134	The color of the label text of selected items in the menu.
	135	.TP
	136	.B xmenu.border
	137	The color of the border around the menu.
	138	.TP
	139	.B xmenu.separator
	140	The color of the separator between items in the menu.
	141	.TP
	142	.B xmenu.gap
	143	The gap, in pixels, between the menus.
	144	.TP
	145	.B xmenu.width
	146	The minimum width, in pixels, of the items in the menu.
	147	.TP
	148	.B xmenu.height
	149	The size in pixels of the height of a single menu item.
	150	.TP
	151	.B xmenu.borderWidth
	152	The size in pixels of the border around the menu.
	153	.TP
	154	.B xmenu.separatorWidth
	155	The size in pixels of the item separator.
	156
	157	.SH EXAMPLES
	158	The following script illustrates the use of
	159	.BR xmenu .
	160	The output is redirected to
	161	.IR sh (1),
	162	creating a command to be run by the shell.
	163	.IP
	164	.EX
	165	#!/bin/sh
	166
	167	cat <<EOF \| xmenu \| sh &
	168	Applications
	169	IMG:./web.png Web Browser firefox
	170	IMG:./gimp.png Image editor gimp
	171	Terminal (xterm) xterm
	172	Terminal (urxvt) urxvt
	173	Terminal (st) st
	174
	175	Shutdown poweroff
	176	Reboot reboot
	177	EOF
	178	.EE
	179	.PP
	180	For example, by selecting \(lqApplications\(rq, a new menu will appear.
	181	Selecting \(lqWeb Browser\(rq in the new menu opens firefox.
	182	.SH SEE ALSO
	183	.IR dmenu (1),
	184	.IR 9menu (1),
	185	.IR thingmenu (1)