Merge pull request #182 from 3rd/feat/toggle-rendering

feat: toggle rendering

Author: 3rd

README.md

@@ -398,6 +398,21 @@ Check https://github.com/3rd/image.nvim/issues/190#issuecomment-2378156235 for h
 
 ## How to ...?
 
+#### General
+
+<details>
+<summary>Enable / disable / get plugin status</summary>
+
+You can enable/disable the plugin and check its status on demand.
+
+```lua
+require("image").enable() -- enable the plugin
+require("image").disable() -- disable the plugin
+print(require("image").is_enabled()) -- bool
+```
+
+</details>
+
 #### Integrations
 
 <details>
@@ -415,7 +430,7 @@ require("image").setup({
 })
 ```
 
-</details
+</details>
 
 ## API
 

lua/image/image.lua

@@ -45,6 +45,8 @@ end
 
 ---@param geometry? ImageGeometry
 function Image:render(geometry)
+  if not self.global_state.enabled then return end
+
   if geometry then self.geometry = vim.tbl_deep_extend("force", self.geometry, geometry) end
 
   -- don't render if we are in the conmmand-line-window, in this case previously rendered images can

lua/image/init.lua

@@ -53,6 +53,7 @@ local state = {
   tmp_dir = vim.fn.tempname(),
   disable_decorator_handling = false,
   hijacked_win_buf_images = {},
+  enabled = true,
 }
 
 ---@type API
@@ -102,6 +103,9 @@ api.setup = function(options)
   local window_history = {}
   vim.api.nvim_set_decoration_provider(state.extmarks_namespace, {
     on_win = function(_, winid, bufnr, topline, botline)
+      -- bail if not enabled
+      if not state.enabled then return false end
+
       -- bail if decorator handling is disabled
       if state.disable_decorator_handling then return false end
 
@@ -208,6 +212,9 @@ api.setup = function(options)
   vim.api.nvim_create_autocmd({ "BufLeave", "WinClosed", "TabEnter" }, {
     group = group,
     callback = function() -- auto-clear images when windows and buffers change
+      -- bail if not enabled
+      if not state.enabled then return end
+
       vim.schedule(function()
         local images = api.get_images()
 
@@ -251,6 +258,9 @@ api.setup = function(options)
   vim.api.nvim_create_autocmd({ "WinScrolled" }, {
     group = group,
     callback = function(au)
+      -- bail if not enabled
+      if not state.enabled then return end
+
       local images = api.get_images({ window = tonumber(au.file) })
       for _, current_image in ipairs(images) do
         current_image:render()
@@ -262,6 +272,9 @@ api.setup = function(options)
   vim.api.nvim_create_autocmd({ "WinResized" }, {
     group = group,
     callback = function()
+      -- bail if not enabled
+      if not state.enabled then return end
+
       local images = api.get_images()
       for _, current_image in ipairs(images) do
         if current_image.window ~= nil then current_image:render() end
@@ -303,9 +316,11 @@ api.setup = function(options)
     vim.api.nvim_create_autocmd("FocusLost", {
       group = group,
       callback = function() -- auto-clear images when windows and buffers change
+        -- bail if not enabled
+        if not state.enabled then return end
+
         vim.schedule(function()
           -- utils.debug("FocusLost")
-
           if
             state.options.editor_only_render_when_focused
             or (utils.tmux.is_tmux and utils.tmux.get_window_id() ~= initial_tmux_window_id)
@@ -328,6 +343,9 @@ api.setup = function(options)
     vim.api.nvim_create_autocmd("FocusGained", {
       group = group,
       callback = function() -- auto-clear images when windows and buffers change
+        -- bail if not enabled
+        if not state.enabled then return end
+
         -- utils.debug("FocusGained")
 
         state.disable_decorator_handling = false
@@ -362,6 +380,9 @@ api.setup = function(options)
       group = group,
       pattern = state.options.hijack_file_patterns,
       callback = function(event)
+        -- bail if not enabled
+        if not state.enabled then return end
+
         local buf = event.buf
         local win = vim.api.nvim_get_current_win()
         local path = vim.api.nvim_buf_get_name(buf)
@@ -375,6 +396,9 @@ api.setup = function(options)
   vim.api.nvim_create_autocmd({ "BufWritePost", "TextChanged", "TextChangedI", "InsertEnter" }, {
     group = group,
     callback = function(event)
+      -- bail if not enabled
+      if not state.enabled then return end
+
       local images = api.get_images({ buffer = event.buf })
       for _, img in ipairs(images) do
         local has_moved, extmark_y, extmark_x = img:has_extmark_moved()
@@ -492,4 +516,25 @@ api.create_report = function()
   return report.create(state)
 end
 
+---@return boolean
+api.is_enabled = function()
+  return state.enabled
+end
+
+api.enable = function()
+  state.enabled = true
+  local images = api.get_images()
+  for _, current_image in ipairs(images) do
+    current_image:render()
+  end
+end
+
+api.disable = function()
+  state.enabled = false
+  local images = api.get_images()
+  for _, current_image in ipairs(images) do
+    current_image:clear(true)
+  end
+end
+
 return api

lua/image/utils/document.lua

@@ -52,8 +52,9 @@ local create_document_integration = function(config)
   local render = vim.schedule_wrap(
     ---@param ctx IntegrationContext
     function(ctx)
-      local windows = utils.window.get_windows({ normal = true, floating = ctx.options.floating_windows })
+      if not ctx.state.enabled then return end
 
+      local windows = utils.window.get_windows({ normal = true, floating = ctx.options.floating_windows })
       local image_queue = {}
 
       for _, window in ipairs(windows) do

lua/types.lua

@@ -7,8 +7,12 @@
 ---@field clear fun(id?: string)
 ---@field get_images fun(opts?: { window?: number, buffer?: number, namespace?: string }): Image[]
 ---@field hijack_buffer fun(path: string, window?: number, buffer?: number, options?: ImageOptions): Image|nil
+---@field is_enabled fun(): boolean
+---@field enable fun()
+---@field disable fun()
 
 ---@class State
+---@field enabled boolean
 ---@field backend Backend
 ---@field options Options
 ---@field images { [string]: Image }