Skip to content

mwseMCMTemplate⚓︎

A Template is the top level component in MCM. It determines the overall layout of the menu. Can be created with a table or a string (name).

This type inherits the following: mwseMCMComponent

Properties⚓︎

childIndent⚓︎

The left padding size in pixels. Used on all the child components.

Returns:

  • result (integer, nil)

childSpacing⚓︎

The bottom border size in pixels. Used on all the child components.

Returns:

  • result (integer, nil)

class⚓︎

Every MCM component has a unique string indentifier specific to that component. These strings are the filename of the file implementing a component. These are found in core\\mcm\\components.

Returns:

  • result (string)

componentType⚓︎

The type of this component.

Returns:

  • result ("Template")

createContentsContainer⚓︎

This method creates the contents of a component. Not every component implements this method.

Returns:

currentPage⚓︎

The currently displayed page in this Template.

Returns:

description⚓︎

If in a Sidebar Page, the description will be shown on mouseover.

Returns:

  • result (string, nil)

elements⚓︎

This dictionary-style table holds all the UI elements of the Template, for easy access.

Returns:

headerImagePath⚓︎

The path to the header image. It's relative to Data Files/. The image must have power-of-2 dimensions (i.e. 16, 32, 64, 128, 256, 512, 1024, etc.).

Returns:

  • result (string, nil)

indent⚓︎

The left padding size in pixels. Only used if the childIndent isn't set on the parent component.

Returns:

  • result (integer)

inGameOnly⚓︎

If true, then this component will be disabled when on the main menu.

Returns:

  • result (boolean)

label⚓︎

The text of the component. Not all component types have a label.

Returns:

  • result (string)

mouseOvers⚓︎

This array of UI elements will have an event handler registered to trigger "MCM:MouseOver" event. For more info, see registerMouseOverElements method.

Returns:

name⚓︎

The name field is the mod name, used to register the MCM, and is displayed in the mod list on the lefthand pane.

Returns:

  • result (string)

onClose⚓︎

A function which will be called when the menu is closed. Useful for saving your config after exiting the MCM.

Use template:saveOnClose(configFilename, configTable) to assign a simple save function to onClose. If you want to do more on closing, assign a custom function to onClose and call mwse.saveConfig(configFilename, configTable) when you want to save.

Returns:

onSearch⚓︎

A custom search handler function. This function should return true if this mod Template should show up in search results for given searchText.

Returns:

  • result (nil, fun(searchText: string): boolean)

paddingBottom⚓︎

The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.

Returns:

  • result (integer)

pages⚓︎

Pages in this Template.

Returns:

parentComponent⚓︎

Returns:

postCreate⚓︎

Custom formatting function to make adjustments to any element saved in self.elements.

Returns:

sCancel⚓︎

Set to the value of sCancel GMST.

Returns:

  • result (string)

searchChildDescriptions⚓︎

If true, when the user searches the MCM list, all the pages and settings in this MCM template will be searched over. The matching will be performed on setting description fields.

Returns:

  • result (boolean)

searchChildLabels⚓︎

If true, when the user searches the MCM list, all the pages and settings in this MCM template will be searched over. The matching will be performed on setting label and text fields.

Returns:

  • result (boolean)

sNo⚓︎

Set to the value of sNo GMST.

Returns:

  • result (string)

sOff⚓︎

Set to the value of sOff GMST.

Returns:

  • result (string)

sOK⚓︎

Set to the value of sOK GMST.

Returns:

  • result (string)

sOn⚓︎

Set to the value of sOn GMST.

Returns:

  • result (string)

sYes⚓︎

Set to the value of sYes GMST.

Returns:

  • result (string)

Methods⚓︎

checkDisabled⚓︎

Returns true if the component should be disabled.

Componets with a variable:

  • True if the Component's variable has inGameOnly field set to true, and the game is on the main menu. For components with multiple subcomponent (Category), the check is done for each subcomponent.

Components without a variable:

  • True if the Component's inGameOnly field is set to true, and the game is on the main menu.
local result = myObject:checkDisabled()

Returns:

  • result (boolean)

clickTab⚓︎

Destroys the currently display page and creates the given page as the new current page.

myObject:clickTab(thisPage)

Parameters:

create⚓︎

