1Glib::BookmarkFile(3) User Contributed Perl DocumentationGlib::BookmarkFile(3)
2
6 Glib::BookmarkFile - Parser for bookmark files
7
9 use Glib;
10 $date .= $_ while (<DATA>);
12 $b = Glib::BookmarkFile->new;
14 $b->load_from_data($data);
15 $uri = 'file:///some/path/to/a/file.txt';
16 if ($b->has_item($uri)) {
17 $title = $b->get_title($uri);
18 $desc = $b->get_description($uri);
19 print "Bookmark for `$uri' ($title):\n";
21 print " $desc\n";
22 }
23 0;
24 __DATA__
26 <?xml version="1.0" encoding="UTF-8"?>
27 <xbel version="1.0"
28 xmlns:bookmark="http://www.freedesktop.org/standards/desktop-bookmarks"
29 xmlns:mime="http://www.freedesktop.org/standards/shared-mime-info">
30 <bookmark href="file:///tmp/test-file.txt" added="2006-03-22T18:54:00Z" modified="2006-03-22T18:54:00Z" visited="2006-03-22T18:54:00Z">
31 <title>Test File</title>
32 <desc>Some test file</desc>
33 <info>
34 <metadata owner="http://freedesktop.org">
35 <mime:mime-type type="text/plain"/>
36 <bookmark:applications>
37 <bookmark:application name="Gedit" exec="gedit %u" timestamp="1143053640" count="1"/>
38 </bookmark:applications>
39 </metadata>
40 </info>
41 </bookmark>
42 </xbel>
43
45 Glib::BookmarkFile lets you parse, edit or create files containing
46 lists of bookmarks to resources pointed to by URIs, with some meta-data
47 bound to them, following the Desktop Bookmark Specification. The
48 recent files support inside GTK+ uses this type of files to store the
49 list of recently used files.
50 The syntax of bookmark files is described in detail in the Desktop
52 Bookmarks Specification, here is a quick summary: bookmark files use a
53 subclass of the XML Bookmark Exchange Language (XBEL) document format,
54 defining meta-data such as the MIME type of the resource pointed by a
55 bookmark, the list of applications that have registered the same URI
56 and the visibility of the bookmark.
57
59 bookmarkfile = Glib::BookmarkFile->new
60 $bookmark_file->add_application ($uri, $name, $exec)
62 * $uri (string)
64 * $name (string or undef)
65 * $exec (string or undef)
66 Adds the application with $name and $exec to the list of applica‐
68 tions that have registered a bookmark for $uri into $bookmark_file.
69 Every bookmark inside a "Glib::BookmarkFile" must have at least an
71 application registered. Each application must provide a name, a
72 command line useful for launching the bookmark, the number of times
73 the bookmark has been registered by the application and the last
74 time the application registered this bookmark.
75 If $name is undef, the name of the application will be the same
77 returned by Glib::get_application_name(); if $exec is undef, the
78 command line will be a composition of the program name as returned
79 by Glib::get_prgname() and the "%u" modifier, which will be
80 expanded to the bookmark's URI.
81 This function will automatically take care of updating the regis‐
83 trations count and timestamping in case an application with the
84 same $name had already registered a bookmark for $uri inside the
85 bookmark file. If no bookmark for $uri is found one is created.
86 $bookmark_file->add_group ($uri, $group)
88 * $uri (string)
90 * $group (string)
91 Adds $group to the list of groups to which the bookmark for $uri
93 belongs to. If no bookmark for $uri is found one is created.
94 unix timestamp = $bookmark_file->get_added ($uri)
96 * $uri (string)
98 Glib::BookmarkFile::set_added ($bookmark_file, $uri, $value)
100 * $bookmark_file (Glib::BookmarkFile)
102 * $uri (string)
103 * $value (unix timestamp)
104 Sets the time the bookmark for $uri was added. If no bookmark for
106 $uri is found one is created.
107 ($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)
109 * $uri (string)
111 * $name (string)
112 Gets the registration informations of $name for the bookmark for
114 $uri. See Glib::BookmarkFile::set_app_info() for more informations
115 about the returned data.
116 May croak with a Glib::Error in $@ on failure.
118 $bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)
120 * $uri (string)
122 * $name (string)
123 * $exec (string)
124 * $count (integer)
125 * $stamp (unix timestamp)
126 Sets the meta-data of application $name inside the list of applica‐
128 tions that have registered a bookmark for $uri inside $book‐
129 mark_file.
130 You should rarely use this method; use Glib::Bookmark‐
132 File::add_application() and Glib::BookmarkFile::remove_applica‐
133 tion() instead.
134 $name can be any UTF-8 encoded string used to identify an applica‐
136 tion. $exec can have one of these two modifiers: "%f", which will
137 be expanded as the local file name retrieved from the bookmark's
138 URI; "%u", which will be expanded as the bookmark's URI. The expan‐
139 sion is done automatically when retrieving the stored command line
140 using the Glib::BookmarkFile::get_app_info() method. $count is the
141 number of times the application has registered the bookmark; if it
142 is < 0, the current registration count will be increased by one, if
143 it is 0, the application with $name will be removed from the list
144 of registered applications. $stamp is the Unix time of the last
145 registration, as returned by time(); if it is -1, the current time
146 will be used.
147 If you try to remove an application by setting its registration
149 count to zero, and no bookmark for $uri is found, %FALSE is
150 returned and an exception is fired.
151 May croak with a Glib::Error in $@ on failure.
153 list = $bookmark_file->get_applications ($uri)
155 * $uri (string)
157 Retrieves the names of the applications that have registered the
159 bookmark for $uri.
160 May croak with a Glib::Error in $@ on failure.
162 $bookmark_file->get_description ($uri)
164 * $uri (string)
166 Gets the description of the bookmark for $uri.
168 May croak with a Glib::Error in $@ on failure.
170 $bookmark_file->set_description ($uri, $description)
172 * $uri (string)
174 * $description (string)
175 Sets the description of the bookmark for $uri. If no bookmark for
177 $uri is found one is created.
178 list = $bookmark_file->get_groups ($uri)
180 * $uri (string)
182 Retrieves the list of group names of the bookmark for $uri.
184 May croak with a Glib::Error in $@ on failure.
186 $bookmark_file->set_groups ($uri, ...)
188 * $uri (string)
190 * ... (list) one or more group names
191 Sets a list of group names for the item with URI $uri. Each previ‐
193 ously set group name list is removed. If no bookmark for $uri is
194 found one is created.
195 boolean = $bookmark_file->has_application ($uri, $name)
197 * $uri (string)
199 * $name (string)
200 Checks whether the bookmark for $uri inside $bookmark_file has been
202 registered by application $name.
203 May croak with a Glib::Error in $@ on failure.
205 boolean = $bookmark_file->has_group ($uri, $group)
207 * $uri (string)
209 * $group (string)
210 Checks whether $group appears in the list of groups to which the
212 bookmark for $uri belongs to.
213 May croak with a Glib::Error in $@ on failure.
215 boolean = $bookmark_file->has_item ($uri)
217 * $uri (string)
219 Looks whether the bookmark file has a bookmark for $uri.
221 ($href, $mime_type) = $bookmark_file->get_icon ($uri)
223 * $uri (string)
225 Gets the icon of the bookmark for $uri.
227 May croak with a Glib::Error in $@ on failure.
229 $bookmark_file->set_icon ($uri, $href, $mime_type)
231 * $uri (string)
233 * $href (string or undef)
234 * $mime_type (string or undef)
235 Sets the icon for the bookmark for $uri. If $href is undef, unsets
237 the currently set icon.
238 boolean = $bookmark_file->get_is_private ($uri)
240 * $uri (string)
242 May croak with a Glib::Error in $@ on failure.
244 $bookmark_file->set_is_private ($uri, $is_private)
246 * $uri (string)
248 * $is_private (boolean)
249 $bookmark_file->load_from_data ($buf)
251 * $buf (scalar)
253 Parses a string containing a bookmark file structure.
255 May croak with a Glib::Error in $@ on failure.
257 ($full_path) = $bookmark_file->load_from_data_dirs ($file)
259 * $file (localized file name)
261 Parses a bookmark file, searching for it inside the data directo‐
263 ries. If a file is found, it returns the full path.
264 May croak with a Glib::Error in $@ on failure.
266 $bookmark_file->load_from_file ($file)
268 * $file (localized file name)
270 Parses a bookmark file.
272 May croak with a Glib::Error in $@ on failure.
274 string = $bookmark_file->get_mime_type ($uri)
276 * $uri (string)
278 Gets the MIME type of the bookmark for $uri.
280 May croak with a Glib::Error in $@ on failure.
282 $bookmark_file->set_mime_type ($uri, $mime_type)
284 * $uri (string)
286 * $mime_type (string)
287 Sets the MIME type of the bookmark for $uri. If no bookmark for
289 $uri is found one is created.
290 unix timestamp = $bookmark_file->get_modified ($uri)
292 * $uri (string)
294 Glib::BookmarkFile::set_modified ($bookmark_file, $uri, $value)
296 * $bookmark_file (Glib::BookmarkFile)
298 * $uri (string)
299 * $value (unix timestamp)
300 Sets the time the bookmark for $uri was last modified. If no book‐
302 mark for $uri is found one is created.
303 $bookmark_file->move_item ($old_uri, $new_uri)
305 * $old_uri (string)
307 * $new_uri (string or undef)
308 Changes the URI of a bookmark item from $old_uri to $new_uri. Any
310 existing bookmark for $new_uri will be overwritten. If $new_uri is
311 undef, then the bookmark is removed.
312 May croak with a Glib::Error in $@ on failure.
314 $bookmark_file->remove_application ($uri, $name)
316 * $uri (string)
318 * $name (string)
319 Removes application registered with $name from the list of applica‐
321 tions that have registered a bookmark for $uri inside $book‐
322 mark_file.
323 May croak with a Glib::Error in $@ on failure.
325 $bookmark_file->remove_group ($uri, $group)
327 * $uri (string)
329 * $group (string)
330 Removes $group from the list of groups to which the bookmark for
332 $uri belongs to.
333 May croak with a Glib::Error in $@ on failure.
335 $bookmark_file->remove_item ($uri)
337 * $uri (string)
339 Removes the bookmark for $uri from the bookmark file.
341 May croak with a Glib::Error in $@ on failure.
343 integer = $bookmark_file->get_size
345 Gets the number of bookmarks inside the bookmark file.
347 $bookmark_file->get_title ($uri, $title)
349 * $uri (string)
351 Gets the title of the bookmark for $uri.
353 May croak with a Glib::Error in $@ on failure.
355 $bookmark_file->set_title ($uri, $title)
357 * $uri (string)
359 * $title (string)
360 Sets the title of the bookmark for $uri. If no bookmark for $uri
362 is found one is created.
363 string = $bookmark_file->to_data
365 Returns the bookmark file as a string.
367 May croak with a Glib::Error in $@ on failure.
369 $bookmark_file->to_file ($file)
371 * $file (localized file name)
373 Saves the contents of a bookmark file into a file. The write oper‐
375 ation is guaranteed to be atomical by writing the contents of the
376 bookmark file to a temporary file and then moving the file to the
377 target file.
378 May croak with a Glib::Error in $@ on failure.
380 list = $bookmark_file->get_uris
382 Returns the URI of all the bookmarks in the bookmark file.
384 unix timestamp = $bookmark_file->get_visited ($uri)
386 * $uri (string)
388 Glib::BookmarkFile::set_visited ($bookmark_file, $uri, $value)
390 * $bookmark_file (Glib::BookmarkFile)
392 * $uri (string)
393 * $value (unix timestamp)
394 Sets the time the bookmark for $uri was last visited. If no book‐
396 mark for $uri is found one is created.
397
399 Glib
400
402 Copyright (C) 2003-2007 by the gtk2-perl team.
403 This software is licensed under the LGPL. See Glib for a full notice.
405perl v5.8.8 2007-02-26 Glib::BookmarkFile(3)