Module `wf`

--The arguments are passed in the form:
set { 'section', option = value, ...}

-- The wayfire.ini equivalent:
--
-- [section]
-- option = value
-- ...

function map(opts: ?{pop_keys:number}, keys: string, handler: fn()) line 328

Map a sequence of keys to an action.

The keys string follows similar formatting to that of emacs. Every key is separated by whitespace, and formatted as:

 (Modifier-)*Key

Modifiers are:

| | | | - | - | | S | Shift | | M | Alt / Meta / Mod1 | | C | Ctrl | | s | Super / Logo / Mod4 | | c | Caps |

| | | | - | - | | M1 | Alt / Meta / Mod1 | | M2 | Mod2 | | M3 | Mod3 | | M4 | Super / Logo / Mod4 | | M5 | Mod5 |

Keys must be valid keysym names as defined in <xkbcommon-keysyms.h> or a Latin-1 symbol. (utf8 strings are not handled)

(You can use $ xkbcli interactive-wayland from the xkbcommon tools package to interactively display the keysym names as you type on the keybaord.)

Examples:

| | | | --- | -- | | C-a | Ctrl and a pressed at the same time. | | C-S-a | Ctrl, Shift and a pressed at the same time. | | C-a b c | Ctrl and a pressed at the same time, then b pressed, then c | | | pressed. |

Usage:

-- Open a terminal window on super + return.
wf.map('s-Return', function()
    wf.get_core():run('foot')
end)

-- Vim/emacs-like Modal keybinds :)
--
-- Toggle music on 'super + n' followed by 'p'.
wf.map('s-n p', function()
    wf.get_core():run('mpc toggle')
end)

function outputs:hook(signal: string, handler: fn(output,data)): fn(output,data) line 1140

Hook into a signal on all outputs.

Start listening for and calling handler on this signal. output is the specific Output that triggered the signal. The type of data depends on the signal being listened for. See (TODO: signal definitions page).

Note that this differs from calling Output:hook() on a specific output as we are hooking into this signal for all outputs simultaneously.

Usage:

local wf = require 'wf'

wf.outputs:hook('view-focused', function(output, data)
    print('View ', data.view, ' focused on output ', output)
end)

assert(handler == wf.outputs:hook('view-focused', handler))

function outputs:unhook(signal: string, handler: fn(output,data)) line 1168

Unhook from a signal on all outputs.

Stop listening for and calling handler on this signal.

Usage:

local handler = wf.outputs:hook('view-focused',
                                function(output, data) end)
wf.outputs:unhook('view-focused', handler)

local handler = function() end
wf.outputs:hook('view-mapped', handler)
wf.outputs:hook('view-focused', handler)
wf.outputs:unhook('view-mapped', handler)
wf.outputs:unhook('view-focused', handler)

function reload_init() line 1193

Reload the lua init file.

Usage:

-- Reload init on when super + shift + r is pressed.
wf.map('s-R', wf.reload_init)

Class Core

The Wayfire compositor instance.

Usage:

local core = wf.get_core()
-- move the cursor to (100, 100)
core:warp_cursor({100, 100})

function Core:set_cursor(name: string) line 433

Set the cursor to the given name from the cursor theme.

function Core:hide_cursor() line 442

Request to hide the cursor.

Increments the hide-cursor reference count and hides the cursor if it is not already hidden.

function Core:unhide_cursor() line 449

Request to unhide the cursor.

Decrement the hide-cursor reference count. If it goes to 0, then the cursor is actually unhidden.

function Core:warp_cursor(position: Pointf) line 456

Move the cursor to the given point.

The point is interpreted as being in global coordinates.

function Core:get_cursor_position(): Pointf line 464

Get the cursor position in global coordinates.

function Core:get_cursor_focus_view(): View line 472

Get the view that currently has cursor focus.

function Core:get_touch_focus_view(): View line 480

Get the view that currently has touch focus.

function Core:get_view_at(point: Pointf): ?View line 491

Get the view at the given point.

The point is interpreted as being in global coordinates. Returns nil if there is no view at the point.

function Core:set_active_view(view: View) line 499

Give a view keyboard focus.

function Core:focus_view(view: View) line 508

Focus the given view and it's output.

Also brings the view to the front of the stack.

function Core:focus_output(output: Output) line 516

Focus the given output.

function Core:get_active_output(): Output line 524

Get the currently focused output.

