Attract-Mode Frontend

Overview

The Attract-mode layout sets out what gets displayed to the user. Layouts consist of a layout.nut script file and a collection of related resources (images, other scripts, etc.) used by the script.

Layouts are stored under the "layouts" subdirectory of the Attract-Mode config directory. Each layout is stored in its own separate subdirectory or archive file (Attract-Mode can read layouts and plugins directly from .zip, .7z, .rar, .tar.gz, .tar.bz2 and .tar files).

Each layout can have one or more layout*.nut script files. The "Toggle Layout" command in Attract-Mode allows users to cycle between each of the layout*.nut script files located in the layout's directory. Attract-Mode remembers the last layout file toggled to for each layout and will go back to that same file the next time the layout is loaded. This allows for variations of a particular layout to be implemented and easily selected by the user (for example, a layout could provide a layout.nut for horizontal monitor orientations and a layout-vert.nut for vertical).

The Attract-Mode screen saver and intro modes are really just special case layouts. The screensaver gets loaded after a user-configured period of inactivity, while the intro mode gets run when the frontend first starts and exits as soon as any action is triggered (for example if the user hits the select button). The screen saver script is located in the screensaver.nut file stored in the "screensaver" subdirectory. The intro script is located in the intro.nut file stored in the "intro" subdirectory.

Plug-ins are similar to layouts in that they consist of at least one squirrel script file and a collection of related resources. Plug-ins are stored in the "plugins" subdirectory of the Attract-Mode config directory. Plug-ins can be a single ".nut" file stored in this subdirectory. They can also have their own separate subdirectory or archive file (in which case the script itself needs to be in a file called plugin.nut).

Squirrel Language

Attract-Mode's layouts are scripts written in the Squirrel programming language. Squirrel's standard "Blob", "IO", "Math", "String" and "System" library functions are available for use in a script. For more information on programming in Squirrel and using its standard libraries, consult the Squirrel manuals:

Language Extensions

Attract-Mode includes the following home-brewed extensions to the squirrel language and standard libraries:

• A zip_extract_archive( zipfile, filename ) function that will open a specified zipfile archive file and extract filename from it, returning the contents as a squirrel blob.
• A zip_get_dir( zipfile ) function that will return an array of the filenames contained in the zipfile archive file.

Supported archive formats are: .zip, .7z, .rar, .tar.gz, .tar.bz2 and .tar

Frontend Binding

All of the functions, objects and classes that Attract-Mode exposes to Squirrel are arranged under the fe table, which is bound to Squirrel's root table.

Example:

    fe.layout.base_rotation = RotateScreen.Right;
    fe.add_image( "bg.png", 0, 0 );
    local marquee = fe.add_artwork( "marquee", 256, 20, 512, 256 );
    marquee.set_rgb( 100, 100, 100 );

The remainder of this document describes the functions, objects, classes and constants that are exposed to layout and plug-in scripts.

Magic Tokens

Image names, as well as the messages displayed by Text and Listbox objects, can all contain one or more "Magic Tokens". Magic tokens are enclosed in square brackets, and the frontend automatically updates them accordingly as the user navigates the frontend. So for example, a Text message set to "[Manufacturer]" will be automatically updated with the appropriate Manufacturer's name. There are more examples below.

• The following magic tokens are currently supported:
  • [DisplayName] - the name of the current display
  • [ListSize] - the number of items in the game list
  • [ListEntry] - the number of the current selection in the game list
  • [FilterName] - the name of the filter
  • [Search] - the search rule currently applied to the game list
  • [SortName] - the attribute that the list was sorted by
  • [Name] - the short name of the selected game
  • [Title] - the full name of the selected game
  • [Emulator] - the emulator to use for the selected game
  • [CloneOf] - the short name of the game that the selection is a clone of
  • [Year] - the year for the selected game
  • [Manufacturer] - the manufacturer for the selected game
  • [Category] - the category for the selected game
  • [Players] - the number of players for the selected game
  • [Rotation] - the rotation for the selected game
  • [Control] - the primary control for the selected game
  • [Status] - the emulation status for the selected game
  • [DisplayCount] - the number of displays for the selected game
  • [DisplayType] - the display type for the selected game
  • [AltRomname] - the alternative Romname for the selected game
  • [AltTitle] - the alternative title for the selected game
  • [PlayedTime] - the amount of time the selected game has been played
  • [PlayedCount] - the number of times the selected game has been played
  • [SortValue] - the value used to order the selected game in the list
  • [System] - the first "System" name configured for the selected game's emulator
  • [SystemN] - the last "System" name configured for the selected game's emulator
