Module tvbrowser
Package devplugin

Class Plugin

  • All Implemented Interfaces:
    ContextMenuIf, Marker, ProgramReceiveIf, java.lang.Comparable<ProgramReceiveIf>
    Direct Known Subclasses:
    DummyPlugin

    public abstract class Plugin
    extends java.lang.Object
    implements Marker, ContextMenuIf, ProgramReceiveIf
    Superclass for all Java-TV-Browser plugins.

    To create a plugin do the following:

    1. Create a class that extends this class and name its package equal to the class name but with lower case letters. E.g. myplugin.MyPlugin.
    2. Write your plugin code in that class.
    3. Pack your plugin class including all needed resources in a jar file named equal to your class. E.g. MyPlugin.jar.
    4. Put the jar in the plugin directory of your TV-Browser installation.
    Author:
    Martin Oberhauser, Til Schneider, www.murfman.de
    • Field Detail

      • CATEGORY_REMOTE_CONTROL_SOFTWARE

        public static final java.lang.String CATEGORY_REMOTE_CONTROL_SOFTWARE
        See Also:
        Constant Field Values
      • CATEGORY_REMOTE_CONTROL_HARDWARE

        public static final java.lang.String CATEGORY_REMOTE_CONTROL_HARDWARE
        See Also:
        Constant Field Values
      • CATEGORY_ADDITONAL_DATA_SERVICE_SOFTWARE

        public static final java.lang.String CATEGORY_ADDITONAL_DATA_SERVICE_SOFTWARE
        See Also:
        Constant Field Values
      • CATEGORY_ADDITONAL_DATA_SERVICE_HARDWARE

        public static final java.lang.String CATEGORY_ADDITONAL_DATA_SERVICE_HARDWARE
        See Also:
        Constant Field Values
      • CATEGORY_RATINGS

        public static final java.lang.String CATEGORY_RATINGS
        See Also:
        Constant Field Values
      • ALL_CATEGORY

        @Deprecated(since="3.4.4")
        public static final java.lang.String ALL_CATEGORY
        Deprecated.
        since 3.4.4 use CATEGORY_ALL instead
        See Also:
        Constant Field Values
      • RATINGS_CATEGORY

        @Deprecated(since="3.4.4")
        public static final java.lang.String RATINGS_CATEGORY
        Deprecated.
        since 3.4.4 use CATEGORY_RATINGS instead
        See Also:
        Constant Field Values
      • OTHER_CATEGORY

        @Deprecated(since="3.4.4")
        public static final java.lang.String OTHER_CATEGORY
        Deprecated.
        since 3.4.4 use CATEGORY_OTHER instead
        See Also:
        Constant Field Values
      • BIG_ICON

        public static final java.lang.String BIG_ICON
        The name to use for the big icon (the 22x22 one for the toolbar) of the button action.
        See Also:
        getButtonAction(), Constant Field Values
      • NO_ICON_RESIZE

        public static final java.lang.String NO_ICON_RESIZE
        Key for button action to disable icon resize. Set value to true to disable button resize.
        See Also:
        Constant Field Values
      • ACTION_ID_KEY

        public static final java.lang.String ACTION_ID_KEY
        A key for sub action menu entries unique ID.
        See Also:
        Constant Field Values
      • DISABLED_ON_TASK_MENU

        public static final java.lang.String DISABLED_ON_TASK_MENU
        The name to use for disabling a menu part for showing in ProgramInfo.
        Since:
        2.6
        See Also:
        Constant Field Values
      • SINGLE_CLICK_WAITING_TIME

        public static final int SINGLE_CLICK_WAITING_TIME
        The waiting time for single click performing.
        Since:
        2.7
      • mLocalizer

        public static final Localizer mLocalizer
        The localizer used by this class.
    • Constructor Detail

      • Plugin

        public Plugin()
    • Method Detail

      • setPluginManager

        public static final void setPluginManager​(PluginManager manager)
        Called by the host-application to provide access to the plugin manager.
        Parameters:
        manager - The plugin manager the plugins should use.
      • getPluginManager

        public static final PluginManager getPluginManager()
        Use this method to call methods of the plugin manager.

        The plugin manager is your connection to TV-Browser. Every communication between TV-Browser and the plugin is either initiated by TV-Browser or made by using the plugin manager.

        Returns:
        The plugin manager.
      • getId

        public final java.lang.String getId()
        Gets the ID of this plugin.
        Specified by:
        getId in interface ContextMenuIf
        Specified by:
        getId in interface Marker
        Specified by:
        getId in interface ProgramReceiveIf
        Returns:
        The ID of this plugin.
      • setParent

        public final void setParent​(java.awt.Frame parent)
        Called by the host-application to provide the parent frame.
        Parameters:
        parent - The parent frame.
      • getParentFrame

        protected final java.awt.Frame getParentFrame()
        Gets the parent frame.

        The parent frame may be used for showing dialogs.

        Returns:
        The parent frame.
      • createImageIcon

        protected final javax.swing.ImageIcon createImageIcon​(java.lang.String fileName)
        Helper method that loads an ImageIcon from the plugin jar file and returns it.
        Parameters:
        fileName - The name of the icon file.
        Returns:
        The icon.
      • createImageIconForFileName

        protected final javax.swing.ImageIcon createImageIconForFileName​(java.lang.String fileName)
        Helper method that loads an ImageIcon from the file system and returns it.
        Parameters:
        fileName - The name of the icon file.
        Returns:
        The icon.
        Since:
        2.3
      • createImageIcon

        public final javax.swing.ImageIcon createImageIcon​(java.lang.String category,
                                                           java.lang.String icon,
                                                           int size)
        Helper method that Loads an ImageIcon from the IconTheme
        Parameters:
        category - Category the Icon resists in
        icon - Icon to load (without extension)
        size - Size of the Icon
        Returns:
        The Icon
        Since:
        2.2
      • createImageIcon

        public final javax.swing.ImageIcon createImageIcon​(java.lang.String category,
                                                           java.lang.String icon)
        Helper method that Loads an ImageIcon from the IconTheme with default size
        Parameters:
        category - Category the Icon resists in
        icon - Icon to load (without extension)
        Returns:
        The Icon
        Since:
        2.2
      • createImageIcon

        public final javax.swing.ImageIcon createImageIcon​(ThemeIcon icon)
        Helper method that Loads an ImageIcon from the IconTheme
        Parameters:
        icon - Icon to load
        Returns:
        The Icon
        Since:
        2.2
      • readData

        public void readData​(java.io.ObjectInputStream in)
                      throws java.io.IOException,
                             java.lang.ClassNotFoundException
        Called by the host-application during start-up.

        Override this method to load any objects from the file system.

        Parameters:
        in - The stream to read the objects from.
        Throws:
        java.io.IOException - If reading failed.
        java.lang.ClassNotFoundException - If an object could not be casted correctly.
        See Also:
        writeData(ObjectOutputStream)
      • writeData

        public void writeData​(java.io.ObjectOutputStream out)
                       throws java.io.IOException
        Counterpart to loadData. Called when the application shuts down.

        Override this method to store any objects to the file system. ATTENTION: Don't use any logger, thread or access to Frames in this method.

        Parameters:
        out - The stream to write the objects to
        Throws:
        java.io.IOException - If writing failed.
        See Also:
        readData(ObjectInputStream)
      • loadSettings

        public void loadSettings​(java.util.Properties settings)
        Called by the host-application during start-up.

        Override this method to load your plugins settings from the file system.

        Parameters:
        settings - The settings for this plugin (May be empty).
      • storeSettings

        public java.util.Properties storeSettings()
        Called by the host-application during shut-down.

        Override this method to store your plugins settings to the file system. ATTENTION: Don't use any logger, thread or access to Frames in this method.

        Returns:
        The settings for this plugin or null if this plugin does not need to save any settings.
      • getVersion

        public static Version getVersion()
        Gets the version of this plugin.

        Override this to provide a check of the plugin for the version to load from main plugins dir or the user plugins dir. The plugin with the highest version will be loaded.

        Returns:
        The version of this plugin.
        Since:
        2.6
      • getInfo

        public PluginInfo getInfo()
        Gets the meta information about the plugin.

        Override this method to provide information about your plugin.

        Returns:
        The meta information about the plugin.
      • getContextMenuActions

        public ActionMenu getContextMenuActions​(Program program)
        Gets the actions for the context menu of a program.

        Override this method to provide context menu items for programs (e.g. in the program table). If your plugin shows a context menu only for some programs, but not for all, then you should explicitly return a non-null menu for the example program. Otherwise your context menu will not be shown in the settings dialog for the context menu order.

        The following action values will be used:

        • Action.NAME: The text for the context menu item.
        • Action.SMALL_ICON: The icon for the context menu item. Should be 16x16.
        Specified by:
        getContextMenuActions in interface ContextMenuIf
        Parameters:
        program - The program the context menu will be shown for.
        Returns:
        the actions this plugin provides for the given program or null if the plugin does not provide this feature.
        See Also:
        getProgramFromContextMenuActionEvent(ActionEvent)
      • getContextMenuActions

        public ActionMenu getContextMenuActions​(Channel channel)
        Gets the actions for the context menu of a channel.

        Override this method to provide context menu items for channels.

        The following action values will be used:

        • Action.NAME: The text for the context menu item.
        • Action.SMALL_ICON: The icon for the context menu item. Should be 16x16.
        Parameters:
        channel - The channel the context menu will be shown for.
        Returns:
        the actions this plugin provides for the given program or null if the plugin does not provide this feature.
        Since:
        3.0
        See Also:
        getContextMenuActions(Program)
      • getProgramFromContextMenuActionEvent

        protected final Program getProgramFromContextMenuActionEvent​(java.awt.event.ActionEvent evt)
        Gets the Program from the ActionEvent that was passed to a context menu action

        NOTE: At the moment the Program is passed as ActionEvent source. Please use this method to get the program and not directly the ActionEvent source. Because in future versions of TV-Browser the Program may be passed in another way!!

        Parameters:
        evt - The ActionEvent to get the Program from.
        Returns:
        The Program from the ActionEvent.
        See Also:
        getContextMenuActions(Program)
      • getButtonAction

        public ActionMenu getButtonAction()
        Gets the action to use for the main menu and the toolbar.

        Override this method to provide a menu item in the main menu and a toolbar button.

        The following action values will be used:

        • Action.NAME: The text for the main menu item and the toolbar button.
        • Action.SHORT_DESCRIPTION: The description for the button action. Used as tooltip and for the status bar.
        • Action.SMALL_ICON: The icon for the main menu item. Should be 16x16.
        • BIG_ICON: The icon for the toolbar button. Should be 24x24.
        Returns:
        the action to use for the menu and the toolbar or null if the plugin does not provide this feature.
      • getProgramTableIconText

        public java.lang.String getProgramTableIconText()
        Gets the description text for the program table icons provided by this Plugin.

        Override this method if your plugin provides icons for the program table (shown below the start time). The returned String will be shown in settings dialog (german: Aussehen - Sendungsanzeige - Plugin-Icons).

        Returns:
        The description text for the program table icons or null if the plugin does not provide this feature.
        See Also:
        getProgramTableIcons(Program)
      • getProgramTableToolTipIcons

        public ToolTipIcon[] getProgramTableToolTipIcons​(Program program)
        Gets the ToolTipIcons for the program table icons provided by this Plugin.

        Override this method if your plugin provides icons for the program table (shown below the start time) and you want the icons to be shown in the tooltip.

        Parameters:
        program - The program to get the ToolTipIcons for.
        Returns:
        The description text for the program table icons or null if the plugin does not provide this feature.
        Since:
        3.4.2
        See Also:
        getProgramTableIcons(Program)
      • getProgramTableIcons

        public javax.swing.Icon[] getProgramTableIcons​(Program program)
        Gets the icons this Plugin provides for the given program. These icons will be shown in the program table under the start time.

        Override this method to return the icons for the program table (shown below the start time).

        This method is only called, if the option to show program table icons for this plugin is set in the options.

        Parameters:
        program - The program to get the icons for.
        Returns:
        The icons for the given program or null if the plugin does not provide this feature.
        See Also:
        getProgramTableIconText()
      • getSettingsTab

        public SettingsTab getSettingsTab()
        Gets the SettingsTab object, which is added to the settings-window.

        Override this method to provide a settings tab. The settings tab will be shown in the settings dialog in the plugin section.

        Returns:
        the SettingsTab object or null if the plugin does not provide this feature.
      • getMarkIcon

        public final javax.swing.Icon getMarkIcon()
        Gets the icon used for marking programs in the program table.
        Specified by:
        getMarkIcon in interface Marker
        Returns:
        the icon to use for marking programs in the program table.
        See Also:
        getMarkIconName()
      • getMarkIcons

        public final javax.swing.Icon[] getMarkIcons​(Program p)
        Gets the icons used for marking programs in the program table.
        Specified by:
        getMarkIcons in interface Marker
        Parameters:
        p - The program to check.
        Returns:
        the icons to use for marking programs in the program table.
        Since:
        2.5
      • getMarkIconsForProgram

        public javax.swing.Icon[] getMarkIconsForProgram​(Program p)
        This gets the mark icons for a Program. Please cache the icons in the Plugin.
        Parameters:
        p - The Program to get the icons for.
        Returns:
        The icons for the Program.
        Since:
        2.5
      • getMarkIconName

        protected java.lang.String getMarkIconName()
        Gets the name of the file, containing your mark icon (in the jar-File). Should be 16x16.

        This icon is used for marking programs in the program table.

        Override this method if your plugin is able to mark programs As an alternative you can use an Icon from the Icon-Theme using getMarkIconFromTheme()

        Returns:
        the name of the file, containing your icon for the toolbar or null if the plugin does not provide this feature.
        See Also:
        getMarkIcon(), Program.mark(Plugin), Program.unmark(Plugin)
      • onActivation

        public void onActivation()
        This method is automatically called immediately before the plugin gets activated.
        Since:
        1.1
      • onDeactivation

        public void onDeactivation()
        This method is automatically called immediately after deactivating the plugin. ATTENTION: Don't use any logger, thread or access to Frames in this method.
        Since:
        1.1
      • canUseProgramTree

        public boolean canUseProgramTree()
        Signal whether this plugin participates in the plugin tree view or not.
        Returns:
        true, if the programs of this plugin are handled by the plugin tree view
        Since:
        1.1
        See Also:
        getRootNode()
      • handleTvBrowserStartFinished

        public void handleTvBrowserStartFinished()
        This method is called when the TV-Browser start is finished.
        Since:
        2.2
      • storeRootNode

        public void storeRootNode()
        Saves the entries under the root node in a file.
      • storeRootNode

        protected void storeRootNode​(PluginTreeNode node)
      • receivePrograms

        public boolean receivePrograms​(int eventType,
                                       Program[] programArr,
                                       ProgramReceiveTarget receiveTarget)
        Method called when programs are send to this plugin.
        Specified by:
        receivePrograms in interface ProgramReceiveIf
        Parameters:
        type - The type of the event that caused the sending of the programs.
        Returns:
        true, if the programs were correctly received and the target really exists.
        Since:
        4.2.2
        See Also:
        #getSupportedProgramRecieveType()
      • receiveValues

        public boolean receiveValues​(int type,
                                     java.lang.String[] values,
                                     ProgramReceiveTarget receiveTarget)
        Receives a list of Strings from another plugin with a target.
        Specified by:
        receiveValues in interface ProgramReceiveIf
        Parameters:
        type - The type of the programs send by other plugin.
        values - The value array passed from the other plugin.
        receiveTarget - The receive target of the programs.
        Returns:
        true if the value array was handled correct, false otherwise.
        Since:
        4.2.2
        See Also:
        #getSupportedProgramRecieveType()
      • getAvailableFilter

        public PluginsProgramFilter[] getAvailableFilter()
        Returns the available program filters that the plugin supports.
        Returns:
        The available program filters that the plugin supports or null if it supports no filter.
        Since:
        2.5
      • isAllowedToDeleteProgramFilter

        public boolean isAllowedToDeleteProgramFilter​(PluginsProgramFilter programFilter)
        Is used to track if a program filter be deleted. Should be make sure only the plugin itself can delete program filters.
        Parameters:
        programFilter - The program filter to delete.
        Returns:
        True if the program filter component can be deleted.
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • getAvailableFilterComponentClasses

        public java.lang.Class<? extends PluginsFilterComponent>[] getAvailableFilterComponentClasses()
        Returns the available plugins filter component classes.
        ATTENTON: Use return (Class<? extends PluginsFilterComponent>[]) new Class[] {MyFilterComponent1.class,MyFilterComponent2.class}; because the creation of a class array with generic type didn't work.
        Returns:
        The available plugins filter components classes or null if no plugins filter components are supported.
        Since:
        2.5
      • saveMe

        protected final boolean saveMe()
        Says the plugin proxy manager to store the settings and data of this plugin.

        Returns:
        True if the settings could be saved successfully.
        Since:
        2.5.3
      • layoutWindow

        public final void layoutWindow​(java.lang.String windowId,
                                       java.awt.Window window)
        Sets the window position and size for the given window from remembered values for that id.
        Parameters:
        windowId - The relative id of the window. The ID only needs to unique for this plugin.
        window - The window to layout.
        Since:
        2.7
      • layoutWindow

        public final void layoutWindow​(java.lang.String windowId,
                                       java.awt.Window window,
                                       java.awt.Dimension defaultSize)
        Sets the window position and size for the given window from remembered values for that id.
        Parameters:
        windowId - The relative id of the window. The ID only needs to unique for this plugin.
        window - The window to layout.
        defaultSize - The default size for the window.
        Since:
        2.7
      • getRatingInterfaces

        public ProgramRatingIf[] getRatingInterfaces()
        If this plugin can rate programs, this interface makes it possible to offer this ratings to other plugins. You can get all ProgramRatingIfs of all plugins using PluginManager.getAllProgramRatingIfs() The plugin can return more than one ratingif, e.g. average ratings, user rating ...
        Returns:
        the RatingIfs of this plugin
        Since:
        2.7
      • getAfterDataUpdateInfoPanel

        public AfterDataUpdateInfoPanel getAfterDataUpdateInfoPanel()
        Gets a panel that contains infos that should be shown for this Plugins after a data update.

        Returns:
        The panel with the infos.
        Since:
        3.2
      • handleTvBrowserSettingsChanged

        public void handleTvBrowserSettingsChanged()
        Is called when settings of TV-Browser or Plugins were changed, so this Plugin can react on that change.
        Since:
        3.2
      • handleTvDataUpdateStarted

        @Deprecated(since="3.3.3")
        public void handleTvDataUpdateStarted()
        Deprecated.
        since 3.3.3 Use handleTvDataUpdateStarted(Date) instead
        Is called when a TV data update is started.
        Since:
        3.2
      • handleTvDataUpdateStarted

        public void handleTvDataUpdateStarted​(Date until)
        Is called when a TV data update is started.
        Parameters:
        until - The last date of the data update.
        Since:
        3.3.3
      • getCommunicationClass

        public PluginCommunication getCommunicationClass()
        If you want to grant access to functions of your Plugin for other Plugins provide a communication class for you Plugin.

        Returns:
        The class that grants Plugin communication to your Plugin.
        Since:
        3.3.4
      • isAllowingArtificialPluginTree

        public boolean isAllowingArtificialPluginTree()
        Gets if an artificial plugin tree is allowed for this Plugin.

        Returns:
        true if an artificial plugin tree is allowed for this Plugin.
        Since:
        3.4.1
      • getAddtionalProgramInfoForProgram

        public ProgramInfo[] getAddtionalProgramInfoForProgram​(Program p,
                                                               java.lang.String uniqueId)
        Gets additional program infos for the given program. This method should return an array with all possible infos when called with the TV-Browser example Program and it's names and an emptry value String. Every additional info must have an unique ID, so the name might be changed but the ID never must.

        Parameters:
        p - The program to get the additional program info for.
        uniqueId - If not null the id of the program info to get.
        Returns:
        An array with the additional program info or null if no additional info is available.
        Since:
        3.4.4