FileSelection.chs

{-# LANGUAGE CPP #-}
-- -*-haskell-*-
--  GIMP Toolkit (GTK) Widget FileSelection
--
--  Author : Manuel M T Chakravarty
--
--  Created: 20 January 1999
--
--  Copyright (C) 1999-2005 Manuel M T Chakravarty, Jens Petersen
--
--  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 2.1 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.
--
-- |
-- Maintainer  : gtk2hs-users@lists.sourceforge.net
-- Stability   : provisional
-- Portability : portable (depends on GHC)
--
-- Prompt the user for a file or directory name
--
-- * As of Gtk+ 2.4 this module has been deprecated in favour of 'FileChooser'
--
-- This module is empty in Gtk3.
module Graphics.UI.Gtk.Selectors.FileSelection (
-- * Detail
--
-- | 'FileSelection' should be used to retrieve file or directory names from
-- the user. It will create a new dialog window containing a directory list,
-- and a file list corresponding to the current working directory. The
-- filesystem can be navigated using the directory list or the drop-down
-- history menu. Alternatively, the TAB key can be used to navigate using
-- filename completion - common in text based editors such as emacs and jed.
--
-- File selection dialogs are created with a call to 'fileSelectionNew'.
--
-- The default filename can be set using 'fileSelectionSetFilename' and the
-- selected filename retrieved using 'fileSelectionGetFilename'.
--
-- Use 'fileSelectionComplete' to display files and directories that match a
-- given pattern. This can be used for example, to show only *.txt files, or
-- only files beginning with gtk*.
--
-- Simple file operations; create directory, delete file, and rename file,
-- are available from buttons at the top of the dialog. These can be hidden
-- using 'fileSelectionHideFileopButtons' and shown again using
-- 'fileSelectionShowFileopButtons'.
--

-- * Class Hierarchy
-- |
-- @
-- |  'GObject'
-- |   +----'Object'
-- |         +----'Widget'
-- |               +----'Container'
-- |                     +----'Bin'
-- |                           +----'Window'
-- |                                 +----'Dialog'
-- |                                       +----FileSelection
-- @
#if GTK_MAJOR_VERSION < 3
-- * Types
  FileSelection,
  FileSelectionClass,
  castToFileSelection, gTypeFileSelection,
  toFileSelection,

-- * Constructors
  fileSelectionNew,

-- * Methods
  fileSelectionSetFilename,
  fileSelectionGetFilename,
  fileSelectionShowFileopButtons,
  fileSelectionHideFileopButtons,
  fileSelectionGetButtons,
  fileSelectionComplete,
  fileSelectionGetSelections,
  fileSelectionSetSelectMultiple,
  fileSelectionGetSelectMultiple,

-- * Attributes
  fileSelectionFilename,
  fileSelectionShowFileops,
  fileSelectionSelectMultiple,
#endif
  ) where
#if GTK_MAJOR_VERSION < 3
import Control.Monad            (liftM)

import System.Glib.FFI
import System.Glib.UTFString
import System.Glib.Attributes
import System.Glib.Properties
{#import Graphics.UI.Gtk.Types#}
import Graphics.UI.Gtk.Abstract.Object  (makeNewObject)
import Graphics.UI.Gtk.General.Structs  (fileSelectionGetButtons)

{# context lib="libgtk" prefix="gtk" #}

--------------------
-- Constructors

-- | Creates a new file selection dialog box. By default it will contain a
-- 'TreeView' of the application's current working directory, and a file
-- listing. Operation buttons that allow the user to create a directory, delete
-- files and rename files, are also present.
--
fileSelectionNew :: GlibString string
 => string           -- ^ @title@ - a message that will be placed in the file
                     -- requestor's titlebar.
 -> IO FileSelection
fileSelectionNew title =
  makeNewObject mkFileSelection $
  liftM (castPtr :: Ptr Widget -> Ptr FileSelection) $
  withUTFString title $ \titlePtr ->
  {# call unsafe file_selection_new #}
    titlePtr

--------------------
-- Methods

-- | Sets a default path for the file requestor. If @filename@ includes a
-- directory path, then the requestor will open with that path as its current
-- working directory.
--
-- This has the consequence that in order to open the requestor with a
-- working directory and an empty filename, @filename@ must have a trailing
-- directory separator.
--
fileSelectionSetFilename :: (FileSelectionClass self, GlibString string) => self
 -> string -- ^ @filename@ - a string to set as the default file name.
 -> IO ()
fileSelectionSetFilename self filename =
  withUTFString filename $ \filenamePtr ->
#if defined (WIN32) && GTK_CHECK_VERSION(2,6,0)
  {# call unsafe gtk_file_selection_set_filename_utf8 #}
#else
  {# call unsafe gtk_file_selection_set_filename #}
#endif
    (toFileSelection self)
    filenamePtr

-- | This function returns the selected filename.
--
-- If no file is selected then the selected directory path is returned.
--
fileSelectionGetFilename :: (FileSelectionClass self, GlibString string) => self
 -> IO string -- ^ returns currently-selected filename
fileSelectionGetFilename self =
#if defined (WIN32) && GTK_CHECK_VERSION(2,6,0)
  {# call unsafe gtk_file_selection_get_filename_utf8 #}
#else
  {# call unsafe gtk_file_selection_get_filename #}
#endif
    (toFileSelection self)
  >>= peekUTFString

-- | Shows the file operation buttons, if they have previously been hidden.
-- The rest of the widgets in the dialog will be resized accordingly.
--
fileSelectionShowFileopButtons :: FileSelectionClass self => self -> IO ()
fileSelectionShowFileopButtons self =
  {# call file_selection_show_fileop_buttons #}
    (toFileSelection self)

-- | Hides the file operation buttons that normally appear at the top of the
-- dialog. Useful if you wish to create a custom file selector, based on
-- 'FileSelection'.
--
fileSelectionHideFileopButtons :: FileSelectionClass self => self -> IO ()
fileSelectionHideFileopButtons self =
  {# call file_selection_hide_fileop_buttons #}
    (toFileSelection self)

-- | Will attempt to match @pattern@ to a valid filenames or subdirectories in
-- the current directory. If a match can be made, the matched filename will
-- appear in the text entry field of the file selection dialog. If a partial
-- match can be made, the \"Files\" list will contain those file names which
-- have been partially matched, and the \"Folders\" list those directories
-- which have been partially matched.
--
fileSelectionComplete :: (FileSelectionClass self, GlibString string) => self
 -> string -- ^ @pattern@ - a string of characters which may or may not match
           -- any filenames in the current directory.
 -> IO ()
fileSelectionComplete self pattern =
  withUTFString pattern $ \patternPtr ->
  {# call file_selection_complete #}
    (toFileSelection self)
    patternPtr

-- | Retrieves the list of file selections the user has made in the dialog
-- box. This function is intended for use when the user can select multiple
-- files in the file list.
--
fileSelectionGetSelections :: (FileSelectionClass self, GlibString string) => self -> IO [string]
fileSelectionGetSelections self = do
  cStrArr <-
#if defined (WIN32) && GTK_CHECK_VERSION(2,6,0)
    {# call gtk_file_selection_get_selections_utf8 #}
#else
    {# call gtk_file_selection_get_selections #}
#endif
    (toFileSelection self)
  cStrs <- peekArray0 nullPtr cStrArr
  result <- mapM peekUTFString cStrs
  {# call unsafe g_strfreev #} cStrArr
  return result

-- | Sets whether the user is allowed to select multiple files in the file
-- list. Use 'fileSelectionGetSelections' to get the list of selected files.
--
fileSelectionSetSelectMultiple :: FileSelectionClass self => self
 -> Bool  -- ^ @selectMultiple@ - whether or not the user is allowed to select
          -- multiple files in the file list.
 -> IO ()
fileSelectionSetSelectMultiple self selectMultiple =
  {# call gtk_file_selection_set_select_multiple #}
    (toFileSelection self)
    (fromBool selectMultiple)

-- | Determines whether or not the user is allowed to select multiple files in
-- the file list. See 'fileSelectionSetSelectMultiple'.
--
fileSelectionGetSelectMultiple :: FileSelectionClass self => self
 -> IO Bool -- ^ returns @True@ if the user is allowed to select multiple
            -- files in the file list
fileSelectionGetSelectMultiple self =
  liftM toBool $
  {# call gtk_file_selection_get_select_multiple #}
    (toFileSelection self)

--------------------
-- Attributes

-- | The currently selected filename.
--
--
fileSelectionFilename :: (FileSelectionClass self, GlibString string) => Attr self string
fileSelectionFilename = newAttr
  fileSelectionGetFilename
  fileSelectionSetFilename

-- | Whether buttons for creating\/manipulating files should be displayed.
--
-- Default value: @False@
--
fileSelectionShowFileops :: FileSelectionClass self => Attr self Bool
fileSelectionShowFileops = newAttrFromBoolProperty "show-fileops"

-- | Whether to allow multiple files to be selected.
--
-- Default value: @False@
--
fileSelectionSelectMultiple :: FileSelectionClass self => Attr self Bool
fileSelectionSelectMultiple = newAttr
  fileSelectionGetSelectMultiple
  fileSelectionSetSelectMultiple
#endif