Module: gears.history

A generic and stateful history tracking class.

This module hosts an abstract implementation of history tracking. It can be used with any datatype and hide the implementation details.

Alt+Tab like iterator for clients

local h = gears.history {
    unique = true , -- Automagically deduplicate entries
    count  = false, -- Keep track of the number of time an item was pushed
}

-- Listen to event to push/pop/remove objects without boilerplate code.
client.connect_signal("focus"   , h.push   )
client.connect_signal("manage"  , h.push   )
client.connect_signal("unmanage", h.remove )

-- Abstract way to select objects.
h:connect_signal("request::select", function(_, c)
    client.focus = c
    c:jump_to()
end)

-- Support multiple iterators per history object.
local h_i = h:iterate_newest {
    filter = function(c) return c.screen == awful.screen.focused() end,
}

-- Easy to use for transactions.
awful.keygrabber {
    keybindings = {
        {{'Mod1'         }, 'Tab', h_i.select_next    },
        {{'Mod1', 'Shift'}, 'Tab', h_i.select_previous},
    },
    stop_key           = 'Mod1', -- This is (left) "Alt".
    stop_event         = 'release',
    start_callback     = h.pause,
    stop_callback      = h.resume,
    export_keybindings = true,
}

-- Easy to iterate.
h.paused = true

for my_object in h:iterate_oldest() do
    -- something
end

h.paused = false

Info:

  • Copyright: 2014-2019 Emmanuel Lepage Vallee
  • Originally authored by: Emmanuel Lepage Vallee <elv1313@gmail.com>
    (Full contributors list available on our github project)

Constructors

gears.history {[args]} Create a new history tracking object.

Object properties

mode string The history updating mode.
maximum_entries number The maximum number of entries.
count boolean Count the number of time an entry is used.
paused boolean Is the history tracking currently paused.

Object methods

:resume () Resume tracking.
:pause () Pause tracking.
:push (object) Push an entry to the front (most recent) spot.
:remove (value) Remove a value.
:iterate_newest {[args]} Create a new iterator that starts with the newest entry.
:iterate_oldest {[args]} Create a new iterator that starts with the oldest entry.
:oldest () -> () Returns the oldest object tracked by this history.
:newest () -> () Returns the newest object tracked by this history.
:pop_newest () Pop (remove) the most recent entry.
:pop_oldest () Pop (remove) the least recent entry.
:emit_signal (name, ...) Emit a signal. Inherited from gears.object
:connect_signal (name, func) Connect to a signal. Inherited from gears.object
:weak_connect_signal (name, func) Connect to a signal weakly. Inherited from gears.object

Signals

paused Emitted when the history tracking is paused.
resumed Emitted when the history tracking is resumed.
request::select Emitted when the iterator :select() method is called.
entry::ousted Emitted when an entry is ousted because it exeed the maximum_entries.
entry::pushed Emitted when an object is pushed to the history.
entry::added Emitted when an object is added to the history.
entry::removed Emitted when an object is removed from the stack.

Iterator methods

:next () Move the iterator to the next element.
:previous () Move the iterator to the previous element.
:select_next () Move the iterator to the next element and select it.
:select_previous () Move the iterator to the previous element and select it.
:select () Emit the request::select signal on the current object.
:reset () Reset the iterator position.

Iterator properties

current N/A The current entry.
index number The current index.
rotate boolean Start over when :next() or :previous() reach the end.
filter function The filter function used to skip some entries.


Constructors

gears.history {[args]}
Create a new history tracking object.

Parameters:

  • args
    • count boolean Track the number of time an item is pushed. (default false)

Returns:

    A new history tracking object.

Object properties

mode string

The history updating mode.

Possible values are:

  • heap: Always keep a single instance of each entry (default)
  • multi: Allow an entry to be in multiple positions
maximum_entries number
The maximum number of entries.

Use math.huge for unlimited.

See also:

count boolean
Count the number of time an entry is used.
paused boolean
Is the history tracking currently paused.

When paused, all push will be ignored.

Object methods

:resume ()
Resume tracking.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

:pause ()
Pause tracking.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

:push (object)

Push an entry to the front (most recent) spot.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

Note that when the history tracking is paused, calling this has no effect. This allows to connect the function directly without additional boilerplate to take the state into account.

Usage for clients:

