sage.api
Class WidgetAPI

java.lang.Object
  sage.api.WidgetAPI

public class WidgetAPI
extends java.lang.Object

Widget reflection API

Method Summary

sage.Widget	AddWidget(java.lang.String WidgetType) Creates a new Widget of the specified type and adds it to the STV
void	AddWidgetChild(sage.Widget WidgetParent, sage.Widget WidgetChild) Creates a parent-child relationship between two Widgets.
sage.Widget	AddWidgetWithSymbol(java.lang.String WidgetType, java.lang.String Symbol) Creates a new Widget of the specified type and adds it to the STV.
java.lang.Object	EvaluateExpression(java.lang.String Expression) Evaluates the passed in expression and returns the result.
java.lang.Object	ExecuteWidgetChain(sage.Widget Widget) Executes a Widget and the chain of child Widgets underneath it
java.lang.Object	ExecuteWidgetChainInCurrentMenuContext(sage.Widget Widget) Executes a Widget and the chain of child Widgets underneath it.
sage.Widget	FindWidgetBySymbol(java.lang.String Symbol) Returns the Widget represented by the specified UID symbol
sage.Widget[]	GetAllWidgets() Gets all of the Widgets that are in the currently loaded STV
sage.Widget	GetCurrentMenuWidget() Gets the Widget the defines the menu that is currently loaded by the system
java.lang.String	GetCurrentSTVFile() Gets the STV file that is currently loaded by the system
java.io.File	GetDefaultSTVFile() Returns the file path for the default STV file
java.lang.String	GetSTVName() Returns the value of the 'STVName' Attribute under the Global Theme Widget.
java.lang.String	GetSTVVersion() Returns the value of the 'STVVersion' Attribute under the Global Theme Widget.
sage.Widget	GetUIWidgetContext() Returns the Widget for the corresponding UI component that this execution originated from.
sage.Widget	GetWidgetChild(sage.Widget Widget, java.lang.String Type, java.lang.String Name) Searches the children of the specified Widget for one with the specified type and name.
sage.Widget[]	GetWidgetChildren(sage.Widget Widget) Gets the list of Widgets that are children of the specified Widget.
sage.Widget[]	GetWidgetMenuBackHistory() Gets a list of the Widgets that have defined the menus that were recently displayed in the UI.
sage.Widget[]	GetWidgetMenuHistory() Gets a list of the Widgets that have defined the menus that were recently displayed in the UI
java.lang.String	GetWidgetName(sage.Widget Widget) Returns the name of the specified Widget
sage.Widget	GetWidgetParent(sage.Widget Widget, java.lang.String Type, java.lang.String Name) Searches the parents of the specified Widget for one with the specified type and name.
sage.Widget[]	GetWidgetParents(sage.Widget Widget) Gets the list of Widgets that are parents of the specified Widget.
java.lang.String	GetWidgetProperty(sage.Widget Widget, java.lang.String PropertyName) Returns the value for a specified property in a Widget
sage.Widget[]	GetWidgetsByType(java.lang.String WidgetType) Gets all of the Widgets that are in the currently loaded STV that are of the specified type
java.lang.String	GetWidgetSymbol(sage.Widget Widget) Returns the UID symbol for the specified Widget
java.lang.String	GetWidgetType(sage.Widget Widget) Returns the type of a Widget
boolean	HasWidgetProperty(sage.Widget Widget, java.lang.String PropertyName) Returns true if the specified Widget has a property defined with the specified name
java.lang.Object	ImportSTVFile(java.io.File STVFile) Imports a SageTV Application Definition file into the current STV file that is loaded.
void	InsertWidgetChild(sage.Widget WidgetParent, sage.Widget WidgetChild, int ChildIndex) Creates a parent-child relationship between two Widgets.
boolean	IsSTVModified() Returns true if the currently loaded STV has been modified at all since its last save
boolean	IsWidgetParentOf(sage.Widget WidgetParent, sage.Widget WidgetChild) Returns true if the specified Widgets have a parent-child relationship.
void	LaunchMenuWidget(sage.Widget Widget) Launches a new menu in SageTV with the specified Widget as the menu's definition.
java.lang.Object	LoadSTVFile(java.io.File STVFile) Loads a new SageTV Application Definition file that defines the entire user interface for SageTV
void	RemoveWidget(sage.Widget Widget) Removes a Widget from the STV
void	RemoveWidgetChild(sage.Widget WidgetParent, sage.Widget WidgetChild) Breaks a parent-child relationships between two Widgets.
boolean	SaveWidgetsAsXML(java.io.File File, boolean Overwrite) Saves all of the current Widgets as an XML file.
void	SetWidgetName(sage.Widget Widget, java.lang.String Name) Sets the name for a Widget
void	SetWidgetProperty(sage.Widget Widget, java.lang.String PropertyName, java.lang.String PropertyValue) Sets a property in a Widget to a specified value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

