[Gtk2hs-commit] (main branch): Add new module System.GIO.File.FileEnumerator

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 454-5900

diffing dir...
Sun Aug 15 14:22:46 EDT 2010  Andy Stewart <laz...@gm...>
  * Add new module System.GIO.File.FileEnumerator
  Ignore-this: 611db116b306692524bc3150d98069d6
    {
    hunk ./gio/System/GIO.hs 36
    +    module System.GIO.File.FileEnumerator,
    hunk ./gio/System/GIO.hs 45
    +import System.GIO.File.FileEnumerator
    addfile ./gio/System/GIO/File/FileEnumerator.chs
    hunk ./gio/System/GIO/File/FileEnumerator.chs 1
    +{-# LANGUAGE CPP #-}
    +--  GIMP Toolkit (GTK) Binding for Haskell: binding to gio -*-haskell-*-
    +--
    +--  Author : Andy Stewart
    +--  Created: 30-Apirl-2010
    +--
    +--  Copyright (c) 2010 Andy Stewart
    +--
    +--  This library is free software: you can redistribute it and/or
    +--  modify it under the terms of the GNU Lesser General Public License
    +--  as published by the Free Software Foundation, either version 3 of
    +--  the License, or (at your option) any later version.
    +--  [_$_]
    +--  This library is distributed in the hope that it will be useful,
    +--  but WITHOUT ANY WARRANTY; without even the implied warranty of
    +--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    +--  Lesser General Public License for more details.
    +--  [_$_]
    +--  You should have received a copy of the GNU Lesser General Public
    +--  License along with this program.  If not, see
    +--  <http://www.gnu.org/licenses/>.
    +--  [_$_]
    +--  GIO, the C library which this Haskell library depends on, is
    +--  available under LGPL Version 2. The documentation included with
    +--  this library is based on the original GIO documentation.
    +--  [_$_]
    +-- | Maintainer  : gtk...@li...
    +--   Stability   : alpha
    +--   Portability : portable (depends on GHC)
    +module System.GIO.File.FileEnumerator (
    +-- * Details
    +--
    +-- | 'FileEnumerator' allows you to operate on a set of 'File's, returning a 'FileInfo' structure for each
    +-- file enumerated (e.g.  'fileEnumerateChildren' will return a 'FileEnumerator' for each of the
    +-- children within a directory).
    +-- [_$_]
    +-- To get the next file's information from a 'FileEnumerator', use 'fileEnumeratorNextFile' or its
    +-- asynchronous version, 'fileEnumeratorNextFilesAsync'. Note that the asynchronous version will
    +-- return a list of 'FileInfo', whereas the synchronous will only return the next file in the
    +-- enumerator.
    +-- [_$_]
    +-- To close a 'FileEnumerator', use 'fileEnumeratorClose', or its asynchronous version,
    +-- 'fileEnumeratorCloseAsync'.  [_$_]
    +--
    +-- * Types
    +    FileEnumerator (..),
    +    FileEnumeratorClass,
    +
    +-- * Methods
    +    fileEnumeratorNextFile,
    +    fileEnumeratorClose,
    +    fileEnumeratorNextFilesAsync,
    +    fileEnumeratorNextFilesFinish,
    +    fileEnumeratorCloseAsync,
    +    fileEnumeratorCloseFinish,
    +    fileEnumeratorIsClosed,
    +    fileEnumeratorHasPending,
    +    fileEnumeratorSetPending,
    +#if GLIB_CHECK_VERSION(2,18,0)
    +    fileEnumeratorGetContainer,
    +#endif
    +    ) where
    +
    +import Control.Monad
    +import System.GIO.Enums
    +import System.Glib.FFI
    +import System.Glib.Flags
    +import System.Glib.GError
    +import System.Glib.GList
    +import System.Glib.GObject
    +import System.Glib.UTFString
    +{#import System.GIO.Async.AsyncResult#}
    +{#import System.GIO.Base#}
    +{#import System.GIO.Types#}
    +
    +{# context lib = "gio" prefix = "g" #}
    +
    +-- | Returns information for the next file in the enumerated object. Will block until the information is
    +-- available. The 'FileInfo' returned from this function will contain attributes that match the
    +-- attribute string that was passed when the 'FileEnumerator' was created.
    +-- [_$_]
    +-- On error, returns 'Nothing' and sets error to the error. If the enumerator is at the end, 'Nothing' will be
    +-- returned and error will be unset.
    +fileEnumeratorNextFile :: FileEnumeratorClass enumerator => enumerator
    + -> Maybe Cancellable -- ^ @cancellable@ optional 'Cancellable' object, 'Nothing' to ignore.
    + -> IO (Maybe FileInfo)     -- ^ returns     A 'FileInfo' or 'Nothing' on error or end of enumerator. [_$_]
    +fileEnumeratorNextFile enumerator cancellable =
    +    maybeNull (makeNewGObject mkFileInfo) $
    +    withGObject (toFileEnumerator enumerator) $ \cEnumerator ->
    +        maybeWith withGObject cancellable $ \cCancellable ->
    +            propagateGError $ \gErrorPtr -> [_$_]
    +                g_file_enumerator_next_file cEnumerator cCancellable gErrorPtr
    +    where _ = {# call g_file_enumerator_next_file #}
    +
    +-- | Releases all resources used by this enumerator, making the enumerator return GIoErrorClosed on
    +-- all calls.
    +-- [_$_]
    +-- This will be automatically called when the last reference is dropped, but you might want to call
    +-- this function to make sure resources are released as early as possible.
    +fileEnumeratorClose :: FileEnumeratorClass enumerator => enumerator
    + -> Maybe Cancellable -- ^ @cancellable@ optional 'Cancellable' object, 'Nothing' to ignore.           [_$_]
    + -> IO Bool -- ^ returns     'True' on success or 'False' on error.                      [_$_]
    +fileEnumeratorClose enumerator cancellable =
    +    liftM toBool $
    +    withGObject (toFileEnumerator enumerator) $ \cEnumerator ->
    +        maybeWith withGObject cancellable $ \cCancellable ->
    +            propagateGError $ \gErrorPtr -> [_$_]
    +                g_file_enumerator_close cEnumerator cCancellable gErrorPtr
    +    where _ = {# call g_file_enumerator_close #}
    +
    +-- | Request information for a number of files from the enumerator asynchronously. When all i/o for the
    +-- operation is finished the callback will be called with the requested information.
    +-- [_$_]
    +-- The callback can be called with less than @numFiles@ files in case of error or at the end of the
    +-- enumerator. In case of a partial error the callback will be called with any succeeding items and no
    +-- error, and on the next request the error will be reported. If a request is cancelled the callback
    +-- will be called with 'IoErrorCancelled'.
    +-- [_$_]
    +-- During an async request no other sync and async calls are allowed, and will result in
    +-- 'IoErrorPending' errors.
    +-- [_$_]
    +-- Any outstanding i/o request with higher priority (lower numerical value) will be executed before an
    +-- outstanding request with lower priority. Default priority is GPriorityDefault.
    +fileEnumeratorNextFilesAsync :: FileEnumeratorClass enumerator
    + => enumerator
    + -> Int  -- ^ @numFiles@   the number of file info objects to request                  [_$_]
    + -> Int -- ^ @ioPriority@ the io priority of the request.                             [_$_]
    + -> Maybe Cancellable -- ^ @cancellable@ optional 'Cancellable' object, 'Nothing' to ignore.               [_$_]
    + -> AsyncReadyCallback -- ^ @callback@    a 'AsyncReadyCallback' to call when the request is satisfied [_$_]
    + -> IO ()
    +fileEnumeratorNextFilesAsync enumerator numFiles ioPriority cancellable callback =
    +    withGObject (toFileEnumerator enumerator) $ \cEnumerator ->
    +        maybeWith withGObject cancellable $ \cCancellable -> do
    +          cCallback <- marshalAsyncReadyCallback callback
    +          g_file_enumerator_next_files_async [_$_]
    +            cEnumerator
    +            (fromIntegral numFiles)
    +            (fromIntegral ioPriority)
    +            cCancellable
    +            cCallback
    +            (castFunPtrToPtr cCallback)
    +    where _ = {# call g_file_enumerator_next_files_async #}
    +  [_$_]
    +-- | Finishes the asynchronous operation started with 'fileEnumeratorNextFilesAsync'.
    +fileEnumeratorNextFilesFinish :: FileEnumeratorClass enumerator => enumerator
    + -> AsyncResult
    + -> IO [FileInfo]
    +fileEnumeratorNextFilesFinish enumerator asyncResult = [_$_]
    +    propagateGError ({# call g_file_enumerator_next_files_finish #} (toFileEnumerator enumerator) asyncResult) [_$_]
    +      >>= \glistPtr -> do
    +        infoPtrs <- fromGList glistPtr
    +        {# call unsafe g_list_free #} glistPtr
    +        mapM (makeNewGObject mkFileInfo . return) infoPtrs
    +        [_$_]
    +-- | Asynchronously closes the file enumerator.
    +-- [_$_]
    +-- If cancellable is not 'Nothing', then the operation can be cancelled by triggering the cancellable object
    +-- from another thread. If the operation was cancelled, the error 'IoErrorCancelled' will be returned
    +-- in 'fileEnumeratorCloseFinish'.
    +fileEnumeratorCloseAsync :: FileEnumeratorClass enumerator
    + => enumerator
    + -> Int -- ^ @ioPriority@ the I/O priority of the request.                            [_$_]
    + -> Maybe Cancellable -- ^ @cancellable@ optional 'Cancellable' object, 'Nothing' to ignore.               [_$_]
    + -> AsyncReadyCallback -- ^ @callback@    a 'AsyncReadyCallback' to call when the request is satisfied [_$_]
    + -> IO ()
    +fileEnumeratorCloseAsync enumerator ioPriority mbCancellable callback =
    +    withGObject (toFileEnumerator enumerator) $ \cEnumerator ->
    +        maybeWith withGObject mbCancellable $ \cCancellable -> do
    +          cCallback <- marshalAsyncReadyCallback callback
    +          g_file_enumerator_close_async [_$_]
    +            cEnumerator
    +            (fromIntegral ioPriority)
    +            cCancellable
    +            cCallback
    +            (castFunPtrToPtr cCallback)
    +    where _ = {# call g_file_enumerator_close_async #}
    +
    +-- | Finishes closing a file enumerator, started from 'fileEnumeratorCloseAsync'.
    +-- [_$_]
    +-- If the file enumerator was already closed when 'fileEnumeratorCloseAsync' was called, then this
    +-- function will report GIoErrorClosed in error, and return 'False'. If the file enumerator had
    +-- pending operation when the close operation was started, then this function will report
    +-- 'IoErrorPending', and return 'False'. If cancellable was not 'Nothing', then the operation may have been
    +-- cancelled by triggering the cancellable object from another thread. If the operation was cancelled,
    +-- the error 'IoErrorCancelled' will be set, and 'False' will be returned.
    +fileEnumeratorCloseFinish :: FileEnumeratorClass enumerator => enumerator
    + -> AsyncResult
    + -> IO Bool -- ^ returns    'True' if the close operation has finished successfully.           [_$_]
    +fileEnumeratorCloseFinish enumerator asyncResult = [_$_]
    +    liftM toBool $
    +    propagateGError ({# call g_file_enumerator_close_finish #} (toFileEnumerator enumerator) asyncResult) [_$_]
    +
    +-- | Checks if the file enumerator has been closed.
    +fileEnumeratorIsClosed :: FileEnumeratorClass enumerator => enumerator
    + -> IO Bool  -- ^ returns    'True' if the enumerator is closed. [_$_]
    +fileEnumeratorIsClosed enumerator =
    +  liftM toBool $
    +  {#call g_file_enumerator_is_closed#} (toFileEnumerator enumerator)
    +
    +-- | Checks if the file enumerator has pending operations.
    +fileEnumeratorHasPending :: FileEnumeratorClass enumerator => enumerator
    + -> IO Bool -- ^ returns    'True' if the enumerator has pending operations. [_$_]
    +fileEnumeratorHasPending enumerator =
    +  liftM toBool $
    +  {#call g_file_enumerator_has_pending#} (toFileEnumerator enumerator)
    +
    +-- | Sets the file enumerator as having pending operations.
    +fileEnumeratorSetPending :: FileEnumeratorClass enumerator => enumerator
    + -> Bool
    + -> IO ()
    +fileEnumeratorSetPending enumerator pending =
    +  {#call g_file_enumerator_set_pending#} (toFileEnumerator enumerator) (fromBool pending)
    +
    +#if GLIB_CHECK_VERSION(2,18,0)
    +-- | Get the 'File' container which is being enumerated.
    +fileEnumeratorGetContainer :: FileEnumeratorClass enumerator => enumerator
    + -> IO File
    +fileEnumeratorGetContainer enumerator =
    +    makeNewGObject mkFile $
    +    {#call g_file_enumerator_get_container#} (toFileEnumerator enumerator)
    +#endif
    hunk ./gio/gio.cabal 60
    +          System.GIO.File.FileEnumerator
    }