*nvim-notify.txt*   A fancy, configurable notification manager for NeoVim

==============================================================================

A fancy, configurable notification manager for NeoVim

notify                                                                  *notify*


                                                                *notify.setup()*
`setup`({user_config})

Configure nvim-notify
   See: ~
       |notify.Config|
       |notify-render|

Parameters~
{user_config} `(notify.Config|nil)`
Default values:
>lua
  {
    background_colour = "NotifyBackground",
    fps = 30,
    icons = {
      DEBUG = "",
      ERROR = "",
      INFO = "",
      TRACE = "✎",
      WARN = ""
    },
    level = 2,
    minimum_width = 50,
    render = "default",
    stages = "fade_in_slide_out",
    time_formats = {
      notification = "%T",
      notification_history = "%FT%T"
    },
    timeout = 5000,
    top_down = true
  }
<

                                                                *notify.Options*
Options for an individual notification
Fields~
{title} `(string)`
{icon} `(string)`
{timeout} `(number|boolean)` Time to show notification in milliseconds, set to false to disable timeout.
{on_open} `(function)` Callback for when window opens, receives window as argument.
{on_close} `(function)` Callback for when window closes, receives window as argument.
{keep} `(function)` Function to keep the notification window open after timeout, should return boolean.
{render} `(function|string)` Function to render a notification buffer.
{replace} `(integer|notify.Record)` Notification record or the record `id` field. Replace an existing notification if still open. All arguments not given are inherited from the replaced notification including message and level.
{hide_from_history} `(boolean)` Hide this notification from the history
{animate} `(boolean)` If false, the window will jump to the timed stage. Intended for use in blocking events (e.g. vim.fn.input)

                                                                 *notify.Events*
Async events for a notification
Fields~
{open} `(function)` Resolves when notification is opened
{close} `(function)` Resolved when notification is closed

                                                                 *notify.Record*
Record of a previously sent notification
Fields~
{id} `(integer)`
{message} `(string[])` Lines of the message
{level} `(string|integer)` Log level. See vim.log.levels
{title} `(string[])` Left and right sections of the title
{icon} `(string)` Icon used for notification
{time} `(number)` Time of message, as returned by `vim.fn.localtime()`
{render} `(function)` Function to render notification buffer

                                                            *notify.AsyncRecord*
Inherits: `notify.Record`

Fields~
{events} `(notify.Events)`

                                                               *notify.notify()*
`notify`({message}, {level}, {opts})

Display a notification.

You can call the module directly rather than using this:
>lua
 require("notify")(message, level, opts)
<
Parameters~
{message} `(string|string[])` Notification message
{level} `(string|number)` Log level. See vim.log.levels
{opts} `(notify.Options)` Notification options
Return~
`(notify.Record)`

                                                                *notify.async()*
`async`({message}, {level}, {opts})

Display a notification asynchronously

This uses plenary's async library, allowing a cleaner interface for
open/close events. You must call this function within an async context.

The `on_close` and `on_open` options are not used.

Parameters~
{message} `(string|string[])` Notification message
{level} `(string|number)` Log level. See vim.log.levels
{opts} `(notify.Options)` Notification options
Return~
`(notify.AsyncRecord)`

                                                              *notify.history()*
`history`({opts})

Get records of all previous notifications

You can use the `:Notifications` command to display a log of previous notifications
Parameters~
{opts?} `(notify.HistoryOpts)`
Return~
`(notify.Record[])`

                                                            *notify.HistoryOpts*
Fields~
{include_hidden} `(boolean)` Include notifications hidden from history

                                                              *notify.dismiss()*
`dismiss`({opts})

Dismiss all notification windows currently displayed
Parameters~
{opts} `(notify.DismissOpts)`

                                                            *notify.DismissOpts*
Fields~
{pending} `(boolean)` Clear pending notifications
{silent} `(boolean)` Suppress notification that pending notifications were dismissed.

                                                                 *notify.open()*
`open`({notif_id}, {opts})

Open a notification in a new buffer
Parameters~
{notif_id} `(integer|notify.Record)`
{opts} `(notify.OpenOpts)`
Return~
`(notify.OpenedBuffer)`

                                                               *notify.OpenOpts*
Fields~
{buffer} `(integer)` Use this buffer, instead of creating a new one
{max_width} `(integer)` Render message to this width (used to limit window decoration sizes)

                                                           *notify.OpenedBuffer*
Fields~
{buffer} `(integer)` Created buffer number
{height} `(integer)` Height of the buffer content including extmarks
{width} `(integer)` width of the buffer content including extmarks
{highlights} `(table<string, string>)` Highlights used for the buffer contents

                                                              *notify.pending()*
`pending`()

Number of notifications currently waiting to be displayed
Return~
`(integer[])`

                                                             *notify.instance()*
`instance`({user_config}, {inherit})

Configure an instance of nvim-notify.
You can use this to manage a separate instance of nvim-notify with completely different configuration.
The returned instance will have the same functions as the notify module.
Parameters~
{user_config} `(notify.Config)`
{inherit?} `(boolean)` Inherit the global configuration, default true


==============================================================================
notify.config                                                    *notify.config*

                                                                 *notify.Config*
Fields~
{level} `(string|integer)` Minimum log level to display. See vim.log.levels.
{timeout} `(number)` Default timeout for notification
{max_width} `(number|function)` Max number of columns for messages
{max_height} `(number|function)` Max number of lines for a message
{stages} `(string|function[])` Animation stages
{background_colour} `(string)` For stages that change opacity this is treated as the highlight behind the window. Set this to either a highlight group, an RGB hex value e.g. "#000000" or a function returning an RGB code for dynamic values
{icons} `(table)` Icons for each level (upper case names)
{time_formats} `(table)` Time formats for different kind of notifications
{on_open} `(function)` Function called when a new window is opened, use for changing win settings/config
{on_close} `(function)` Function called when a window is closed
{render} `(function|string)` Function to render a notification buffer or a built-in renderer name
{minimum_width} `(integer)` Minimum width for notification windows
{fps} `(integer)` Frames per second for animation stages, higher value means smoother animations but more CPU usage
{top_down} `(boolean)` whether or not to position the notifications at the top or not


==============================================================================
notify-render                                                    *notify-render*

Notification buffer rendering

Custom rendering can be provided by both the user config in the setup or on
an individual notification using the `render` key.
The key can either be the name of a built-in renderer or a custom function.

Built-in renderers:
- `"default"`
- `"minimal"`
- `"simple"`
- `"compact"`
- `"wrapped-compact"`

Custom functions should accept a buffer, a notification record and a highlights table

>
    render: fun(buf: integer, notification: notify.Record, highlights: notify.Highlights, config)
<
You should use the provided highlight groups to take advantage of opacity
changes as they will be updated as the notification is animated

                                                             *notify.Highlights*
Fields~
{title} `(string)`
{icon} `(string)`
{border} `(string)`
{body} `(string)`


 vim:tw=78:ts=8:noet:ft=help:norl: