diff --git a/README.md b/README.md index f80ea52..d0a8ab1 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,37 @@ $ cd awesome-viewport $ luarocks make --local rockspec/awesome-viewport-devel-1.rockspec ``` +## Concept + +Once connected to a screen, selecting a single tag will make that tag the active +viewport. This tag will remember any other selected tags when the viewport +changes, so that when it is re-selected, all previously selected tags are +viewed. + +For example: + +![Tag 1 is selected, becoming the active viewport][1] + +* Tag 1 is selected, becoming the active viewport. + +![Tag 2 is toggled into view][2] + +* Tag 2 is toggled into view. Tag 1, as the active viewport, will record this. + +![Tag 2 is selected, but tag 1 is not viewed][3] + +* If tag 2 is selected, it becomes the new active viewport, and tag 1 will not be + viewed. The association is one way. + +![Tag 1 is selected, toggling tag 2 into view][2] + +* Tag 1 is re-selected, becoming the active viewport. Because tag 2 was viewed + when tag 1 was previously the active viewport, it is toggled back into view. + +[1]: https://github.com/jcrd/awesome-viewport/blob/assets/1.png +[2]: https://github.com/jcrd/awesome-viewport/blob/assets/2.png +[3]: https://github.com/jcrd/awesome-viewport/blob/assets/3.png + ## Usage Require the library: @@ -30,9 +61,9 @@ View a single tag: tag1:view_only() ``` -This tag will be the new viewport. +This tag will be the active viewport. -Get the viewport for the focused screen: +Get the active viewport for the focused screen: ```lua viewport() @@ -43,9 +74,9 @@ Toggle another tag into view: awful.tag.viewtoggle(tag2) ``` -`tag1` will remember that `tag2` is toggled while its the viewport, so that if -the viewport changes and `tag1` is re-viewed, `tag2` will also be toggled into -view. +`tag1` will remember that `tag2` is toggled while its the active viewport, so +that if the viewport changes and `tag1` is re-viewed, `tag2` will also be +toggled into view. See the [API documentation](https://jcrd.github.io/awesome-viewport/) for descriptions of all functions. diff --git a/init.lua b/init.lua index 03e38eb..44467f5 100644 --- a/init.lua +++ b/init.lua @@ -3,12 +3,12 @@ --- Manage tags based on viewports. -- -- Once connected to a screen via `viewport.connect(screen)`, selecting a single --- tag will make that tag the new viewport. This tag will remember any other +-- tag will make that tag the active viewport. This tag will remember any other -- selected tags when the viewport changes, so that when it is re-selected, -- all previously selected tags are viewed. -- -- @author James Reed <jcrd@tuta.io> --- @copyright 2019 James Reed +-- @copyright 2019-2020 James Reed -- @module awesome-viewport local awful = require("awful") @@ -32,7 +32,7 @@ local function update(s) end end ---- Get the viewport of a given screen. +--- Get the active viewport of a given screen. -- -- @param s The screen, defaults to `awful.screen.focused().selected_tag`. -- @return The viewport tag.