Package sage.api

Class WidgetAPI


  • public class WidgetAPI
    extends java.lang.Object
    Widget reflection API
    • Constructor Summary

      Constructors 
      Constructor Description
      WidgetAPI()  
    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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