1 .Dd May 29, 2023
2 .Dt XITEMS 1
3 .Os
4 .Sh NAME
5 .Nm xitems
6 .Nd menu for X
7 .Sh SYNOPSIS
8 .Nm
9 .Op Fl font Ar font
10 .Op Fl bg Ar colour
11 .Op Fl fg Ar colour
12 .Op Fl sbg Ar colour
13 .Op Fl sfg Ar colour
14 .Op Fl bc Ar colour
15 .Op Fl bw Ar width
16 .Op Fl hp Ar pad
17 .Op Fl vp Ar pad
18 .Op Fl x Ar x
19 .Op Fl y Ar x
20 .Sh DESCRIPTION
21 The X utility
22 .Nm
23 draws a menu, based on stdin
24 (here refer to a later section)
25 and prints the user's choice to stdout.
26 The options are as follows:
27 .Bl -tag -width Ds
28 .It Fl font Ar font
29 The font to be used for displaying text.
30 Corresponds to the resource font.
31 Default is
32 .Dq DejaVu Sans Mono-10 .
33 .It Fl bg Ar colour
34 Specifies the normal background colour.
35 Corresponds to the resource background.
36 Default is
37 .Dq white .
38 .It Fl fg Ar colour
39 Specifies the normal foreground colour.
40 Corresponds to the resource foreground.
41 Default is
42 .Dq black .
43 .It Fl sbg Ar colour
44 Specifies the background colour for selected item.
45 Corresponds to the resource selectedBackground.
46 Default is
47 .Dq black .
48 .It Fl sfg Ar colour
49 Specifies the foreground colour for selected item.
50 Corresponds to the resource selectedForeground.
51 Default is
52 .Dq white .
53 .It Fl bc Ar colour
54 Specifies the border colour.
55 Corresponds to the resource borderColour.
56 Default is
57 .Dq black .
58 .It Fl bw Ar width
59 Specifies the border width.
60 Corresponds to the resource borderWidth.
61 Default is 1.
62 .It Fl hp Ar pad
63 Specifies the horizontal padding.
64 Corresponds to the resource horizontalPadding.
65 Default is 2.
66 .It Fl vp Ar pad
67 Specifies the vertical padding.
68 Corresponds to the resource verticalPadding.
69 Default is 1.
70 .It Fl x Ar x
71 The horizontal position to spawn the window at.
72 Default corresponds to the horizontal position of the pointer.
73 .It Fl y Ar y
74 The vertical position to spawn the window at.
75 Default corresponds to the vertical position of the pointer.
76 .El
77 .Pp
78 The options, which correspond to a resource take precedence over that
79 resource.
80 .Pp
81 .Nm
82 reads contents of the menu on stdin.
83 The input consists of one, or several newline-separated entries (items).
84 Each entry has the following format:
85 .Pp
86 .Dl ITEM := [KEYS] TAB LABEL
87 .Pp
88 The optional KEYS field consists of one or more space-separated key
89 strings, such that can be used with
90 .Xr XStringToKeysym 3 .
91 Pressing any of these keys immediately select this item.
92 Keys are configured case-insensitively.
93 .Ss Key and button bindings
94 .Nm
95 can be intuitively controlled with mouse by bringing the pointer over
96 the desired item and clicking.
97 Additional key and button bindings are as follows:
98 .Bl -tag -width Ds
99 .It Scroll down , j , down , control-n
100 Move selection one item down.
101 .It Scroll up , k , up , control-p
102 Move selection one item up.
103 .It Escape , control-c
104 Quit, outputting nothing.
105 .It Return , control-m , control-j
106 Quit, outputting the selected item.
107 .It Button 1, button 2, button 3
108 Quit.
109 If the pointer is inside the window, output the selected item,
110 otherwise output nothing.
111 .El
112 .Sh RESOURCES
113 .Nm
114 understands the following resources:
115 .Bl -tag -width Ds
116 .It Ic xitems.font
117 Specifies the font to be used for displaying text.
118 .It Ic xitems.foreground , xitems,background
119 Specifies the normal foreground and background colours.
120 .It Ic xitems.selectedForeground , xitems,selectedBackground
121 Specifies the foreground and background colours for selected items.
122 .It Ic xitems.borderColour
123 Specifies the border colour.
124 .It Ic xitems.borderWidth
125 Specifies the border width.
126 .It Ic xitems.verticalPadding , xitems.horizontalPadding
127 Specifies the vertical and horizontal padding.
128 .El
129 .Sh EXAMPLES
130 The following script displays a menu with items
131 .Dq Monitor ,
132 .Dq xTerm
133 and
134 .Dq xCalc .
135 Each can be selected by pressing the key, corresponding to the capital
136 letter, or the Cyrillic key, sharing the same position.
137 Selecting
138 .Dq Monitor
139 creates a similar menu, and selecting anything else runs the
140 corresponding command.
141 .Bd -literal -offset indent
142 #!/bin/sh
143 
144 topmenu() {
145 	xitems <<-x
146 m Cyrillic_softsign	Monitor
147 t Cyrillic_e	xTerm
148 e Cyrillic_u	xCalc
149 	x
150 }
151 
152 monitormenu() {
153 	xitems <<-x
154 b Cyrillic_i	xBiff
155 c Cyrillic_es	xConsole
156 	x
157 }
158 
159 s=$(topmenu)
160 
161 [ -z "$s" ] && exit
162 
163 if [ "$s" = Monitor ]; then
164 	monitormenu
165 else
166 	echo $s
167 fi | tr '[A-Z]' '[a-z]' | sh
168 .Ed
169 .Sh AUTHORS
170 .An Alexander Arkhipov Aq Mt aa@manpager.net .
171 .Sh EXIT STATUS
172 .Ex -std