dao::options

A plugin’s own settings in the game’s options screen.

Declared in dao/Options.h.

Classes

Class
Button	A button in a plugin’s section, like the screen’s own Restore Defaults.
Choice	A choice of one of a few named values in a plugin’s section.
EntryState	A control on the screen: a plugin’s, or the game’s own.
TabState	One of the screen’s tabs.
Toggle	A checkbox in a plugin’s section.

Enumerations

ChoiceStyle

enum class ChoiceStyle

How a Choice is shown.

Value
Slider	a slider with a stop for each value, like the detail sliders on the Video tab
Dropdown	a button that opens a list of the values, like Difficulty on the Game tab

Column

enum class Column

The column of its tab a section would be in.

Value
Either	the first with room: the left, then the right
Left
Right

Kind

enum class Kind : std::uint8_t

What a control is.

Value
Toggle	a checkbox: 0 or 1
Choice	a slider with named stops or a dropdown: an index of its values
Slider	a slider of numbers from least to most, the game’s own volumes, gamma and mouse
Button	a plugin’s button

Refusal

enum class Refusal : std::uint8_t

Why a step on the options screen was refused, or None if it was taken.

Value
None
NotShown	the screen is not open; for Open, nothing to open it from; for Set, its tab is not shown
AlreadySo	the screen is open already, or the tab shown already
Disabled	the tab’s button is disabled
NotOffered	no control of a plugin’s by that name is on the screen
OutOfRange	a checkbox given other than 0 or 1, or a choice an index it has not

SectionState

enum class SectionState

What became of a section given to AddSection.

Value
Unknown	no section with that title was added
Waiting	the game has not opened its options screen yet
Shown	placed on its tab
NoRoom	its tab has not the free rows for it, or sections added earlier took them
Failed	the options screen’s Flash movie was not as expected, so it was left alone

Tab

enum class Tab

A tab of the options screen.

Value
Game	five free rows in its left column, six in its right
Video	its right column, fourteen rows: a heading, two checkboxes and eight sliders, say
Online	nine free rows in its left column, seven in its right
Controls	the key bindings; no room for a section
Audio	no room for a section

Functions

AddSection()

bool AddSection(std::wstring title, std::vector<Toggle> toggles, std::vector<Choice> choices={}, Column column=Column::Either, Tab tab=Tab::Game, std::vector<Button> buttons={})

Adds a section of settings to a tab of the options screen.

Call it from DAOLib_Load, before the game first opens its options screen. A tab’s free rows are shared by every plugin. A heading takes two rows, a checkbox one and a dropdown two; sliders stand as close as the game’s own, six of them in seven rows, and buttons two in three; and a section takes whole rows of one column. A section on the Video tab has the tab laid out for it: the game’s own settings closer together and all in the left column, and the right column, a heading and twelve rows, for sections. Sections are placed in the order they were added. The first section a tab has no room for is left out, and so is every later section on that tab; the plugin’s log has a warning for each, and StateOf says NoRoom.

Parameter
title	the section’s heading, which is also its key for StateOf
toggles	the checkboxes, listed first
choices	the sliders and dropdowns, listed after the checkboxes in the order given
column	the column the section goes in if that column has the rows for it; it goes in the other if not
tab	the tab the section is on
buttons	the buttons, listed after the choices in the order given

Returns false, with nothing added, if the section has no toggles, choices or buttons, a name is not letters and digits or is already taken, a callback is missing, a choice has fewer than two values, or the tab is Controls or Audio

Cancel()

Refusal Cancel()

Presses Cancel as the player does: the screen closed, and each plugin’s control given back, through its set, the value it had when the screen opened.

Entries()

std::vector<EntryState> Entries(Tab tab)

Returns the controls on a tab: this plugin’s placed there, and, while the tab is shown, the game’s own and the other plugins’ checkboxes and choices.

None if the screen is not open.

IsOpen()

bool IsOpen()

Returns whether the options screen is open.

Call it, and the rest below, on the game thread.

Ok()

Refusal Ok()

Presses OK as the player does: the changes kept and the screen closed.

A change the game needs a restart or a confirmation for opens the game’s message box first (dao/Gui.h, CurrentPopup).

Open()

Refusal Open()

Opens the options screen as the player does: the start menu’s Options button, or Escape’s menu’s, with that menu opened first in the game.

The screen comes with the menu’s backing panel. The screen opens a few frames later: IsOpen says when.

Returns None once it is asked for, NotShown where neither menu can be had (a conversation, a cutscene, a loading screen, another full screen), AlreadySo if it is open

Set()

Refusal Set(std::wstring_view name, double value)

Sets a control as the player’s click or drag on it does: a checkbox to 0 or 1, a choice to an index of its values, a slider to a number from its least to its most, a plugin’s button pressed (its value is ignored).

A plugin’s set or pressed runs a frame later; the game’s own option changes as its control’s would, and OK keeps it or Cancel puts it back as the game does.

Returns NotShown unless the screen is open with the control’s tab shown; Disabled for a control that takes no change now

ShowTab()

Refusal ShowTab(Tab tab)

Shows a tab as a click on its button does: the button lit, the page shown, and Restore Defaults acting on it.

StateOf()

SectionState StateOf(std::wstring_view title)

Returns what became of the section with that title.

Tabs()

std::vector<TabState> Tabs()

Returns the screen’s tabs in their order, or none if it is not open.