Class rtk.Popup

Class Hierarchy

An rtk.Viewport that behaves as a modal pop-up which hijacks focus until the popup is closed. Because popups are viewports, scrolling of the child widget is supported.

Unlike other widgets, rtk.Popups don't need to be explicitly added to some parent container. They are automatically inserted into the current rtk.Window when opened and removed when closed.

Also, unlike the parent rtk.Viewport class, rtk.Popup widgets have a drop shadow by default. Set shadow to false to explicitly disable.

The following examples assume an rtk.Window has already been created and is (or is about to be) open.

Example
local button = some_container:add(rtk.Button{"Open Popup"})
local popup = rtk.Popup{
    child=rtk.Text{'Hello world!'},
    anchor=button,
}
button.onclick = function(b, event)
    popup:open()
end
Example
local box = rtk.VBox{spacing=20}
local popup = rtk.Popup{child=box, padding=30, overlay='#000000cc', autoclose=false}
local text = box:add(rtk.Text{'Some very important message goes here.'})
local button = box:add(rtk.Button{'Close'}, {halign='right'})
button.onclick = function(b, event)
    popup:close()
end
popup:open()

Synopsis

Attributes
anchor rtk.Widget or nil

read/write

A widget against which to anchor the popup (default nil)

margin number

read/write

When anchor is set, the height will be constrained so that the popup is this many pixels from the edge of the screen (default 20)

width_from_anchor boolean

read/write

When anchor is set, the width of the popup will be matched to the width of the anchor (default true)

overlay colortype or nil

read/write

If set, paints an overlay over top of the window in the given color before drawing the popup (default nil)

autoclose boolean

read/write

If true, the popup will automatically close if the mouse is clicked outside the popup or when the rtk.Window loses focus (default true)

opened boolean

read-only

True when the popup is open

Methods
open()

Opens the modal popup

close()

Closes the popup

Attributes

rtk.Popup.anchor rtk.Widget or nil read/write

A widget against which to anchor the popup (default nil). The popup will be placed below the widget if there is sufficient room, otherwise will be placed above it, depending on which side has more space. When shadow is defined (as it is by default the rtk.Popups, the portion of the shadow against the anchor widget will be significantly reduced so that the anchor isn't obstructed.

rtk.Popup.margin number read/write

When anchor is set, the height will be constrained so that the popup is this many pixels from the edge of the screen (default 20). When anchor is not set, this behaves like standard widget margin.

rtk.Popup.width_from_anchor boolean read/write

When anchor is set, the width of the popup will be matched to the width of the anchor (default true). This also has the effect of dropping the border of the edge of the popup against the anchor.

rtk.Popup.overlay colortype or nil read/write

If set, paints an overlay over top of the window in the given color before drawing the popup (default nil). The alpha channel of this color is respected, so if you want a translucent overlay specify a lower alpha (e.g. #00000055).

This option is useful for things like alert boxes and is a good visual cue that focus has been stolen by the popup, but may not mix well with anchor because the overlay will be drawn over the anchor widget as well.

rtk.Popup.autoclose boolean read/write

If true, the popup will automatically close if the mouse is clicked outside the popup or when the rtk.Window loses focus (default true).

rtk.Popup.opened boolean read-only

True when the popup is open. Calling close() will set to false.

Methods

rtk.Popup:open(attrs)

Opens the modal popup.

By default, the popup will be centered within the rtk.Window unless anchor is defined, in which case the popup will be anchored to that widget. Without an anchor, to override the default positioning of the popup, attrs can be specified.

Example
-- Open with default placement
popup:open()

-- Opens the popup centered horizontally while 30px from the top of the window
popup:open{valign='top', halign='center', tpadding=30}
Parameters
attrs (table or nil)

the cell attributes to use when the popup is added to the rtk.Window. See rtk.Container for more details on available cell attributes.

Return Values
(rtk.Popup)

returns self for method chaining

rtk.Popup:close()

Closes the popup.

Event Handlers

See also handlers for rtk.Widget.

Synopsis

Methods
onopen()

Called just before the popup is opened

onclose()

Called just before the popup is closed

rtk.Popup:onopen()

Called just before the popup is opened.

This event handler has the opportunity block the popup from opening by returning false.

Return Values
(bool)

Returning false will block the popup from opening, while any other return value will allow it to be opened.

rtk.Popup:onclose(event)

Called just before the popup is closed.

The event argument indicates the type of event that is causing the popup to close, if any. This could be rtk.Event.MOUSEDOWN because the user clicked outside the popup and autoclose was true, or it could be rtk.Event.WINDOWCLOSE because the main window is closing. Except in the latter case, this event handler may block closure of the popup by returning false. In the case of rtk.Event.WINDOWCLOSE, this can't be aborted and the return value is ignored.

Parameters
event (rtk.Event or nil)

the event, if any, that is causing the popup to close. It is nil when the popup is programmatically closed.

Return Values
(bool)

Returning false will block the popup from closing, while any other return value will allow its closure.