Skip to content

Dialog

Jump to bottom
coding_jackalope edited this page Oct 9, 2020 · 6 revisions
Table of Contents

Overview

Dialog boxes are windows that rendered on top of everything else. These windows will consume input from all other windows and controls. These are useful for forcing users to interact with a window of importance, such as message boxes and file dialogs.

API

Below is a list of functions associated with the Dialog API.

OpenDialog

Opens the dialog box with the given Id. If the dialog box was opened, then it is pushed onto the stack. Calls to the BeginDialog with this same Id will return true if opened.

Parameter Type Description
Id String A string uniquely identifying this dialog box.

BeginDialog

Begins the dialog window with the given Id if it is open. If this function returns true, then EndDialog must be called. Dialog boxes are windows which are centered in the center of the viewport. The dialog box cannot be moved and will capture all input from all other windows.

Parameter Type Description
Id String A string uniquely identifying this dialog box.
Options Table List of options that control how this dialog box behaves. These are the same parameters found for BeginWindow, with some caveats. Certain options are overridden by the Dialog system. They are: X, Y, Layer, AllowFocus, AllowMove, and AutoSizeWindow.
Return Description
Boolean Returns true if the dialog with the given Id is open.

EndDialog

Ends the dialog window if a call to BeginDialog returns true.

CloseDialog

Closes the currently active dialog box.

MessageBox

Opens a message box to be displayed to the user with a title and a message. Buttons can be specified through the options table which when clicked, the string of the button is returned. This function should be called every frame when a message box wants to be displayed.

if MessageBox then
	local Result = Slab.MessageBox("Message Box", "This is a test message box.")

	if Result ~= "" then
		MessageBox = false
	end
end
Parameter Type Description
Title String The title to display for the message box.
Message String The message to be displayed. The text is aligned in the center. Multi-line strings are supported.
Options Table List of options to control the behavior of the message box.
Option Type Description
Buttons Table List of buttons to display with the message box. The order of the buttons are displayed from right to left.
Return Description
String The name of the button that was clicked. If none was clicked, an emtpy string is returned.

FileDialog

Opens up a dialog box that displays a file explorer for opening or saving files or directories. This function does not create any file handles, it just returns the list of files selected by the user.

if OpenFile then
	local Result = Slab.FileDialog({Type = 'openfile'})

	if Result.Button ~= "" then
		OpenFile = false
	end
end
Parameter Type Description
Options Table List of options that control the behavior of the file dialog.
Option Type Description
AllowMultiSelect Boolean Allows the user to select multiple items in the file dialog.
Directory String The starting directory when the file dialog is open. If none is specified, the dialog will start at love.filesystem.getSourceBaseDirectory and the dialog will remember the last directory navigated to by the user between calls to this function.
Type String The type of file dialog to use. The options are:
openfile: This is the default method. The user will have access to both directories and files. However, only file selections are returned.
opendirectory: This type is used to filter the file dialog for directories only. No files will appearin the list.
savefile: This type is used to select a name of a file to save. The user will be prompted if they wish to overwrite an existing file.
Filters Table A list of filters the user can select from when browsing files. The table can contain tables or strings.
Table: If a table is used for a filter, it should contain two elements. The first element is the filter while the second element is the description of the filter e.g. {"*.lua", "Lua Files"}
String: If a raw string is used, then it should just be the filter. It is recommended to use the table option since a description can be given for each filter.
IncludeParent Boolean This option will include the parent '..' directory item in the file/dialog list. This option is true by default.
Return Description
Table Returns items for how the user interacted with this file dialog.
Name Type Description
Button String The button the user clicked. Will either be OK or Cancel.
Files Table An array of selected file items the user selected when OK is pressed. Will be empty otherwise.
Clone this wiki locally