1 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Long_Description ##### -->
3 The "GDesktopEntry" parser is intended to parse files written to
5 url="http://www.freedesktop.org/Standards/desktop-entry-spec">Desktop
6 Entry Specification</ulink>. It supports deserialization of
7 desktop entries from files and in-memory data. Desktop entries
8 are used for a variety of things including menus, application
9 MIME type registration, and launchers.
13 To load an existing desktop entry from a data directory (as
14 returned by g_get_user_data_dir() and g_get_system_data_dirs())
15 use g_desktop_entry_new_from_data_dirs(). To load an existing
16 desktop entry from an arbitrary location on the file system use
17 g_desktop_entry_new_from_file(). If the desktop entry is already
18 in memory use g_desktop_entry_new_from_data(). Once the desktop
19 entry is loaded its keys can be queried using the g_desktop_entry_get
24 To create a new desktop entry first call g_desktop_entry_new().
25 Then, call the g_desktop_entry_set family of functions. Next,
26 call g_desktop_entry_to_data() to output the desktop entry to
27 a byte array, which can be written to disk or sent over a
28 network. Finally, call g_desktop_entry_free() to deallocate the
29 #GDesktopEntry object returned by g_desktop_entry_new().
33 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:See_Also ##### -->
39 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Short_Description ##### -->
40 serializes and deserializes a desktop entry.
43 <!-- ##### SECTION ./tmpl/desktop_entry.sgml:Title ##### -->
47 <!-- ##### SECTION ./tmpl/glib-unused.sgml:Stability_Level ##### -->
51 <!-- ##### SECTION ./tmpl/testutils.sgml:Long_Description ##### -->
57 <!-- ##### SECTION ./tmpl/testutils.sgml:See_Also ##### -->
63 <!-- ##### SECTION ./tmpl/testutils.sgml:Short_Description ##### -->
67 <!-- ##### SECTION ./tmpl/testutils.sgml:Stability_Level ##### -->
71 <!-- ##### SECTION ./tmpl/testutils.sgml:Title ##### -->
75 <!-- ##### ENUM GChannelError ##### -->
80 @G_CHANNEL_ERROR_ACCES:
81 @G_CHANNEL_ERROR_BADF:
82 @G_CHANNEL_ERROR_DEADLK:
83 @G_CHANNEL_ERROR_FAULT:
84 @G_CHANNEL_ERROR_INVAL:
86 @G_CHANNEL_ERROR_ISDIR:
87 @G_CHANNEL_ERROR_MFILE:
88 @G_CHANNEL_ERROR_NOLCK:
89 @G_CHANNEL_ERROR_NOSPC:
90 @G_CHANNEL_ERROR_PERM:
91 @G_CHANNEL_ERROR_PIPE:
92 @G_CHANNEL_ERROR_SPIPE:
93 @G_CHANNEL_ERROR_ENCODE_RW:
94 @G_CHANNEL_ERROR_FAILED:
96 <!-- ##### ENUM GChannelStatus ##### -->
101 @G_CHANNEL_STATUS_NORMAL:
102 @G_CHANNEL_STATUS_EOF:
103 @G_CHANNEL_STATUS_PARTIAL_CHARS:
104 @G_CHANNEL_STATUS_AGAIN:
105 @G_CHANNEL_STATUS_INTR:
106 @G_CHANNEL_STATUS_ERROR:
107 @G_CHANNEL_STATUS_BAD_INPUT:
109 <!-- ##### USER_FUNCTION GCompareFuncData ##### -->
119 <!-- ##### USER_FUNCTION GCompletionStrcmpFunc ##### -->
128 <!-- ##### STRUCT GDesktopEntry ##### -->
134 <!-- ##### ENUM GDesktopEntryError ##### -->
136 Error codes returned by desktop entry parsing.
139 @G_DESKTOP_ENTRY_ERROR_UNKNOWN_ENCODING: text being parsed is not UTF-8 and
141 @G_DESKTOP_ENTRY_ERROR_BAD_START_GROUP: desktop entry does not start with a
143 @G_DESKTOP_ENTRY_ERROR_PARSE: desktop entry is empty or contains invalid
145 @G_DESKTOP_ENTRY_ERROR_NOT_FOUND: valid desktop entry could not be found.
146 @G_DESKTOP_ENTRY_ERROR_KEY_NOT_FOUND: desktop entry does not have requested
148 @G_DESKTOP_ENTRY_ERROR_GROUP_NOT_FOUND: desktop entry does not have requested
150 @G_DESKTOP_ENTRY_ERROR_INVALID_VALUE: desktop entry contains key which has
151 value that cannot be validated.
153 <!-- ##### ENUM GDesktopEntryFlags ##### -->
155 #GDesktopEntry supports a few flags for tweaking performance during
156 deserialization. #G_DESKTOP_ENTRY_DISCARD_COMMENTS and
157 #G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS will reduce memory footprint,
158 and #G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP will increase key lookup speed.
161 @G_DESKTOP_ENTRY_NONE: use parser defaults
162 @G_DESKTOP_ENTRY_DISCARD_COMMENTS: Discard all lines that are blank
164 @G_DESKTOP_ENTRY_DISCARD_TRANSLATIONS: Only retain translations that
165 are returned by g_get_language_names().
166 @G_DESKTOP_ENTRY_GENERATE_LOOKUP_MAP: Generate a lookup map for key names to make lookups constant time at the cost of more memory.
168 <!-- ##### USER_FUNCTION GErrorFunc ##### -->
170 Specifies the type of function passed to g_set_error_handler().
173 @str: the error message.
175 <!-- ##### USER_FUNCTION GHookFreeFunc ##### -->
183 <!-- ##### ENUM GIOFileMode ##### -->
188 @G_IO_FILE_MODE_READ:
189 @G_IO_FILE_MODE_WRITE:
190 @G_IO_FILE_MODE_APPEND:
191 @G_IO_FILE_MODE_READ_WRITE:
192 @G_IO_FILE_MODE_READ_WRITE_TRUNCATE:
193 @G_IO_FILE_MODE_READ_WRITE_APPEND:
195 <!-- ##### ENUM GMatchType ##### -->
197 Enumeration representing different kinds of patterns. This is only used
198 internally for optimizing the match algorithm.
201 @G_MATCH_ALL: a general pattern.
202 @G_MATCH_ALL_TAIL: a general pattern which contains a fixed part matching
203 the end of the string.
204 @G_MATCH_HEAD: a pattern matching every string with a certain prefix.
205 @G_MATCH_TAIL: a pattern matching every string with a certain suffix.
206 @G_MATCH_EXACT: a pattern matching exactly one string.
209 <!-- ##### USER_FUNCTION GWarningFunc ##### -->
211 Specifies the type of function passed to g_set_warning_handler().
214 @str: the warning message.
216 <!-- ##### MACRO G_CHANNEL_ERROR ##### -->
222 <!-- ##### MACRO G_DESKTOP_ENTRY_ERROR ##### -->
224 Error domain for desktop entry parsing. Errors in this domain will
225 be from the #GDesktopEntryError enumeration. See #GError for information on
230 <!-- ##### MACRO G_HOOK_DEFERRED_DESTROY ##### -->
236 <!-- ##### MACRO G_IO_CHANNEL_DEFAULT_LINE_TERM ##### -->
238 One of %G_IO_CHANNEL_UNIX_LINE_TERM, %G_IO_CHANNEL_DOS_LINE_TERM,
239 or %G_IO_CHANNEL_MACINTOSH_LINE_TERM (unimplemented)
240 depending on the system type.
244 <!-- ##### MACRO G_IO_CHANNEL_DOS_LINE_TERM ##### -->
250 <!-- ##### MACRO G_IO_CHANNEL_ENCODE_RAW ##### -->
252 Encoding for nonbuffered IO. With this encoding, data must be
253 read using g_io_channel_read_chars(); the other functions will
258 <!-- ##### MACRO G_IO_CHANNEL_MACINTOSH_LINE_TERM ##### -->
264 <!-- ##### MACRO G_IO_CHANNEL_UNIX_LINE_TERM ##### -->
270 <!-- ##### MACRO NAME_MAX ##### -->
272 Provided for UNIX emulation on Windows; equivalent to UNIX macro
273 %NAME_MAX, which is the maximum length of a single path component.
274 i.e. just the <filename>foo</filename> in <filename>/usr/bin/foo</filename>.
278 <!-- ##### MACRO _ ##### -->
280 Marks a string for translation, gets replaced with the translated string
284 @String: the string to be translated
287 <!-- ##### MACRO access ##### -->
293 <!-- ##### MACRO close ##### -->
299 <!-- ##### FUNCTION closedir ##### -->
301 Provided for UNIX emulation on Windows; see documentation for <function>closedir()</function>
308 <!-- ##### MACRO fdopen ##### -->
314 <!-- ##### MACRO ftruncate ##### -->
316 Provided for UNIX emulation on Windows; see documentation for ftruncate()
323 <!-- ##### FUNCTION g_channel_error_from_errno ##### -->
331 <!-- ##### FUNCTION g_channel_error_quark ##### -->
338 <!-- ##### FUNCTION g_convert_error_quark ##### -->
345 <!-- ##### FUNCTION g_desktop_entry_escape_strings ##### -->
353 <!-- ##### FUNCTION g_desktop_entry_free ##### -->
360 <!-- ##### FUNCTION g_desktop_entry_get_boolean ##### -->
371 <!-- ##### FUNCTION g_desktop_entry_get_boolean_list ##### -->
383 <!-- ##### FUNCTION g_desktop_entry_get_groups ##### -->
392 <!-- ##### FUNCTION g_desktop_entry_get_integer ##### -->
403 <!-- ##### FUNCTION g_desktop_entry_get_integer_list ##### -->
415 <!-- ##### FUNCTION g_desktop_entry_get_keys ##### -->
426 <!-- ##### FUNCTION g_desktop_entry_get_locale_string ##### -->
438 <!-- ##### FUNCTION g_desktop_entry_get_locale_string_list ##### -->
451 <!-- ##### FUNCTION g_desktop_entry_get_start_group ##### -->
459 <!-- ##### FUNCTION g_desktop_entry_get_string ##### -->
470 <!-- ##### FUNCTION g_desktop_entry_get_string_list ##### -->
482 <!-- ##### FUNCTION g_desktop_entry_has_group ##### -->
491 <!-- ##### FUNCTION g_desktop_entry_has_key ##### -->
502 <!-- ##### FUNCTION g_desktop_entry_new ##### -->
511 <!-- ##### FUNCTION g_desktop_entry_new_from_data ##### -->
523 <!-- ##### FUNCTION g_desktop_entry_new_from_data_dirs ##### -->
535 <!-- ##### FUNCTION g_desktop_entry_new_from_file ##### -->
546 <!-- ##### FUNCTION g_desktop_entry_remove_group ##### -->
555 <!-- ##### FUNCTION g_desktop_entry_remove_key ##### -->
565 <!-- ##### FUNCTION g_desktop_entry_set_boolean ##### -->
576 <!-- ##### FUNCTION g_desktop_entry_set_boolean_list ##### -->
588 <!-- ##### FUNCTION g_desktop_entry_set_integer ##### -->
599 <!-- ##### FUNCTION g_desktop_entry_set_integer_list ##### -->
611 <!-- ##### FUNCTION g_desktop_entry_set_locale_string ##### -->
623 <!-- ##### FUNCTION g_desktop_entry_set_locale_string_list ##### -->
636 <!-- ##### FUNCTION g_desktop_entry_set_string ##### -->
647 <!-- ##### FUNCTION g_desktop_entry_set_string_list ##### -->
659 <!-- ##### FUNCTION g_desktop_entry_to_data ##### -->
669 <!-- ##### FUNCTION g_file_replace ##### -->
680 <!-- ##### FUNCTION g_format_file_size_for_display ##### -->
688 <!-- ##### FUNCTION g_io_channel_error_quark ##### -->
695 <!-- ##### VARIABLE g_log_domain_glib ##### -->
697 The log domain used for messages logged by GLib itself.
701 <!-- ##### FUNCTION g_main_add_poll ##### -->
703 Adds a file descriptor to be polled.
704 This is usually combined with g_source_add() to add an event source.
705 The event source's check function will typically test the revents
706 field in the #GPollFD struct and return TRUE if events need to be processed.
709 @fd: a #GPollFD, which is a file descriptor together with a bitwise
710 combination of #GIOCondition flags determining which events to poll for.
711 @priority: the priority of the poll, which should be the same as the priority
712 used for g_source_add() to ensure that the file descriptor is polled whenever
713 the results may be needed.
714 See #G_PRIORITY_DEFAULT, #G_PRIORITY_DEFAULT_IDLE, #G_PRIORITY_HIGH,
715 #G_PRIORITY_HIGH_IDLE, and #G_PRIORITY_LOW.
717 <!-- ##### FUNCTION g_main_context_get ##### -->
725 <!-- ##### FUNCTION g_main_loop_destroy ##### -->
732 <!-- ##### FUNCTION g_main_remove_poll ##### -->
734 Removes a file descriptor from the list being polled.
737 @fd: the #GPollFD to remove.
739 <!-- ##### FUNCTION g_main_win32_get_poll_func ##### -->
746 <!-- ##### FUNCTION g_mem_check ##### -->
748 Checks if the given memory has already been freed. If it has it outputs
750 To use this function you must configure glib with the flag
751 '--enable-mem-check=yes' before compiling.
754 @mem: the memory to check.
756 <!-- ##### FUNCTION g_regex_error_quark ##### -->
763 <!-- ##### FUNCTION g_regex_free ##### -->
770 <!-- ##### FUNCTION g_scanner_stat_mode ##### -->
772 Gets the file attributes.
773 This is the <structfield>st_mode</structfield> field from the
774 <structname>stat</structname> structure. See the <function>stat()</function>
778 @filename: the file name.
779 @Returns: the file attributes.
781 <!-- ##### FUNCTION g_set_error_handler ##### -->
783 Sets the function to be called to handle error messages.
784 This function is deprecated in favour of the new logging facilities.
787 @func: the function to be called to handle error messages.
788 @Returns: the old error handler.
790 <!-- ##### FUNCTION g_set_message_handler ##### -->
792 Sets the function to be called to handle messages.
793 This function is deprecated in favour of the new logging facilities.
796 @func: the function to be called to handle normal messages.
797 @Returns: the old message handler.
799 <!-- ##### FUNCTION g_set_warning_handler ##### -->
801 Sets the function to be called to handle warning messages.
802 This function is deprecated in favour of the new logging facilities.
805 @func: the function to be called to handle warning messages.
806 @Returns: the old warning handler.
808 <!-- ##### FUNCTION g_source_add ##### -->
822 <!-- ##### FUNCTION g_source_connect ##### -->
832 <!-- ##### FUNCTION g_source_connect_indirect ##### -->
841 <!-- ##### FUNCTION g_source_remove_by_source_data ##### -->
843 Removes the first event source found with the given source data.
846 Event sources are sorted with the highest priority first. Sources with equal
847 priority are stored in the order in which they were added.
850 @source_data: the source data, which contains information specific to the
852 @Returns: TRUE if an event source was found and removed.
854 <!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
863 <!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
873 <!-- ##### MACRO g_string ##### -->
875 Turns the argument into a string literal by using the '#' stringizing operator.
878 @x: text to convert to a literal string.
880 <!-- ##### FUNCTION g_warn_message ##### -->
891 <!-- ##### MACRO getcwd ##### -->
897 <!-- ##### MACRO getpid ##### -->
903 <!-- ##### VARIABLE glib_binary_age ##### -->
905 This is the binary age passed to <application>libtool</application>. If
906 <application>libtool</application> means nothing to you, don't worry
911 <!-- ##### FUNCTION glib_check_version ##### -->
921 <!-- ##### VARIABLE glib_interface_age ##### -->
923 This is the interface age passed to <application>libtool</application>. If
924 <application>libtool</application> means nothing to you, don't worry
929 <!-- ##### VARIABLE glib_major_version ##### -->
931 The major version number of the GLib library.
932 (e.g. in GLib version 1.2.5 this is 1.)
936 This variable is in the library, so represents the
937 GLib library you have linked against. Contrast with the
938 #GLIB_MAJOR_VERSION macro, which represents the major version of the
939 GLib headers you have included.
943 <!-- ##### VARIABLE glib_micro_version ##### -->
945 The micro version number of the GLib library.
946 (e.g. in GLib version 1.2.5 this is 5.)
950 This variable is in the library, so represents the GLib library you
951 have linked against. Contrast with the #GLIB_MICRO_VERSION macro, which
952 represents the micro version of the GLib headers you have included.
956 <!-- ##### VARIABLE glib_minor_version ##### -->
958 The minor version number of the GLib library.
959 (e.g. in GLib version 1.2.5 this is 2.)
963 This variable is in the library, so represents the
964 GLib library you have linked against. Contrast with the
965 #GLIB_MINOR_VERSION macro, which represents the minor version of the
966 GLib headers you have included.
970 <!-- ##### MACRO lseek ##### -->
976 <!-- ##### MACRO open ##### -->
982 <!-- ##### FUNCTION opendir ##### -->
984 Provided for UNIX emulation on Windows; see documentation for <function>opendir()</function>
991 <!-- ##### MACRO pclose ##### -->
997 <!-- ##### MACRO pipe ##### -->
999 Provided for UNIX emulation on Windows; see documentation for pipe()
1003 @phandles: file descriptors, the first one for reading, the second one for writing.
1005 <!-- ##### MACRO popen ##### -->
1011 <!-- ##### MACRO read ##### -->
1017 <!-- ##### MACRO readdir ##### -->
1019 Provided for UNIX emulation on Windows; see documentation for <function>readdir()</function>
1024 <!-- ##### FUNCTION rewinddir ##### -->
1026 Provided for UNIX emulation on Windows; see documentation for <function>rewinddir()</function>
1032 <!-- ##### MACRO write ##### -->