NAME

Rofi::Script - perl interface to the rofi menu

DESCRIPTION

rofi is a lightweight, extensible, scriptable, menu interface for Linux. It has a scripting API documented in rofi-script. This module is a perl interface to that API.

Generally, the interface works by printing options to STDOUT, which appear in the rofi menu for selection. Each time a user selects an option, the script is called again with the most recent selection pushed onto @ARGV.

There are also some envars that let you inspect certain user actions. Those are exposed via:

"is_initial_call"

"provided_entry_selected"

"custom_entry_selected"

There are also some options that can be set by printing specially formatted strings to STDOUT.

SYNOPSIS

  use Rofi::Script;

  # print options on the first call; if a user selects these, we can detect that
  # in the SWITCH below
  if (rofi->is_initial_call) {
      rofi->set_prompt("Please select one")
          ->add_option("Show markup example");
  }

  # handle user selections
  SWITCH: for (rofi->shift_arg) {
      next unless $_;

      /markup/ && rofi
          ->set_prompt("markup")
          ->enable_markup_rows
          ->add_option(qq{<i>You can use pango for markup</i>});
  }

  rofi->show;

See also the example implementation script in bin/example.pl.

EXPORTED FUNCTIONS

rofi

  rofi
    ->set_prompt('Please choose')
    ->add_option("Foo")
    ->add_option("Bar")
  if rofi->is_initial_call;

  if (my $cmd = rofi->shift_arg) {
    $cmd =~ /foo/ && rofi
      ->set_prompt("foo")
      ->add_option("bar");
  }

This is a god object that's the primary interface to the entire script interface. This object uses a fluid configuration style where you can chain various methods and configuration options.

With the standard initialization, the object returned by rofi will:

• Parse args from @ARGV

• Print output to STDOUT (this is how the rofi app actually displays things)

If it doesn't look like the script was called by rofi (i.e. ROFI_RETV is unset), and ROFI_SCRIPT_DEBUG is unset, this will return undef. So it's possible to know if your script (or whatever) was called from rofi or not.

METHODS

get_args

Gets the arguments "rofi" is aware of.

set_args

Setter for the args "rofi" cares about.

shift_arg

  my $cmd = rofi->shift_arg

Pop the last arg from the args queue. This is how you would navigate your way through the rofi's "call stack"

add_option

    rofi->add_option("Choice #1");
    rofi->add_option(
        "You can also pass options to rows" => (
            nonselectable => 1,
            urgent        => 1,
            meta          => 'invisible search terms',
            icon          => 'path/to/icon/to/show/in/row'
        )
    );

Add a row to rofi's output. If you select a row, it will cause your script to be re-called, with the selected row pushed onto the args stack.

You can also pass an even sized list after the row text to modify certain aspects of the row.

show

  rofi->show;

Renders the script output to whatever handle was set by "set_show_handle". By default, this goes to STDOUT.

set_show_handle

  my $str = '';
  open my $h, '>', $str;
  rofi->set_show_handle($h);

Set the handle that is printed to by show.

get_show_handle

  my $h = rofi->get_show_handle;
  close $h;

Return the output handle used by "show", set by "set_show_handle".

is_initial_call

True if this is the first time the script is being called

provided_entry_selected

The user selected a value from the list of provided entries

custom_entry_selected

User manually entered a value on the previous run

set_prompt

  rofi->set_prompt("Please select a value");

Set the prompt on the rofi popup

set_message

Set a message in the rofi box

enable_markup_rows

Turn on pango markup for rows

disable_markup_rows

Turn off pango markup for rows

markup_rows_enabled

Query whether or not markup rows are enabled

set_delim

Change the delimiter used to indicate new lines. This is \n by default. There's not really a need to mess with this. I'm not even sure it's implemented 100% correctly.

set_no_custom

Call this to ignore any custom entries from the user

debug

  # dump the rofi object
  rofi->debug

  # dump whatever
  Rofi::Script::debug($whatever);

Dump the contents of the "rofi" object (or anything else) to STDERR. Set ROFI_SCRIPT_DEBUG to enable this.

cpanm Rofi::Script

perl -MCPAN -e shell
install Rofi::Script