implement tornoff menus; move examples to examples/

Author: phillbush

Makefile

@@ -2,6 +2,7 @@ PROG = xmenu
 OBJS = ${PROG:=.o} ctrlfnt.o
 SRCS = ${OBJS:.o=.c}
 MAN = ${PROG:=.1}
+DOC = README.md
 
 PREFIX ?= /usr/local
 MANPREFIX ?= ${PREFIX}/share/man
@@ -19,6 +20,16 @@ mandir = ${DESTDIR}${MANPREFIX}/man1
 
 all: ${PROG}
 
+# generate README.md from manual; you do not need to run this
+${DOC}: ${MAN}
+	{ \
+		cat README ; \
+		mandoc -I os=UNIX -T ascii ${MAN} | \
+		col -b | \
+		expand -t 8 | \
+		sed 's,^,	,' ; \
+	} >${DOC}
+
 ${PROG}: ${OBJS}
 	${CC} -o $@ ${OBJS} ${LIBS} ${LDFLAGS}
 

README.md

@@ -17,7 +17,6 @@ XMenu understand the following command-line options.
 
 * `-N name`:      Specify a resource/instance name for XMenu.
 * `-p position`:  Specify a position to place XMenu.
-* `-t`:           Enable menus to be torn off.
 * `-w`:           Initiate XMenu as a regular window.
 
 ## Environment
@@ -50,6 +49,8 @@ Reboot			reboot
 
 ![demo](./demo.png)
 
+An example script can be found at `./examples/xmenu.sh`.
+
 ## Customization
 XMenu can be customized by setting the following X resources before
 invoking XMenu.
@@ -68,17 +69,21 @@ invoking XMenu.
 * `XMenu.opacity`:          Background opacity (from 0.0 to 1.0).
 * `XMenu.separatorColor`:   Separator color.
 * `XMenu.shadowThickness`:  3D relief size.
+* `XMenu.tearOff`:          Enable menus to be torn off.
 * `XMenu.topShadowColor`, `XMenu.middleShadowColor`, `XMenu.bottomShadowColor`:
   Colors of the 3D relief.
 
+An example style configurationcanbe found at `./examples/Xresources`.
+
 ## Installation
 Run `make all` to build, and `make install` to install the binary and
 the manual into `${PREFIX}` (`/usr/local`).
 
-## Usage
+## Features
 
 * XMenu reads something in and prints something out, the UNIX way.
 * Submenus (some menu entries can spawn another menu).