• Magic tokens can also be used to run a function defined in your layout or plugin's squirrel script to obtain the desired text. These tokens are in the form [!<function_name>]. When used, Attract-Mode will run the corresponding function (defined in the squirrel "root table"). This function should then return the string value that you wish to have replace the magic token. The function defined in squirrel can optionally have up to two parameters passed to it. If it is defined with a first parameter, Attract-Mode will supply the appropriate indexoffset in that parameter when it calls the function. If a second parameter is present as well, the appropriate filteroffset is supplied.

Examples:

    // Add a text that displays the filter name and list location
    //
    fe.add_text( "[FilterName] [[ListEntry]/[ListSize]]",
            0, 0, 400, 20 );

    // Add an image that will match to the first word in the
    // Manufacturer name (i.e. "Atari.png", "Nintendo.jpg")
    //
    function strip_man( ioffset )
    {
        local m = fe.game_info(Info.Manufacturer,ioffset);
        return split( m, " " )[0];
    }
    fe.add_image( "[!strip_man]", 0, 0 );

    // Add a text that will display a copyright message if both
    // the manufacturer name and a year are present.  Otherwise,
    // just show the Manufactuer name.
    //
    function well_formatted()
    {
        local m = fe.game_info( Info.Manufacturer );
        local y = fe.game_info( Info.Year );

        if (( m.len() > 0 ) && ( y.len() > 0 ))
            return "Copyright " + y + ", " + m;

        return m;
    }
    fe.add_text( "[!well_formatted]", 0, 0 );

Functions

fe.add_image()

fe.add_image( name )
fe.add_image( name, x, y )
fe.add_image( name, x, y, w, h )

Adds an image or video to the end of Attract-Mode's draw list.

fe.add_artwork()

fe.add_artwork( label )
fe.add_artwork( label, x, y )
fe.add_artwork( label, x, y, w, h )

Add an artwork to the end of Attract-Mode's draw list. The image/video displayed in an artwork is updated automatically whenever the user changes the game selection.

Parameters:

• label - the label of the artwork to display. This should correspond to an artwork configured in Attract-Mode (artworks are configured per emulator in the config menu) or scraped using the scraper. Attract- Mode's standard artwork labels are: "snap", "marquee", "flyer", "wheel", and "fanart".
• x - the x coordinate of the top left corner of the artwork (in layout coordinates).
• y - the y coordinate of the top left corner of the artwork (in layout coordinates).
• w - the width of the artwork (in layout coordinates). Artworks will be scaled accordingly. If set to 0 artwork is left unscaled. Default value is 0.
• h - the height of the artwork (in layout coordinates). Artworks will be scaled accordingly. If set to 0 artwork is left unscaled. Default value is 0.

Return Value:

fe.add_surface()

fe.add_surface( w, h )

Add a surface to the end of Attract-Mode's draw list. A surface is an off- screen texture upon which you can draw other image, artwork, text, listbox and surface objects. The resulting texture is treated as a static image by Attract-Mode which can in turn have image effects applied to it (scale, position, pinch, skew, shaders, etc) when it is drawn.

Parameters:

• w - the width of the surface texture (in pixels).
• h - the height of the surface texture (in pixels).

Return Value:

fe.add_clone()

fe.add_clone( img )

Clone an image, artwork or surface object and add the clone to the back of Attract-Mode's draw list. The texture pixel data of the original and clone is shared as a result.

Parameters:

• img - the image, artwork or surface object to clone. This needs to be an instance of the class fe.Image.

Return Value:

fe.add_text()

fe.add_text( msg, x, y, w, h )

Add a text label to the end of Attract-Mode's draw list.

