diff --git a/.gitkeep b/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/index.html b/index.html new file mode 100644 index 0000000..122f141 --- /dev/null +++ b/index.html @@ -0,0 +1,364 @@ + + + + + A declarative API to connect signals for the AwesomeWM + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

Module init

+

AwesomeWM - Slot

+ +

A declarative API to connect signals for the AwesomeWM.

+

+ +

It completes the native gears.signal module to make signal connection + easier to manage.

+ +

Usage example

+ +

Tis module allows to create Slot objects. These object can connect to any + signals from Awesome WM's gears.objects and module level signals.

+ +

In the following example, we create a slot that connects to the client + global "request::default_keybindings" signal to attach keybindings to + clients.

+ +

The slot.slots.client.append_keybindings function is part of this module + and is defined as a function iterating over the keybindings parameter to + register all defined keybindings with the awful.keyboard.append_client_keybindings + function.

+ + +
+local client_keybinding = slot {
+  id = "CLIENT_KEY_BINDINGS",
+  connect = true,
+  target = capi.client,
+  signal = "request::default_keybindings",
+  slot = slot.slots.client.append_keybindings,
+  slot_params = {
+    keybindings = {
+      awful.key({ "Mod4" }, "f",
+        function(client)
+         client.fullscreen = not client.fullscreen
+         client:raise()
+        end,
+        { description = "toggle fullscreen", group = "client" }),
+      },
+      -- ...
+    },
+}
+
+ +

+

Info:

+ + + +

Constructor

+ + + + + +
awesome_slotCreate a new Slot instance.
+

Static functions

+ + + + + + + + + + + + + + + + + +
awesome_slot.get_slotFind a previously registered slot.
awesome_slot.removeRemove a registered slot and disconnect it.
awesome_slot.connectConnect a slot to its signal.
awesome_slot.disconnectDisconnect a slot from its signal.
+

Tables

+ + + + + + + + + +
awesome_slot.slotsSlots defined by this module.
awesome_slot.static_connectSpecial objects that require a static connection instead of object level connection.
+ +
+
+ + +

Constructor

+ +
+
+ + awesome_slot + line 116 +
+
+ Create a new Slot instance. + + +

Parameters:

+
    +
  • params + + +
      +
    • id + string + The slot ID. + (optional) +
      • +
    • target + any + The slot target object. +
      • +
    • signal + string + The signal the slot connects to. +
      • +
    • slot + function + The callback function to connect to the signal. +
      • +
    • slot_params + table + The parameters to pass to the callback + function. (The signal will invok the callback function with this table as + parameter) +
      • +
    • connect + boolean + Connect the slot now. + (default false) +
      • +
    +
+ + + + + +
+
+

Static functions

+ +
+
+ + awesome_slot.get_slot + line 95 +
+
+ Find a previously registered slot.

+ +

If the slot asked doesn't exist, the function will fail and throw an error. + + +

Parameters:

+
    +
  • slot + string or Slot + The slot id or instance to find. +
    • +
+ + + + + +
+
+ + awesome_slot.remove + line 147 +
+
+ Remove a registered slot and disconnect it. + + +

Parameters:

+
    +
  • slot + Slot + The slot to remove. +
    • +
+ + + + + +
+
+ + awesome_slot.connect + line 162 +
+
+ Connect a slot to its signal. + + +

Parameters:

+
    +
  • slot + Slot + The slot to connect. +
    • +
+ + + + + +
+
+ + awesome_slot.disconnect + line 184 +
+
+ Disconnect a slot from its signal. + + +

Parameters:

+
    +
  • slot + Slot + The slot to disconnect. +
    • +
+ + + + + +
+
+

Tables

+ +
+
+ + awesome_slot.slots + line 59 +
+
+ Slots defined by this module. + + + + + + + +
+
+ + awesome_slot.static_connect + line 63 +
+
+ Special objects that require a static connection instead of object level connection. + + +

Fields:

+
    +
  • client + + + +
    • +
  • screen + + + +
    • +
  • tag + + + +
    • +
  • ruled_client + + + +
    • +
  • ruled_notification + + + +
    • +