This method creates the UI elements that comprise a component. To call this method, the mwseMCMComponent-derived type needs to have createContentsContainer method implemented.

myObject:create(parentBlock)

Parameters:

createContentsContainer⚓︎

This method creates the UI elements specific to a Template.

myObject:createContentsContainer(parentBlock)

Parameters:

createExclusionsPage⚓︎

Creates a new Exclusions Page in this Template.

local page = myObject:createExclusionsPage({ showHeader = ..., label = ..., variable = ..., filters = ..., description = ..., toggleText = ..., leftListLabel  = ..., rightListLabel  = ..., showAllBlocked  = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ... })

Parameters:

  • data (table)
    • showHeader (boolean): Default: false. The page's label will only be created if set to true.
    • label (string): The label field is displayed in the tab for that page at the top of the menu. Defaults to: "Page {number}".
    • variable (mwseMCMVariable, mwseMCMSettingNewVariable): The Variable used to store blocked list entries.
    • filters (mwseMCMExclusionsPageFilter[]): A list of filters. Filters control which items will appear in the lists of the Exclusions Page. At least one filter is required. See the filter page for description.
    • description (string): Optional. Displayed at the top of the page above the lists.
    • toggleText (string): Optional. The text for the button that toggles filtered items from one list to another. The default is a localised version of "Toggle Filtered".
    • leftListLabel (string): Optional. The label on the left list. The default is a localised version of "Blocked".
    • rightListLabel (string): Optional. The label on the right list. The default is a localised version of "Allowed".
    • showAllBlocked (boolean): Default: false. When set to true, the left list shows all items in the blocked table, regardless of the filter being used.
    • indent (integer): Default: 6. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.

Returns:

createFilterPage⚓︎

Creates a new Filter Page in this Template.

local page = myObject:createFilterPage({ showHeader = ..., label = ..., noScroll = ..., description = ..., placeholderSearchText = ..., components = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ... })

Parameters:

  • data (table, string): Optional. If passing only a string, it will be used as the Filter Page's label.
    • showHeader (boolean): Default: false. The page's label will only be created if set to true.
    • label (string): Optional. The label field is displayed in the tab for that page at the top of the menu. Defaults to: "Page {number}".
    • noScroll (boolean): Default: false. When set to true, the page will not have a scrollbar. Particularly useful if you want to use a ParagraphField, which is not compatible with scroll panes.
    • description (string): Optional. Default sidebar text shown when the mouse isn't hovering over a component inside this Sidebar Page. It will be added to right column as a mwseMCMInfo.
    • placeholderSearchText (string): Default: Search.... The text shown in the search bar when no text is entered.
    • components (mwseMCMComponent.getComponent.componentData[]): Optional. Use this if you want to directly create all the nested components in this Page. This table is described at getComponent.
    • indent (integer): Default: 6. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMFilterPage)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

createInnerContainer⚓︎

Creates component's innerContainer UI element inside given parentBlock, and stores it in the self.elements.innerContainer. The innerContainer will add self.indent additional padding on the left if the component has a label.

myObject:createInnerContainer(parentBlock)

Parameters:

createLabel⚓︎

If a Template has headerImagePath defined, this method creates an image UI element from image at given path. If not, creates a label UI block with self.label text.

myObject:createLabel(parentBlock)

Parameters:

createLabelBlock⚓︎

Creates component's labelBlock UI element inside given parentBlock, and stores it in the self.elements.labelBlock and self.mouseOvers.

myObject:createLabelBlock(parentBlock)

Parameters:

createMouseOverPage⚓︎

Creates a new MouseOverPage in this Template.

local page = myObject:createMouseOverPage({ showHeader = ..., label = ..., noScroll = ..., components = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ... })

Parameters:

  • data (table): Optional.
    • showHeader (boolean): Default: false. The page's label will only be created if set to true.
    • label (string): Optional. The page label.
    • noScroll (boolean): Default: true. When set to true, the page will not have a scrollbar. Particularly useful if you want to use a ParagraphField, which is not compatible with scroll panes.
    • components (mwseMCMComponent.getComponent.componentData[]): Optional. Use this if you want to directly create all the nested components in this Page. This table is described at getComponent.
    • indent (integer): Default: 6. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMMouseOverPage)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

