From 5909d2f155984e39431e57e6211249bd76a5196b Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2022 23:02:26 -0700 Subject: [PATCH] awful.popup: Update the property documentation. --- lib/awful/popup.lua | 89 ++++++++++++++++++++++++++++----------------- 1 file changed, 56 insertions(+), 33 deletions(-) diff --git a/lib/awful/popup.lua b/lib/awful/popup.lua index 9c5845891..71ca6a6a1 100644 --- a/lib/awful/popup.lua +++ b/lib/awful/popup.lua @@ -145,13 +145,6 @@ local popup = {} -- parent menu. If there is no space on the right, it tries on the left and so -- on. -- --- Valid directions are: --- --- * left --- * right --- * top --- * bottom --- -- The basic use case for this method is to give it a parent wibox: -- -- @DOC_awful_popup_position1_EXAMPLE@ @@ -162,8 +155,16 @@ local popup = {} -- @DOC_awful_popup_position2_EXAMPLE@ -- -- @property preferred_positions --- @tparam table|string preferred_positions A position name or an ordered --- table of positions +-- @tparam table|string preferred_positions +-- @propertydefault `{ "right", "left", "top", "bottom" }` +-- @propertytype string A single position with no fallback. It will be used +-- even if it doesn't fit. +-- @propertytype table A list of possible positions. The first one to fit will be +-- used. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" -- @see awful.placement.next_to -- @see awful.popup.preferred_anchors -- @propemits true false @@ -176,12 +177,6 @@ end --- Set the preferred popup anchors relative to the parent. -- --- The possible values are: --- --- * front --- * middle --- * back --- -- For details information, see the `awful.placement.next_to` documentation. -- -- In this example, it is possible to see the effect of having a fallback @@ -190,8 +185,14 @@ end -- @DOC_awful_popup_anchors_EXAMPLE@ -- -- @property preferred_anchors --- @tparam table|string preferred_anchors Either a single anchor name or a table +-- @tparam[opt="back"] table|string preferred_anchors -- ordered by priority. +-- @propertytype string A single anchor value with no fallback. +-- @propertytype table A list of possible anchor, the first one has the higher +-- priority, but will fallback if it doesn't fit. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" -- @propemits true false -- @see awful.placement.next_to -- @see awful.popup.preferred_positions @@ -210,7 +211,14 @@ end -- isn't enough space, it can also be one of the fallback. -- -- @property current_position --- @tparam string current_position Either "left", "right", "top" or "bottom" +-- @tparam string current_position +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "left" +-- @propertyvalue "right" +-- @propertyvalue "top" +-- @propertyvalue "bottom" +-- @readonly +-- @see awful.popup.preferred_positions function popup:get_current_position() return self._private.current_position @@ -224,7 +232,13 @@ end -- opposite direction from the anchor. -- -- @property current_anchor --- @tparam string current_anchor Either "front", "middle", "back" +-- @tparam string current_anchor +-- @propertydefault This depends on where the popup was displayed. +-- @propertyvalue "front" +-- @propertyvalue "middle" +-- @propertyvalue "back" +-- @readonly +-- @see awful.popup.preferred_anchors function popup:get_current_anchor() return self._private.current_anchor @@ -275,7 +289,8 @@ function popup:bind_to_widget(widget, button) end --- Unbind the popup from a widget button. --- @tparam widget widget The widget +-- @tparam widget widget +-- @propertytype widget A widget or declarative widget construct. -- @method unbind_to_widget -- @noreturn function popup:unbind_to_widget(widget) @@ -298,25 +313,33 @@ end --- The popup minimum width. -- -- @property minimum_width --- @tparam[opt=1] number minimum_width The minimum width. +-- @tparam[opt=1] integer minimum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup minimum height. -- -- @property minimum_height --- @tparam[opt=1] number minimum_height The minimum height. +-- @tparam[opt=1] integer minimum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum width. -- -- @property maximum_width --- @tparam[opt=1] number maximum_width The maximum width. +-- @tparam[opt=1] integer maximum_width +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false --- The popup maximum height. -- -- @property maximum_height --- @tparam[opt=1] number maximum_height The maximum height. +-- @tparam[opt=1] integer maximum_height +-- @propertyunit pixel +-- @rangestart 1 -- @propemits true false for _, orientation in ipairs {"_width", "_height"} do @@ -340,9 +363,13 @@ end -- -- @DOC_awful_popup_position3_EXAMPLE@ -- @property offset --- @tparam table|integer offset An integer value or a `{x=, y=}` table. --- @tparam[opt=offset] integer offset.x The horizontal distance. --- @tparam[opt=offset] integer offset.y The vertical distance. +-- @tparam[opt=0] table|integer offset +-- @tparam[opt=0] integer offset.x The horizontal offset. +-- @tparam[opt=0] integer offset.y The vertical offset. +-- @propertytype integer A value for both `x` and `y` simultaneously. +-- @propertytype table Specify values for `x` and `y` individually. +-- @negativeallowed true +-- @propertyunit pixel -- @propemits true false function popup:set_offset(offset) @@ -369,10 +396,10 @@ end --- Set the placement function. -- --- (or false to disable placement) --- -- @property placement --- @tparam[opt=awful.placement.next_to] function|string|boolean placement The placement function or name +-- @tparam[opt=awful.placement.next_to] placement|string|boolean placement +-- @propertytype boolean Use `false` to disable automatic placement. +-- @propertytype string The name of an `awful.placement` function, like `"next_to"`. -- @propemits true false -- @see awful.placement @@ -496,8 +523,4 @@ local function create_popup(_, args) return w end ---@DOC_wibox_COMMON@ - ---@DOC_object_COMMON@ - return setmetatable(module, {__call = create_popup})