Clock.nvim

Display the time or a simple pomodoro timer in a floating window.

Purpose

Learning the basics about creating a plugin for neovim.

Installation

Install via package manager.

Using lazy.nvim

-- plugins/clock.lua
return {
    "rushjs1/clock.nvim",
    event = "VeryLazy",
}

Using packer.nvim

use("rushjs1/clock.nvim")

-- Packer
use({
    "rushjs1/clock.nvim",
    config = function()
        require("clock").setup({})
    end,
})

Setup

No need to call setup when using default options

For custom options using Lazy.nvim, please only use opts. Calling setup is only necessary when using custom options with packer.

Example using custom options

-- Lazy.nvim
-- plugins/clock.lua
return {
  "rushjs1/clock.nvim",
  event = "VeryLazy",
  opts = {
    title_pos = "left", -- "left, right or center"
    window_pos = "center", -- "TR(top right) or center"
    timeout = false, -- disable the timeout
    timeout_duration = 3000, --duration for the timeout
    timer_opts = {
      timer_duration = 600, --(10mins - in seconds)
      timer_completion_duration = 10000, --(10 seconds - in miliseconds)
      timer_title = "Focus Time", -- title for the timer floating window
      timer_duration_selections = { -- define durations(in seconds) for the selection window for the timer
        20, -- 20 Seconds
        300, -- 5 Minutes
        600, -- 10 Minutes
        900, -- 15 Minutes
        1200, -- 20 Minutes
        1820, -- 30 Minutes and 20 Seconds
      },
    },
  },
}

-- Packer.nvim
-- Call the setup function and pass the following options
require("clock").setup({
    title_pos = "left", -- "left, right or center"
    window_pos = "center", -- "TR(top right) or center"
    timeout = false, -- disable the timeout
    timeout_duration = 3000, --duration for the timeout
    timer_opts = {
        timer_duration = 600, --(10mins - in seconds)
        timer_completion_duration = 10000, --(10 seconds - in miliseconds)
        timer_title = "Focus Time", -- title for the timer floating window
        timer_duration_selections = { -- define durations(in seconds) for the selection window for the timer
			20, -- 20 Seconds
			300, -- 5 Minutes
			600, -- 10 Minutes
			900, -- 15 Minutes
			1200, -- 20 Minutes
			1820, -- 30 Minutes and 20 Seconds
        }
    }
})

Commands

:ClockShowTime Toggle the 'time' window.

:ClockSelectTime Opens the window to select a duration for the timer.

:ClockRestartTimer Restart the pomodoro timer.

:ClockStopTimer Stop and clear the pomodoro timer.

:ClockStartTimer Start the pomodoro timer (uses default or duration defined in setup).

:ClockToggleTimer Toggle the pomodoro timer floating window(timer continues to run in the background).

keymap.set("n", "<leader><leader>t", ":ClockShowTime<CR>")
keymap.set("n", "<leader><leader>s", ":ClockSelectTime<CR>")
keymap.set("n", "<leader><leader>dt", ":ClockToggleTimer<CR>")

Configuration

--default_options

--@field title_pos string
--@field window_pos string
--@field timeout boolean
--@field timeout_duration integer
--@table timer_opts
--@field timer_duration integer
--@field timer_completion_duration integer
--@field timer_title string
--@field timer_duration_selections table

M.default_options = {
    title_pos = "center", -- "left, right or center"
    window_pos = "TR", -- "TR(top right) or center"
    timeout = true, -- disable the timeout
    timeout_duration = 5000,
    timer_opts = {
        timer_duration = 600, --(10mins - in seconds)
        timer_completion_duration = 10000, --(10seconds - in miliseconds)
        timer_title = "Focus Time", --title for the timer floating window
        timer_duration_selections = { -- define durations(in seconds) for the selection window for the timer
			60,
			300,
			600,
			900,
			1200,
			1500,
			1800,
			2100,
			2400,
			2700,
			3000,
			3300,
        }
    }
}