LoadSTVFile

public java.lang.Object LoadSTVFile(java.io.File STVFile)

Loads a new SageTV Application Definition file that defines the entire user interface for SageTV

Parameters:

STVFile - the new .stv file that should be loaded for the UI

Returns:

true if it was succesful, otherwise an error string

ImportSTVFile

public java.lang.Object ImportSTVFile(java.io.File STVFile)

Imports a SageTV Application Definition file into the current STV file that is loaded. This will essentially merge the two together.

Parameters:

STVFile - the .stv file that should be imported into the currently loaded one

Returns:

true if it was succesful, otherwise an error string

IsSTVModified

public boolean IsSTVModified()

Returns true if the currently loaded STV has been modified at all since its last save

Returns:

true if the currently loaded STV has been modified at all since its last save

Since:

6.1

GetAllWidgets

public sage.Widget[] GetAllWidgets()

Gets all of the Widgets that are in the currently loaded STV

Returns:

all of the Widgets that are in the currently loaded STV

GetWidgetsByType

public sage.Widget[] GetWidgetsByType(java.lang.String WidgetType)

Gets all of the Widgets that are in the currently loaded STV that are of the specified type

Returns:

all of the Widgets that are in the currently loaded STV that are of the specified type

AddWidget

public sage.Widget AddWidget(java.lang.String WidgetType)

Creates a new Widget of the specified type and adds it to the STV

Parameters:

WidgetType - the type of the new Widget

Returns:

the newly created Widget

AddWidgetWithSymbol

public sage.Widget AddWidgetWithSymbol(java.lang.String WidgetType,
                                       java.lang.String Symbol)

Creates a new Widget of the specified type and adds it to the STV. This also allows specifying the desired symbol to use for the Widget. If the symbol is already in use; then a new symbol will automatically be assigned to this Widget instead.

Parameters:

WidgetType - the type of the new Widget

Returns:

the newly created Widget

Since:

7.0

RemoveWidget

public void RemoveWidget(sage.Widget Widget)

Removes a Widget from the STV

Parameters:

Widget - the Widget (or a String which represents the symbol for that Widget) to remove

AddWidgetChild

public void AddWidgetChild(sage.Widget WidgetParent,
                           sage.Widget WidgetChild)

Creates a parent-child relationship between two Widgets. If the relationship already exists, this call has no effect. This new child will be the last child of the parent.

Parameters:

WidgetParent - the Widget (or a String which represents the symbol for that Widget) that should be the parent in the relationship

WidgetChild - the Widget (or a String which represents the symbol for that Widget) that should be the child in the relationship

InsertWidgetChild

public void InsertWidgetChild(sage.Widget WidgetParent,
                              sage.Widget WidgetChild,
                              int ChildIndex)

Creates a parent-child relationship between two Widgets. Since parent-child relationships are ordered, this allows specifying where in that order this relationship should be.

Parameters:

WidgetParent - the Widget (or a String which represents the symbol for that Widget) that should be the parent in the relationship

WidgetChild - the Widget (or a String which represents the symbol for that Widget) that should be the child in the relationship

ChildIndex - the 0-based index in the parent's child relationships list that the new relationship should occupy

RemoveWidgetChild

public void RemoveWidgetChild(sage.Widget WidgetParent,
                              sage.Widget WidgetChild)

Breaks a parent-child relationships between two Widgets. If the Widgets do not have the specified parent-child relationship then there is no effect.

Parameters:

WidgetParent - the parent of the Widget (or a String which represents the symbol for that Widget) relationship to break

WidgetChild - the child of the Widget (or a String which represents the symbol for that Widget) relationship to break

IsWidgetParentOf

public boolean IsWidgetParentOf(sage.Widget WidgetParent,
                                sage.Widget WidgetChild)

Returns true if the specified Widgets have a parent-child relationship.

Parameters:

WidgetParent - the parent Widget (or a String which represents the symbol for that Widget) to test

WidgetChild - the child Widget (or a String which represents the symbol for that Widget) to test

Returns:

true if the specified parent has a parent-child relationship with the specified child, false otherwise

GetWidgetType

public java.lang.String GetWidgetType(sage.Widget Widget)

Returns the type of a Widget

Parameters:

Widget - the Widget (or a String which represents the symbol for that Widget) object

Returns:

the type name of the specified Widget

HasWidgetProperty

public boolean HasWidgetProperty(sage.Widget Widget,
                                 java.lang.String PropertyName)

Returns true if the specified Widget has a property defined with the specified name

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

PropertyName - the name of the property to check existence of

Returns:

true if the specified Widget has a property defined with the specified name, false otherwise

SetWidgetProperty

public void SetWidgetProperty(sage.Widget Widget,
                              java.lang.String PropertyName,
                              java.lang.String PropertyValue)

Sets a property in a Widget to a specified value. If that property is already defined, this will overwrite it.

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

PropertyName - the name of the property to set in the Widget

PropertyValue - the value to set the property to

GetWidgetProperty

public java.lang.String GetWidgetProperty(sage.Widget Widget,
                                          java.lang.String PropertyName)

Returns the value for a specified property in a Widget

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

PropertyName - the name of the property to get

Returns:

the value for a specified property in a Widget

GetWidgetName

public java.lang.String GetWidgetName(sage.Widget Widget)

Returns the name of the specified Widget

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

Returns:

the name of the specified Widget

SetWidgetName

public void SetWidgetName(sage.Widget Widget,
                          java.lang.String Name)

Sets the name for a Widget

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

Name - the value to set the name to for this Widget

GetWidgetParents

public sage.Widget[] GetWidgetParents(sage.Widget Widget)

Gets the list of Widgets that are parents of the specified Widget. The ordering of this list has no effect.

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

Returns:

a list of Widgets which are all parents of the specified Widget

GetWidgetChildren

public sage.Widget[] GetWidgetChildren(sage.Widget Widget)

Gets the list of Widgets that are children of the specified Widget. The ordering of this list does have an effect.

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget)

Returns:

a list of Widgets which are all children of the specified Widget

ExecuteWidgetChain

public java.lang.Object ExecuteWidgetChain(sage.Widget Widget)

Executes a Widget and the chain of child Widgets underneath it

Parameters:

Widget - the root of the Widget (or a String which represents the symbol for that Widget) action chain to execute

Returns:

the value returned by the last executed Widget in the chain

ExecuteWidgetChainInCurrentMenuContext

public java.lang.Object ExecuteWidgetChainInCurrentMenuContext(sage.Widget Widget)

Executes a Widget and the chain of child Widgets underneath it. This will use the context of the currently loaded menu to do this which is useful if you want to launch an OptionsMenu programatically w/ the proper parent context.

Parameters:

Widget - the root of the Widget (or a String which represents the symbol for that Widget) action chain to execute

Returns:

the value returned by the last executed Widget in the chain

Since:

7.0

LaunchMenuWidget

public void LaunchMenuWidget(sage.Widget Widget)

Launches a new menu in SageTV with the specified Widget as the menu's definition.

Parameters:

Widget - the Widget object (or a String which represents the symbol for that Widget) to use for the launched menu, this must be a Menu type Widget

GetCurrentSTVFile

public java.lang.String GetCurrentSTVFile()

Gets the STV file that is currently loaded by the system

Returns:

the STV file that is currently loaded by the system

GetWidgetChild

public sage.Widget GetWidgetChild(sage.Widget Widget,
                                  java.lang.String Type,
                                  java.lang.String Name)

Searches the children of the specified Widget for one with the specified type and name. If no match is found then null is returned. If there are multiple matches then the first one is returned.