+* Torn off menus (menus can be managed by the window manager like a regular window).
 * Separators (menu entries can be separated by a line).
 * Icons (menu entries can be preceded by an icon image).
 * X resources support (you don't need to recompile xmenu for configuring it).
@@ -88,5 +93,207 @@ the manual into `${PREFIX}` (`/usr/local`).
 The code and manual are under the MIT/X license.
 See `./LICENSE` for more information.
 
-## Epilogue
-**Read the manual.**
+## Manual
+
+	XMENU(1)                    General Commands Manual                   XMENU(1)
+	
+	NAME
+	     xmenu - menu utility for X
+	
+	SYNOPSIS
+	     xmenu [-w] [-N name] [-p position] [title]
+	
+	DESCRIPTION
+	     xmenu is a menu for X.  It reads a list of newline-separateditems from
+	     standard input; shows a menu for the user to select one of the items; and
+	     writes the selected item into standard output.
+	
+	     The options are as follows:
+	
+	     -N name
+	             Specifiy the res_name member of the XClassHint(3) property.  Ar
+	             name is used to retrieve resources.  If not specified, defaults
+	             to the command that xmenu was invoked as (that is, the
+	             basename(3) of its argv[0]).
+	
+	     -p position
+	             Set the position to spawn xmenu.  Without this option, xmenu
+	             spawns next to the cursor.  Position is a string of the form
+	             GEOMETRY[:MONITOR], where GEOMETRY is a geometry parsed by
+	             XParseGeometry(3).  MONITOR is the number of the monitor the
+	             geometry is relative to (counting from 0); it can instead be a
+	             string like "current" or "cursor", specifyingthe monitor where
+	             the cursor is on.
+	
+	     -w      Asks the window manager to draw a border around the menu.  This
+	             makes xmenu start torn off.
+	
+	     Each item read from standard input has the following format (bracket
+	     groups optional elements):
+	
+	           [TABS] [IMAGE TABS] LABEL [TABS OUTPUT] NEWLINE
+	     or
+	
+	           [TABS] [:] NEWLINE
+	
+	     The components are as follows:
+	
+	     o   The initial tabs indicate the menu hierarchy: items indented with a
+	         tab are placed in a submenu of the preceding item not indented.  An
+	         item without initial tabs is a top-level item.
+	
+	     o   The image is a string of the form "IMG:/path/to/image.png".  It
+	         specifies the path to an image file to be shown as icon at the left
+	         of the entry.  If the path does not begin with "/", "./", or "../",
+	         the file is searched on the paths specified in the ICONPATH
+	         environment variable.
+	
+	     o   The label is the string that will be shown as an item in the menu.
+	         An item without label or with a single colon (:) as label is
+	         considered a separator and is drawn as a thin line in the menu
+	         separating the item above from the item below.
+	
+	     o   The output is the string that will be output after selecting the
+	         item.  If an item does not have tabs after the label, its label is
+	         used as its output.  If the output is empty or is a colon (:), the
+	         item cannot be selected.
+	
+	     o   The newline terminates the item specification.
+	
+	     If the argument title is given, the title of the menu window is set to
+	     it.
+	
+	USAGE
+	     xmenu is controlled by the mouse, but can also be controlled by the
+	     keyboard.  Items can be selected using the arrow keys.  Tab (with and
+	     without Shift), Home, End, Enter and Esc, and 1-9 keys.  Itams can also
+	     be selected by typing the first several characters in it.
+	
+	     Down    Cycle through the items in the regular direction.
+	
+	     End     Selects the last item in the menu.
+	
+	     Esc     Go to the menu above in the hierarchy or exit xmenu.
+	
+	     Home    Selects the first item in the menu.
+	
+	     Left    Go to the menu above in the hierarchy.
+	
+	     Right, Enter
+	             Select the highlighted item.
+	
+	     Shift-Tab
+	             Cycle through the items in the reverse direction.  When the type-
+	             to-select feature is active, cycle through matching items
+	             instead.
+	
+	     Tab     Cycle through the items in the regular direction.  When the type-
+	             to-select feature is active, cycle through matching items
+	             instead.
+	
+	     Up      Cycle through the items in the reverse direction.
+	
+	     Additional key bindings can be set at compile time by changing the
+	     config.h file.
+	
+	RESOURCES
+	     xmenu understands the following X resources.  They must be prefixed with
+	     either the "XMenu" class, or the name given with the -N command-line
+	     option, followed by a period.
+	
+	     activeBackground
+	             The backround color of selected items in the menu.
+	
+	     activeForeground
+	             The color of the label text of selected items in the menu.
+	
+	     alignment
+	             If set to "left", "center", or "right", text is aligned to the
+	             left, center, or right of the menu, respectively.  By default,
+	             text is aligned to the left.
+	
+	     background
+	             The background color of non-selected items in the menu.
+	
+	     borderColor
+	             The color of the border around the menu.
+	
+	     borderWidth
+	             The size in pixels of the border around the menu.
+	
+	     faceName
+	             Font for drawing text.  If the value is prefixed with "xft:"
+	             (case insensitive), then xmenu uses the Xft(3) library for
+	             drawing text; and fallback fonts can be specified by delimiting
+	             the fonts with commas.  If the value is prefixed with "x:" or
+	             "x11:" (case insensitive), then xmenu uses the X11 library for
+	             drawing text.
+	
+	     faceSize
+	             The size, in points of the font.  This only affects Xft(3) fonts.
+	
+	     foreground
+	             The color of the label text of non-selected items in the menu.
+	
+	     gap     The gap, in pixels, between the menus.
+	
+	     maxItems
+	             Maximum number of items to be displayed in a menu.  If a menu has
+	             more than this number of items, they will be scrolled with arrow
+	             buttons.
+	
+	     opacity
+	             Background opacity as a floating point number between 0.0 and 1.0
+	             inclusive.
+	
+	     separatorColor
+	             The color of the separator between items in the menu.
+	
+	     shadowThickness
+	             The size in pixels of the Motif-like 3D relief.
+	
+	     tearOff
+	             If set to "True", "On", or "Enable", creates a dashed line on the
+	             top of each non-windowed menu to tear them off into a new
+	             windowed menu.
+	
+	     topShadowColor, middleShadowColor, bottomShadowColor
+	             The color of the top/light, middle and bottom/dark parts of the
+	             Motif-like 3D relief.  Setting these resources override
+	             background and separateColor.
+	
+	ENVIRONMENT
+	     The following environment variables affect the execution of xmenu.
+	
+	     DISPLAY
+	             The display to start xmenu on.
+	
+	     ICONPATH
+	             A colon-separated list of directories used to search for the
+	             location of image files.
+	
+	EXAMPLES
+	     The following script illustrates the use of xmenu.  The output is
+	     redirected to sh(1), creating a command to be run by the shell.
+	
+	           $!/bin/sh
+	
+	           xmenu <<EOF | sh &
+	           Applications
+	                   IMG:./web.png   Web Browser     firefox
+	                   IMG:./gimp.png  Image Editor    gimp
+	           Terminal (xterm)                        xterm
+	           Terminal (urxvt)                        urxvt
+	           Terminal (st)                           st
+	
+	           Shutdown                                poweroff
+	           Reboot                                  reboot
+	           EOF
+	
+	     For example, by selecting "Applications", a new menu will appear.
+	     Selecting "Web Browser" in the new menu opens firefox.
+	
+	SEE ALSO
+	     xclickroot(1), X(7)
+	
+	UNIX                             July 9, 2023                             UNIX

ctrlfnt.c

@@ -691,6 +691,18 @@ ctrlfnt_free(CtrlFontSet *fontset)
 	free(fontset);
 }
 