function Core:move_view_to_output(view: View, new_output: Output, reconf: bool) line 537

Move the given view to the output.

If reconf is true, then clamp the view's geometry to the target output's geometry.

function Core:get_wayland_display(): string line 547

Get the Wayland socket name of the current Wayland session.

function Core:get_xwayland_display(): string line 555

Get the XWayland display name.

function Core:run(command: string): int line 568

Run a command with the system POSIX shell.

Sets the correct WAYLAND_DISPLAY and DISPLAY variables as well as others in order to make the process properly aware of the Wayfire session.

function Core:shutdown() line 573

Shutdown the whole Wayfire process.

function Core:get_output_layout(): OutputLayout line 580

Get the OutputLayout object representing the layout of the outputs.

function Core:hook(signal: string, handler: fn(core,data)): fn(core,data) line 618

Hook into a signal on the Wayfire instance.

Start listening for and calling handler on this signal. The type of data depends on the signal being listened for. See (TODO: signal definitions page).

Usage:

wf.get_core():hook('reload-config', function(core, data)
    print('The wayfire config has been reloaded!')
end)

local wf = require('wf')

-- Whatever the wayfire config file says, override the option value
-- as soon as it's reloaded.
do
    local my_settings = function()
        wf.set {'core', background_color = '#344B5DFF'}
    end

    local core = wf.get_core()
    core:hook('reload-config', function(core, data)
        -- Config was reloaded
        my_settings()
    end)

    my_settings()
end

assert(handler == wf.get_core():hook('startup-finished', handler))

function Core:unhook(signal: string, handler: fn(core,data)) line 648

Unhook from a signal on the Wayfire instance.

Stop listening for and calling handler on this signal.

Usage:

local handler = wf.get_core():hook('view-created',
                            function(core, data) end)
core:unhook('view-created', handler)

local core = wf.get_core()
local handler = function() end
core:hook('view-created', handler)
core:hook('startup-finished', handler)
core:unhook('view-created', handler)
core:unhook('startup-finished', handler)

Class OutputLayout

The current layout of the outputs.

Mainly useful for hooking into output layout signals like "output-added".

Usage:

local output_layout = wf.get_core():get_output_layout()
output_layout:hook("output-added", function(output_layout, data)
    print("new output!", data.output)
end)

function OutputLayout:get_output_at(x: number, y: number): Output line 678

Get the output at the given coordinates.

Returns nil if no output is on the specified coordinate.

function OutputLayout:get_output_coords_at(origin: Pointf): Output, Pointf line 692

Get the output at the given coordinates and the closest point on it.

Returns output, closest meaning the output found at the given origin point and the closest point to the given origin on the output.

function OutputLayout:get_num_outputs(): number line 704

Get the number of current outputs.

function OutputLayout:get_next_output(prev: Output): Output line 723

Iterate through the current outputs.

Start by calling this function with nil as parameter and then successively call it until the returned value is the same as the first call.

Usage:

local first = output_layout:get_next_output(nil)
local output = first
repeat
    print("Current output:", output)
    local output = output_layout:get_next_output(output)
until output == first

function OutputLayout:find_output(name: string): Output line 732

Get an output by name.

function OutputLayout:hook(signal: string, handler: fn(layout,data)): fn(layout,data) line 757

Hook into a signal on the output layout.

Start listening for and calling handler on this signal. The type of data depends on the signal being listened for. See (TODO: signal definitions page).

Usage:

local layout = wf.get_core():get_output_layout()
layout:hook('output-added', function(layout, data)
    print('An output has been added:', data.output)
end)

assert(handler == layout:hook('output-removed', handler))

function OutputLayout:unhook(signal: string, handler: fn(layout,data)) line 788

Unhook from a signal on the output layout.

Stop listening for and calling handler on this signal.

Usage:

local handler = wf.get_core():hook('output-added',
                            function(layout, data) end)
core:unhook('output-added', handler)

local layout = wf.get_core():get_output_layout()
local handler = function() end
layout:hook('output-added', handler)
layout:hook('output-removed', handler)
layout:unhook('output-added', handler)
layout:unhook('output-removed', handler)

Class Output

A wayfire output.

Usage:

local view = -- some View
local output = view:get_output()
output:ensure_visible(view)
output:focus_view(view)

function Output:get_screen_size(): Dimensions line 810

Get the screen size of this output.

function Output:get_relative_geometry(): Geometry line 818