Parameters:

Widget - the Widget (or a String which represents the symbol for that Widget) who's children should be searched

Type - the type of the Widget to search for, if null than any type will match

Name - the name that the Widget to search for must match, if null than any name will match

Returns:

the Widget child of the specified Widget of the specified type and name

GetWidgetParent

public sage.Widget GetWidgetParent(sage.Widget Widget,
                                   java.lang.String Type,
                                   java.lang.String Name)

Searches the parents of the specified Widget for one with the specified type and name. If no match is found then null is returned. If there are multiple matches then the first one is returned.

Parameters:

Widget - the Widget (or a String which represents the symbol for that Widget) who's parents should be searched

Type - the type of the Widget to search for, if null than any type will match

Name - the name that the Widget to search for must match, if null than any name will match

Returns:

the Widget parent of the specified Widget of the specified type and name

GetCurrentMenuWidget

public sage.Widget GetCurrentMenuWidget()

Gets the Widget the defines the menu that is currently loaded by the system

Returns:

the Widget the defines the menu that is currently loaded by the system

GetWidgetMenuHistory

public sage.Widget[] GetWidgetMenuHistory()

Gets a list of the Widgets that have defined the menus that were recently displayed in the UI

Returns:

a list of the Widgets that have defined the menus that were recently displayed in the UI

GetWidgetMenuBackHistory

public sage.Widget[] GetWidgetMenuBackHistory()

Gets a list of the Widgets that have defined the menus that were recently displayed in the UI. Unlike GetWidgetMenuHistory() this only returns Menus that are 'Back' (not Forward) in the navigations the user has performed. Similar to getting only the 'Back' history in a web browser.

Returns:

a list of the Widgets that have defined the menus that were recently displayed in the UI

Since:

5.1

EvaluateExpression

public java.lang.Object EvaluateExpression(java.lang.String Expression)

Evaluates the passed in expression and returns the result. This is executed in a new variable context w/out any user interface context.

Parameters:

Expression - the expression string to evaluate

Returns:

the result of evaluating the specified expression

SaveWidgetsAsXML

public boolean SaveWidgetsAsXML(java.io.File File,
                                boolean Overwrite)

Saves all of the current Widgets as an XML file. Same as the "Save a Copy as XML..." in the Studio.

Parameters:

File - the file to write to

Overwrite - if true then if the File exists it will be overwritten

Returns:

true if successful, false if not

GetWidgetSymbol

public java.lang.String GetWidgetSymbol(sage.Widget Widget)

Returns the UID symbol for the specified Widget

Parameters:

Widget - the Widget object

Returns:

the UID symbol which is used to represent this widget uniquely

Since:

6.4

FindWidgetBySymbol

public sage.Widget FindWidgetBySymbol(java.lang.String Symbol)

Returns the Widget represented by the specified UID symbol

Parameters:

Symbol - the UID symbol to lookup the Widget for

Returns:

the Widget who's symbol matches the argument, null if it cannot be found

Since:

6.4

GetDefaultSTVFile

public java.io.File GetDefaultSTVFile()

Returns the file path for the default STV file

Returns:

the file path for the default STV file

Since:

6.4

GetUIWidgetContext

public sage.Widget GetUIWidgetContext()

Returns the Widget for the corresponding UI component that this execution originated from. For 'green' process chains; this will correspond to the UI component that received the event. For 'blue' UI chains; this will correspond to the UI component who's conditionality is being determined or who's data is being evaluated. This will be null if there is no UI context; such as for non-UI hooks and calls made from Java directly.

Returns:

the Widget that corresponds to the UI context used for the current evaluation, null if there is no context

Since:

6.6

GetSTVName

public java.lang.String GetSTVName()

Returns the value of the 'STVName' Attribute under the Global Theme Widget. This is used for dependencies relating to plugins.

Returns:

the value of the 'STVName' Attribute under the Global Theme Widget

Since:

7.0

GetSTVVersion

public java.lang.String GetSTVVersion()

Returns the value of the 'STVVersion' Attribute under the Global Theme Widget. This is used for dependencies relating to plugins.

Returns:

the value of the 'STVVersion' Attribute under the Global Theme Widget

Since:

7.0