client.connect_signal("focus"  , my_history.push )
client.connect_signal("manage" , my_history.push )

Parameters:

  • object Something to push.
:remove (value)

Remove a value.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

Usage for clients:

client.connect_signal("unmanage", my_history.remove )

Parameters:

  • value
:iterate_newest {[args]}
Create a new iterator that starts with the newest entry.

Parameters:

  • args The arguments.
    • rotate boolean Define if the next and previous iterator methods will rotate once the reach the boundary. This does not affect the behavior when iterating using a for loop. (default true)
    • filter function A filter function. It takes the object as sole parameter and it will allowed if the function returns true. Otherwise, the next element will be passed to the filter until it returns true. (default nil)

Usage:

    my_history.paused = true
for my_object in my_history:iterate_newest() do
    -- something
end
my_history.paused = false
:iterate_oldest {[args]}
Create a new iterator that starts with the oldest entry.

Parameters:

  • args The arguments.
    • rotate boolean Define if the next and previous iterator methods will rotate once the reach the boundary. This does not affect the behavior when iterating using a for loop. (default true)
    • filter function A filter function. It takes the object as sole parameter and it will allowed if the function returns true. Otherwise, the next element will be passed to the filter until it returns true. (default nil)

Usage:

    my_history.paused = true
for my_object in my_history:iterate_oldest() do
    -- something
end
my_history.paused = false
:oldest () -> ()
Returns the oldest object tracked by this history.

Returns:

    The oldest object.
:newest () -> ()
Returns the newest object tracked by this history.

Returns:

    The newest object.
:pop_newest ()
Pop (remove) the most recent entry.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

:pop_oldest ()
Pop (remove) the least recent entry.

Note that this is a function, not a method. It is safe to use directly in connect_signal or as a callback.

:emit_signal (name, ...) · Inherited from gears.object
Emit a signal.

Parameters:

  • name string The name of the signal.
  • ... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal().
:connect_signal (name, func) · Inherited from gears.object
Connect to a signal.

Parameters:

  • name string The name of the signal.
  • func function The callback to call when the signal is emitted.
:weak_connect_signal (name, func) · Inherited from gears.object
Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens.

Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

  • name string The name of the signal.
  • func function The callback to call when the signal is emitted.

Signals

paused
Emitted when the history tracking is paused.
resumed
Emitted when the history tracking is resumed.
request::select

Emitted when the iterator :select() method is called.

Calling :select() itself does nothing beside emitting this signal. It is up to the API user to implement a handler for it.

Usage for clients:

my_history:connect_signal("request::select", function(_, c)
    client.focus = c
    c:jump_to()
end)

Arguments:

  • o The object.
entry::ousted
Emitted when an entry is ousted because it exeed the maximum_entries.

Arguments:

  • o The object.
entry::pushed
Emitted when an object is pushed to the history.

It is sent for both new and existing objects.

Arguments:

  • o The object.

See also:

entry::added
Emitted when an object is added to the history.

It is sent only for new entries that were not already in the stack.

Arguments:

  • o The object.

See also:

entry::removed
Emitted when an object is removed from the stack.

Arguments:

  • o The object.

Iterator methods

Iterators objects are created using :iterate_oldest and :iterate_newest.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

:next ()
Move the iterator to the next element.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

See also:

:previous ()
Move the iterator to the previous element.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

See also:

:select_next ()
Move the iterator to the next element and select it.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

See also:

:select_previous ()
Move the iterator to the previous element and select it.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

See also:

:select ()
Emit the request::select signal on the current object.

Note that that is a function rather than a method, it can be passed directly to connect_signal.

:reset ()
Reset the iterator position.

Iterator properties

current N/A
The current entry.

The type depends on the type of object being stored in the history.

index number
The current index.
rotate boolean
Start over when :next() or :previous() reach the end.
filter function

The filter function used to skip some entries.

Clients from the current tag:

 function(c)
     return (not client.focus) or (
             c.screen == client.focus.screen and c.first_tag.selected
         )
 end

Clients from the current screen:

 function(c) return c.screen == awful.screen.focused() end

Clients from the same application as the focused client:

function(c) return (not client.focus) or client.focus.class == c.class end

Tags from the current screen:

 function(t) return t.screen == awful.screen.focused() end

Tags with clients in them:

function(t) return #t:clients() > 0 end
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50