From 90b17bdc094adcfb873fb214a00cebbbc262074f Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 6 Oct 2018 19:40:36 -0400 Subject: [PATCH] awful.rules: Add proper documentation to the extra client properties. Until now there wasn't much documentation available about how to use these properties. With the new work on `awful.spawn` that rely more and more on `awful.rules` integration, it is worth fixing. This commit add a new documentation section and a future commit will aggregate them to generate an index. --- docs/config.ld | 8 +++- lib/awful/client.lua | 87 ++++++++++++++++++++++++++++++++++++++++++++ lib/awful/rules.lua | 5 --- objects/client.c | 23 +++++++++++- 4 files changed, 116 insertions(+), 7 deletions(-) diff --git a/docs/config.ld b/docs/config.ld index a640e4f7..0d783ace 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -72,6 +72,8 @@ new_type("callback", "Callback functions prototype", false, "Parameters") new_type("rulesources", "Rule sources", false, "param") -- Filter functions for the taglist/tasklist/layoutlist new_type("filterfunction", "List filters", false) +-- Extra client properties available only in awful.rules/spawn constructs +new_type("clientruleproperty", "Extra properties available in awful.rules and awful.spawn", false, "Type") -- More fitting section names kind_names={topic='Documentation', module='Libraries', script='Sample files'} @@ -135,10 +137,14 @@ file = { } } +local no_prefix = { + property = true, signal = true, clientruleproperty = true +} + custom_display_name_handler = function(item, default_handler) -- Remove the "namespace" from the signals and properties - if item.type == "property" or item.type == "signal" then + if no_prefix[item.type] then local name = item.name:match("%.([^.]+)$") return name ~= "" and name or item.name end diff --git a/lib/awful/client.lua b/lib/awful/client.lua index ffa20e04..f75270cf 100644 --- a/lib/awful/client.lua +++ b/lib/awful/client.lua @@ -59,6 +59,93 @@ client.property = {} client.shape = require("awful.client.shape") client.focus = require("awful.client.focus") +--- The client default placement on the screen. +-- +-- The default config uses: +-- +-- awful.placement.no_overlap+awful.placement.no_offscreen +-- +-- @clientruleproperty placement +-- @see awful.placement + +--- When applying the placement, honor the screen padding. +-- @clientruleproperty honor_padding +-- @param[opt=true] boolean +-- @see awful.placement + +--- When applying the placement, honor the screen work area. +-- +-- The workarea is the part of the screen that excludes the bars and docks. +-- +-- @clientruleproperty honor_workarea +-- @param[opt=true] boolean +-- @see awful.placement + +--- The client default tag. +-- @clientruleproperty tag +-- @param tag +-- @see tag +-- @see new_tag +-- @see tags +-- @see switch_to_tags + +--- The client default tags. +-- +-- Avoid using the tag and tags properties at the same time, it will cause +-- issues. +-- +-- @clientruleproperty tags +-- @param[opt={tag}] table +-- @see tag +-- @see new_tag +-- @see tags +-- @see switch_to_tags + +--- Create a new tag for this client. +-- +-- If the value is `true`, the new tag will be named after the client `class`. +-- If it is a string, it will be the tag name. +-- +-- If a table is used, all of its properties will be passed to the tag +-- constructor: +-- +-- new_tag = { +-- name = "My new tag!", -- The tag name. +-- layout = awful.layout.suit.max, -- Set the tag layout. +-- volatile = true, -- Remove the tag when the client is closed. +-- } +-- +-- @tparam[opt=false] table|string|boolean new_tag +-- @clientruleproperty new_tag +-- @see tag +-- @see tags +-- @see switch_to_tags + +--- Unselect the current tags and select this client tags. +-- Note that this property was called `switchtotag` in previous Awesome versions. +-- @clientruleproperty switch_to_tags +-- @param[opt=false] boolean +-- @see tag.selected + +--- Define if the client should grab focus by default. +-- +-- The `request::activate` context for this call is `rules`. +-- +-- @clientruleproperty focus +-- @param[opt=false] boolean + +--- Should this client have a titlebar by default. +-- @clientruleproperty titlebars_enabled +-- @param[opt=false] boolean +-- @see awful.titlebar + +--- A function to call when this client is ready. +-- +-- It can be useful to set extra properties or perform actions. +-- +-- @clientruleproperty callback +-- @see awful.spawn + --- Jump to the given client. -- Takes care of focussing the screen, the right tag, etc. -- diff --git a/lib/awful/rules.lua b/lib/awful/rules.lua index 31ca6d04..f1674187 100644 --- a/lib/awful/rules.lua +++ b/lib/awful/rules.lua @@ -536,11 +536,6 @@ function rules.extra_properties.geometry(c, _, props) c:geometry(new_geo) --TODO use request::geometry end ---- Create a new tag based on a rule. --- @tparam client c The client --- @tparam boolean|function|string value The value. --- @tparam table props The properties. --- @treturn tag The new tag function rules.high_priority_properties.new_tag(c, value, props) local ty = type(value) local t = nil diff --git a/objects/client.c b/objects/client.c index ce3e748d..2144c3c5 100644 --- a/objects/client.c +++ b/objects/client.c @@ -108,7 +108,28 @@ /** Client class. * - * @table object + * This table allow to add more dynamic properties to the clients. For example, + * doing: + * + * function awful.client.object.set_my_cool_property(c, value) + * -- Some logic code + * c._my_secret_my_cool_property = value + * c:emit_signal("property::my_cool_property) + * end + * + * function awful.client.object.get_my_cool_property() + * return c._my_secret_my_cool_property + * end + * + * Will add a new "my_cool_property" dyanmic property to all client. These + * methods will be called when an user does `c.my_cool_property = "something"` + * or set them in `awdul.rules`. + * + * Note that doing this isn't required to set random properties to the client, + * it is only useful when setting or getting these properties require code to + * executed. + * + * @table awful.object */ /** When a client gains focus.