libnautilus-private/nautilus-directory.h

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 8; tab-width: 8 -*-
   2
   3    nautilus-directory.h: Nautilus directory model.
   4
   5    Copyright (C) 1999, 2000, 2001 Eazel, Inc.
   6
   7    This program is free software; you can redistribute it and/or
   8    modify it under the terms of the GNU General Public License as
   9    published by the Free Software Foundation; either version 2 of the
  10    License, or (at your option) any later version.
  11
  12    This program is distributed in the hope that it will be useful,
  13    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15    General Public License for more details.
  16
  17    You should have received a copy of the GNU General Public
  18    License along with this program; if not, write to the
  19    Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20    Boston, MA 02111-1307, USA.
  21
  22    Author: Darin Adler <darin@bentspoon.com>
  23 */
  24
  25 #ifndef NAUTILUS_DIRECTORY_H
  26 #define NAUTILUS_DIRECTORY_H
  27
  28 #include <gtk/gtkobject.h>
  29 #include <gio/gio.h>
  30 #include <libnautilus-private/nautilus-file-attributes.h>
  31
  32 /* NautilusDirectory is a class that manages the model for a directory,
  33    real or virtual, for Nautilus, mainly the file-manager component. The directory is
  34    responsible for managing both real data and cached metadata. On top of
  35    the file system independence provided by gio, the directory
  36    object also provides:
  37
  38        1) A synchronization framework, which notifies via signals as the
  39           set of known files changes.
  40        2) An abstract interface for getting attributes and performing
  41           operations on files.
  42 */
  43
  44 #define NAUTILUS_TYPE_DIRECTORY \
  45         (nautilus_directory_get_type ())
  46 #define NAUTILUS_DIRECTORY(obj) \
  47         (GTK_CHECK_CAST ((obj), NAUTILUS_TYPE_DIRECTORY, NautilusDirectory))
  48 #define NAUTILUS_DIRECTORY_CLASS(klass) \
  49         (GTK_CHECK_CLASS_CAST ((klass), NAUTILUS_TYPE_DIRECTORY, NautilusDirectoryClass))
  50 #define NAUTILUS_IS_DIRECTORY(obj) \
  51         (GTK_CHECK_TYPE ((obj), NAUTILUS_TYPE_DIRECTORY))
  52 #define NAUTILUS_IS_DIRECTORY_CLASS(klass) \
  53         (GTK_CHECK_CLASS_TYPE ((klass), NAUTILUS_TYPE_DIRECTORY))
  54
  55 /* NautilusFile is defined both here and in nautilus-file.h. */
  56 #ifndef NAUTILUS_FILE_DEFINED
  57 #define NAUTILUS_FILE_DEFINED
  58 typedef struct NautilusFile NautilusFile;
  59 #endif
  60
  61 typedef struct NautilusDirectoryDetails NautilusDirectoryDetails;
  62
  63 typedef struct
  64 {
  65         GObject object;
  66         NautilusDirectoryDetails *details;
  67 } NautilusDirectory;
  68
  69 typedef void (*NautilusDirectoryCallback) (NautilusDirectory *directory,
  70                                            GList             *files,
  71                                            gpointer           callback_data);
  72
  73 typedef struct
  74 {
  75         GObjectClass parent_class;
  76
  77         /*** Notification signals for clients to connect to. ***/
  78
  79         /* The files_added signal is emitted as the directory model
  80          * discovers new files.
  81          */
  82         void     (* files_added)         (NautilusDirectory          *directory,
  83                                           GList                      *added_files);
  84
  85         /* The files_changed signal is emitted as changes occur to
  86          * existing files that are noticed by the synchronization framework,
  87          * including when an old file has been deleted. When an old file
  88          * has been deleted, this is the last chance to forget about these
  89          * file objects, which are about to be unref'd. Use a call to
  90          * nautilus_file_is_gone () to test for this case.
  91          */
  92         void     (* files_changed)       (NautilusDirectory         *directory,
  93                                           GList                     *changed_files);
  94
  95         /* The done_loading signal is emitted when a directory load
  96          * request completes. This is needed because, at least in the
  97          * case where the directory is empty, the caller will receive
  98          * no kind of notification at all when a directory load
  99          * initiated by `nautilus_directory_file_monitor_add' completes.
 100          */
 101         void     (* done_loading)        (NautilusDirectory         *directory);
 102
 103         void     (* load_error)          (NautilusDirectory         *directory,
 104                                           GError                    *error);
 105
 106         /*** Virtual functions for subclasses to override. ***/
 107         gboolean (* contains_file)       (NautilusDirectory         *directory,
 108                                           NautilusFile              *file);
 109         void     (* call_when_ready)     (NautilusDirectory         *directory,
 110                                           NautilusFileAttributes     file_attributes,
 111                                           gboolean                   wait_for_file_list,
 112                                           NautilusDirectoryCallback  callback,
 113                                           gpointer                   callback_data);
 114         void     (* cancel_callback)     (NautilusDirectory         *directory,
 115                                           NautilusDirectoryCallback  callback,
 116                                           gpointer                   callback_data);
 117         void     (* file_monitor_add)    (NautilusDirectory          *directory,
 118                                           gconstpointer              client,
 119                                           gboolean                   monitor_hidden_files,
 120                                           gboolean                   monitor_backup_files,
 121                                           NautilusFileAttributes     monitor_attributes,
 122                                           NautilusDirectoryCallback  initial_files_callback,
 123                                           gpointer                   callback_data);
 124         void     (* file_monitor_remove) (NautilusDirectory         *directory,
 125                                           gconstpointer              client);
 126         void     (* force_reload)        (NautilusDirectory         *directory);
 127         gboolean (* are_all_files_seen)  (NautilusDirectory         *directory);
 128         gboolean (* is_not_empty)        (NautilusDirectory         *directory);
 129         char *   (* get_name_for_self_as_new_file) (NautilusDirectory *directory);
 130
 131         /* get_file_list is a function pointer that subclasses may override to
 132          * customize collecting the list of files in a directory.
 133          * For example, the NautilusDesktopDirectory overrides this so that it can
 134          * merge together the list of files in the $HOME/Desktop directory with
 135          * the list of standard icons (Computer, Home, Trash) on the desktop.
 136          */
 137         GList *  (* get_file_list)       (NautilusDirectory *directory);
 138
 139         /* Should return FALSE if the directory is read-only and doesn't
 140          * allow setting of metadata.
 141          * An example of this is the search directory.
 142          */
 143         gboolean (* is_editable)         (NautilusDirectory *directory);
 144 } NautilusDirectoryClass;
 145
 146 /* Basic GObject requirements. */
 147 GType              nautilus_directory_get_type                 (void);
 148
 149 /* Get a directory given a uri.
 150  * Creates the appropriate subclass given the uri mappings.
 151  * Returns a referenced object, not a floating one. Unref when finished.
 152  * If two windows are viewing the same uri, the directory object is shared.
 153  */
 154 NautilusDirectory *nautilus_directory_get                      (GFile                     *location);
 155 NautilusDirectory *nautilus_directory_get_by_uri               (const char                *uri);
 156 NautilusDirectory *nautilus_directory_get_for_file             (NautilusFile              *file);
 157
 158 /* Covers for gtk_object_ref and gtk_object_unref that provide two conveniences:
 159  * 1) You don't have to cast to GtkObject *, so using these is type safe.
 160  * 2) You are allowed to call these with NULL,
 161  */
 162 NautilusDirectory *nautilus_directory_ref                      (NautilusDirectory         *directory);
 163 void               nautilus_directory_unref                    (NautilusDirectory         *directory);
 164
 165 /* Access to a URI. */
 166 char *             nautilus_directory_get_uri                  (NautilusDirectory         *directory);
 167 GFile *            nautilus_directory_get_location             (NautilusDirectory         *directory);
 168
 169 /* Is this file still alive and in this directory? */
 170 gboolean           nautilus_directory_contains_file            (NautilusDirectory         *directory,
 171                                                                 NautilusFile              *file);
 172
 173 /* Get the uri of the file in the directory, NULL if not found */
 174 char *             nautilus_directory_get_file_uri             (NautilusDirectory         *directory,
 175                                                                 const char                *file_name);
 176
 177 /* Get (and ref) a NautilusFile object for this directory. */
 178 NautilusFile *     nautilus_directory_get_corresponding_file   (NautilusDirectory         *directory);
 179
 180 /* Waiting for data that's read asynchronously.
 181  * The file attribute and metadata keys are for files in the directory.
 182  */
 183 void               nautilus_directory_call_when_ready          (NautilusDirectory         *directory,
 184                                                                 NautilusFileAttributes     file_attributes,
 185                                                                 gboolean                   wait_for_all_files,
 186                                                                 NautilusDirectoryCallback  callback,
 187                                                                 gpointer                   callback_data);
 188 void               nautilus_directory_cancel_callback          (NautilusDirectory         *directory,
 189                                                                 NautilusDirectoryCallback  callback,
 190                                                                 gpointer                   callback_data);
 191
 192
 193 /* Monitor the files in a directory. */
 194 void               nautilus_directory_file_monitor_add         (NautilusDirectory         *directory,
 195                                                                 gconstpointer              client,
 196                                                                 gboolean                   monitor_hidden_files,
 197                                                                 gboolean                   monitor_backup_files,
 198                                                                 NautilusFileAttributes     attributes,
 199                                                                 NautilusDirectoryCallback  initial_files_callback,
 200                                                                 gpointer                   callback_data);
 201 void               nautilus_directory_file_monitor_remove      (NautilusDirectory         *directory,
 202                                                                 gconstpointer              client);
 203 void               nautilus_directory_force_reload             (NautilusDirectory         *directory);
 204
 205 /* Get a list of all files currently known in the directory. */
 206 GList *            nautilus_directory_get_file_list            (NautilusDirectory         *directory);
 207
 208 GList *            nautilus_directory_match_pattern            (NautilusDirectory         *directory,
 209                                                                 const char *glob);
 210
 211
 212 /* Return true if the directory has information about all the files.
 213  * This will be false until the directory has been read at least once.
 214  */
 215 gboolean           nautilus_directory_are_all_files_seen       (NautilusDirectory         *directory);
 216
 217 /* Return true if the directory is local. */
 218 gboolean           nautilus_directory_is_local                 (NautilusDirectory         *directory);
 219
 220 gboolean           nautilus_directory_is_in_trash              (NautilusDirectory         *directory);
 221
 222 /* Return false if directory contains anything besides a Nautilus metafile.
 223  * Only valid if directory is monitored. Used by the Trash monitor.
 224  */
 225 gboolean           nautilus_directory_is_not_empty             (NautilusDirectory         *directory);
 226 gboolean           nautilus_directory_file_list_length_reached (NautilusDirectory         *directory);
 227
 228 /* Convenience functions for dealing with a list of NautilusDirectory objects that each have a ref.
 229  * These are just convenient names for functions that work on lists of GtkObject *.
 230  */
 231 GList *            nautilus_directory_list_ref                 (GList                     *directory_list);
 232 void               nautilus_directory_list_unref               (GList                     *directory_list);
 233 void               nautilus_directory_list_free                (GList                     *directory_list);
 234 GList *            nautilus_directory_list_copy                (GList                     *directory_list);
 235 GList *            nautilus_directory_list_sort_by_uri         (GList                     *directory_list);
 236
 237 /* Fast way to check if a directory is the desktop directory */
 238 gboolean           nautilus_directory_is_desktop_directory     (NautilusDirectory         *directory);
 239
 240 gboolean           nautilus_directory_is_editable              (NautilusDirectory         *directory);
 241
 242
 243 #endif /* NAUTILUS_DIRECTORY_H */