Get the screen size of this output as a Geometry. The x,y of the Geometry will be 0.

function Output:get_layout_geometry(): Geometry line 827

Get the geometry of the screen. This should include the screen dimensions as well as meaningful x,y coordinates.

function Output:ensure_pointer(center: bool) line 838

Ensure the pointer is on this output. If the pointer isn't already on this output, move it.

If center is true, move the pointer to the center of the screen regardless of whether it is already on this output.

function Output:get_cursor_position(): Geometry line 846

Get the cursor position relative to the output.

function Output:call_plugin(activator: string): bool line 862

Invoke a plugin's activator.

You can check for the name of an activator by looking at a plugin's metadata xml file and looking for options of type "activator". The actual activator name is prefixed with the name of the plugin followed by a forward slash.

Usage:

wf_core:get_active_output():call_plugin('vswitch/binding_left')

function Output:get_top_view(): View line 873

Get the view at the top of the workspace layer.

function Output:get_active_view(): View line 880

Get the most recently focused view on this output.

function Output:focus_view(view: View, raise: bool): View line 890

Try to focus the view on this output. If raise is true, also raise it to the top of its layer.

function Output:ensure_visible(view: View): bool line 899

Switch workspaces to make this view visible.

function Output:get_workarea(): Geometry line 906

Get the output's workarea geometry.

function Output:hook(signal: string, handler: fn(output,data)): fn(output,data) line 925

Hook into a signal on this output.

Start listening for and calling handler on this signal. The type of data depends on the signal being listened for. See (TODO: signal definitions page).

Usage:

output:hook('view-mapped', function(output, data)
    print('View ', data.view:get_title(), ' mapped!')
end)

assert(handler == output:hook('view-focused', handler))

function Output:unhook(signal: string, handler: fn(output,data)) line 954

Unhook from a signal on this output.

Stop listening for and calling handler on this signal.

Usage:

local handler = output:hook('view-focused',
                            function(output, data) end)
output:unhook('view-focused', handler)

local handler = function() end
output:hook('view-mapped', handler)
output:hook('view-focused', handler)
output:unhook('view-mapped', handler)
output:unhook('view-focused', handler)

Class View

A wayfire view.

Usage:

-- If view is foot, then set its geometry and hook into the 'title-changed'
-- event of this view.
if view:get_app_id() == 'foot' then
    view:set_geometry({1, 2, 500, 300})

    view:hook('title-changed', function(view, data)
        print('View title changed! New title:', data.view:get_title())
        assert(view == data.view)
    end)
end

function View:get_title(): string line 983

Get the view's title.

function View:get_app_id(): string line 990

Get the view's app id.

function View:get_wm_geometry(): Geometry line 997

Get the view's wm geometry.

function View:get_output_geometry(): Geometry line 1004

Get the view's output geometry.

function View:get_bounding_box(): Geometry line 1011

Get the view's bounding box.

function View:get_output(): Output line 1018

Get the view's output.

function View:set_geometry(geo: Geometry) line 1024

Set the view's geometry.

Usage:

view:set_geometry({x, y, w, h})

function View:hook(signal: string, handler: fn(view,data)): fn(view,data) line 1044

Hook into a signal on this view.

Start listening for and calling handler on this signal. The type of data depends on the signal being listened for. See (TODO: signal definitions page).

Usage:

view:hook('title-changed', function(view, data)
    print('View title changed! New title:', data.view:get_title())
    assert(view == data.view)
end)

assert(handler == view:hook('title-changed', handler))

function View:unhook(signal: string, handler: fn(view,data)) line 1071

Unhook from a signal on this view.

Stop listening for and calling handler on this signal.

Usage:

local handler = view:hook('title-changed', function(view, data) end)
view:unhook('title-changed', handler)

local handler = function() end
view:hook('title-changed', handler)
view:hook('app-id-changed', handler)
view:unhook('title-changed', handler)
view:unhook('app-id-changed', handler)

Module wf

Info:

Functions

Class Core

Class OutputLayout

Class Output

Class View

Functions

Usage:

Usage:

Usage:

Usage:

Usage:

Class Core

Usage:

Usage:

Usage:

Class OutputLayout

Usage:

Usage:

Usage:

Usage:

Class Output

Usage:

Usage:

Usage:

Usage:

Class View

Usage:

Usage:

Usage:

Usage:

Module `wf`