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()

Used with the autoclose attribute to influence how the popup should be closed in response to events that occur outside the popup area.

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, which uses the theme's popup_overlay by default. 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.

This attribute is ignored if anchor is defined, because otherwise the overlay would be painted over the anchor widget.

rtk.Popup.autoclose autocloseconst read/write ¶

Allows automatically closing the popup if the mouse is clicked outside the popup bounds or when the rtk.Window loses focus, depending on the setting (default local).

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.

See also handlers for rtk.Widget.

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.