2023-01-26 19:42:40 +01:00
|
|
|
Getting Started
|
|
|
|
---------------
|
|
|
|
|
2023-06-04 22:13:20 +02:00
|
|
|
spmenu is a simple X11 and Wayland menu application which takes standard input, parses
|
|
|
|
it, lets the user choose an option and sends the selected option to standard output.
|
2023-04-24 19:33:59 +02:00
|
|
|
|
2023-05-21 22:16:45 +02:00
|
|
|
In addition to this, it also serves as a run launcher through the included
|
|
|
|
shell script `spmenu_run`, which handles both $PATH listing, .desktop entries
|
|
|
|
and file listing.
|
2023-04-24 19:33:59 +02:00
|
|
|
|
2023-05-21 22:16:45 +02:00
|
|
|
While spmenu is based on dmenu, and is also fully compatible with dmenu,
|
|
|
|
spmenu introduces many new features which can be useful in shell scripting.
|
2023-06-04 22:13:20 +02:00
|
|
|
|
|
|
|
It also serves as a dmenu replacement for Wayland users.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Installing spmenu
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
For up-to-date compilation instructions for spmenu, see [[Compiling spmenu]] or
|
|
|
|
your bundled README.md.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Using spmenu as a run launcher
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
There is a more detailed article covering this, called
|
|
|
|
[[Using spmenu as a run launcher]]. If you just want the basics though,
|
|
|
|
they're covered here.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
spmenu comes with a script called `spmenu_run`. This is a much more powerful
|
|
|
|
run launcher than what dmenu provides. This script handles $PATH listing and
|
|
|
|
executing, .desktop entries (including Steam games), and even file management.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
For $PATH listing (the traditional dmenu_run behavior) you can simply run
|
|
|
|
`spmenu_run`. It should be noted that the default behavior can be overriden
|
|
|
|
and for this reason it is recommended (but not required) that you use
|
|
|
|
`spmenu_run -x` instead. This mode simply lists out all binaries in your
|
|
|
|
$PATH variable. Nothing super fancy. Do however note that you can
|
|
|
|
append entries here, and create functions to parse and do stuff
|
|
|
|
with your selected item/input in the configuration file
|
|
|
|
which can be found at `~/.config/spmenu/run/config`.
|
|
|
|
Doing so is covered in [[Functions in spmenu_run]].
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Using spmenu as a .desktop entry launcher
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
On the other hand, `spmenu_run` provides a .desktop launcher mode as well.
|
|
|
|
To use it, you simply run `spmenu_run -d`. The first time you run this
|
|
|
|
it will take a few seconds depending on the number of .desktop entries you
|
|
|
|
have on your computer. It will start up instantly after that though.
|
|
|
|
It will display your .desktop entries, along with the title and a
|
|
|
|
brief description of what the program does. Of course, you can also
|
|
|
|
append entries to this as well or hide certain entries in the
|
|
|
|
configuration file which can be found at `~/.config/spmenu/run/config`.
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
On X11, the application icon will (optionally) be displayed
|
|
|
|
alongside the desktop entry. Wayland does not yet support displaying
|
|
|
|
images, though so the image will not be displayed.
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
While an option to clear the cache when a new program is installed is
|
|
|
|
available, it does not always work and is disabled for this reason.
|
|
|
|
To clear the cache manually, simply run `spmenu_run -cc`.
|
|
|
|
If you wish to clear the cache every time (this is quite slow), do
|
|
|
|
`spmenu_run -cc -d`.
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Using spmenu to parse text
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
The core concept of spmenu is to take standard input (or the contents
|
|
|
|
of a file), parse it and allow the user to select an item. All scripts
|
|
|
|
written for spmenu use this concept.
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
This is covered in more detail in the article [[Using spmenu to parse text]].
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Customizing spmenu_run
|
2023-05-21 22:16:45 +02:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
To customize `spmenu_run`, you can edit the configuration file
|
|
|
|
which is `~/.config/spmenu/run/config`. For even more customization
|
|
|
|
you can also use functions. A dedicated page for functions exists,
|
|
|
|
called [[Functions in spmenu_run]].
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### Customizing spmenu
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
A basic configuration file can be found at `/usr/share/spmenu/spmenu.conf`.
|
|
|
|
You can use this configuration file by simply copying it to
|
|
|
|
`~/.config/spmenu/spmenu.conf`. If the directory does not already exist,
|
|
|
|
create it.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
This configuration file can be edited using any text editor you want.
|
|
|
|
If you're the kind of person who likes to have many themes, you may want
|
|
|
|
to consider checking out [[User themes]] and the powerful `theme.conf`.
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
### That's it
|
2023-01-26 19:42:40 +01:00
|
|
|
|
2023-06-06 22:00:51 +02:00
|
|
|
That's it. That's all you need to know to get started with spmenu.. and
|
|
|
|
a little more for good measure. From here, you can take a break, or check
|
|
|
|
out [[User scripts]], [[User themes]], [[Functions in spmenu_run]],
|
|
|
|
[[Using spmenu to parse text]], or [[Configuring spmenu]] if you're hungry for more.
|