createOuterContainer⚓︎

Creates component's outerContainer UI element inside given parentBlock, and stores it in the self.elements.outerContainer and self.mouseOvers. The outerContainer holds all the other UI elements that comprise a component.

myObject:createOuterContainer(parentBlock)

Parameters:

createPage⚓︎

Creates a new Page in this Template.

local page = myObject:createPage({ showHeader = ..., label = ..., noScroll = ..., components = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ... })

Parameters:

  • data (table, string): Optional. If passing only a string, it will be used as the Page's label.
    • showHeader (boolean): Default: false. The page's label will only be created if set to true.
    • label (string): Optional. The label field is displayed in the tab for that page at the top of the menu. Defaults to: "Page {number}".
    • noScroll (boolean): Default: false. When set to true, the page will not have a scrollbar. Particularly useful if you want to use a ParagraphField, which is not compatible with scroll panes.
    • components (mwseMCMComponent.getComponent.componentData[]): Optional. Use this if you want to directly create all the nested components in this Page. This table is described at getComponent.
    • indent (integer): Default: 6. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMPage)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

createSideBarPage⚓︎

Creates a new Sidebar Page in this Template.

local page = myObject:createSideBarPage({ showHeader = ..., label = ..., noScroll = ..., description = ..., components = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ... })

Parameters:

  • data (table, string): Optional. If passing only a string, it will be used as the Sidebar Page's label.
    • showHeader (boolean): Default: false. The page's label will only be created if set to true.
    • label (string): Optional. The label field is displayed in the tab for that page at the top of the menu. Defaults to: "Page {number}".
    • noScroll (boolean): Default: false. When set to true, the page will not have a scrollbar. Particularly useful if you want to use a ParagraphField, which is not compatible with scroll panes.
    • description (string): Optional. Default sidebar text shown when the mouse isn't hovering over a component inside this Sidebar Page. It will be added to right column as a mwseMCMInfo.
    • components (mwseMCMComponent.getComponent.componentData[]): Optional. Use this if you want to directly create all the nested components in this Page. This table is described at getComponent.
    • indent (integer): Default: 6. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMSideBarPage)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.

Returns:

createSubcomponentsContainer⚓︎

This method creates the pageBlock UI element and the first page of the Template.

myObject:createSubcomponentsContainer(parentBlock)

Parameters:

createTab⚓︎

This method creates a button for given page in the tabsBlock UI elements of the Template. The button has an event handler registered on tes3.uiEvent.mouseClick that calls self:clickTab(page).

myObject:createTab(page)

Parameters:

createTabsBlock⚓︎

This method creates the outerTabsBlock, previousTabButton, tabsBlock and nextTabButton UI elements of the Template. The page tabs aren't created if the Template contains only one page.

myObject:createTabsBlock(parentBlock)

Parameters:

disable⚓︎

This method disables the component's UI elements. That includes: changing the color of the UI elements to the tes3.palette.disabledColor and setting button widget state to tes3.uiState.disabled.

myObject:disable()

enable⚓︎

Enables the component's UI elements. That includes: changing the color of the UI elements to the tes3.palette.normalColor and registering handlers for tes3.uiEvent.mouseClick for buttons.

myObject:enable()

getComponent⚓︎

Creates a new Component of given class or returns the given Component.

local component = myObject:getComponent({ class = ..., label = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ..., parentComponent = ... })

Parameters:

  • componentData (mwseMCMComponent, table)
    • class (string): The component type to get. On of the following:
      • "Template"
      • "ExclusionsPage"
      • "FilterPage"
      • "MouseOverPage"
      • "Page"
      • "SideBarPage"
      • "Category"
      • "SideBySideBlock"
      • "ActiveInfo"
      • "Hyperlink"
      • "Info"
      • "MouseOverInfo"
      • "Setting"
      • "Button"
      • "OnOffButton"
      • "YesNoButton"
      • "CycleButton"
      • "KeyBinder"
      • "Dropdown"
      • "TextField"
      • "ParagraphField"
      • "Slider"
      • "DecimalSlider"
      • "PercentageSlider"
    • label (string): Optional. The label text to set for the new component. Not all component types have a label.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMComponent)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.
    • parentComponent (mwseMCMComponent): Optional.