+void
+ctrlfnt__free(CtrlFontSet *fontset)
+{
+	if (fontset == NULL)
+		return;
+	if (fontset->xft_fontset != NULL) {
+		free(fontset->xft_fontset->fonts);
+		free(fontset->xft_fontset);
+	}
+	free(fontset);
+}
+
 void
 ctrlfnt_init(void)
 {

ctrlfnt.h

@@ -25,3 +25,6 @@ int ctrlfnt_height(CtrlFontSet *fontset);
 void ctrlfnt_free(CtrlFontSet *fontset);
 void ctrlfnt_init(void);
 void ctrlfnt_term(void);
+
+/* like ctrlfnt_free, but do not destroy X objects */
+void ctrlfnt__free(CtrlFontSet *fontset);

demo.png

@@ -1,15 +1,14 @@
-.Dd July 4, 2023
+.Dd July 9, 2023
 .Dt XMENU 1
 .Os
 .Sh NAME
 .Nm xmenu
 .Nd menu utility for X
 .Sh SYNOPSIS
 .Nm xmenu
-.Op Fl tw
+.Op Fl w
 .Op Fl N Ar name
 .Op Fl p Ar position
-.Op Fl x Ar button
 .Op Ar title
 .Sh DESCRIPTION
 .Nm
@@ -28,8 +27,9 @@ member of the
 property.
 Ar name
 is used to retrieve resources.
-If not specified, defaults to the command
-.Nm was invoked as
+If not specified, defaults to the command that
+.Nm
+was invoked as
 (that is, the
 .Xr basename 3
 of its
@@ -53,38 +53,11 @@ it can instead be a string like
 or
 .Qq Cm cursor ,
 specifyingthe monitor where the cursor is on.
-.It Fl t
-Add a entry at the top of the menu to torn it off.
 .It Fl w
 Asks the window manager to draw a border around the menu.
 This makes
 .Nm
-istart torn off.
-.It Fl x Ar button
-This option requires an argument of the form
-.Cm "[MODIFIER-]BUTTON" ;
-where
-.Cm MODIFIER
-is
-.Cm Mod1
-to
-.Cm Mod5 ,
-or
-.Cm Alt
-(equivalent to
-.Cm Mod1 ) ,
-or
-.Cm Super
-(equivalent to
-.Cm Mod4 ) ;
-and
-.Cm BUTTON
-is the number of a mouse button.
-When this option is used,
-.Nm
-listens to button presses on the root window,
-and shows the menu when the given button is pressed on the root window,
-or (together with the modifier) on any window.
+start torn off.
 .El
 .Pp
 Each item read from standard input has the following format
@@ -229,6 +202,13 @@ Background opacity as a floating point number between 0.0 and 1.0 inclusive.
 The color of the separator between items in the menu.
 .It Ic shadowThickness
 The size in pixels of the Motif-like 3D relief.
+.It Ic tearOff
+If set to
+.Qq Ic True ,
+.Qq Ic On ,
+or
+.Qq Ic Enable ,
+creates a dashed line on the top of each non-windowed menu to tear them off into a new windowed menu.
 .It Ic topShadowColor , middleShadowColor , bottomShadowColor
 The color of the top/light, middle and bottom/dark parts of the Motif-like 3D relief.
 Setting these resources override
@@ -272,6 +252,5 @@ EOF
 For example, by selecting "Applications", a new menu will appear.
 Selecting "Web Browser" in the new menu opens firefox.
 .Sh SEE ALSO
-.Xr 9menu 1 ,
-.Xr dmenu 1 ,
-.Xr thingmenu 1
+.Xr xclickroot 1 ,
+.Xr X 7