Library

struct Anchor

This structure defines an anchor to another object. It should be used in one of the fields anchor_* of ObjectLayout.

Fields

• obj::Union{Symbol, Object}: Reference object.
• side::Symbol: Side of the reference object to which we will apply the attachment.
• pad::Int: A space between the anchors of the two objects.

struct Keystorke

Structure that defines a keystroke.

Fields

• raw::Int32: Raw value of the keystroke.
• value::String: String representing the keystroke.
• ktype::Symbol: Type of the key (:char, :F1, :up, etc.).
• alt::Bool: true if ALT key was pressed (only valid if ktype != :char).
• ctrl::Bool: true if CTRL key was pressed (only valid if ktype != :char).
• shift::Bool: true if SHIFT key was pressed (only valid if ktype != :char).

struct ObjectLayout

This structure defines the layout of an object.

Fields

• anchor_bottom::Anchor: Bottom anchor specification. (Default = _no_anchor)
• anchor_left::Anchor: Left anchor specification. (Default = _no_anchor)
• anchor_right::Anchor: Right anchor specification. (Default = _no_anchor)
• anchor_top::Anchor: Top anchor specification. (Default = _no_anchor)
• anchor_center::Anchor: Center anchor specification. (Default = _no_anchor)
• anchor_middle::Anchor: Middle anchor specification. (Default = _no_anchor)
• top::Union{Int, String}: Absolute position of the object top side. (Default = -1)
• left::Union{Int, String}: Absolute position of the object left side. (Default = -1)
• height::Union{Int, String}: Height of the object. (Default = -1)
• width::Union{Int, String}: Width of the object. (Default = -1)

_check_horizontal_anchor(anchor::Anchor)

Check if the side parameter of anchor is valid for horizontal positioning. If anchor is _no_anchor, then true is always returned.

_check_vertical_anchor(anchor::Nothing)
_check_vertical_anchor(anchor::Anchor)

Check if the side parameter of anchor is valid for vertical positioning. If anchor is _no_anchor, then true is always returned.

_select_radio_button(rb::WidgetRadioButton)

Deselect the radio button rb in its group name.

_destroy_widget!(widget; refresh::Bool = true)

Private function that destroys a widget. This can be used if a new widget needs to reimplement the destroy function.

_draw_title(container::WidgetContainer)

Draw the title in the container container.

_get_anchor(anchor::Anchor, parent)

Return the line or column related to the anchor anchor. If the object in anchor is the parent, then the positioning will be computed relative to the parent.

_get_color_index(color::Symbol)

Return the index related to the color color.

_get_window_cur_pos(win::Ptr{WINDOW})

Get the cursor position of the window win and return it on a tuple (cur_y, cur_x). If the window is not initialized, then this function returns (-1, -1).

_get_window_dims(win::Ptr{WINDOW})

Get the dimensions of the window win and return it on a tuple (dim_y, dim_x). If the window is not initialized, then this function returns (-1, -1).

_next_widget(container::WidgetContainer)

Move the focus of container container to the next widget.

_previous_widget(container::WidgetContainer)

Move the focus of container container to the previous widget.

_process_horizontal_info(layout::ObjectLayout)

Process the horizontal positioning information in layout and write the variable horizontal of the same structure. The possible horizontal positioning information are:

• :aleft_aright: Left and right anchors were specified.
• :aleft_height: Left anchor and height were specified.
• :aright_height: Right anchor and height were specified.
• :acenter_height: Center anchor and height were specified.
• :right_height: Right and height were specified.
• :unknown: Insufficient information to compute the horizontal positioning.

_process_positioning_value(v, dim::Symbol, parent::WidgetParent)

Process the positioning value v related to the dimension dim of the parent widget parent. dim can be :height or :width.

If v is an Int, then it return v.

_process_vertical_info(layout::ObjectLayout)

Process the vertical positioning information in layout and write the variable vertical of the same structure. The possible vertical positioning information are:

• :abottom_atop: Bottom and top anchors were specified.
• :abottom_height: Bottom anchor and height were specified.
• :atop_height: Top anchor and height were specified.
• :amiddle_height: Middle anchor and height were specified.
• :top_height: Top and height were specified.
• :unknown: Insufficient information to compute the vertical positioning.

