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)
61 · $uri (string)
62 · $name (string or undef)
64 · $exec (string or undef)
66 Adds the application with $name and $exec to the list of applications
68 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 the
73 bookmark has been registered by the application and the last time the
74 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 by
79 Glib::get_prgname() and the "%u" modifier, which will be expanded to
80 the bookmark's URI.
81 This function will automatically take care of updating the
83 registrations 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)
89 · $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)
97 $bookmark_file->set_added ($uri, $value)
99 · $uri (string)
100 · $value (unix timestamp)
102 Sets the time the bookmark for $uri was added. If no bookmark for $uri
104 is found one is created.
105 ($exec, $count, $stamp) = $bookmark_file->get_app_info ($uri, $name)
107 · $uri (string)
108 · $name (string)
110 Gets the registration information of $name for the bookmark for $uri.
112 See Glib::BookmarkFile::set_app_info() for more information about the
113 returned data.
114 May croak with a Glib::Error in $@ on failure.
116 $bookmark_file->set_app_info ($uri, $name, $exec, $count, $stamp)
118 · $uri (string)
119 · $name (string)
121 · $exec (string)
123 · $count (integer)
125 · $stamp (unix timestamp)
127 Sets the meta-data of application $name inside the list of applications
129 that have registered a bookmark for $uri inside $bookmark_file.
130 You should rarely use this method; use
132 Glib::BookmarkFile::add_application() and
133 Glib::BookmarkFile::remove_application() instead.
134 $name can be any UTF-8 encoded string used to identify an application.
136 $exec can have one of these two modifiers: "%f", which will be expanded
137 as the local file name retrieved from the bookmark's URI; "%u", which
138 will be expanded as the bookmark's URI. The expansion is done
139 automatically when retrieving the stored command line using the
140 Glib::BookmarkFile::get_app_info() method. $count is the number of
141 times the application has registered the bookmark; if it is < 0, the
142 current registration count will be increased by one, if it is 0, the
143 application with $name will be removed from the list of registered
144 applications. $stamp is the Unix time of the last registration, as
145 returned by time(); if it is -1, the current time will be used.
146 If you try to remove an application by setting its registration count
148 to zero, and no bookmark for $uri is found, %FALSE is returned and an
149 exception is fired.
150 May croak with a Glib::Error in $@ on failure.
152 list = $bookmark_file->get_applications ($uri)
154 · $uri (string)
155 Retrieves the names of the applications that have registered the
157 bookmark for $uri.
158 May croak with a Glib::Error in $@ on failure.
160 $bookmark_file->get_description ($uri)
162 · $uri (string)
163 Gets the description of the bookmark for $uri.
165 May croak with a Glib::Error in $@ on failure.
167 $bookmark_file->set_description ($uri, $description)
169 · $uri (string)
170 · $description (string)
172 Sets the description of the bookmark for $uri. If no bookmark for $uri
174 is found one is created.
175 list = $bookmark_file->get_groups ($uri)
177 · $uri (string)
178 Retrieves the list of group names of the bookmark for $uri.
180 May croak with a Glib::Error in $@ on failure.
182 $bookmark_file->set_groups ($uri, ...)
184 · $uri (string)
185 · ... (list) one or more group names
187 Sets a list of group names for the item with URI $uri. Each previously
189 set group name list is removed. If no bookmark for $uri is found one
190 is created.
191 boolean = $bookmark_file->has_application ($uri, $name)
193 · $uri (string)
194 · $name (string)
196 Checks whether the bookmark for $uri inside $bookmark_file has been
198 registered by application $name.
199 May croak with a Glib::Error in $@ on failure.
201 boolean = $bookmark_file->has_group ($uri, $group)
203 · $uri (string)
204 · $group (string)
206 Checks whether $group appears in the list of groups to which the
208 bookmark for $uri belongs to.
209 May croak with a Glib::Error in $@ on failure.
211 boolean = $bookmark_file->has_item ($uri)
213 · $uri (string)
214 Looks whether the bookmark file has a bookmark for $uri.
216 ($href, $mime_type) = $bookmark_file->get_icon ($uri)
218 · $uri (string)
219 Gets the icon of the bookmark for $uri.
221 May croak with a Glib::Error in $@ on failure.
223 $bookmark_file->set_icon ($uri, $href, $mime_type)
225 · $uri (string)
226 · $href (string or undef)
228 · $mime_type (string or undef)
230 Sets the icon for the bookmark for $uri. If $href is undef, unsets the
232 currently set icon.
233 boolean = $bookmark_file->get_is_private ($uri)
235 · $uri (string)
236 May croak with a Glib::Error in $@ on failure.
238 $bookmark_file->set_is_private ($uri, $is_private)
240 · $uri (string)
241 · $is_private (boolean)
243 $bookmark_file->load_from_data ($buf)
245 · $buf (scalar)
246 Parses a string containing a bookmark file structure.
248 May croak with a Glib::Error in $@ on failure.
250 ($full_path) = $bookmark_file->load_from_data_dirs ($file)
252 · $file (localized file name)
253 Parses a bookmark file, searching for it inside the data directories.
255 If a file is found, it returns the full path.
256 May croak with a Glib::Error in $@ on failure.
258 $bookmark_file->load_from_file ($file)
260 · $file (localized file name)
261 Parses a bookmark file.
263 May croak with a Glib::Error in $@ on failure.
265 string = $bookmark_file->get_mime_type ($uri)
267 · $uri (string)
268 Gets the MIME type of the bookmark for $uri.
270 May croak with a Glib::Error in $@ on failure.
272 $bookmark_file->set_mime_type ($uri, $mime_type)
274 · $uri (string)
275 · $mime_type (string)
277 Sets the MIME type of the bookmark for $uri. If no bookmark for $uri
279 is found one is created.
280 unix timestamp = $bookmark_file->get_modified ($uri)
282 · $uri (string)
283 $bookmark_file->set_modified ($uri, $value)
285 · $uri (string)
286 · $value (unix timestamp)
288 Sets the time the bookmark for $uri was last modified. If no bookmark
290 for $uri is found one is created.
291 $bookmark_file->move_item ($old_uri, $new_uri)
293 · $old_uri (string)
294 · $new_uri (string or undef)
296 Changes the URI of a bookmark item from $old_uri to $new_uri. Any
298 existing bookmark for $new_uri will be overwritten. If $new_uri is
299 undef, then the bookmark is removed.
300 May croak with a Glib::Error in $@ on failure.
302 $bookmark_file->remove_application ($uri, $name)
304 · $uri (string)
305 · $name (string)
307 Removes application registered with $name from the list of applications
309 that have registered a bookmark for $uri inside $bookmark_file.
310 May croak with a Glib::Error in $@ on failure.
312 $bookmark_file->remove_group ($uri, $group)
314 · $uri (string)
315 · $group (string)
317 Removes $group from the list of groups to which the bookmark for $uri
319 belongs to.
320 May croak with a Glib::Error in $@ on failure.
322 $bookmark_file->remove_item ($uri)
324 · $uri (string)
325 Removes the bookmark for $uri from the bookmark file.
327 May croak with a Glib::Error in $@ on failure.
329 integer = $bookmark_file->get_size
331 Gets the number of bookmarks inside the bookmark file.
332 $bookmark_file->get_title ($uri, $title)
334 · $uri (string)
335 Gets the title of the bookmark for $uri.
337 May croak with a Glib::Error in $@ on failure.
339 $bookmark_file->set_title ($uri, $title)
341 · $uri (string)
342 · $title (string)
344 Sets the title of the bookmark for $uri. If no bookmark for $uri is
346 found one is created.
347 string = $bookmark_file->to_data
349 Returns the bookmark file as a string.
350 May croak with a Glib::Error in $@ on failure.
352 $bookmark_file->to_file ($file)
354 · $file (localized file name)
355 Saves the contents of a bookmark file into a file. The write operation
357 is guaranteed to be atomic by writing the contents of the bookmark file
358 to a temporary file and then moving the file to the target file.
359 May croak with a Glib::Error in $@ on failure.
361 list = $bookmark_file->get_uris
363 Returns the URI of all the bookmarks in the bookmark file.
364 unix timestamp = $bookmark_file->get_visited ($uri)
366 · $uri (string)
367 $bookmark_file->set_visited ($uri, $value)
369 · $uri (string)
370 · $value (unix timestamp)
372 Sets the time the bookmark for $uri was last visited. If no bookmark
374 for $uri is found one is created.
375
377 Glib
378
380 Copyright (C) 2003-2011 by the gtk2-perl team.
381 This software is licensed under the LGPL. See Glib for a full notice.
383perl v5.28.0 2018-10-04 Glib::BookmarkFile(3)