sage.api
Class Utility

java.lang.Object
  sage.api.Utility

public class Utility
extends java.lang.Object

Contains miscellaneous methods useful for a variety of purposes

Method Summary

boolean	AddElement(java.util.Collection Data, java.lang.Object Value) Add the element with the specified value to this data.
boolean	AddToGrouping(java.util.Map Grouping, java.lang.Object Key, java.lang.Object Value) Adds the specified value into the grouping using the specified key.
boolean	Animate(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration) Starts an animation for the specified Widget in the specified Layer.
boolean	AnimateDelayed(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable) This is the same as the Animate API call; but it allows specifiying a delay that should occur before the animation actually starts.
boolean	AnimateTransition(java.lang.String SourceWidgetName, java.lang.String TargetWidgetName, java.lang.String LayerName, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable) Performs an Animation between two different Widgets.
boolean	AnimateVariable(java.lang.String WidgetName, java.lang.String LayerName, java.lang.String VarName, java.lang.Object VarValue, java.lang.String AnimationName, long Duration, long StartDelay, boolean Interruptable) For more details on Animations see here: Animate() In addition to what's specified in the Animate API call; this also offers restricting of an Animation by a variable name and value.
boolean	AreCoreAnimationsEnabled() Returns whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)
boolean	AreCoreAnimationsSupported() Returns whether or not animation support is possible in the current UI environment.
java.lang.String	CalculateMD5Sum(java.io.File FilePath) Calculates the MD5 Sum of a given file
void	ClearMenuCache() Clears the cache that links Widgets to the in memory-menu representations for this UI.
java.lang.Object[]	CreateArray(java.lang.Object Value) Creates a java.lang.Object array and initializes each element to the passed in argument.
java.io.File	CreateFilePath(java.lang.String Directory, java.lang.String File) Creates a new file object for the specified directory and file name or relative path
boolean	CreateNewDirectory(java.io.File DirectoryPath) Creates a new directory and any parent directories for the specified directory path.
boolean	CreateNewLocalDirectory(java.io.File DirectoryPath) Creates a new local directory and any parent directories for the specified directory path.
java.lang.Long[]	CreateTimeSpan(long StartTime, long EndTime) Returns a length 2 Long object array which can be used for specifying a time span in a table.
java.lang.String	DateFormat(java.lang.String Format, java.lang.Object Date) Returns a formatted date string for the specified Date.
boolean	DeleteFilePath(java.io.File FilePath) Deletes the file/directory at the corresponding file path (directories must be empty first)
boolean	DeleteLocalFilePath(java.io.File FilePath) Deletes the file/directory at the corresponding local file path (directories must be empty first)
boolean	DidImageLoadFail(java.lang.Object Image) Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album failed to load successfully.
java.io.File[]	DirectoryListing(java.io.File DirectoryPath) Returns a list of the files in the specified directory
java.io.File[]	DirectoryListing(java.io.File DirectoryPath, java.lang.String MediaMask) Returns a list of the files in the specified directory.
java.lang.String	DurFormat(java.lang.String Format, long Duration) Returns a formatted duration String for a period of time in milliseconds.
java.lang.Process	ExecuteProcess(java.lang.String CommandString, java.lang.Object Arguments, java.io.File WorkingDirectory, boolean ConsoleApp) Executes a new process on the system
java.lang.String	ExecuteProcessReturnOutput(java.lang.String CommandString, java.lang.Object Arguments, java.io.File WorkingDirectory, boolean ReturnStdout, boolean ReturnStderr) Executes a new process on the system and returns as a String the output of the process
java.lang.Object	FindComparativeElement(java.lang.Object Data, java.lang.Comparable Criteria, java.lang.String Method) Searches a sorted list of data to find the index that the specified criteria exists at; or if it doesn't exist in the data it will use the index that would be the appropriate insertion point for the criteria in the data in order to maintain sort order.
int	FindElementIndex(java.lang.Object Data, java.lang.Object Element) Returns the index in the data that the specified element is found at.
java.lang.String	GetAbsoluteFilePath(java.io.File FilePath) Returns the full path name from the specified file path..
long	GetDiskFreeSpace(java.lang.String DrivePath) Returns the amount of disk free space in bytes at the specified path
long	GetDiskTotalSpace(java.lang.String DrivePath) Returns the amount of total disk space in bytes at the specified path
java.lang.Object	GetElement(java.lang.Object Data, int Index) Returns the element at the specified index in this data; works for arrays and java.util.List implementations (i.e.
java.lang.String	GetFileAsString(java.io.File FilePath) Opens the file at the specified path and reads the entire contents of it and returns it as a String.
java.lang.String	GetFileExtensionFromPath(java.lang.String FilePath) Returns the file name extension from the specified file path (not including the '.')
java.lang.String	GetFileNameFromPath(java.io.File FilePath) Returns the file name from the specified file path; this just returns the filename without any path information.
long	GetFilePathSize(java.io.File FilePath) Returns the size in bytes of the specified file path
java.io.File[]	GetFileSystemRoots() Returns the root directories of the file systems (on Linux this'll just be / and on Windows it'll be the drive letters)
java.lang.String	GetFileSystemType(java.lang.String DrivePath) Gets the name of the filesystem type at the specified path
java.awt.image.BufferedImage	GetImageAsBufferedImage(java.lang.Object Resource) Returns a java.awt.image.BufferedImage object.
long	GetLocalFilePathSize(java.io.File FilePath) Returns the size in bytes of the specified local file path
java.io.File[]	GetLocalFileSystemRoots() Returns the root directories of the local file systems (on Linux this'll just be / and on Windows it'll be the drive letters)
java.lang.String	GetLocalIPAddress() Returns the IP address of the machine
long	GetLocalPathLastModifiedTime(java.io.File FilePath) Returns the last modified time of the specified local file path
long	GetPathLastModifiedTime(java.io.File FilePath) Returns the last modified time of the specified file path
java.io.File	GetPathParentDirectory(java.io.File FilePath) Returns the parent directory for the specified file path
java.awt.image.BufferedImage	GetScaledImageAsBufferedImage(java.lang.Object Resource, int Width, int Height) Returns a java.awt.image.BufferedImage object.
java.lang.Object	GetSubgroup(java.util.Map Grouping, java.lang.Object Key) Gets the value for the specified key out of a map.
long	GetTimeSinceLastInput() Returns the amount of time in milliseconds since the last user input occurred for this UI (used for doing things while the user is idle)
boolean	GetUIRefreshLock() Acquires the lock for this user interface system to prevent other updates from occuring.
int	GetWindowsRegistryDWORDValue(java.lang.String Root, java.lang.String Key, java.lang.String Name) Returns a DWORD value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
java.lang.String[]	GetWindowsRegistryNames(java.lang.String Root, java.lang.String Key) Returns a list of the Windows registry names which exist under the specified root & key (Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
int	GetWindowsRegistryStringValue(java.lang.String Root, java.lang.String Key, java.lang.String Name) Returns a string value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
java.lang.String	GetWorkingDirectory() Returns the current working directory for the application (if this is a client; it'll be the working directory of the server)
java.lang.String	GuessMajorFileType(java.lang.String Filename) Guesses what media type the specified filename corresponds to.
boolean	HasLocalFilesystem() Returns true if this client has a local file system that can be accessed.
java.lang.Object	If(boolean Condition, java.lang.Object True, java.lang.Object False) Returns the second argument if the first argument is true, otherwise the third argument is returned.
boolean	IsDirectoryPath(java.lang.String FilePath) Returns true if the specified path denotes a directory that exists
boolean	IsEmpty(java.lang.Object Data) Returns true if the argument is null, zero, an empty string or a failed image load
boolean	IsFilePath(java.lang.String FilePath) Returns true if the specified file path denotes a file that exists and is not a directory
boolean	IsFilePathHidden(java.lang.String FilePath) Returns true if the specified file path is marked as a hidden file
boolean	IsImageLoaded(java.lang.Object Image) Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album is loaded into system memory or into the VRAM cache of the corresponding UI making the call.
boolean	IsImportableFileType(java.lang.String Filename) Returns true if the specified file path has a file extension which would be imported by SageTV into its library.
boolean	IsLocalDirectoryPath(java.lang.String FilePath) Returns true if the specified local path denotes a directory that exists
boolean	IsLocalFilePath(java.lang.String FilePath) Returns true if the specified local file path denotes a file that exists and is not a directory
boolean	IsLocalFilePathHidden(java.lang.String FilePath) Returns true if the specified local file path is marked as a hidden file
boolean	IsLocalRestartNeeded() Returns true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall
boolean	IsServerRestartNeeded() Returns true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall
void	Keystroke(java.lang.String Character, boolean System) Executes the specified keystroke in either the SageTV event system or by emulation in the operating system
sage.MetaImage	LoadImage(java.lang.Object Resource) Returns a MetaImage object that refers to a specified image resource.
sage.MetaImage	LoadImageFile(java.io.File FilePath) Returns a MetaImage object that refers to the specified image file.
java.io.File[]	LocalDirectoryListing(java.io.File DirectoryPath) Returns a list of the files in the specified directory on the local filesystem
java.lang.String	LocalizeString(java.lang.String EnglishText) Returns a localized version of the specified string.
java.lang.Number	Max(java.lang.Number Value1, java.lang.Number Value2) Returns the maximum of the two arguments; the type of the returned argument will be the same as the highest precision argument
java.lang.Number	Min(java.lang.Number Value1, java.lang.Number Value2) Returns the minimum of the two arguments; the type of the returned argument will be the same as the highest precision argument
java.lang.String	NumberFormat(java.lang.String Format, float Number) Returns a formatted numeric string for the specified number.
void	PlaySound(java.lang.String SoundFile) Plays the specified sound file (used for sound effects, don't use for music playback)
java.lang.String	PrintCurrentTime() Returns a string that represents the current time.
java.lang.String	PrintDate(long Date) Returns a formatted date string using the java.text.DateFormat.MEDIUM formatting technique
java.lang.String	PrintDateFull(long Date) Returns a formatted date string using the java.text.DateFormat.FULL formatting technique
java.lang.String	PrintDateLong(long Date) Returns a formatted date string using SageTV's default detailed date formatting
java.lang.String	PrintDateShort(long Date) Returns a formatted date string using the java.text.DateFormat.SHORT formatting technique
java.lang.String	PrintDuration(long Duration) Returns a formatted duration string according to SageTV's verbose duration formating, minutes is the most detailed resolution of this format
java.lang.String	PrintDurationShort(long Duration) Returns a formatted duration string according to SageTV's concise duration formating, minutes is the most detailed resolution of this format
java.lang.String	PrintDurationWithSeconds(long Duration) Returns a formatted duration string according to SageTV's default duration formating, seconds is the most detailed resolution of this format
java.lang.String	PrintTime(long Time) Returns a formatted time string using the java.text.DateFormat.MEDIUM formatting technique
java.lang.String	PrintTimeFull(long Time) Returns a formatted time string using the java.text.DateFormat.FULL formatting technique
java.lang.String	PrintTimeLong(long Time) Returns a formatted time string using the java.text.DateFormat.LONG formatting technique
java.lang.String	PrintTimeShort(long Time) Returns a formatted time string using the java.text.DateFormat.SHORT formatting technique
java.lang.String	QueryServerMacAddress(java.lang.String Hostname) Gets the MAC address of the SageTV server at the specified hostname.
boolean	ReleaseUIRefreshLock() Releases the lock for this user interface system to allow other updates to occur.
java.lang.Object	RemoveElement(java.lang.Object Data, java.lang.Object Value) Removes the element at with the specified value from this data.
java.lang.Object	RemoveElementAtIndex(java.util.List Data, int Index) Removes the element at the specified index in this data; works java.util.List implementations (i.e.
boolean	RemoveWindowsRegistryValue(java.lang.String Root, java.lang.String Key, java.lang.String Name) Removes a value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)
boolean	RenameFilePath(java.io.File OriginalFilePath, java.io.File NewFilePath) Renames a file/directory
boolean	Restart() Restarts the local instance of SageTV.
java.lang.Object	Round(java.lang.Object Number) Rounds a floating point number to an integral value.
java.awt.image.BufferedImage	ScaleBufferedImage(java.awt.image.BufferedImage JavaBufferedImage, int Width, int Height, boolean Alpha) Scales a java.awt.image.BufferedImage object using optimized techniques
boolean	SendNetworkCommand(java.lang.String Hostname, int Port, java.lang.Object Command) Opens a TCP/IP socket connection to the specified hostname on the specified port and then sends the specified command.
boolean	ServerRestart() Restarts the server instance of SageTV.
void	SetCoreAnimationsEnabled(boolean Enabled) Sets whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)
java.lang.Object	SetElement(java.lang.Object Data, int Index, java.lang.Object Value) Sets the element at the specified index in this data; works for arrays and java.util.List implementations (i.e.
void	SetScrollPosition(float RelativeX, float RelativeY) Scrolls the closest pageable UI parent component (or sibling of a parent) to the specified position.
boolean	SetWindowsRegistryDWORDValue(java.lang.String Root, java.lang.String Key, java.lang.String Name, int Value) Sets a DWORD value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist.
boolean	SetWindowsRegistryStringValue(java.lang.String Root, java.lang.String Key, java.lang.String Name, java.lang.String Value) Sets a string value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist.
int	Size(java.lang.Object Data) Returns the size of the specified data.
boolean	StringEndsWith(java.lang.String FullString, java.lang.String MatchString) Returns true if the first string ends with the second, uses java.lang.String.endsWith
int	StringIndexOf(java.lang.String FullString, java.lang.String MatchString) Returns the index of the second string within the first string, -1 if it is not found.
int	StringLastIndexOf(java.lang.String FullString, java.lang.String MatchString) Returns the last index of the second string within the first string, -1 if it is not found.
boolean	StringStartsWith(java.lang.String FullString, java.lang.String MatchString) Returns true if the first string starts with the second, uses java.lang.String.startsWith
java.lang.String	Substring(java.lang.String String, int StartIndex, int EndIndex) Returns the substring from a specified string.
java.lang.String	SubstringBegin(java.lang.String String, int EndOffset) Returns the substring from a specified string.
int	TestPlaceshifterConnectivity(java.lang.String LocatorID) Connects to the SageTV Locator server and submits the specified Locator ID for a 'ping'.
long	Time() Returns the current time; see java.lang.System.currentTimeMillis() for the explanation of the units.
void	UnloadImage(java.lang.String ResPath) Unloads the specified image resource from memory.
void	Wait(long Time) Causes the currently executing thread to sleep for the specified amount of time in milliseconds.

Methods inherited from class java.lang.Object

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

Method Detail

GetSubgroup

public java.lang.Object GetSubgroup(java.util.Map Grouping,
                                    java.lang.Object Key)

Gets the value for the specified key out of a map. Useful for analyzing data from a GroupByMethod () call.

Parameters:

Grouping - the map to get the value from

Key - the key to use for retrieving the value

Returns:

the value for the specified key in the specified map

Keystroke

public void Keystroke(java.lang.String Character,
                      boolean System)

Executes the specified keystroke in either the SageTV event system or by emulation in the operating system

Parameters:

Character - the keystroke to perform, can contain Ctrl, Shift, Alt and combinations thereof with the specified key name

System - if true then an operating system keystroke should be emulated, if false then keep the keystroke within SageTV

Size

public int Size(java.lang.Object Data)

Returns the size of the specified data.

Parameters:

Data - the object to get the data size of

Returns:

for a Collection or Map, the size of it; for an array, the length; for a string, the length, otherwise 0 is returned

IsEmpty

public boolean IsEmpty(java.lang.Object Data)

Returns true if the argument is null, zero, an empty string or a failed image load

Parameters:

Data - the object to test

Returns:

true if the argument is null, zero, an empty string or a failed image load

Since:

7.0

DateFormat

public java.lang.String DateFormat(java.lang.String Format,
                                   java.lang.Object Date)

Returns a formatted date string for the specified Date.

Parameters:

Format - null if SageTV's default date format should be used, otherwise use a formatting string as specified in java.text.SimpleDateFormat

Date - either a java.util.Date object or a long which corresponds to the date

Returns:

the date formatted string

NumberFormat

public java.lang.String NumberFormat(java.lang.String Format,
                                     float Number)

Returns a formatted numeric string for the specified number.

Parameters:

Format - a formatting string as specified in java.text.DecimalFormat

Number - the floating point number to format

Returns:

the formatted numeric string

DurFormat

public java.lang.String DurFormat(java.lang.String Format,
                                  long Duration)

Returns a formatted duration String for a period of time in milliseconds. The formatting string uses the % character for escapement (%% is not supported, you cannot display the % symbol in a duration string). The 'd', 'h', 'm' and 's' characters can be used to indicate days, hours, minutes and seconds respectively. Any format character may be prefixed by the 'r' character to indicate it is a required field.

For example, the format string %rh:%m for 20 minutes would return 0:20 and for the string $h:%m it would return 20 If there's characters before a field value then that value will be zero padded, i.e. 65 minutes for %h:%m would be 1:05

Parameters:

Format - the duration format string, or null to use SageTV's default duration formatting

Duration - the duration to print out in milliseconds

Returns:

the formatted duration string

CreateTimeSpan

public java.lang.Long[] CreateTimeSpan(long StartTime,
                                       long EndTime)

Returns a length 2 Long object array which can be used for specifying a time span in a table. The first element will be the StartTime and the second will be the EndTime

Parameters:

StartTime - the long value which specifies the start value of the time span

EndTime - the long value which specifies the end value of the time span

Returns:

an array which represents this time span

GetElement

public java.lang.Object GetElement(java.lang.Object Data,
                                   int Index)

Returns the element at the specified index in this data; works for arrays and java.util.List implementations (i.e. Vector, etc.)

Parameters:

Data - the java.util.List or array object to get the element from

Index - the 0-based index of the element to retrieve

Returns:

the element at the specified index or null if there is no such element

SetElement

public java.lang.Object SetElement(java.lang.Object Data,
                                   int Index,
                                   java.lang.Object Value)

Sets the element at the specified index in this data; works for arrays and java.util.List implementations (i.e. Vector, etc.)

Parameters:

Data - the java.util.List or array object to set the element for

Index - the 0-based index of the element to set

Value - the value to set

Returns:

the Value parameters is returned

RemoveElementAtIndex

public java.lang.Object RemoveElementAtIndex(java.util.List Data,
                                             int Index)

Removes the element at the specified index in this data; works java.util.List implementations (i.e. Vector, etc.)

Parameters:

Data - the java.util.List object to remove the element from

Index - the 0-based index of the element to remove

Returns:

the element at the specified index or null if there is no such element

RemoveElement

public java.lang.Object RemoveElement(java.lang.Object Data,
                                      java.lang.Object Value)

Removes the element at with the specified value from this data. Works for java.util.Collection or java.util.Map implementations. If the value appears multiple times in the data (for Collections) only the first occurrence is removed.

Parameters:

Data - the java.util.Collection or java.util.Map object to remove the element from; for maps it removes based on key

Value - the value to remove from the data

Returns:

for java.util.Collections true if the element exists and was removed, false otherwise; for java.util.Maps it returns the value that the specified key corresponded to

AddElement

public boolean AddElement(java.util.Collection Data,
                          java.lang.Object Value)

Add the element with the specified value to this data. Works for java.util.Collection implementations.

Parameters:

Data - the java.util.Collection object to add the element to

Value - the value to add to the data

Returns:

for java.util.Collections true if the data changed as a result of the call (i.e. the add succeded and was not redundant), false otherwise

Since:

7.0

FindElementIndex

public int FindElementIndex(java.lang.Object Data,
                            java.lang.Object Element)

Returns the index in the data that the specified element is found at. If there are multiple occurrences of this element only the first index is returned. This works for arrays and java.util.List implementations.

Parameters:

Data - the java.util.List or array to look in

Element - the value to search the data for

Returns:

the 0-based index of the specified element in the data, or -1 if it does not exist

FindComparativeElement

public java.lang.Object FindComparativeElement(java.lang.Object Data,
                                               java.lang.Comparable Criteria,
                                               java.lang.String Method)

Searches a sorted list of data to find the index that the specified criteria exists at; or if it doesn't exist in the data it will use the index that would be the appropriate insertion point for the criteria in the data in order to maintain sort order. The element at that index is what is returned

Parameters:

Data - the data to sort, this must be a java.util.Collection, a java.util.Map, or an array

Criteria - the object to compare the elements to; this must implement java.lang.Comparable

Method - the method name to execute on each element to get the value to compare; use null to compare the elements themselves

Returns:

the element at the comparative insertion point

Substring

public java.lang.String Substring(java.lang.String String,
                                  int StartIndex,
                                  int EndIndex)

Returns the substring from a specified string. Same as java.lang.String.substring(int startIndex, int endIndex)

Parameters:

String - the string to get the substring of

StartIndex - the 0-based index that the substring starts at

EndIndex - the 0-based index that the substring ends at or -1 if the substring goes to the end of the string

Returns:

the substring from the specified string

SubstringBegin

public java.lang.String SubstringBegin(java.lang.String String,
                                       int EndOffset)

Returns the substring from a specified string. The substring will start at the beginning of the string and end EndIndex characters before the end of the string. Same as Substring(String, 0, Size(String) - EndOffset).

Parameters:

String - the string to get the substring of

EndOffset - the number of characters from the end of the string to terminate the substring (0 implies return the entire string)

Returns:

the substring from the specified string

Since:

7.0

Round

public java.lang.Object Round(java.lang.Object Number)

Rounds a floating point number to an integral value. For Doubles a Long is returned, for Floats an Integer is returned

Parameters:

Number - the number to round

Returns:

the rounded value

Time

public long Time()

Returns the current time; see java.lang.System.currentTimeMillis() for the explanation of the units.

Returns:

the current time

PrintCurrentTime

public java.lang.String PrintCurrentTime()

Returns a string that represents the current time.

Returns:

a string that represents the current time.

PrintDate

public java.lang.String PrintDate(long Date)

Returns a formatted date string using the java.text.DateFormat.MEDIUM formatting technique

Parameters:

Date - the date value to format

Returns:

a formatted date string

PrintDateLong

public java.lang.String PrintDateLong(long Date)

Returns a formatted date string using SageTV's default detailed date formatting

Parameters:

Date - the date value to format

Returns:

a formatted date string

PrintDateShort

public java.lang.String PrintDateShort(long Date)

Returns a formatted date string using the java.text.DateFormat.SHORT formatting technique

Parameters:

Date - the date value to format

Returns:

a formatted date string

PrintDateFull

public java.lang.String PrintDateFull(long Date)

Returns a formatted date string using the java.text.DateFormat.FULL formatting technique

Parameters:

Date - the date value to format

Returns:

a formatted date string

PrintTime

public java.lang.String PrintTime(long Time)

Returns a formatted time string using the java.text.DateFormat.MEDIUM formatting technique

Parameters:

Time - the time value to format

Returns:

a formatted time string

PrintTimeLong

public java.lang.String PrintTimeLong(long Time)

Returns a formatted time string using the java.text.DateFormat.LONG formatting technique

Parameters:

Time - the time value to format

Returns:

a formatted time string

PrintTimeShort

public java.lang.String PrintTimeShort(long Time)

Returns a formatted time string using the java.text.DateFormat.SHORT formatting technique

Parameters:

Time - the time value to format

Returns:

a formatted time string

PrintTimeFull

public java.lang.String PrintTimeFull(long Time)

Returns a formatted time string using the java.text.DateFormat.FULL formatting technique

Parameters:

Time - the time value to format

Returns:

a formatted time string

PrintDuration

public java.lang.String PrintDuration(long Duration)

Returns a formatted duration string according to SageTV's verbose duration formating, minutes is the most detailed resolution of this format

Parameters:

Duration - the duration in milliseconds to print

Returns:

the formatted duration string

PrintDurationWithSeconds

public java.lang.String PrintDurationWithSeconds(long Duration)

Returns a formatted duration string according to SageTV's default duration formating, seconds is the most detailed resolution of this format

Parameters:

Duration - the duration in milliseconds to print

Returns:

the formatted duration string

PrintDurationShort

public java.lang.String PrintDurationShort(long Duration)

Returns a formatted duration string according to SageTV's concise duration formating, minutes is the most detailed resolution of this format

Parameters:

Duration - the duration in milliseconds to print

Returns:

the formatted duration string

GetDiskFreeSpace

public long GetDiskFreeSpace(java.lang.String DrivePath)

Returns the amount of disk free space in bytes at the specified path

Parameters:

DrivePath - the path string of a disk to get the free space of

Returns:

the free space on the specified disk in bytes

GetDiskTotalSpace

public long GetDiskTotalSpace(java.lang.String DrivePath)

Returns the amount of total disk space in bytes at the specified path

Parameters:

DrivePath - the path string of a disk to get the total space of

Returns:

the total space on the specified disk in bytes

GetFileSystemType

public java.lang.String GetFileSystemType(java.lang.String DrivePath)

Gets the name of the filesystem type at the specified path

Parameters:

DrivePath - the path string of a disk to get the filesystem type for

Returns:

the name of the filesystem type at the specified path

GetWindowsRegistryNames

public java.lang.String[] GetWindowsRegistryNames(java.lang.String Root,
                                                  java.lang.String Key)

Returns a list of the Windows registry names which exist under the specified root & key (Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to look in

Key - the key path in the registry hive

Returns:

the names stored in the registry under the specified key

GetWindowsRegistryDWORDValue

public int GetWindowsRegistryDWORDValue(java.lang.String Root,
                                        java.lang.String Key,
                                        java.lang.String Name)

Returns a DWORD value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to look in

Key - the key path in the registry hive

Name - the name of the registry value to retrieve

Returns:

the value of the specified registry setting as a DWORD

GetWindowsRegistryStringValue

public int GetWindowsRegistryStringValue(java.lang.String Root,
                                         java.lang.String Key,
                                         java.lang.String Name)

Returns a string value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to look in

Key - the key path in the registry hive

Name - the name of the registry value to retrieve

Returns:

the value of the specified registry setting as a string

RemoveWindowsRegistryValue

public boolean RemoveWindowsRegistryValue(java.lang.String Root,
                                          java.lang.String Key,
                                          java.lang.String Name)

Removes a value from the Windows registry for the specified root, key and name(Windows only) Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to look in

Key - the key path in the registry hive

Name - the name of the registry value to remove

Returns:

true if the specified setting was removed, false otherwise

SetWindowsRegistryDWORDValue

public boolean SetWindowsRegistryDWORDValue(java.lang.String Root,
                                            java.lang.String Key,
                                            java.lang.String Name,
                                            int Value)

Sets a DWORD value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist. Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to use

Key - the key path in the registry hive

Name - the name of the registry value to set

Value - the value of the specified registry setting as a DWORD

Returns:

true if the operation was successful, false otherwise

SetWindowsRegistryStringValue

public boolean SetWindowsRegistryStringValue(java.lang.String Root,
                                             java.lang.String Key,
                                             java.lang.String Name,
                                             java.lang.String Value)

Sets a string value in the Windows registry for the specified root, key and name(Windows only) The name will be created if it doesn't already exist. Acceptable values for the Root are: "HKCR", "HKEY_CLASSES_ROOT", "HKCC", "HKEY_CURRENT_CONFIG", "HKCU", "HKEY_CURRENT_USER", "HKU", "HKEY_USERS", "HKLM" or "HKEY_LOCAL_MACHINE" (HKLM is the default if nothing matches)

Parameters:

Root - the registry hive to use

Key - the key path in the registry hive

Name - the name of the registry value to set

Value - the value of the specified registry setting as a string

Returns:

true if the operation was successful, false otherwise

PlaySound

public void PlaySound(java.lang.String SoundFile)

Plays the specified sound file (used for sound effects, don't use for music playback)

Parameters:

SoundFile - the path of the sound resource to play back

If

public java.lang.Object If(boolean Condition,
                           java.lang.Object True,
                           java.lang.Object False)

Returns the second argument if the first argument is true, otherwise the third argument is returned. All 3 arguments will be evaluated in all cases. This does NOT have a short-circuit which prevents evaluation of the third argument if the first is true.

Parameters:

Condition - the value to test to see if it is true

True - the value to return if the Condition is true

False - the value to return if the Condition is not true

Returns:

the appropriate value based on the condition

GetFileNameFromPath

public java.lang.String GetFileNameFromPath(java.io.File FilePath)

Returns the file name from the specified file path; this just returns the filename without any path information.

Parameters:

FilePath - the filepath to get the filename for

Returns:

the filename from the specified file path

GetAbsoluteFilePath

public java.lang.String GetAbsoluteFilePath(java.io.File FilePath)

Returns the full path name from the specified file path..

Parameters:

FilePath - the filepath to get the full path from

Returns:

the full path from the specified file path

Since:

7.0

GetFileExtensionFromPath

public java.lang.String GetFileExtensionFromPath(java.lang.String FilePath)

Returns the file name extension from the specified file path (not including the '.')

Parameters:

FilePath - the file path to get the extension of

Returns:

the extension from the specified file path

Since:

6.4

Wait

public void Wait(long Time)

Causes the currently executing thread to sleep for the specified amount of time in milliseconds.

Parameters:

Time - the amount of time to sleep this thread for in milliseconds

Max

public java.lang.Number Max(java.lang.Number Value1,
                            java.lang.Number Value2)

Returns the maximum of the two arguments; the type of the returned argument will be the same as the highest precision argument

Parameters:

Value1 - one of the values

Value2 - the other value

Returns:

the maximum of the passed in values

Min

public java.lang.Number Min(java.lang.Number Value1,
                            java.lang.Number Value2)

Returns the minimum of the two arguments; the type of the returned argument will be the same as the highest precision argument

Parameters:

Value1 - one of the values

Value2 - the other value

Returns:

the minimum of the passed in values

ExecuteProcess

public java.lang.Process ExecuteProcess(java.lang.String CommandString,
                                        java.lang.Object Arguments,
                                        java.io.File WorkingDirectory,
                                        boolean ConsoleApp)

Executes a new process on the system

Parameters:

CommandString - the command to execute (i.e. C:\windows\notepad.exe or ifconfig)

Arguments - the arguments to pass to the command that is executed, if it's a java.util.Collection or array then each element is an argument, otherwise it is considered a single argument; use null for no arguments

WorkingDirectory - the directory to execute the process from or null to execute it from the current working directory

ConsoleApp - if true then SageTV will consume the stdout and stderr output from the process that is launched; if false it will not

Returns:

the java.lang.Process object that represents the launched process

ExecuteProcessReturnOutput

public java.lang.String ExecuteProcessReturnOutput(java.lang.String CommandString,
                                                   java.lang.Object Arguments,
                                                   java.io.File WorkingDirectory,
                                                   boolean ReturnStdout,
                                                   boolean ReturnStderr)

Executes a new process on the system and returns as a String the output of the process

Parameters:

CommandString - the command to execute (i.e. C:\windows\notepad.exe or ifconfig)

Arguments - the arguments to pass to the command that is executed, if it's a java.util.Collection or array then each element is an argument, otherwise it is considered a single argument; use null for no arguments

WorkingDirectory - the directory to execute the process from or null to execute it from the current working directory

ReturnStdout - if true then SageTV will return the data from stdout as part of the return value

ReturnStderr - if true then SageTV will return the data from stderr as part of the return value

Returns:

a String which contains the data from stdout/stderr (depending upon the arguments), null if there was a failure

Since:

6.0

LoadImageFile

public sage.MetaImage LoadImageFile(java.io.File FilePath)

Returns a MetaImage object that refers to the specified image file. Used for passing images into Widgets.

Parameters:

FilePath - the file path of the image to load

Returns:

the loaded image object

LoadImage

public sage.MetaImage LoadImage(java.lang.Object Resource)

Returns a MetaImage object that refers to a specified image resource. This can be used to load images from URLs, JAR resources or the file system.

It also has a secondary purpose where you can pass it a MetaImage and then it will load that image into the current image cache so it will render as fast as possible in the next drawing cycle. Good for preloading the next image in a slideshow. If a MetaImage is passed in; this call will not return until that image is loaded into the cache.

Parameters:

Resource - if this is a MetaImage then the image is loaded into the cache, otherwise its converted to a string and then a MetaImage is returned for that resource

Returns:

the MetaImage that refers to the passed specified resource, if a MetaImage was passed in then the same object is returned

GetImageAsBufferedImage

public java.awt.image.BufferedImage GetImageAsBufferedImage(java.lang.Object Resource)

Returns a java.awt.image.BufferedImage object. This can be used to load images from URLs, JAR resources or the file system.

Parameters:

Resource - if this is a MetaImage then the buffered image is taken from that, otherwise its converted to a string and then the image is loaded from that path

Returns:

a newly allocated java.awt.image.BufferedImage corresponding to the specified resource

Since:

4.1

GetScaledImageAsBufferedImage

public java.awt.image.BufferedImage GetScaledImageAsBufferedImage(java.lang.Object Resource,
                                                                  int Width,
                                                                  int Height)

Returns a java.awt.image.BufferedImage object. This can be used to load images from URLs, JAR resources or the file system. The size of the returned image will match the passed in arguments.

Parameters:

Resource - if this is a MetaImage then the buffered image is taken from that, otherwise its converted to a string and then the image is loaded from that path

Width - the desired width of the returned image

Height - the desired height of the returned image

Returns:

a newly allocated java.awt.image.BufferedImage corresponding to the specified resource

Since:

4.1

UnloadImage

public void UnloadImage(java.lang.String ResPath)

Unloads the specified image resource from memory. NOTE: This does not care about the internal reference count in SageTV for this image which could mean bad things will happen if you use this on images other than ones that you are explicitly managing.

Parameters:

ResPath - the path to the image resource, can be a url, JAR resource path or a file path

IsImageLoaded

public boolean IsImageLoaded(java.lang.Object Image)

Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album is loaded into system memory or into the VRAM cache of the corresponding UI making the call.

Parameters:

Image - the MetaImage to check, or a MediaFile or an Album or a java.io.File or a java.net.URL

Returns:

true if the MetaImage (or the MetaImage that would correspond to the passed in resource) is loaded into system memory or the calling UI's VRAM, false otherwise

Since:

6.1

DidImageLoadFail

public boolean DidImageLoadFail(java.lang.Object Image)

Checks whether the passed in MetaImage (from an API call that returns MetaImage), MediaFile, File, URL or Album failed to load successfully. This will return false if the image load has not been attempted yet.

Parameters:

Image - the MetaImage to check, or a MediaFile or an Album or a java.io.File or a java.net.URL

Returns:

true if the MetaImage (or the MetaImage that would correspond to the passed in resource) has already tried to load; and the load failed

Since:

7.0

DirectoryListing

public java.io.File[] DirectoryListing(java.io.File DirectoryPath)

Returns a list of the files in the specified directory

Parameters:

DirectoryPath - the directory to list the files in

Returns:

a list of files in the specified directory

DirectoryListing

public java.io.File[] DirectoryListing(java.io.File DirectoryPath,
                                       java.lang.String MediaMask)

Returns a list of the files in the specified directory. Only directories and file matching the media mask will be returned.

Parameters:

DirectoryPath - the directory to list the files in

MediaMask - the types of content allowed, any combination of 'M'=Music, 'P'=Pictures or 'V'=Videos

Returns:

a list of folders and matching files in the specified directory

Since:

7.0

LocalDirectoryListing

public java.io.File[] LocalDirectoryListing(java.io.File DirectoryPath)

Returns a list of the files in the specified directory on the local filesystem

Parameters:

DirectoryPath - the directory to list the files in

Returns:

a list of files in the specified directory

Since:

6.4

GetFileSystemRoots

public java.io.File[] GetFileSystemRoots()

Returns the root directories of the file systems (on Linux this'll just be / and on Windows it'll be the drive letters)

Returns:

the root directories of the file systems

GetLocalFileSystemRoots

public java.io.File[] GetLocalFileSystemRoots()

Returns the root directories of the local file systems (on Linux this'll just be / and on Windows it'll be the drive letters)

Returns:

the root directories of the local file systems

Since:

6.4

StringEndsWith

public boolean StringEndsWith(java.lang.String FullString,
                              java.lang.String MatchString)

Returns true if the first string ends with the second, uses java.lang.String.endsWith

Parameters:

FullString - the string to search in

MatchString - the string to search for

Returns:

true if FullString ends with MatchString, false otherwise

StringStartsWith

public boolean StringStartsWith(java.lang.String FullString,
                                java.lang.String MatchString)

Returns true if the first string starts with the second, uses java.lang.String.startsWith

Parameters:

FullString - the string to search in

MatchString - the string to search for

Returns:

true if FullString starts with MatchString, false otherwise

StringIndexOf

public int StringIndexOf(java.lang.String FullString,
                         java.lang.String MatchString)

Returns the index of the second string within the first string, -1 if it is not found. Uses java.lang.String.indexOf

Parameters:

FullString - the string to search in

MatchString - the string to search for

Returns:

the first 0-based index in FullString that MatchString occurs at or -1 if it is not found

StringLastIndexOf

public int StringLastIndexOf(java.lang.String FullString,
                             java.lang.String MatchString)

Returns the last index of the second string within the first string, -1 if it is not found. Uses java.lang.String.lastIndexOf

Parameters:

FullString - the string to search in

MatchString - the string to search for

Returns:

the last 0-based index in FullString that MatchString occurs at or -1 if it is not found

GetWorkingDirectory

public java.lang.String GetWorkingDirectory()

Returns the current working directory for the application (if this is a client; it'll be the working directory of the server)

Returns:

the current working directory for the application

HasLocalFilesystem

public boolean HasLocalFilesystem()

Returns true if this client has a local file system that can be accessed.

Returns:

true if this client has a local file system that can be accessed

Since:

6.4

CreateFilePath

public java.io.File CreateFilePath(java.lang.String Directory,
                                   java.lang.String File)

Creates a new file object for the specified directory and file name or relative path

Parameters:

Directory - the directory name

File - the file within the directory or relative file path

Returns:

a new file object for the specified directory and file name or relative path

IsFilePathHidden

public boolean IsFilePathHidden(java.lang.String FilePath)

Returns true if the specified file path is marked as a hidden file

Parameters:

FilePath - the file path to test

Returns:

true if the specified file path is marked as a hidden file

IsLocalFilePathHidden

public boolean IsLocalFilePathHidden(java.lang.String FilePath)

Returns true if the specified local file path is marked as a hidden file

Parameters:

FilePath - the file path to test

Returns:

true if the specified local file path is marked as a hidden file

Since:

6.4

IsFilePath

public boolean IsFilePath(java.lang.String FilePath)

Returns true if the specified file path denotes a file that exists and is not a directory

Parameters:

FilePath - the file path to test

Returns:

true if the specified file path denotes a file that exists and is not a directory

IsLocalFilePath

public boolean IsLocalFilePath(java.lang.String FilePath)

Returns true if the specified local file path denotes a file that exists and is not a directory

Parameters:

FilePath - the file path to test

Returns:

true if the specified local file path denotes a file that exists and is not a directory

Since:

6.4

IsDirectoryPath

public boolean IsDirectoryPath(java.lang.String FilePath)

Returns true if the specified path denotes a directory that exists

Parameters:

FilePath - the file path to test

Returns:

true if the specified path denotes a directory that exists

IsLocalDirectoryPath

public boolean IsLocalDirectoryPath(java.lang.String FilePath)

Returns true if the specified local path denotes a directory that exists

Parameters:

FilePath - the file path to test

Returns:

true if the specified local path denotes a directory that exists

Since:

6.4

CreateNewDirectory

public boolean CreateNewDirectory(java.io.File DirectoryPath)

Creates a new directory and any parent directories for the specified directory path.

Parameters:

DirectoryPath - the directory to create

Returns:

true if successful, false otherwise

CreateNewLocalDirectory

public boolean CreateNewLocalDirectory(java.io.File DirectoryPath)

Creates a new local directory and any parent directories for the specified directory path.

Parameters:

DirectoryPath - the directory to create

Returns:

true if successful, false otherwise

Since:

6.4

GetPathParentDirectory

public java.io.File GetPathParentDirectory(java.io.File FilePath)

Returns the parent directory for the specified file path

Parameters:

FilePath - the file path to get the parent directory for

Returns:

the parent directory for the specified file path

GetPathLastModifiedTime

public long GetPathLastModifiedTime(java.io.File FilePath)

Returns the last modified time of the specified file path

Parameters:

FilePath - the file path

Returns:

the last modified time of the specified file path

GetLocalPathLastModifiedTime

public long GetLocalPathLastModifiedTime(java.io.File FilePath)

Returns the last modified time of the specified local file path

Parameters:

FilePath - the file path

Returns:

the last modified time of the specified local file path

Since:

6.4

GetFilePathSize

public long GetFilePathSize(java.io.File FilePath)

Returns the size in bytes of the specified file path

Parameters:

FilePath - the file path

Returns:

the size in bytes of the specified file path

Since:

6.4

GetLocalFilePathSize

public long GetLocalFilePathSize(java.io.File FilePath)

Returns the size in bytes of the specified local file path

Parameters:

FilePath - the file path

Returns:

the size in bytes of the specified local file path

Since:

6.4

DeleteFilePath

public boolean DeleteFilePath(java.io.File FilePath)

Deletes the file/directory at the corresponding file path (directories must be empty first)

Parameters:

FilePath - the file path

Returns:

true if successful, false otherwise

Since:

6.3.9

DeleteLocalFilePath

public boolean DeleteLocalFilePath(java.io.File FilePath)

Deletes the file/directory at the corresponding local file path (directories must be empty first)

Parameters:

FilePath - the file path

Returns:

true if successful, false otherwise

Since:

6.4

RenameFilePath

public boolean RenameFilePath(java.io.File OriginalFilePath,
                              java.io.File NewFilePath)

Renames a file/directory

Parameters:

OriginalFilePath - the file path to rename

NewFilePath - the new name for the file path

Returns:

true if successful, false otherwise

Since:

6.3.9

AddToGrouping

public boolean AddToGrouping(java.util.Map Grouping,
                             java.lang.Object Key,
                             java.lang.Object Value)

Adds the specified value into the grouping using the specified key. Useful on results from GroupByMethod() This works using a Map implementation that has Collections as the values and objects as the keys. So if two objects have the same key they will both still exist in the map by being in the Collection that corresponds to their key.

Parameters:

Grouping - the grouping (Map) to add the new key/value pair to

Key - the key to use to store the value in the map

Value - the value to store

Returns:

true is always returned

SendNetworkCommand

public boolean SendNetworkCommand(java.lang.String Hostname,
                                  int Port,
                                  java.lang.Object Command)

Opens a TCP/IP socket connection to the specified hostname on the specified port and then sends the specified command. After that the socket is closed.

Parameters:

Hostname - the hostname to connect to

Port - the port to connect on

Command - either a byte[] or a String to send across the socket

Returns:

true if successful, false otherwise

ScaleBufferedImage

public java.awt.image.BufferedImage ScaleBufferedImage(java.awt.image.BufferedImage JavaBufferedImage,
                                                       int Width,
                                                       int Height,
                                                       boolean Alpha)

Scales a java.awt.image.BufferedImage object using optimized techniques

Parameters:

JavaBufferedImage - the BufferedImage object that is the source for the scaling

Width - the width of the target image

Height - the height of the target image

Alpha - true if the scaling should be done in ARGB, false if it should be done in RGB

Returns:

a new BufferedImage that is a scaled version of the specified image

LocalizeString

public java.lang.String LocalizeString(java.lang.String EnglishText)

Returns a localized version of the specified string. Uses SageTV's core translation properties to do this.

Parameters:

EnglishText - the English string to translate from

Returns:

the translated version of the specified string in the currently configured language

GetLocalIPAddress

public java.lang.String GetLocalIPAddress()

Returns the IP address of the machine

Returns:

the IP address of the machine

IsImportableFileType

public boolean IsImportableFileType(java.lang.String Filename)

Returns true if the specified file path has a file extension which would be imported by SageTV into its library.

Parameters:

Filename - the file path to test

Returns:

true if the specified file path has a file extension which would be imported by SageTV into its library, false otherwise

GuessMajorFileType

public java.lang.String GuessMajorFileType(java.lang.String Filename)

Guesses what media type the specified filename corresponds to. It does this based on the configuration for the import library file types.

Parameters:

Filename - the file path to test

Returns:

"M", "V", "P", "B" or "D" for a music, video, picture, BluRay or DVD file respectively; if it can't tell it returns "V"

Since:

6.4

TestPlaceshifterConnectivity

public int TestPlaceshifterConnectivity(java.lang.String LocatorID)

Connects to the SageTV Locator server and submits the specified Locator ID for a 'ping'. The Locator server will then attempt to connect to the IP for that GUID and report back the status. The return code is an integer as follows: -1 - Unable to connect to the locator server (internet connection is down or locator server is down) 0 - The locator server did not have an IP address registered for this GUID 1 - The locator server could not connect to the IP address registered for the GUID 2 - The locator server can connect to the IP address registered for the GUID, but not to the Placeshifter port 3 - The locator server can connect to the IP address/port for the GUID, but the server that is there is not the Placeshifter 10 - The ping was successful. External connections to the Placeshifter should work correctly.

Parameters:

LocatorID - the GUID that should be used for the 'ping'

Returns:

an integer status code as described above.

CreateArray

public java.lang.Object[] CreateArray(java.lang.Object Value)

Creates a java.lang.Object array and initializes each element to the passed in argument. NOTE: This method takes a variable number of arguments, and the length of the returned array will be equal to the number of arguments. i.e. calling CreateArray(1, 2) returns an Object array with elements 1 and 2 in it

Parameters:

Value - a value for an element of the array (multiple arguments allowed)

Returns:

the newly allocated Object array with its elements set to the arguments

Since:

6.0

SetScrollPosition

public void SetScrollPosition(float RelativeX,
                              float RelativeY)

Scrolls the closest pageable UI parent component (or sibling of a parent) to the specified position.

Parameters:

RelativeX - the X position to scroll to between 0.0 and 1.0 (use a negative number to not change the X position)

RelativeY - the Y position to scroll to between 0.0 and 1.0 (use a negative number to not change the Y position)

Since:

6.2

ClearMenuCache

public void ClearMenuCache()

Clears the cache that links Widgets to the in memory-menu representations for this UI. This also clears the back/forward history to remove any references contained in there as well.

Since:

6.2

Animate

public boolean Animate(java.lang.String WidgetName,
                       java.lang.String LayerName,
                       java.lang.String AnimationName,
                       long Duration)

Starts an animation for the specified Widget in the specified Layer. If the Widget name ends with a '*' then all Widgets that match will be animated; otherwise only the first visible Widget matching the name will be animated. The Widget must also have the specified Layer as it's animation layer (i.e. if the Layer is Foreground, then the corresponding Widget should have an Animation property of LayerForeground). The type of animation is controlled by AnimtionName. There's also suffixes that can be appened to the AnimationName that effect how the timescale for the animation progresses. There's also other suffixes that can be used to specify other options for the animations.

Valid strings for the AnimationName are:

• FullSlideDownOut - slides down off the bottom of the screen
• FullSlideDownIn - slides down in from the top of the screen
• FullSlideUpOut - slides up off the top of the screen
• FullSlideUpIn - slides up in from the bottom of the screen
• FullSlideLeftOut - slides off to the left of the screen
• FullSlideLeftIn - slides in from the left of the screen
• FullSlideRightOut - slides off the right of the screen
• FullSlideRightIn - slides in from the right of the screen
• SlideDownOut - slides down off the bottom of its parent component
• SlideDownIn - slides down in from the top of its parent component
• SlideUpOut - slides up off the top of its parent component
• SlideUpIn - slides up in from the bottom of its parent component
• SlideLeftOut - slides off to the left of its parent component
• SlideLeftIn - slides in from the left of its parent component
• SlideRightOut - slides off the right of its parent component
• SlideRightIn - slides in from the right of its parent component
• FadeOut - fades out
• FadeIn - fades in
• Smooth - smoothly transitions from one position & size to another; the destination image is used for the animation
• Morph - smoothly transitions from one position & size to another; the image fades between the source and the destination
• ZoomOut - shrinks the size down to nothing from its source size
• ZoomIn - grows the size from nothing to its destination size
HZoomOut - shrinks the size down to nothing horitonzatlly from its source size
• HZoomIn - grows the size from nothing horitonzatlly to its destination size
VZoomOut - shrinks the size down to nothing vertically from its source size
• VZoomIn - grows the size from nothing vertically to its destination size

Timeline modifications for animations affect how the timescale progresses. For out animations, they are eased out if non-linear. For in animations, they are eased in if non-linear. For animations that are neither; the timescale modification occurs at both ends. Bounce only works properly for 'in' animations.

Valid suffixes for any of the animations are (default is Quadratic):

• Linear - animation follows a smooth timeline (first order)
• Quadratic - animation follows a quadratic timeline (second order)
• Cubic - animation follows a cubic timeline (third order)
• Bounce - animation follows a timeline that looks like it 'bounces' in

Additional options for the animation may also be specified by combining additional suffixes to the AnimationName. The following is a list of valid option suffixes.

• Fade - applies an additional fade in/out effect to the animation (i.e. ZoomOutFade)
• North - for Zoom animations will center the zoom around the top of the component (i.e. ZoomInNorth)
• West - for Zoom animations will center the zoom around the left of the component
• South - for Zoom animations will center the zoom around the bottom of the component
• East - for Zoom animations will center the zoom around the right of the component

Behind - for Out animations will cause it to be rendered behind the other layers instead of on top as Out animations usually are Unclipped - for Slide animations will cause the same motion to occur but without clipping the area when drawn Unease - for In or Out animations it will reverse the 'easing' direction so you can slide in & out the same panel w/ out overlap

You may combine the directional suffixes to get an additional four directions (i.e. ZoomOutNorthEast). And this can also be combined with the timeline suffixes as well, or even Fade (i.e. ZoomInQuadraticSouthWestFade)
For delaying the start of an animation; see here AnimateDelayed()

Parameters:

WidgetName - the name of the Widget that should be animated

LayerName - the name of the Layer the animated Widget must be in

AnimationName - the name of the animation to perform

Duration - the time in milliseconds that it should take for the animation to complete

Returns:

returns true if a matching Widget was found to perform the animation on; false otherwise

Since:

6.2

AnimateVariable

public boolean AnimateVariable(java.lang.String WidgetName,
                               java.lang.String LayerName,
                               java.lang.String VarName,
                               java.lang.Object VarValue,
                               java.lang.String AnimationName,
                               long Duration,
                               long StartDelay,
                               boolean Interruptable)

For more details on Animations see here: Animate() In addition to what's specified in the Animate API call; this also offers restricting of an Animation by a variable name and value. Usage of the '*' suffix on the WidgetName is allowed.

Parameters:

WidgetName - the name of the Widget that should be animated

LayerName - the name of the Layer the animated Widget must be in

VarName - the name of the variable that must match for the Widget to be animated

VarValue - the value of the variable to match

AnimationName - the name of the animation to perform

Duration - the time in milliseconds that it should take for the animation to complete

StartDelay - the delay in milliseconds before this animation should start

Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)

Returns:

returns true if a matching Widget was found to perform the animation on; false otherwise

Since:

6.3

AnimateTransition

public boolean AnimateTransition(java.lang.String SourceWidgetName,
                                 java.lang.String TargetWidgetName,
                                 java.lang.String LayerName,
                                 java.lang.String AnimationName,
                                 long Duration,
                                 long StartDelay,
                                 boolean Interruptable)

Performs an Animation between two different Widgets. Normally animations are performed between two different states for a single Widget. This API call allows an animation to occur between two different Widgets and will usually be used with a 'Morph' AnimationName. This may only target a single Widget; so the '*' suffix is not used on the WidgetNames in this call.
For more details on Animations see here: Animate()

Parameters:

SourceWidgetName - the name of the Widget to use as the source for this animation

TargetWidgetName - the name of the Widget to use as the target (destination) for this animation

LayerName - the name of the Layer the animated Widget must be in

AnimationName - the name of the animation to perform

Duration - the time in milliseconds that it should take for the animation to complete

StartDelay - the delay in milliseconds before this animation should start

Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)

Returns:

returns true if a matching Widget was found to perform the animation on; false otherwise

Since:

6.3

AnimateDelayed

public boolean AnimateDelayed(java.lang.String WidgetName,
                              java.lang.String LayerName,
                              java.lang.String AnimationName,
                              long Duration,
                              long StartDelay,
                              boolean Interruptable)

This is the same as the Animate API call; but it allows specifiying a delay that should occur before the animation actually starts. Useful for creating sequences of animation effects. For more details see here: Animate()

Parameters:

WidgetName - the name of the Widget that should be animated

LayerName - the name of the Layer the animated Widget must be in

AnimationName - the name of the animation to perform

Duration - the time in milliseconds that it should take for the animation to complete

StartDelay - the delay in milliseconds before this animation should start

Interruptable - true if the animation can be interrupted to render the next UI update; false if it must complete (this parameter is optional and defaults to false)

Returns:

returns true if a matching Widget was found to perform the animation on; false otherwise

Since:

6.2

SetCoreAnimationsEnabled

public void SetCoreAnimationsEnabled(boolean Enabled)

Sets whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)

Parameters:

Enabled - true to enable core animations; false otherwise

Since:

6.2

AreCoreAnimationsEnabled

public boolean AreCoreAnimationsEnabled()

Returns whether or not animation support is enabled (either layered or Effect based animations; depending upon the STV configuration)

Returns:

true if core animations are enabled; false otherwise

Since:

6.2

AreCoreAnimationsSupported

public boolean AreCoreAnimationsSupported()

Returns whether or not animation support is possible in the current UI environment. Certain clients (like the MVP) do not support animations; and animations over remote connections are also disabled due to performance reasons.

Returns:

true if core animations are supported; false otherwise

Since:

7.0

GetUIRefreshLock

public boolean GetUIRefreshLock()

Acquires the lock for this user interface system to prevent other updates from occuring. This can be used at the start of an animation sequence before the refresh call is made to ensure that the animations will all occur on the same refresh cycle. The return value indicates if the lock was acquired. Do NOT release the lock unless you acquired the lock. This lock is re-entrant and is thread-based. You must release it from the same thread that acquired the lock. If this method return false, then you already have the lock. IMPORTANT: It is of CRITICAL IMPORTANCE that ReleaseUIRefreshLock() is called after GetUIRefreshLock() if this method returns true or the user interface system will become completely locked up for this client. It's also important to not release the lock unless you acquired it.

Returns:

true if the lock was acquired (which means it MUST be released), false if it was not

Since:

6.4

ReleaseUIRefreshLock

public boolean ReleaseUIRefreshLock()

Releases the lock for this user interface system to allow other updates to occur. This must ONLY be used after GetUIRefreshLock() was called and ONLY if GetUIRefreshLock() actually returned true. This must also be called from the same thread that called GetUIRefreshLock()

Since:

6.4

CalculateMD5Sum

public java.lang.String CalculateMD5Sum(java.io.File FilePath)

Calculates the MD5 Sum of a given file

Parameters:

FilePath - the path to the file who's MD sum should be calculated

Returns:

the MD5 sum of the specified file as a String, null if the file doesn't exist or there's an error reading it

Since:

6.3

GetTimeSinceLastInput

public long GetTimeSinceLastInput()

Returns the amount of time in milliseconds since the last user input occurred for this UI (used for doing things while the user is idle)

Returns:

the amount of time in milliseconds since the last user input occurred

Since:

6.6

GetFileAsString

public java.lang.String GetFileAsString(java.io.File FilePath)

Opens the file at the specified path and reads the entire contents of it and returns it as a String.

Parameters:

FilePath - the file path

Returns:

a String which represents the contents of the file; the emptry string if there was a failure

Since:

6.6

IsLocalRestartNeeded

public boolean IsLocalRestartNeeded()

Returns true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall

Returns:

true if the local instance of SageTV needs to be restarted due to a plugin install/uninstall, false otherwise

Since:

7.0

IsServerRestartNeeded

public boolean IsServerRestartNeeded()

Returns true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall

Returns:

true if the server instance of SageTV needs to be restarted due to a plugin install/uninstall, false otherwise

Since:

7.0

Restart

public boolean Restart()

Restarts the local instance of SageTV. Sometimes needed after a plugin install/uninstall. If you want to restart the local and server instance; then perform the restart on the server first. This is only supported on Windows and Linux currently. If this is called from a SageTVClient running on the same machine as the server, this will invoke a restart of the locally running server as well in order to ensure proper file upgrade synchronization.

Returns:

true if restarting is supported (Although the restart will likely complete and the method will never return), false otherwise (Mac OS X does not have restart support)

Since:

7.0

ServerRestart

public boolean ServerRestart()

Restarts the server instance of SageTV. Sometimes needed after a plugin install/uninstall. If you want to restart the local and server instance; then perform the restart on the server first. This is only supported on Windows servers and Linux servers currently.

Returns:

true if restarting is supported (Although the restart will likely complete and the method will never return), false otherwise (Mac OS X server does not have restart support)

Since:

7.0

QueryServerMacAddress

public java.lang.String QueryServerMacAddress(java.lang.String Hostname)

Gets the MAC address of the SageTV server at the specified hostname. This will only work if SageTV is running on that host. This call uses a 3 second timeout internally.

Parameters:

Hostname - the hostname/IP of the SageTV server

Returns:

a String in the format 00:xx:xx:xx:xx:xx that represents the MAC of the server, or null if it fails

Since:

7.0