SageTV Platform
V9.0

sage.api
Class WidgetAPI

java.lang.Object
  extended by sage.api.WidgetAPI

public class WidgetAPI
extends java.lang.Object

Widget reflection API


Constructor Summary
WidgetAPI()
           
 
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
 

Constructor Detail

WidgetAPI

public WidgetAPI()
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

Parameters:
WidgetType - the name of the widget 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
Symbol - the symbol name for the new widget (UID)
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. NOTE: If this does launch an OptionsMenu then the value returned from this function will not be usable and this call will return once the OptionsMenu is launched. Once it is closed the core will resume execution of the widget chain using one of its own internal threads at that point.

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

SageTV Platform
V9.0

SageTV is a trademark or registered trademark of Google, Inc. in the US and other countries.
Copyright 2000-2015 The SageTV Authors. All Rights Reserved.