Docstrings

ToggleMenus

The ToggleMenus module provides a TerminalMenu where options may be toggled through several states. A template is constructed with a ToggleMenuMaker, which is used to construct a ToggleMenu. The result is passed to TerminalMenus.request for display in the REPL.

mutable struct ToggleMenu <: _ConfiguredMenu{Config}
    options::StringVector
    settings::Vector{Char}
    selections::Vector{Char}
    icons::Dict{Char,Union{String,Char}}
    header::Union{AbstractString,Function}
    braces::Tuple{String,String}
    maxicon::Int
    keypress::Function
    pagesize::Int
    pageoffset::Int
    cursor::Ref{Int}
    config::Config
    aux::Any
end

ToggleMenuMaker(header, settings, icons, pagesize=15; kwargs...)

Create a template with the defining values of a ToggleMenu, which may be called with further arguments to create one.

Arguments

• header: An AbstractString, which should inform the user what the options do, or a function header(m::ToggleMenu)::String.
• settings: A Vector{Char}, every element must be unique, and should be easy to type. Pressing a key corresponding to one of the settings will toggle that option directly to that setting.
• icons: Optional Vector{Char} or Vector{String}. If provided, these must also be unique, and must have the same number of elements as settings. These are used as the selection icons, which will default to settings if none are provided.
• pagesize: Number of options to display before scrolling.

Keyword Arguments

• braces: This may be a tuple of Strings or Chars, defaults to ("[", "]").
• keypress: A second function to run on keypress, only called if the standard inputs aren't handled. Signature is (menu::ToggleMenu, i::UInt32), where i is a somewhat funky representation of the character typed, as provided by REPL.TerminalMenus. This should return false unless the menu is completed, in which case, return true.

Other keyword arguments are passed through to TerminalMenus.Config, and may be used to configure aspects of menu presentation and behavior.

The ToggleMenuMaker is callable to produce a ToggleMenu.

(maker::ToggleMenuMaker)(options[, selections])::ToggleMenu
(maker::ToggleMenuMaker)(opts::Tuple{StringVector,Vector{Char}})::ToggleMenu
(maker::ToggleMenuMaker)(header::AbstractString, options...)::ToggleMenu

Make a ToggleMenu.

The options are a Vector of some String type, which have states which may be toggled through. selections is an optional Vector{Char} of initial selected states for the options. If a selection is \0, the menu will skip that line during navigation, and it will not be togglable. If not provided, the menu options will begin in the first setting.

If you want a header specific to one menu, provide it as the first argument, this will override the header in the maker (which can be "" if desired).

When the menu is finished, it will return a Vector of Tuples, the first of which is a selection, the last an option. This precomposes the options with their selections, which is probably what you want, as well as allowing menu functions to modify both options and selections. If canceled, all selections will be \0.

Use

ToggleMenus are inherently designed for use at the REPL, and the type signatures are designed for easy composition. For example, this works:

julia> (["option 1", "option 2"], ['a', 'b']) |> maker |> request

Which is more useful with a function which prepares options and selections. Once that function is stable one may use composition:

action = request ∘ maker ∘ prepare

Such that action(data) will prepare data to be presented in ToggleMenu format, pass it to the maker, and call request.

ToggleMenus also adds methods to request to make do notation possible for ToggleMenus, making this sort of workflow possible:

request(menu(options, selections)) do selected
    # handle the returned settings here
end

request(λ::Function, args...)

A do-notation-compatible form of request.

request(m::ToggleMenu; kwargs..., cursor=m.cursor)

All REPL.AbstractMenu methods for request are overloaded for ToggleMenu, to provide m.cursor as a keyword argument. This value is used internally in a way which presumes that the Ref will be the same one seen by the runtime, as such, it is passed after kwargs..., meaning that overloading it will have no effect.

didcancelmenu(result::Vector{Tuple{Char,String}})::Bool

Called on the result returned from a ToggleMenu, this will return true if the results comes from menu having been cancelled.

makemenu(maker::ToggleMenuMaker, options [, selections])::ToggleMenu

Makes a ToggleMenu.

This is not exported, and is subject to change without notice, you should invoke it by calling ToggleMenuMaker.