fe.add_listbox()

fe.add_listbox( x, y, w, h )

Add a listbox to the end of Attract-Mode's draw list.

Parameters:

• x - the x coordinate of the top left corner of the listbox (in layout coordinates).
• y - the y coordinate of the top left corner of the listbox (in layout coordinates).
• w - the width of the listbox (in layout coordinates).
• h - the height of the listbox (in layout coordinates).

Return Value:

fe.add_shader()

fe.add_shader( type, file1, file2 )
fe.add_shader( type, file1 )
fe.add_shader( type )

Add a GLSL shader (vertex and/or fragment) for use in the layout.

Parameters:

• type - the type of shader to add. Can be one of the following values:

  • Shader.VertexAndFragment - add a combined vertex and fragment shader
  • Shader.Vertex - add a vertex shader
  • Shader.Fragment - add a fragment shader
  • Shader.Empty - add an empty shader. An object's shader property can be set to an empty shader to stop using a shader on that object where one was set previously.

• file1 - the name of the shader file located in the layout/plugin directory. For the VertexAndFragment type, this should be the vertex shader.

• file2 - This parameter is only used with the VertexAndFragment type, and should be the name of the fragment shader file located in the layout/ plugin directory.

Return Value:

fe.add_sound()

fe.add_sound( name, reuse )
fe.add_sound( name )

Add an audio file that can then be played by Attract-Mode.

Parameters:

• name - the name of the audio file. If a relative path is provided, it is treated as relative to the directory for the layout/plugin that called this function.
• reuse - [bool] if set to true, reuse any previously added sound that has the same name. Default value is true.

Return Value:

fe.add_ticks_callback()

fe.add_ticks_callback( environment, function_name )
fe.add_ticks_callback( function_name )

Register a function in your script to get "tick" callbacks. Tick callbacks occur continuously during the running of the frontend. The function that is registered should be in the following form:

function tick( tick_time )
{
   // do stuff...
}

The single parameter passed to the tick function is the amount of time (in milliseconds) since the layout began.

Parameters:

• environment - the squirrel object that the function is associated with (default value: the root table of the squirrel vm)
• function_name - a string naming the function to be called.

Return Value:

• None.

fe.add_transition_callback()

fe.add_transition_callback( environment, function_name )
fe.add_transition_callback( function_name )

Register a function in your script to get transition callbacks. Transition callbacks are triggered by certain events in the frontend. The function that is registered should be in the following form:

function transition( ttype, var, transition_time )
{
   local redraw_needed = false;

   // do stuff...

   if ( redraw_needed )
      return true;

   return false;
}

The ttype parameter passed to the transition function indicates what is happening. It will have one of the following values:

• Transition.StartLayout
• Transition.EndLayout
• Transition.ToNewSelection
• Transition.FromOldSelection
• Transition.ToGame
• Transition.FromGame
• Transition.ToNewList
• Transition.EndNavigation
• Transition.ShowOverlay
• Transition.HideOverlay
• Transition.NewSelOverlay

The value of the var parameter passed to the transition function depends upon the value of ttype:

• When ttype is Transition.ToNewSelection, var indicates the index offset of the selection being transitioned to (i.e. -1 when moving back one position in the list, 1 when moving forward one position, 2 when moving forward two positions, etc.)

• When ttype is Transition.FromOldSelection, var indicates the index offset of the selection being transitioned from (i.e. 1 after moving back one position in the list, -1 after moving forward one position, -2 after moving forward two positions, etc.)

• When ttype is Transition.StartLayout, var will be one of the following:

  • FromTo.Frontend if the frontend is just starting,
  • FromTo.ScreenSaver if the layout is starting (or the list is being loaded) because the built-in screen saver has stopped, or
  • FromTo.NoValue otherwise.

• When ttype is Transition.EndLayout, var will be:

  • FromTo.Frontend if the frontend is shutting down,
  • FromTo.ScreenSaver if the layout is stopping because the built-in screen saver is starting, or
  • FromTo.NoValue otherwise.