_select_radio_button(rb::WidgetRadioButton)

Select the radio button rb in its group name.

_str(wpc::ObjectLayout)

Convert the information in wpc to a string for debugging purposes.

accept_focus(widget)

Return true is the widget widget accepts focus or false otherwise.

accept_focus(window::Window)

Check if the window window can accept focus and, if it can, then perform the actions to change the focus.

add_widget!(container::WidgetContainer, widget::Widget)

Add the widget widget to the container `container.

add_widget!(win::Window, widget::Widget)

Add widget widget to the window win. If the win already have a widget, then it will be replaced.

app_main_loop(;fprev::Function = (k)->true, fpost::Function = (k)->true, destroy_on_exit::Bool = true, manage_window_switch::Bool = true)

Initialize the application main loop.

The function fprev is called after every pressed key and before the focus is processed. It must have the following signature:

fprev(k::Keystroke)::Bool

If it returns true, then the keystroke is processed. Otherwise, the software waits for another keystroke.

The function fpost is called after the keystroke is processed. It must have the following signature:

fpost(k::Keystroke)::Bool

If it return true, then the loop continues and a next keysotrke is requested. Otherwise, the loop is terminated.

Configuration keywords

• destroy_on_exit::Bool: If true, then destroy_tui() is called when we exit from the loop.
• manage_window_switch::Bool: If true, then F2 and F3 move to next and previous windows.

change_glyph!(widget::WidgetHorizontalLine, glyph::String)

Change the glyph of the horizontal line widget to glyph.

change_label!(button::WidgetButton, label::AbstractString)

Change the label of button button to label.

change_text!(widget::WidgetAnsiLabel, new_text::AbstractString; alignment = :l)

Change to text of the label widget widget to new_text.

The text alignment in the widget can be selected by the keyword alignment, which can be:

• :l: left alignment (default);
• :c: Center alignment; or
• :r: Right alignment.

change_text!(widget::WidgetLabel, new_text::AbstractString; alignment = :l, color::Int = -1)

Change to text of the label widget widget to new_text.

The text alignment in the widget can be selected by the keyword alignment, which can be:

• :l: left alignment (default);
• :c: Center alignment; or
• :r: Right alignment.

The text color can be selected by the keyword color. It it is negative (default), then the current color will not be changed.

change_value!(widget::WidgetProgressBar, new_value::Int; color::Int = -1)

Change the value of the progress bar to new_value.

The color can be selected by the keyword color. It it is negative (default), then the current color will not be changed.

clear_data!(widget::WidgetForm)

Clear the data in all the input fields in the form widget.

clear_data!(widget::WidgetInputField)

Clear the data in the input field widget.

compute_object_layout(layout::ObjectLayout, parent)

Compute the object layout based on the configuration layout and on its parent object parent.

Return

• The object height.
• The object width.
• The top position w.r.t. the parent object.
• The left position w.r.t. the parent object.

create_widget(T, layout::ObjectLayout, args...; kwargs...)
create_widget(T, parent::WidgetParent, layout::ObjectLayout, args...; kwargs)

Create the widget of type T using the positioning configuration layout.

Additional arguments and keywords related to each widget can be passed using args and kwargs, respectively.

If the second signature is called, then the created widget is added to the parent parent.

function create_window(layout::ObjectLayout = ObjectLayout(), id::String = "";  kwargs...)

Create a window. The window ID id is used to identify the new window in the global window list. The size and location of the window is configured by the object layout.

Keyword

• bcols::Int: Number of columns in the window buffer. This will be automatically increased to, at least, fit the viewable part of the window. (Default = 0)
• blines::Int: Number of lines in the window buffer. This will be automatically increased to, at least, fit the viewable part of the window. (Default = 0)
• border::Bool: If true, then the window will have a border. (Default = true)
• border_color::Int: Color mask that will be used to print the border. See function ncurses_color. If negative, then the color will not be changed. (Default = -1)
• focusable::Bool: If true, then the window can have focus. Otherwise, all focus request will be rejected. (Default = true)
• title::String: The title of the window, which will only be printed if border is true. (Default = "")
• title_color::Int: Color mask that will be used to print the title. See function ncurses_color. If negative, then the color will not be changed. (Default = -1)

create_window_with_container(vargs...; kwargs...)

Create a window with a container as its widget. The arguments and keywords are the same ones of the function create_window. The container will have the same size of the window buffer.

Return

• The created window.
• The created container.

destroy_all_windows()

Destroy all windows managed by the TUI.

destroy_tui()

Destroy the Text User Interface (TUI).

destroy_widget!(widget; refresh::Bool = true)

Destroy the widget widget.

If refresh is true (default), then a full refresh will be performed on the parent window. Otherwise, no refresh will be performed.

destroy_widget_buffer!(widget::Widget)

Destroy the buffer of the widget widget.

destroy_window!(win::Window)

Destroy the window win.

get_buffer(widget)

Return the buffer of the widget widget.

get_buffer(win::Window)

Return the buffer of the window win.

get_color_pair(foreground::Int, background::Int)

Return the ID of the color pair (foreground, background), or nothing if the color pair is not initialized.

get_selected_item(widget::WidgetListBox)

Return the ID of the current item of the list box widget and the data associated with it.

get_data(widget::WidgetInputField)

Return a vector with the data of all fields.

get_data(widget::WidgetInputField)

Get the data of widget as a string. If the validator is enabled and the data is not valid, then return nothing.

get_data(widget::WidgetListBox)

Return the data of the list box widget.

get_focused_window()

Return the focused window.

get_height(object)

Return the usable height of object object.

get_height_for_child

Return the usable height of the object for a child object.

get_bottom(object)

Return the left of the object w.r.t. its parent.

get_left_for_child

Return the left of the object for a child object.

get_parent(widget)

Return the parent of the widget widget.

get_parent(win::Window)

Return nothing since the window has no parent.

get_selected(group_name::AbstractString)

Return the WidgetRadioButton that is selected in group with name group_name. If the group_name does not exists or if no button is selected, then nothing is returned.

get_selected(widget::WidgetListBox)

Return an array of Bool indicating which elements of the list box widget are selected.

get_top(object)

Return the top of the object w.r.t. its parent.

get_top_for_child

Return the top of the object for a child object.

get_width(object)

Return the usable width of object object.

get_width_for_child

Return the usable width of object object for a child object.

has_focus(container::WidgetContainer, widget)

Return true if the widget widget is in focus on container container, or false otherwise.

has_focus(window::Window, widget)

Return true if the widget widget is in focus on window window, or false otherwise.

hide_window(win::Window)

Hide the window win.

init_color_pair(foreground::Symbol, background::Symbol)

Initialize the color pair (foreground, background) and return its ID. If the pair already exists, then just the function just returns its ID.

init_focus_manager()

Initialization of the focus manager. The elements in focus_chain are iterated to find the first one that can accept the focus.

init_tui(dir::String = "")

Initialize the Text User Interface (TUI). The full-path of the ncurses directory can be specified by dir. If it is empty or omitted, then it will look on the default library directories.

init_widget_buffer!(widget::Widget)

Initialize the buffer of widget widget. The variables layout and parent must be set before calling this function. If the buffer is already initialized, then it will be deleted first.

jlgetch(win::Union{Ptr{WINDOW},Nothing} = nothing)

Wait for an keystroke in the window win and return it (see Keystroke). If win is nothing, then getch() will be used instead of wgetch(win) to listen for the keystroke.

log_message(level::Int, msg::AbstractString, id::AbstractString = "")

Log the message msg with level level. The ID of the called can be specified by id.

If a line is @log_pad X, then the following lines will have a padding of X.

modify_color([name::Symbol, ]id::Int, r::Int, g::Int, b::Int)

Modify the color ID id to the RGB value (r,g,b). If the symbol name is available, then the user can select this color ID by using name instead of the id.

If the color name name already exists, then nothing will be changed.

Notice that the range for the RGB color components is [0,1000].

If the color was initialized, then it returns the color ID. Otherwise, it returns -1.

move_view!(win::Window, y::Int, x::Int; update::Bool = true)

Move the origin of the view of window win to the position (y,x). This routine makes sure that the view will never reach positions outside the buffer.

move_view_inc!(win::Window; Δy::Int, Δx::Int; kwargs...)

Move the view of the window win to the position (y+Δy, x+Δx). This function has the same set of keywords of the function move_view.

move_window(win::Window, starty::Int, startx::Int)

Move the window win to the position (starty, startx).

move_window_to_top(win::Window)

Move window win to the top.

ncurses_color([foreground, background,] attrs::Integer = 0; kwargs...)

Return a mask to apply a color format with the foreground color foreground, background color background, and the attributes attrs.

If the pair (foreground, background) is omitted, then the foreground and background color will not be changed.

The colors can be specified by their names using Symbol or by their indices using Int.

Keywords

• bold::Boolean: If true, then apply bold format mask to attrs. (Default = false)
• underline::Boolean: If true, then apply underline format mask to attrs. (Default = false)

next_window()

Move the focus to the next window.

obj_desc(obj)

Return a string with the description of the object obj formed by:

<Object type> (<Object address if mutable>)

 function obj_to_ptr(obj)

Returns the hexadecimal representation of the address of the object obj. It only works with mutable objects. If obj is immutable, then 0x0 will be returned.

previous_window()

Move the focus to the previous window.

process_focus(widget, k::Keystroke)

Process the actions when widget widget is in focus and the keystroke k is pressed. If it returns false, then it is means that the widget was not capable to process the focus. Otherwise, it must return true.

process_focus(k::Keystroke)

Process the focus considering the user's keystorke k.

process_focus(window::Window, k::Keystroke)

Process the focus on window window due to keystroke k.

function process_keystroke(widget, k::Keystroke)

Default function of widget to process a keystroke. This function is called inside process_focus. If the widget could process the keystore, then if must return true. Otherwise, if must return false. In this case, the keystroke will be passed to the next widget in the focus list.

redraw(widget)

Redraw the widget inside its content window cwin.

refresh_all_windows()

Refresh all the windows, including the root window.

refresh_window(id::String)

Refresh the window with id id and all its parents windows except for the root window.

refresh_window(container::WidgetContainer; force_redraw::Bool = false)

Ask the parent widget to refresh the window. If force_redraw is true, then all widgets in the window will be updated.

refresh_window(win::Window; force_redraw = false)

Refresh the window win and its widget. If the view needs to be updated (see view_needs_update) or if force_redraw is true, then the content of the buffer will be copied to the view before updating.

release_focus(widget)

Request focus to be released. It should return true if the focus can be released or false otherwise.

remove_widget!(container::WidgetContainer, widget::Widget)

Remove the widget widget from the container container.

remove_widget!(win::Window, widget::Widget)

Remove the widget widget from the window win. If widget does not belong to win, then nothing is done.

reposition!(object)

Reposition the object baesd on the stored configuration.

request_focus!(container::WidgetContainer, widget)

Request the focus to the widget widget of the container container. It returns true if the focus could be changed or false otherwise.

request_focus(widget)

Request to focus to the widget widget.

request_focus(win::Window)

Request the focus to the window win. If win cannot get the focus, then nothing happens and it returns false. If wincan get the focus, then the focus is passed to it and the function returns true.

Remarks

Even if win is in the focus chain, the focus_id will not change by requesting focus to win. This means that the window focus order is not altered by this function.

request_next_widget(container::WidgetContainer)

Request the next widget in container. It returns true if a widget has get the focus or false otherwise.

request_prev_widget(container::WidgetContainer)

Request the previous widget in container. It returns true if a widget has get the focus or false otherwise.

request_update!(widget)

Request update of the widget widget.

request_update!(win::Window)

Request update of the window win because its widget was updated.

request_view_update!(win::Window)

Request to update the view of window win. Notice that this must also request update on all parent windows until the root window.

require_cursor()

If true, then the physical cursor will be shown and the position will be updated according to its position in the widget window. Otherwise, the physical cursor will be hidden.

select_item!(widget::WidgetListBox, id::Int)

Select the item id in the list box widget. Notice that id refers to the position of the item in the array data.

set_color([win::Window,] color::Int)

Set the color of the window win to color (see ncurses_color). If win is omitted, then it defaults to the root window.

set_focus_chain(wins::Window...; new_focus_id::Int = 1)

Set the focus chain, i.e. the ordered list of windows that can receive the focus. The keyword new_focus_id can be set to specify which element is currently focused in the new chain.

set_widget_color(widget, color::Int)

Set the background color of widget to color.

set_window_title!(win::Window, title::AbstractString; ...)

Set the title of the window win to title.

Keywords

• title_color::Int: Color mask that will be used to print the title. See function ncurses_color. If negative, then the color will not be changed. (Default = -1)

show_window(win::Window)

Show the window win.

sync_cursor(widget::WidgetContainer)

Synchronize the cursor to the position of the focused widget in container container. This is necessary because all the operations are done in the buffer and then copied to the view.

sync_cursor(window::Window)

Synchronize the cursor to the position of the focused widget in window window. This is necessary because all the operations are done in the buffer and then copied to the view.

tui_update()

Update the entire TUI.

unset_color([win::Window,] color::Number)

Unset the color color (see ncurses_color) in the window win. If win is omitted, then it defaults to the root window.

update(widget; force_redraw = false)

Update the widget by calling the function redraw. This function returns true if the widget needed to be updated of false otherwise.

If force_redraw is true, then the widget will be updated even if it is not needed.

update_view!(win::Window; force::Bool = false)

Update the view of window win by copying the contents from the buffer. If the view does not need to be updated (see view_needs_update), then nothing is done. If the keyword force is true, then the copy will always happen.

Return

It returns true if the view has been updated and false otherwise.

validate_str(str::AbstractString, v)

Validate the string str using the validator v. v is an element of the type that will be used to validate or a regex.

@composed_widget(ex)

Declare a structure of a composed widget.

@connect_signal(obj, signal::Symbol, f::Symbol, vargs...)

Connect the signal signal of the object obj to the function f passing the additional arguments vargs. Thus, when signal is emitted by obj, then fcall will be executed.

@create_widget_helper(widget_symbol[, macro_name])

This macro defines a helper to create a widget of type widget_symbol. The helper name is macro_name. If the latter is not available, then it will be composed of the prefix tui_ plus the widget_symbol.

@derived_widget(ex)

Declare a structure of a derived widget.

@disconnect_signal(obj, signal::Symbol)

Disconnect the signal signal from object obj.

@emit_signal(obj, signal::Symbol, params...)

Emit the signal signal of the object obj with the parameters params..., causing to execute the connected function.

@forward_signal(src, dest, signal::Symbol)

Forward the signal signal from src to dest. This means that every time that the signal signal is generated in src, then the function in dest will be called.

macro log(level, msg, id)

Log the messagem msg with level level of the caller id

macro log(level, msg)

Log the message msg with level level.

@signal(name)

Create the signal named name. This must be used inside the widget structure that must be declared with @with_kw option (see package Parameters.jl).

@tui_ansi_label(args...)

This macro creates a widget of type ansi_label using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_button(args...)

This macro creates a widget of type button using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_canvas(args...)

This macro creates a widget of type canvas using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_combo_box(args...)

This macro creates a widget of type combo_box using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_container(args...)

This macro creates a widget of type container using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_form(args...)

This macro creates a widget of type form using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_horizontal_line(args...)

This macro creates a widget of type horizontal_line using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_input_field(args...)

This macro creates a widget of type input_field using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_label(args...)

This macro creates a widget of type label using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_list_box(args...)

This macro creates a widget of type list_box using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_progress_bar(args...)

This macro creates a widget of type progress_bar using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@tui_radio_button(args...)

This macro creates a widget of type radio_button using the arguments args....

args must be a set of expressions as follows:

<parameter> = <value>

If the parameter parent is present, then the created widget will be added to parent. Otherwise, the widget will be created and returned, but not added to any parent.

@widget(ex)

Declare a structure of a widget.