Returns:

new⚓︎

Creates a new Template.

local template = myObject:new({ name = ..., label = ..., headerImagePath = ..., onClose = ..., searchChildLabels = ..., searchChildDescriptions = ..., onSearch = ..., pages = ..., indent = ..., childIndent = ..., paddingBottom = ..., childSpacing = ..., inGameOnly = ..., postCreate = ..., class = ..., parentComponent = ... })

Parameters:

  • data (table)
    • name (string): Optional. The name field is the mod name, used to register the MCM, and is displayed in the mod list on the lefthand pane.
    • label (string): Optional. Used in place of name if that argument isn't passed. You need to pass at least one of the name and label arguments. If headerImagePath is not passed, a UI element will be created with label as text.
    • headerImagePath (string): Optional. Set it to display an image at the top of your menu. Path is relative to Data Files/. The image must have power-of-2 dimensions (i.e. 16, 32, 64, 128, 256, 512, 1024, etc.).
    • onClose (fun(modConfigContainer: tes3uiElement)): Optional. Set this to a function which will be called when the menu is closed. Useful for saving variables, such as TableVariable.
    • searchChildLabels (boolean): Default: true. If true, default search handler will search through all the page and setting label and text fields in this MCM template.
    • searchChildDescriptions (boolean): Default: true. If true, default search handler will search through all the page and setting description fields in this MCM template.
    • onSearch (fun(searchText: string): boolean): Optional. A custom search handler function. This function should return true if this mod Template should show up in search results for given searchText.
    • pages (mwseMCMPage.new.data[]): Optional. You can create pages for the template directly here. The entries in the array must specify the class of the page.
    • indent (integer): Default: 12. The left padding size in pixels. Only used if the childIndent isn't set on the parent component.
    • childIndent (integer): Optional. The left padding size in pixels. Used on all the child components.
    • paddingBottom (integer): Default: 4. The bottom border size in pixels. Only used if the childSpacing is unset on the parent component.
    • childSpacing (integer): Optional. The bottom border size in pixels. Used on all the child components.
    • inGameOnly (boolean): Default: false.
    • postCreate (fun(self: mwseMCMTemplate)): Optional. Can define a custom formatting function to make adjustments to any element saved in self.elements.
    • class (string): Optional.
    • parentComponent (mwseMCMComponent): Optional.

Returns:

onSearchInternal⚓︎

Performs searching routine for given searchText.

local result = myObject:onSearchInternal(searchText)

Parameters:

  • searchText (string)

Returns:

  • result (boolean): True if given searchText matches this MCM template.

prepareData⚓︎

Prepares the provided parameters table and sets the parentComponent field to mwseMCMComponent.

local data = myObject:prepareData(data)

Parameters:

  • data (string, mwseMCMComponent.new.data): Optional.

Returns:

  • data (mwseMCMComponent.new.data)

printComponent⚓︎

Prints the component table to the mwse.log. If a component is passed, it will be printed. If called without arguments, the component it was called on will be printed.

myObject:printComponent(component)

Parameters:

  • component (table): Default: self.

register⚓︎

A convenience function that registers the mod's configuration menu using its Template. In addition, sets self:onSearchInternal as the onSearch handler.

You don't need to call mwse.registerModConfig or mwse.mcm.register if calling this function.

myObject:register()

registerMouseOverElements⚓︎

Registers an event handler on each given UI element for the tes3.uiEvent.mouseOver and tes3.uiEvent.mouseLeave that will trigger "MCM:MouseOver" event. That event is used by the MCM to update the sidebar on the mwseMCMSideBarPage.

myObject:registerMouseOverElements(mouseOverList)

Parameters:

  • mouseOverList (tes3uiElement[]): Optional. If this argument isn't passed, does nothing.

saveOnClose⚓︎

This method assigns a new function to onClose field that calls mwse.saveConfig with given parameters.

myObject:saveOnClose(fileName, config)

Parameters:

  • fileName (string)
  • config (unknown)

setCustomSearchHandler⚓︎

This method assigns a custom search handler for the Template. This function should return true if this mod should show up in search results for given searchText.

myObject:setCustomSearchHandler(callback)

Parameters:

  • callback (nil, fun(searchText: string): boolean)