• When ttype is Transition.ToNewList, var indicates the filter index offset of the filter being transitioned to (i.e. -1 when moving back one filter, 1 when moving forward) if known, otherwise var is 0.

• When ttype is Transition.ShowOverlay, var will be:

  • Overlay.Custom if a script generated overlay is being shown
  • Overlay.Exit if the exit menu is being shown
  • Overlay.Displays if the displays menu is being shown
  • Overlay.Filters if the filters menu is being shown
  • Overlay.Tags if the tags menu is being shown

• When ttype is Transition.NewSelOverlay, var will be the index of the new selection in the Overlay menu.

• When ttype is Transition.ToGame, Transition.FromGame, Transition.EndNavigation, or Transition.HideOverlay, var will be FromTo.NoValue.

The transition_time parameter passed to the transition function is the amount of time (in milliseconds) since the transition began.

The transition function must return a boolean value. It should return true if a redraw is required, in which case Attract-Mode will redraw the screen and immediately call the transition function again with an updated transition_time.

The transition function must eventually return false to notify Attract-Mode that the transition effect is done, allowing the normal operation of the frontend to proceed.

Parameters:

• environment - the squirrel object that the function is associated with (default value: the root table of the squirrel vm)
• function_name - a string naming the function to be called.

Return Value:

• None.

fe.game_info()

fe.game_info( id )
fe.game_info( id, index_offset )
fe.game_info( id, index_offset, filter_offset )

Get information about the selected game.

Parameters:

• id - id of the information attribute to get. Can be one of the following values:
  • Info.Name
  • Info.Title
  • Info.Emulator
  • Info.CloneOf
  • Info.Year
  • Info.Manufacturer
  • Info.Category
  • Info.Players
  • Info.Rotation
  • Info.Control
  • Info.Status
  • Info.DisplayCount
  • Info.DisplayType
  • Info.AltRomname
  • Info.AltTitle
  • Info.Extra
  • Info.Favourite
  • Info.Tags
  • Info.PlayedCount
  • Info.PlayedTime
  • Info.FileIsAvailable
  • Info.System
• index_offset - the offset (from the current selection) of the game to retrieve info on. i.e. -1=previous game, 0=current game, 1=next game... and so on. Default value is 0.
• filter_offset - the offset (from the current filter) of the filter containing the selection to retrieve info on. i.e. -1=previous filter, 0=current filter. Default value is 0.

Return Value:

• A string containing the requested information.

fe.get_art()

fe.get_art( label )
fe.get_art( label, index_offset )
fe.get_art( label, index_offset, filter_offset )
fe.get_art( label, index_offset, filter_offset, flags )

Get the filename of an artwork for the selected game. If multiple files are matched, one is chosen randomly and returned.

Parameters:

• label - the label of the artwork to retrieve. This should correspond to an artwork configured in Attract-Mode (artworks are configured per emulator in the config menu) or scraped using the scraper. Attract- Mode's standard artwork labels are: "snap", "marquee", "flyer", "wheel", and "fanart".
• index_offset - the offset (from the current selection) of the game to retrieve the filename for. i.e. -1=previous game, 0=current game, 1=next game... and so on. Default value is 0.
• filter_offset - the offset (from the current filter) of the filter containing the selection to retrieve the filename for. i.e. -1=previous filter, 0=current filter. Default value is 0.
• flags - flags to control the filename that gets returned. Can be set to either of the following:
  • Art.Default
  • Art.ImageOnly (only return an image match, no videos)

Return Value:

• A string containing the filename of the requested artwork. If no file is found, an empty string is returned. If the artwork is contained in an archive, then both the archive path and the internal path are returned, separated by a pipe | character: "|"

fe.get_input_state()

fe.get_input_state( input_id )

Check if a specific keyboard key, mouse button, joystick button or joystick direction is currently pressed, or check if any input mapped to a particular frontend action is pressed.

Parameter:

• input_id - [string] the input to test. This can be a string in the same format as used in the attract.cfg file for input mappings. For example, "LControl" will check the left control key, "Joy0 Up" will check the up direction on the first joystick, "Mouse MiddleButton" will check the middle mouse button, and "select" will check for any input mapped to the game select button...

  Note that mouse moves and mouse wheel movements are not available through this function.

