[Gtk2hs-commit] (main branch): gstreamer: document & implement missing API for M.S.G.Core.ElementFactory

[<du...@co...>]

Sun Feb 17 20:12:06 EST 2008  Peter Gavin <pg...@gm...>
  * gstreamer: document & implement missing API for M.S.G.Core.ElementFactory

    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 26
    --- | Maintainer  : gtk...@li...
    ---   Stability   : alpha
    ---   Portability : portable (depends on GHC)
    +--  |
    +--  Maintainer  : gtk...@li...
    +--  Stability   : alpha
    +--  Portability : portable (depends on GHC)
    +--  [_$_]
    +--  A factory for creating 'Element's.
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 33
    -  [_$_]
    +
    +-- * Detail
    +
    +  -- | 'ElementFactory' is used to create instances of 'Element's.
    +  --   [_$_]
    +  --   Use 'elementFactoryFind' and 'elementFactoryCreate' to create
    +  --   element instances, or use 'elementFactoryMake' as a convenient
    +  --   shortcut.
    +
    +-- * Types  [_$_]
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 48
    +-- * ElementFactory Operations
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 58
    +  elementFactoryHasInterface,
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 60
    -  elementFactoryMake
    +  elementFactoryMake,
    +  elementFactoryCanSinkCaps,
    +  elementFactoryCanSrcCaps,
    +  elementFactoryGetPadTemplates
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 67
    -import Control.Monad         ( liftM )
    +import Control.Monad         ( liftM
    +                             , (>=>) )
    +import Data.Maybe            ( fromMaybe )
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 75
    +import System.Glib.GList     ( readGList )
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 80
    -elementFactoryFind :: String
    -                   -> IO ElementFactory
    +-- | Search for an element factory with the given name.
    +elementFactoryFind :: String                    -- ^ @name@ - the name of the desired factory
    +                   -> IO (Maybe ElementFactory) -- ^ the factory if found, otherwise 'Nothing'
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 84
    -    withUTFString name {# call element_factory_find #} >>= takeObject
    +    withUTFString name {# call element_factory_find #} >>= maybePeek takeObject
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 86
    -elementFactoryGetElementType :: (ElementFactoryClass elementFactory) =>
    -                                elementFactory
    -                             -> IO (Maybe GType)
    +-- | Get the 'GType' for elements managed by the given factory. The type
    +--   can only be retrieved if the element factory is loaded, which can
    +--   be assured with
    +--   'Media.Streaming.GStreamer.Core.PluginFeature.pluginFeatureLoad'.
    +elementFactoryGetElementType :: (ElementFactoryClass elementFactory)
    +                             => elementFactory   -- ^ @factory@ - an element factory
    +                             -> IO (Maybe GType) -- ^ the type of elements managed
    +                                                 --   by the factory, or 'Nothing' if
    +                                                 --   the factory is not loaded
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 101
    -elementFactoryGetLongname :: (ElementFactoryClass elementFactory) =>
    -                             elementFactory
    -                          -> IO String
    +-- | Get the long name for the given factory.
    +elementFactoryGetLongname :: (ElementFactoryClass elementFactory)
    +                          => elementFactory -- ^ @factory@ - an element factory
    +                          -> IO String      -- ^ the factory's long name
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 109
    -elementFactoryGetKlass :: (ElementFactoryClass elementFactory) =>
    -                          elementFactory
    -                       -> IO String
    +-- | Get the class for the given factory.
    +elementFactoryGetKlass :: (ElementFactoryClass elementFactory)
    +                       => elementFactory -- ^ @factory@ - an element factory
    +                       -> IO String      -- ^ the factory's class
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 117
    -elementFactoryGetDescription :: (ElementFactoryClass elementFactory) =>
    -                                elementFactory
    -                             -> IO String
    +-- | Get the description for the given factory.
    +elementFactoryGetDescription :: (ElementFactoryClass elementFactory)
    +                             => elementFactory -- ^ @factory@ - an element factory
    +                             -> IO String      -- ^ the factory's description
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 125
    -elementFactoryGetAuthor :: (ElementFactoryClass elementFactory) =>
    -                           elementFactory
    -                        -> IO String
    +-- | Get the author of the given factory.
    +elementFactoryGetAuthor :: (ElementFactoryClass elementFactory)
    +                        => elementFactory -- ^ @factory@ - an element factory
    +                        -> IO String      -- ^ the factory's author
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 133
    -elementFactoryGetNumPadTemplates :: (ElementFactoryClass elementFactory) =>
    -                                    elementFactory
    -                                 -> IO Word
    +-- | Get the number of 'PadTemplate's provided by the given factory.
    +elementFactoryGetNumPadTemplates :: (ElementFactoryClass elementFactory)
    +                                 => elementFactory -- ^ @factory@ - an element factory
    +                                 -> IO Word        -- ^ the number of 'PadTemplate's
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 141
    -elementFactoryGetURIType :: (ElementFactoryClass elementFactory) =>
    -                            elementFactory
    -                         -> IO Word
    +-- | Get the type of URIs supported by the given factory.
    +elementFactoryGetURIType :: (ElementFactoryClass elementFactory)
    +                         => elementFactory -- ^ @factory@ - an element factory
    +                         -> IO Int         -- ^ the type of URIs supported by the factory
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 149
    -elementFactoryGetURIProtocols :: (ElementFactoryClass elementFactory) =>
    -                                 elementFactory
    -                              -> IO (Maybe [String])
    +-- | Get the list of protocols supported by the given factory.
    +elementFactoryGetURIProtocols :: (ElementFactoryClass elementFactory)
    +                              => elementFactory -- ^ @factory@ - an element factory
    +                              -> IO [String]    -- ^ the supported protocols
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 155
    -        maybePeek peekUTFStringArray0
    +        liftM (fromMaybe []) . maybePeek peekUTFStringArray0
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 157
    -elementFactoryCreate :: (ElementFactoryClass elementFactory) =>
    -                        elementFactory
    -                     -> String
    -                     -> IO (Maybe Element)
    +-- | Check if the given factory implements the interface with the given name.
    +elementFactoryHasInterface :: (ElementFactoryClass elementFactory)
    +                           => elementFactory -- ^ @factory@ - an element factory
    +                           -> String         -- ^ @name@ - the interface name
    +                           -> IO Bool        -- ^ true if the interface is implemented
    +elementFactoryHasInterface factory name =
    +    liftM toBool .
    +        withUTFString name .
    +        {# call element_factory_has_interface #} .
    +        toElementFactory $
    +        factory
    +
    +-- | Create a new element of the type supplied by the given
    +--   factory. It will be given the name supplied.
    +elementFactoryCreate :: (ElementFactoryClass elementFactory)
    +                     => elementFactory     -- ^ @factory@ - an element factory
    +                     -> String             -- ^ @name@ - the new element's name
    +                     -> IO (Maybe Element) -- ^ the new element if it could be created,
    +                                           --   otherwise 'Nothing'
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 181
    -elementFactoryMake :: String
    -                   -> String
    -                   -> IO (Maybe Element)
    +-- | Create a new element of the type supplied by the named
    +--   factory.
    +elementFactoryMake :: String             -- ^ @factoryName@ - the name of an element factory
    +                   -> Maybe String       -- ^ @name@ - the new element's name, or
    +                                         --   'Nothing' generate a unique name
    +                   -> IO (Maybe Element) -- ^ the new element if it could be created,
    +                                         --   otherwise 'Nothing'
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 190
    -        withUTFString name $ \cName ->
    +        maybeWith withUTFString name $ \cName ->
    hunk ./gstreamer/Media/Streaming/GStreamer/Core/ElementFactory.chs 194
    +-- | Check if the given factory can sink the given capabilities.
    +elementFactoryCanSinkCaps :: (ElementFactoryClass elementFactory)
    +                          => elementFactory -- ^ @factory@ - an element factory
    +                          -> Caps           -- ^ @caps@ - the capabilities to check for
    +                          -> IO Bool        -- ^ 'True' if @factory@ can sink the given capabilities
    +elementFactoryCanSinkCaps factory caps =
    +    liftM toBool $ {# call element_factory_can_sink_caps #} (toElementFactory factory) caps
    +
    +-- | Check if the given factory can source the given capabilities.
    +elementFactoryCanSrcCaps :: (ElementFactoryClass elementFactory)
    +                         => elementFactory -- ^ @factory@ - an element factory
    +                         -> Caps           -- ^ @caps@ - the capabilities to check for
    +                         -> IO Bool        -- ^ 'True' if @factory@ can source the given capabilities
    +elementFactoryCanSrcCaps factory caps =
    +    liftM toBool $ {# call element_factory_can_src_caps #} (toElementFactory factory) caps
    +
    +-- | Get the pad templates provided by the given factory.
    +elementFactoryGetPadTemplates :: (ElementFactoryClass elementFactory)
    +                              => elementFactory   -- ^ @factory@ - an element factory
    +                              -> IO [PadTemplate] -- ^ the provided pad templates
    +elementFactoryGetPadTemplates =
    +    {# call element_factory_get_static_pad_templates #} . toElementFactory >=>
    +        readGList >=> mapM staticPadTemplateGet
    +