/ 
Rofi-Script-1.242630
River stage zero No dependents
/ Rofi::Script

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.

If you're just writing a simple script with a set of options and code that should run when one of those options is selected, consider Rofi::Script::Simple.

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.