Return Value:

• true if input is pressed, false otherwise.

fe.get_input_pos()

fe.get_input_pos( input_id )

Return the current position for the specified joystick axis.

Parameter:

• input_id - [string] the input to test. The format of this string is the same as that used in the attract.cfg file. For example, "Joy0 Up" is the up direction on the first joystick.

Return Value:

• Current position of the specified axis, in range [0..100].

fe.signal()

fe.signal( signal_str )

Signal that a particular frontend action should occur.

Parameters:

• signalstr - the action to signal for. Can be one of the following strings:
  • "select"
  • "up"
  • "down"
  • "pageup"
  • "pagedown"
  • "prevlist"
  • "nextlist"
  • "displaysmenu"
  • "prevfilter"
  • "nextfilter"
  • "filtersmenu"
  • "togglelayout"
  • "togglemovie"
  • "togglemute"
  • "togglerotateright"
  • "toggleflip"
  • "togglerotateleft"
  • "exit"
  • "exitnomenu"
  • "screenshot"
  • "configure"
  • "randomgame"
  • "replaylastgame"
  • "addfavourite"
  • "prevfavourite"
  • "nextfavourite"
  • "addtags"
  • "screensaver"
  • "prevletter"
  • "nextletter"
  • "intro"
  • "custom1"
  • "custom2"
  • "custom3"
  • "custom4"
  • "custom5"
  • "custom6"
  • "resetwindow"
  • "reload"

Return Value:

• None.

fe.set_display()

fe.set_display( index )

Change to the display at the specified index. This should align with the index of the fe.displays array that contains the intended display.

NOTE that changing the display causes all layout and plugin scripts to reload.

Parameters:

• index - The index of the display to change to. This should correspond to the index in the fe.displays array of the intended new display. The index for the current display is stored in fe.list.display_index.

Return Value:

• None.

fe.add_signal_handler()

fe.add_signal_handler( environment, function_name )
fe.add_signal_handler( function_name )

fe.remove_signal_handler()

fe.remove_signal_handler( environment, function_name )
fe.remove_signal_handler( function_name )

fe.do_nut()

fe.do_nut( name )

Execute another Squirrel script.

Parameters:

• name - the name of the script file. If a relative path is provided, it is treated as relative to the directory for the layout/plugin that called this function.

Return Value:

• None.

fe.load_module()

fe.load_module( name )

Loads a module (a "library" Squirrel script).

Parameters:

• name - the name of the library module to load. This should correspond to a script file in the "modules" subdirectory of your Attract-Mode configuration (without the file extension).

Return Value:

• true if the module was loaded, `false' if it was not found.

fe.plugin_command()

fe.plugin_command( executable, arg_string )
fe.plugin_command( executable, arg_string, environment, callback_function )
fe.plugin_command( executable, arg_string, callback_function )

Execute a plug-in command and wait until the command is done.

Parameters:

• executable - the name of the executable to run.
• arg_string - the arguments to pass when running the executable.
• environment - the squirrel object that the callback function is associated with.

• callback_function - a string containing the name of the function in Squirrel to call with any output that the executable provides on stdout. The function should be in the following form:

  function callback_function( op )
  {
  }
  

  If provided, this function will be called with each output line in op.

Return Value:

• None.

fe.plugin_command_bg()

fe.plugin_command_bg( executable, arg_string )

Execute a plug-in command in the background and return immediately.

Parameters:

• executable - the name of the executable to run.
• arg_string - the arguments to pass when running the executable.

Return Value:

• None.

fe.path_expand()

fe.path_expand( path )

Expand the given path name. A leading ~ or $HOME token will be become the user's home directory. On Windows systems, a leading %SYSTEMROOT% token will become the path to the Windows directory and a leading %PROGRAMFILES% will become the path to the "Program Files" directory.

Parameters:

• path - the path string to expand.

Return Value:

• The expansion of path.

fe.get_config()

Get the user configured settings for this layout/plugin/screensaver/intro.

NOTE this function will not return valid settings when called from a callback function registered with fe.addtickscallback(), fe.addtransitioncallback() or fe.addsignalhandler()

Parameters:

• None.

Return Value:

• A table containing each of the applicable user configured settings. A layout or plug-in can signal its user configured settings to Attract-Mode by defining a class named "UserConfig" at the very start of the script. In the case a layouts, the "UserConfig" class must be located in a file named 'layout.nut' in the layout directory.

  For an example, please see one of the plug-ins included with Attract- Mode or the "Attrac-Man" layout.

Objects and Variables

fe.ambient_sound

fe.ambient_sound is an instance of the fe.Sound class and can be used to control the ambient sound track.

fe.layout

fe.layout is an instance of the fe.LayoutGlobals class and is where global layout settings are stored.

fe.list

fe.list is an instance of the fe.CurrentList class and is where current display settings are stored.

fe.overlay

fe.overlay is an instance of the fe.Overlay class and is where overlay functionality may be accessed.

fe.obj

fe.obj contains the Attract-Mode draw list. It is an array of fe.Image, fe.Text and fe.ListBox instances.

fe.displays

fe.displays contains information on the available displays. It is an array of fe.Display instances.

fe.filters

fe.filters contains information on the available filters. It is an array of fe.Filter instances.

fe.monitors

fe.monitors is an array of fe.Monitor instances, and provides the mechanism for interacting with the various monitors in a multi-monitor setup. There will always be at least one entry in this list, and the first entry will always be the "primary" monitor.

fe.script_dir

When Attract-Mode runs a layout or plug-in script, fe.script_dir is set to the layout or plug-in's directory.

fe.script_file

When Attract-Mode runs a layout or plug-in script, fe.script_file is set to the name of the layout or plug-in script file.

fe.nv

The fe.nv table can be used by layouts and plugins to store persistent values. The values in this table get saved by Attract-Mode whenever the layout changes and are saved to disk when Attract-Mode is shut down. Boolean, integer, float, string, array and table values can be stored in this table.

Classes

fe.LayoutGlobals

This class is a container for global layout settings. The instance of this class is the fe.layout object. This class cannot be otherwise instantiated in a script.

Properties:

• width - Get/set the layout width. Default value is ScreenWidth.
• height - Get/set the layout height. Default value is ScreenHeight.
• font - Get/set the layout font name. Default value is the default font configured for Attract-Mode.
• base_rotation - Get/set the base (i.e the default) orientation of the layout. This can be one of the following values:
  • RotateScreen.None (default)
  • RotateScreen.Right
  • RotateScreen.Flip
  • RotateScreen.Left
• toggle_rotation - Get/set the "toggle" orientation of the layout. The toggle rotation is added to the base_rotation to determine what the actual rotation is at any given time. The user can change this value using the Rotation Toggle inputs. This can be one of the following values:
  • RotateScreen.None (default)
  • RotateScreen.Right
  • RotateScreen.Flip
  • RotateScreen.Left
• page_size - Get/set the number of entries to jump each time the "Page Up" or "Page Down" button is pressed.
• preserve_aspect_ratio - Get/set whether the overall layout aspect ratio should be preserved by the frontend. Default value is false.
• time - Get the number of millseconds that the layout has been showing.

Notes:

• The actual rotation of the layout can be determined using the following equation: ( fe.layout.base_rotation + fe.layout.toggle_rotation ) % 4

fe.CurrentList

This class is a container for status information regarding the current display. The instance of this class is the fe.list object. This class cannot be otherwise instantiated in a script.

Properties:

• name - Get the name of the current display.
• display_index - Gett the index of the current display. Use the fe.set_display() function if you want to change the current display.
• filter_index - Get/set the index of the currently selected filter. (see fe.filters for the list of available filters).
• index - Get/set the index of the currently selected game.
• search_rule - Get/set the search rule applied to the current game list. If you set this and the resulting search finds no results, then the current game list remains displayed in its entirety. If there are results, then those results are shown instead, until search_rule is cleared or the user navigates away from the display/filter.
• size - Get the size of the current game list. If a search rule has been applied, this will be the number of matches found (if > 0)

fe.Overlay

This class is a container for overlay functionality. The instance of this class is the fe.overlay object. This class cannot be otherwise instantiated in a script.

Properties:

• is_up - Get whether the overlay is currently being displayed (i.e. config mode, etc).

Member Functions:

• set_custom_controls( caption_text, options_listbox )
• set_custom_controls( caption_text )
• set_custom_controls() - tells the frontend that the layout will provide custom controls for displaying overlay menus such as the exit dialog, displays menu, etc. The caption_text parameter is the FeText object that the frontend end should use to display the overlay caption (i.e. "Exit Attract-Mode?"). The options_listbox parameter is the FeListBox object that the frontend should use to display the overlay options.
• clear_custom_controls() - tell the frontend that the layout will NOT do any custom control handling for overlay menus. This will result in the frontend using its built-in default menus instead for overlays.
• list_dialog( options, title, default_sel, cancel_sel )
• list_dialog( options, title, default_sel )
• list_dialog( options, title )
• list_dialog( options ) - The list_dialog function prompts the user with a menu containing a list of options, returning the index of the selection. The options parameter is an array of strings that are the menu options to display in the list. The title parameter is a caption for the list. default_sel is the index of the entry to be selected initially (default is 0). cancel_sel is the index to return if the user cancels (default is -1). The return value is the index selected by the user.
• edit_dialog( msg, text ) - Prompt the user to input/edit text. The msg parameter is the prompt caption. text is the initial text to be edited. The return value a the string of text as edited by the user.
• splash_message( msg, second_msg="" ) - immediately provide text feedback to the user. This could be useful during computationally-intensive operations.

fe.Display

This class is a container for information about the available displays. Instances of this class are contained in the fe.displays array. This class cannot otherwise be instantiated in a script.

Properties:

• name - Get the name of the display.
• layout - Get the layout used by this display.
• romlist - Get the romlist used by this display.
• in_cycle - Get whether the display is shown in the prev display/next display cycle.
• in_menu - Get whether the display is shown in the "Displays Menu"

fe.Filter

This class is a container for information about the available filters. Instances of this class are contained in the fe.filters array. This class cannot otherwise be instantiated in a script.

Properties:

• name - Get the filter name.
• index - Get the index of the currently selected game in this filter.
• size - Get the size of the game list in this filter.
• sort_by - Get the attribute that the game list has been sorted by. Will be equal to one of the following values:
  • Info.NoSort
  • Info.Name
  • Info.Title
  • Info.Emulator
  • Info.CloneOf
  • Info.Year
  • Info.Manufacturer
  • Info.Category
  • Info.Players
  • Info.Rotation
  • Info.Control
  • Info.Status
  • Info.DisplayCount
  • Info.DisplayType
  • Info.AltRomname
  • Info.AltTitle
  • Info.Extra
  • Info.Favourite
  • Info.Tags
  • Info.PlayedCount
  • Info.PlayedTime
  • Info.FileIsAvailable
• reverse_order - [bool] Will be equal to true if the list order has been reversed.
• list_limit - Get the value of the list limit applied to the filter game list.

fe.Monitor

This class represents a monitor in Attract-Mode, and provides the interface to the extra monitors in a multi-monitor setup. Instances of this class are contained in the fe.monitors array. This class cannot otherwise be instantiated in a script.

Properties:

• num - Get the monitor number.
• width - Get the monitor width in pixels.
• height - Get the monitor height in pixels.

Member Functions:

fe.Image

The class representing an image in Attract-Mode. Instances of this class are returned by the add_image(), add_artwork(), add_surface and add_clone() functions and also appear in the fe.obj array (the Attract-Mode draw list). This class cannot be otherwise instantiated in a script.

Properties:

• Note that Attract-Mode defers the loading of artwork and dynamic images (images with Magic Tokens) until after all layout and plug-in scripts have completed running. This means that the texture_width, texture_height and file_name attributes are not available when a layout or plug-in script first adds the artwork/dynamic image resource. These attributes are available during transition callbacks, and in particular during the Transition.FromOldSelection and Transition.ToNewList transitions. Example:

```` squirrel local myart = fe.addartwork( "snap", 0, 0, 100, 100 );

fe.addtransitioncallback("artworktransition"); function artworktransition( ttype, var, ttime ) { if (( ttype == Transition.FromOldSelection ) || ( ttype == Transition.ToNewList )) { // // do stuff with myart's texturewidth or textureheight here... // // for example, flip the image vertically: myart.subimgheight = -1 * textureheight; myart.subimgy = texture_height; }

  return false;

}

````

• To flip an image vertically, set the subimg_height property to -1 * texture_height and subimg_y to texture_height.
• To flip an image horizontally, set the subimg_width property to -1 * texture_width and subimg_x to texture_width.

```` squirrel

// flip "img" vertically function flipy( img ) { img.subimgheight = -1 * img.textureheight; img.subimgy = img.texture_height; } ````

fe.Text

The class representing a text label in Attract-Mode. Instances of this class are returned by the add_text() functions and also appear in the fe.obj array (the Attract-Mode draw list). This class cannot be otherwise instantiated in a script.

fe.ListBox

The class representing the listbox in Attract-Mode. Instances of this class are returned by the add_listbox() functions and also appear in the fe.obj array (the Attract-Mode draw list). This class cannot be otherwise instantiated in a script.

Properties:

fe.Sound

The class representing an audio track. Instances of this class are returned by the fe.add_sound() function. This is also the class for the fe.ambient_sound object. Object of this class cannot be otherwise instantiated in a script.

Properties:

• file_name - Get/set the audio filename. If file_name is contained in an archive, this string should formatted: "|"
• playing - Get/set whether the track is currently playing (boolean).
• loop - Get/set whether the track should be looped (boolean).
• pitch - Get/set the audio pitch (float). Default value is 1.
• x - Get/set the x position of the sound. Default value is 0.
• y - Get/set the y position of the sound. Default value is 0.
• z - Get/set the z position of the sound. Default value is 0.
• duration - Get the audio track duration (in milliseconds).
• time - Get the time that the audio track is current at (in milliseconds).

Member Functions:

• get_metadata( tag ) - Get the meta data (if available in the source file) that corresponds to the specified tag (i.e. "artist", "album", etc.)
• load_from_archive( archive, filename ) - Load the sound from the specified archive file (.zip, etc).

fe.Shader

The class representing a GLSL shader. Instances of this class are returned by the fe.add_shader() function. This class cannot be otherwise instantiated in a script.

Properties:

• type - Get the shader type. Can be one of the following values:
  • Shader.VertexAndFragment
  • Shader.Vertex
  • Shader.Fragment
  • Shader.Empty

Member Functions:

• set_param( name, f ) - Set the float variable (float GLSL type) with the specified name to the value of f.
• set_param( name, f1, f2 ) - Set the 2-component vector variable (vec2 GLSL type) with the specified name to (f1,f2).
• set_param( name, f1, f2, f3 ) - Set the 3-component vector variable (vec3 GLSL type) with the specified name to (f1,f2,f3).
• set_param( name, f1, f2, f3, f4 ) - Set the 4-component vector variable (vec4 GLSL type) with the specified name to (f1,f2,f3,f4).
• set_texture_param( name ) - Set the texture variable (sampler2D GLSL type) with the specified name. The texture used will be the texture for whatever object (fe.Image, fe.Text, fe.Listbox) the shader is drawing.
• set_texture_param( name, image ) - Set the texture variable (sampler2D GLSL type) with the specified name to the texture contained in "image". "image" must be an instance of the fe.Image class.

Constants

FeVersion [string]

FeVersionNum [int]

The current Attract-Mode version.

FeConfigDirectory [string]

The path to Attract-Mode's config directory.

ScreenWidth [int]

ScreenHeight [int]

The screen width and height in pixels.

ScreenSaverActive [bool]

true if the screen saver is active, false otherwise.

IntroActive [bool]

true if the intro is active, false otherwise.

OS [string]

The Operating System that Attract-Mode is running under. Will be one of: "Windows", "OSX", "FreeBSD", "Linux" or "Unknown"

ShadersAvailable [bool]

true if GLSL shaders are available on this system, false otherwise.