libs/gtkmm2/gtk/gtkmm/recentinfo.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_RECENTINFO_H
   4 #define _GTKMM_RECENTINFO_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* Copyright (C) 2006 The gtkmm Development Team
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Library General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Library General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Library General Public
  22  * License along with this library; if not, write to the Free
  23  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24  */
  25
  26 #include <gdkmm/pixbuf.h>
  27
  28 #include <time.h>
  29
  30
  31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  32 typedef struct _GtkRecentInfo GtkRecentInfo;
  33 #endif //DOXYGEN_SHOULD_SKIP_THIS
  34
  35 namespace Gtk
  36 {
  37
  38
  39 /** Contains informations found when looking up an entry of the
  40  * recently used files list.
  41  *
  42  * @newin2p10
  43  *
  44  * @ingroup RecentFiles
  45  */
  46 class RecentInfo
  47 {
  48   public:
  49 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  50   typedef RecentInfo CppObjectType;
  51   typedef GtkRecentInfo BaseObjectType;
  52 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  53
  54
  55   // For use with Glib::RefPtr<> only.
  56   void reference()   const;
  57   void unreference() const;
  58
  59   ///Provides access to the underlying C instance.
  60   GtkRecentInfo*       gobj();
  61
  62   ///Provides access to the underlying C instance.
  63   const GtkRecentInfo* gobj() const;
  64
  65   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
  66   GtkRecentInfo* gobj_copy() const;
  67
  68 protected:
  69   // Do not derive this.  Gtk::RecentInfo can neither be constructed nor deleted.
  70   RecentInfo();
  71   void operator delete(void*, size_t);
  72
  73 private:
  74   // noncopyable
  75   RecentInfo(const RecentInfo&);
  76   RecentInfo& operator=(const RecentInfo&);
  77
  78
  79 public:
  80
  81   bool equal(const RecentInfo& other) const;
  82   /// Tests whether the RecentInfo is valid.
  83   operator bool() const;
  84
  85
  86   /** Gets the URI of the resource.
  87    * @return The URI of the resource.  The returned string is
  88    * owned by the recent manager, and should not be freed.
  89    *
  90    * @newin2p10.
  91    */
  92   Glib::ustring get_uri() const;
  93
  94   /** Gets the name of the resource.  If none has been defined, the basename
  95    * of the resource is obtained.
  96    * @return The display name of the resource.  The returned string
  97    * is owned by the recent manager, and should not be freed.
  98    *
  99    * @newin2p10.
 100    */
 101   Glib::ustring get_display_name() const;
 102
 103   /** Gets the (short) description of the resource.
 104    * @return The description of the resource.  The returned string
 105    * is owned by the recent manager, and should not be freed.
 106    *
 107    * @newin2p10.
 108    */
 109   Glib::ustring get_description() const;
 110
 111   /** Gets the MIME type of the resource.
 112    * @return The MIME type of the resource.  The returned string
 113    * is owned by the recent manager, and should not be freed.
 114    *
 115    * @newin2p10.
 116    */
 117   Glib::ustring get_mime_type() const;
 118
 119
 120   /** Gets the timestamp (seconds from system's Epoch) when the resource
 121    * was added to the recently used resources list.
 122    * @return The number of seconds elapsed from system's Epoch when
 123    * the resource was added to the list, or -1 on failure.
 124    *
 125    * @newin2p10.
 126    */
 127   time_t get_added() const;
 128
 129   /** Gets the timestamp (seconds from system's Epoch) when the resource
 130    * was last modified.
 131    * @return The number of seconds elapsed from system's Epoch when
 132    * the resource was last modified, or -1 on failure.
 133    *
 134    * @newin2p10.
 135    */
 136   time_t get_modified() const;
 137
 138   /** Gets the timestamp (seconds from system's Epoch) when the resource
 139    * was last visited.
 140    * @return The number of seconds elapsed from system's Epoch when
 141    * the resource was last visited, or -1 on failure.
 142    *
 143    * @newin2p10.
 144    */
 145   time_t get_visited() const;
 146
 147
 148   /** Gets the value of the "private" flag.  Resources in the recently used
 149    * list that have this flag set to <tt>true</tt> should only be displayed by the
 150    * applications that have registered them.
 151    * @return <tt>true</tt> if the private flag was found, <tt>false</tt> otherwise.
 152    *
 153    * @newin2p10.
 154    */
 155   bool get_private_hint() const;
 156
 157
 158   /** Gets the data regarding the application that has registered the resource
 159    * pointed by @a info .
 160    *
 161    * If the command line contains any escape characters defined inside the
 162    * storage specification, they will be expanded.
 163    * @param app_name The name of the application that has registered this item.
 164    * @param app_exec Return location for the string containing the command line.
 165    * @param count Return location for the number of times this item was registered.
 166    * @param time Return location for the timestamp this item was last registered
 167    * for this application.
 168    * @return <tt>true</tt> if an application with @a app_name  has registered this
 169    * resource inside the recently used list, or <tt>false</tt> otherwise.  You should
 170    * free the returned command line using Glib::free().
 171    *
 172    * @newin2p10.
 173    */
 174   bool get_application_info(const Glib::ustring& app_name, Glib::StringArrayHandle& app_exec, guint& count, time_t& time) const;
 175   Glib::StringArrayHandle get_applications() const;
 176
 177   //_WRAP_METHOD(Glib::StringArrayHandle get_applications(unsigned& length) const, gtk_recent_info_get_applications)
 178
 179   /** Gets the name of the last application that have registered the
 180    * recently used resource represented by @a info .
 181    * @return An application name.  Use Glib::free() to free it.
 182    *
 183    * @newin2p10.
 184    */
 185   Glib::ustring last_application() const;
 186
 187   /** Checks whether an application registered this resource using @a app_name .
 188    * @param app_name A string containing an application name.
 189    * @return <tt>true</tt> if an application with name @a app_name  was found,
 190    * <tt>false</tt> otherwise.
 191    *
 192    * @newin2p10.
 193    */
 194   bool has_application(const Glib::ustring& app_name) const;
 195
 196   Glib::StringArrayHandle get_groups() const;
 197
 198   //_WRAP_METHOD(Glib::StringArrayHandle get_groups(unsigned& length) const, gtk_recent_info_get_groups)
 199
 200   /** Checks whether @a group_name  appears inside the groups registered for the
 201    * recently used item @a info .
 202    * @param group_name Name of a group.
 203    * @return <tt>true</tt> if the group was found.
 204    *
 205    * @newin2p10.
 206    */
 207   bool has_group(const Glib::ustring& group) const;
 208
 209
 210   /** Retrieves the icon of size @a size  associated to the resource MIME type.
 211    * @param size The size of the icon in pixels.
 212    * @return A Gdk::Pixbuf containing the icon, or <tt>0</tt>.
 213    *
 214    * @newin2p10.
 215    */
 216   Glib::RefPtr<Gdk::Pixbuf> get_icon(int size);
 217
 218   /** Retrieves the icon of size @a size  associated to the resource MIME type.
 219    * @param size The size of the icon in pixels.
 220    * @return A Gdk::Pixbuf containing the icon, or <tt>0</tt>.
 221    *
 222    * @newin2p10.
 223    */
 224   Glib::RefPtr<const Gdk::Pixbuf> get_icon(int size) const;
 225
 226
 227   /** Computes a valid UTF-8 string that can be used as the name of the item in a
 228    * menu or list.  For example, calling this function on an item that refers to
 229    * "file:///foo/bar.txt" will yield "bar.txt".
 230    * @return A newly-allocated string in UTF-8 encoding; free it with
 231    * Glib::free().
 232    *
 233    * @newin2p10.
 234    */
 235   Glib::ustring get_short_name() const;
 236
 237   /** Gets a displayable version of the resource's URI.  If the resource
 238    * is local, it returns a local path; if the resource is not local,
 239    * it returns the UTF-8 encoded content of gtk_recent_info_get_uri().
 240    * @return A UTF-8 string containing the resource's URI or <tt>0</tt>
 241    *
 242    * @newin2p10.
 243    */
 244   Glib::ustring get_uri_display() const;
 245
 246
 247   /** Gets the number of days elapsed since the last update of the resource
 248    * pointed by @a info .
 249    * @return A positive integer containing the number of days elapsed
 250    * since the time this resource was last modified.
 251    *
 252    * @newin2p10.
 253    */
 254   int get_age() const;
 255
 256   /** Checks whether the resource is local or not by looking at the
 257    * scheme of its URI.
 258    * @return <tt>true</tt> if the resource is local.
 259    *
 260    * @newin2p10.
 261    */
 262   bool is_local() const;
 263
 264   /** Checks whether the resource pointed by @a info  still exists.  At
 265    * the moment this check is done only on resources pointing to local files.
 266    * @return <tt>true</tt> if the resource exists
 267    *
 268    * @newin2p10.
 269    */
 270   bool exists() const;
 271
 272
 273   //_WRAP_METHOD(bool match(const RecentInfo& b) const, gtk_recent_info_match)
 274
 275
 276 };
 277
 278
 279 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 280
 281 struct RecentInfoTraits
 282 {
 283   typedef Glib::RefPtr<RecentInfo> CppType;
 284   typedef const GtkRecentInfo* CType;
 285   typedef GtkRecentInfo* CTypeNonConst;
 286
 287   static CType to_c_type(const CppType& obj) { return Glib::unwrap(obj); }
 288   static CType to_c_type(const CType& obj) { return obj; }
 289   static CppType to_cpp_type(const CType& obj); //Implemented in the .cpp file
 290   static void release_c_type(const CType& /* obj */) { /* gtk_recent_info_unref(const_cast<CTypeNonConst>(obj)); */}
 291 };
 292 #endif
 293
 294 //TODO: We normally put these inside the class:
 295
 296 /** @relates Gtk::RecentInfo */
 297 inline bool operator==(const RecentInfo& lhs, const RecentInfo& rhs)
 298   { return lhs.equal(rhs); }
 299
 300 /** @relates Gtk::RecentInfo */
 301 inline bool operator!=(const RecentInfo& lhs, const RecentInfo& rhs)
 302   { return !lhs.equal(rhs); }
 303
 304 } // namespace Gtk
 305
 306
 307 namespace Glib
 308 {
 309
 310   /** A Glib::wrap() method for this object.
 311    *
 312    * @param object The C instance.
 313    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 314    * @result A C++ instance that wraps this C instance.
 315    *
 316    * @relates Gtk::RecentInfo
 317    */
 318   Glib::RefPtr<Gtk::RecentInfo> wrap(GtkRecentInfo* object, bool take_copy = false);
 319
 320 } // namespace Glib
 321
 322
 323 #endif /* _GTKMM_RECENTINFO_H */
 324