+ + + + + +
+
+ + +
+
+
+generated by LDoc 1.4.6 +Last updated 2021-10-21 17:48:08 +
+
+ + diff --git a/ldoc.css b/ldoc.css new file mode 100644 index 0000000..52c4ad2 --- /dev/null +++ b/ldoc.css @@ -0,0 +1,303 @@ +/* BEGIN RESET + +Copyright (c) 2010, Yahoo! Inc. All rights reserved. +Code licensed under the BSD License: +http://developer.yahoo.com/yui/license.html +version: 2.8.2r1 +*/ +html { + color: #000; + background: #FFF; +} +body,div,dl,dt,dd,ul,ol,li,h1,h2,h3,h4,h5,h6,pre,code,form,fieldset,legend,input,button,textarea,p,blockquote,th,td { + margin: 0; + padding: 0; +} +table { + border-collapse: collapse; + border-spacing: 0; +} +fieldset,img { + border: 0; +} +address,caption,cite,code,dfn,em,strong,th,var,optgroup { + font-style: inherit; + font-weight: inherit; +} +del,ins { + text-decoration: none; +} +li { + margin-left: 20px; +} +caption,th { + text-align: left; +} +h1,h2,h3,h4,h5,h6 { + font-size: 100%; + font-weight: bold; +} +q:before,q:after { + content: ''; +} +abbr,acronym { + border: 0; + font-variant: normal; +} +sup { + vertical-align: baseline; +} +sub { + vertical-align: baseline; +} +legend { + color: #000; +} +input,button,textarea,select,optgroup,option { + font-family: inherit; + font-size: inherit; + font-style: inherit; + font-weight: inherit; +} +input,button,textarea,select {*font-size:100%; +} +/* END RESET */ + +body { + margin-left: 1em; + margin-right: 1em; + font-family: arial, helvetica, geneva, sans-serif; + background-color: #ffffff; margin: 0px; +} + +code, tt { font-family: monospace; font-size: 1.1em; } +span.parameter { font-family:monospace; } +span.parameter:after { content:":"; } +span.types:before { content:"("; } +span.types:after { content:")"; } +.type { font-weight: bold; font-style:italic } + +body, p, td, th { font-size: .95em; line-height: 1.2em;} + +p, ul { margin: 10px 0 0 0px;} + +strong { font-weight: bold;} + +em { font-style: italic;} + +h1 { + font-size: 1.5em; + margin: 20px 0 20px 0; +} +h2, h3, h4 { margin: 15px 0 10px 0; } +h2 { font-size: 1.25em; } +h3 { font-size: 1.15em; } +h4 { font-size: 1.06em; } + +a:link { font-weight: bold; color: #004080; text-decoration: none; } +a:visited { font-weight: bold; color: #006699; text-decoration: none; } +a:link:hover { text-decoration: underline; } + +hr { + color:#cccccc; + background: #00007f; + height: 1px; +} + +blockquote { margin-left: 3em; } + +ul { list-style-type: disc; } + +p.name { + font-family: "Andale Mono", monospace; + padding-top: 1em; +} + +pre { + background-color: rgb(245, 245, 245); + border: 1px solid #C0C0C0; /* silver */ + padding: 10px; + margin: 10px 0 10px 0; + overflow: auto; + font-family: "Andale Mono", monospace; +} + +pre.example { + font-size: .85em; +} + +table.index { border: 1px #00007f; } +table.index td { text-align: left; vertical-align: top; } + +#container { + margin-left: 1em; + margin-right: 1em; + background-color: #f0f0f0; +} + +#product { + text-align: center; + border-bottom: 1px solid #cccccc; + background-color: #ffffff; +} + +#product big { + font-size: 2em; +} + +#main { + background-color: #f0f0f0; + border-left: 2px solid #cccccc; +} + +#navigation { + float: left; + width: 14em; + vertical-align: top; + background-color: #f0f0f0; + overflow: visible; +} + +#navigation h2 { + background-color:#e7e7e7; + font-size:1.1em; + color:#000000; + text-align: left; + padding:0.2em; + border-top:1px solid #dddddd; + border-bottom:1px solid #dddddd; +} + +#navigation ul +{ + font-size:1em; + list-style-type: none; + margin: 1px 1px 10px 1px; +} + +#navigation li { + text-indent: -1em; + display: block; + margin: 3px 0px 0px 22px; +} + +#navigation li li a { + margin: 0px 3px 0px -1em; +} + +#content { + margin-left: 14em; + padding: 1em; + width: 700px; + border-left: 2px solid #cccccc; + border-right: 2px solid #cccccc; + background-color: #ffffff; +} + +#about { + clear: both; + padding: 5px; + border-top: 2px solid #cccccc; + background-color: #ffffff; +} + +@media print { + body { + font: 12pt "Times New Roman", "TimeNR", Times, serif; + } + a { font-weight: bold; color: #004080; text-decoration: underline; } + + #main { + background-color: #ffffff; + border-left: 0px; + } + + #container { + margin-left: 2%; + margin-right: 2%; + background-color: #ffffff; + } + + #content { + padding: 1em; + background-color: #ffffff; + } + + #navigation { + display: none; + } + pre.example { + font-family: "Andale Mono", monospace; + font-size: 10pt; + page-break-inside: avoid; + } +} + +table.module_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.module_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.module_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.module_list td.summary { width: 100%; } + + +table.function_list { + border-width: 1px; + border-style: solid; + border-color: #cccccc; + border-collapse: collapse; +} +table.function_list td { + border-width: 1px; + padding: 3px; + border-style: solid; + border-color: #cccccc; +} +table.function_list td.name { background-color: #f0f0f0; min-width: 200px; } +table.function_list td.summary { width: 100%; } + +ul.nowrap { + overflow:auto; + white-space:nowrap; +} + +dl.table dt, dl.function dt {border-top: 1px solid #ccc; padding-top: 1em;} +dl.table dd, dl.function dd {padding-bottom: 1em; margin: 10px 0 0 20px;} +dl.table h3, dl.function h3 {font-size: .95em;} + +/* stop sublists from having initial vertical space */ +ul ul { margin-top: 0px; } +ol ul { margin-top: 0px; } +ol ol { margin-top: 0px; } +ul ol { margin-top: 0px; } + +/* make the target distinct; helps when we're navigating to a function */ +a:target + * { + background-color: #FF9; +} + + +/* styles for prettification of source */ +pre .comment { color: #558817; } +pre .constant { color: #a8660d; } +pre .escape { color: #844631; } +pre .keyword { color: #aa5050; font-weight: bold; } +pre .library { color: #0e7c6b; } +pre .marker { color: #512b1e; background: #fedc56; font-weight: bold; } +pre .string { color: #8080ff; } +pre .number { color: #f8660d; } +pre .operator { color: #2239a8; font-weight: bold; } +pre .preprocessor, pre .prepro { color: #a33243; } +pre .global { color: #800080; } +pre .user-keyword { color: #800080; } +pre .prompt { color: #558817; } +pre .url { color: #272fc2; text-decoration: underline; } + diff --git a/source/init.lua.html b/source/init.lua.html new file mode 100644 index 0000000..062c048 --- /dev/null +++ b/source/init.lua.html @@ -0,0 +1,262 @@ + + + + + A declarative API to connect signals for the AwesomeWM + + + + +
+ +
+ +
+
+
+ + +
+ + + + + + +
+ +

init.lua

+
+-----
+-- AwesomeWM - Slot
+--
+-- A declarative API to connect signals for the AwesomeWM.
+-- It completes the native gears.signal module to make signal connection
+-- easier to manage.
+--
+-- Usage example
+-- ---
+--
+-- Tis module allows to create Slot objects. These object can connect to any
+-- signals from Awesome WM's gears.objects and module level signals.
+--
+-- In the following example, we create a slot that connects to the client
+-- global "request::default_keybindings" signal to attach keybindings to
+-- clients.
+--
+-- The slot.slots.client.append_keybindings function is part of this module
+-- and is defined as a function iterating over the keybindings parameter to
+-- register all defined keybindings with the awful.keyboard.append_client_keybindings
+-- function.
+--
+--    local client_keybinding = slot {
+--      id = "CLIENT_KEY_BINDINGS",
+--      connect = true,
+--      target = capi.client,
+--      signal = "request::default_keybindings",
+--      slot = slot.slots.client.append_keybindings,
+--      slot_params = {
+--        keybindings = {
+--          awful.key({ "Mod4" }, "f",
+--            function(client)
+--             client.fullscreen = not client.fullscreen
+--             client:raise()
+--            end,
+--            { description = "toggle fullscreen", group = "client" }),
+--          },
+--          -- ...
+--        },
+--    }
+--
+-- @author Aire-One
+-- @copyright 2021 Aire-One <aireone@aireone.xyz>
+-----
+
+local gtable = require "gears.table"
+
+local capi = {
+    client = _G.client,
+    screen = _G.screen,
+    tag = _G.tag,
+}
+
+local awesome_slot = {
+    mt = {},
+
+    --- Slots defined by this module.
+    -- @table awesome_slot.slots
+    slots = require "awesome-slot.slots",
+
+    --- Special objects that require a static connection instead of object level connection.
+    -- @table awesome_slot.static_connect
+    static_connect = {
+        client = capi.client,
+        screen = capi.screen,
+        tag = capi.tag,
+        ruled_client = require "ruled.client",
+        ruled_notification = require "ruled.notification",
+    },
+
+    _private = {
+        registered_slots = {},
+    },
+}
+
+local function generate_id(base_id)
+    local id = base_id
+    local n = 0
+
+    while awesome_slot.slots[id] ~= nil do
+        n = n + 1
+        id = base_id .. "_#" .. n
+    end
+
+    return id
+end
+
+--- Find a previously registered slot.
+--
+-- If the slot asked doesn't exist, the function will fail and throw an error.
+--
+-- @tparam string|Slot slot The slot id or instance to find.
+-- @treturn Slot The slot.
+-- @staticfct awesome_slot.get_slot
+function awesome_slot.get_slot(slot)
+    assert(slot)
+    local id = type(slot) == "string" and slot or slot.id
+    assert(id, "Slot not found!")
+
+    return awesome_slot._private.registered_slots[id]
+end
+
+--- Create a new Slot instance.
+--
+-- @tparam table params
+-- @tparam[opt] string params.id The slot ID.
+-- @tparam any params.target The slot target object.
+-- @tparam string params.signal The signal the slot connects to.
+-- @tparam function params.slot The callback function to connect to the signal.
+-- @tparam table params.slot_params The parameters to pass to the callback
+--   function. (The signal will invok the callback function with this table as
+--   parameter)
+-- @tparam[opt=false] boolean params.connect Connect the slot now.
+-- @treturn Slot The created Slot instance.
+-- @constructorfct awesome_slot
+function awesome_slot.create(params)
+    local slot = {}
+
+    slot.id = generate_id(params.id or "UNNAMED_SLOT")
+    slot.target = params.target
+    slot.signal = params.signal
+    slot.connected = false
+
+    if params.slot_params then
+        slot.params = params.slot_params
+        slot.callback = function()
+            params.slot(slot.params)
+        end
+    else
+        slot.callback = params.slot
+    end
+
+    -- Insert the new slot into the slots list
+    awesome_slot._private.registered_slots[slot.id] = slot
+
+    if params.connect then
+        awesome_slot.connect(slot)
+    end
+
+    return slot
+end
+
+--- Remove a registered slot and disconnect it.
+--
+-- @tparam Slot slot The slot to remove.
+-- @staticfct awesome_slot.remove
+function awesome_slot.remove(slot)
+    local s = awesome_slot.get_slot(slot)
+
+    if s.connected then
+        awesome_slot.disconnect_slot(s)
+    end
+
+    awesome_slot._private.registered_slots[s.id] = nil
+end
+
+--- Connect a slot to its signal.
+--
+-- @tparam Slot slot The slot to connect.
+-- @treturn Slot The slot.
+-- @staticfct awesome_slot.connect
+function awesome_slot.connect(slot)
+    local s = awesome_slot.get_slot(slot)
+
+    -- Some modules expose a static connect_signals function
+    -- at the module level, while other tables/objects inheriting from
+    -- gears.object implement the signal connection API at the instance level.
+    if gtable.hasitem(awesome_slot.static_connect, s.target) then
+        s.target.connect_signal(s.signal, s.callback)
+    else
+        s.target:connect_signal(s.signal, s.callback)
+    end
+
+    s.connected = true
+
+    return s
+end
+
+--- Disconnect a slot from its signal.
+--
+-- @tparam Slot slot The slot to disconnect.
+-- @treturn Slot The slot.
+-- @staticfct awesome_slot.disconnect
+function awesome_slot.disconnect(slot)
+    local s = awesome_slot.get_slot(slot)
+
+    -- Please check the :connect_slot method to understand why we do this.
+    if gtable.hasitem(awesome_slot.static_connect, s.target) then
+        s.target.disconnect_slot(s.signal, s.callback)
+    else
+        s.target:disconnect_slot(s.signal, s.callback)
+    end
+
+    s.connected = false
+
+    return s
+end
+
+function awesome_slot.mt:__call(...) -- luacheck: ignore unused argument self
+    return awesome_slot.create(...)
+end
+
+return setmetatable(awesome_slot, awesome_slot.mt)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+ + +
+
+
+generated by LDoc 1.4.6 +Last updated 2021-10-21 17:48:08 +
+
+ +