:right-sidebar: True BookmarkFile =================================================================== .. currentmodule:: gi.repository.GLib .. versionadded:: 2.12 .. class:: BookmarkFile(**kwargs) :no-contents-entry: :Constructors: :: new() -> GLib.BookmarkFile Constructors ------------ .. rst-class:: interim-class .. class:: BookmarkFile :no-index: .. classmethod:: new() -> ~gi.repository.GLib.BookmarkFile Creates a new empty :obj:`~gi.repository.GLib.BookmarkFile` object. Use :func:`~gi.repository.GLib.BookmarkFile.load_from_file`, :func:`~gi.repository.GLib.BookmarkFile.load_from_data` or :func:`~gi.repository.GLib.BookmarkFile.load_from_data_dirs` to read an existing bookmark file. .. versionadded:: 2.12 Methods ------- .. rst-class:: interim-class .. class:: BookmarkFile :no-index: .. method:: add_application(uri: str, name: str | None = None, exec: str | None = None) -> None Adds the application with ``name`` and ``exec`` to the list of applications that have registered a bookmark for ``uri`` into ``bookmark``. Every bookmark inside a :obj:`~gi.repository.GLib.BookmarkFile` must have at least an application registered. Each application must provide a name, a command line useful for launching the bookmark, the number of times the bookmark has been registered by the application and the last time the application registered this bookmark. If ``name`` is :const:`None`, the name of the application will be the same returned by :func:`~gi.repository.GLib.get_application_name`; if ``exec`` is :const:`None`, the command line will be a composition of the program name as returned by :func:`~gi.repository.GLib.get_prgname` and the "\``%u``" modifier, which will be expanded to the bookmark's URI. This function will automatically take care of updating the registrations count and timestamping in case an application with the same ``name`` had already registered a bookmark for ``uri`` inside ``bookmark``. If no bookmark for ``uri`` is found, one is created. .. versionadded:: 2.12 :param uri: a valid URI :param name: the name of the application registering the bookmark or :const:`None` :param exec: command line to be used to launch the bookmark or :const:`None` .. method:: add_group(uri: str, group: str) -> None Adds ``group`` to the list of groups to which the bookmark for ``uri`` belongs to. If no bookmark for ``uri`` is found then it is created. .. versionadded:: 2.12 :param uri: a valid URI :param group: the group name to be added .. method:: error_quark() -> int .. method:: free() -> None Frees a :obj:`~gi.repository.GLib.BookmarkFile`. .. versionadded:: 2.12 .. method:: get_added(uri: str) -> int Gets the time the bookmark for ``uri`` was added to ``bookmark`` In the event the URI cannot be found, -1 is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.get_added_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI .. method:: get_added_date_time(uri: str) -> ~gi.repository.GLib.DateTime Gets the time the bookmark for ``uri`` was added to ``bookmark`` In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.66 :param uri: a valid URI .. method:: get_app_info(uri: str, name: str) -> tuple[bool, str, int, int] Gets the registration information of ``app_name`` for the bookmark for ``uri``. See :func:`~gi.repository.GLib.BookmarkFile.set_application_info` for more information about the returned data. The string returned in ``app_exec`` must be freed. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event that no application with name ``app_name`` has registered a bookmark for ``uri``, :const:`False` is returned and error is set to :const:`~gi.repository.GLib.BookmarkFileError.APP_NOT_REGISTERED`. In the event that unquoting the command line fails, an error of the ``%G_SHELL_ERROR`` domain is set and :const:`False` is returned. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.get_application_info` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI :param name: an application's name .. method:: get_application_info(uri: str, name: str) -> tuple[bool, str, int, ~gi.repository.GLib.DateTime] Gets the registration information of ``app_name`` for the bookmark for ``uri``. See :func:`~gi.repository.GLib.BookmarkFile.set_application_info` for more information about the returned data. The string returned in ``app_exec`` must be freed. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event that no application with name ``app_name`` has registered a bookmark for ``uri``, :const:`False` is returned and error is set to :const:`~gi.repository.GLib.BookmarkFileError.APP_NOT_REGISTERED`. In the event that unquoting the command line fails, an error of the ``%G_SHELL_ERROR`` domain is set and :const:`False` is returned. .. versionadded:: 2.66 :param uri: a valid URI :param name: an application's name .. method:: get_applications(uri: str) -> list[str] Retrieves the names of the applications that have registered the bookmark for ``uri``. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_description(uri: str) -> str Retrieves the description of the bookmark for ``uri``. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_groups(uri: str) -> list[str] Retrieves the list of group names of the bookmark for ``uri``. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. The returned array is :const:`None` terminated, so ``length`` may optionally be :const:`None`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_icon(uri: str) -> tuple[bool, str, str] Gets the icon of the bookmark for ``uri``. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_is_private(uri: str) -> bool Gets whether the private flag of the bookmark for ``uri`` is set. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event that the private flag cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.INVALID_VALUE`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_mime_type(uri: str) -> str Retrieves the MIME type of the resource pointed by ``uri``. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event that the MIME type cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.INVALID_VALUE`. .. versionadded:: 2.12 :param uri: a valid URI .. method:: get_modified(uri: str) -> int Gets the time when the bookmark for ``uri`` was last modified. In the event the URI cannot be found, -1 is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.get_modified_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI .. method:: get_modified_date_time(uri: str) -> ~gi.repository.GLib.DateTime Gets the time when the bookmark for ``uri`` was last modified. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.66 :param uri: a valid URI .. method:: get_size() -> int Gets the number of bookmarks inside ``bookmark``. .. versionadded:: 2.12 .. method:: get_title(uri: str | None = None) -> str Returns the title of the bookmark for ``uri``. If ``uri`` is :const:`None`, the title of ``bookmark`` is returned. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI or :const:`None` .. method:: get_uris() -> list[str] Returns all URIs of the bookmarks in the bookmark file ``bookmark``. The array of returned URIs will be :const:`None`-terminated, so ``length`` may optionally be :const:`None`. .. versionadded:: 2.12 .. method:: get_visited(uri: str) -> int Gets the time the bookmark for ``uri`` was last visited. In the event the URI cannot be found, -1 is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.get_visited_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI .. method:: get_visited_date_time(uri: str) -> ~gi.repository.GLib.DateTime Gets the time the bookmark for ``uri`` was last visited. In the event the URI cannot be found, :const:`None` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.66 :param uri: a valid URI .. method:: has_application(uri: str, name: str) -> bool Checks whether the bookmark for ``uri`` inside ``bookmark`` has been registered by application ``name``. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI :param name: the name of the application .. method:: has_group(uri: str, group: str) -> bool Checks whether ``group`` appears in the list of groups to which the bookmark for ``uri`` belongs to. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param uri: a valid URI :param group: the group name to be searched .. method:: has_item(uri: str) -> bool Looks whether the desktop bookmark has an item with its URI set to ``uri``. .. versionadded:: 2.12 :param uri: a valid URI .. method:: load_from_data(data: ~typing.Sequence[int]) -> bool Loads a bookmark file from memory into an empty :obj:`~gi.repository.GLib.BookmarkFile` structure. If the object cannot be created then ``error`` is set to a ``GBookmarkFileError``. .. versionadded:: 2.12 :param data: desktop bookmarks loaded in memory .. method:: load_from_data_dirs(file: str) -> tuple[bool, str] This function looks for a desktop bookmark file named ``file`` in the paths returned from :func:`~gi.repository.GLib.get_user_data_dir` and :func:`~gi.repository.GLib.get_system_data_dirs`, loads the file into ``bookmark`` and returns the file's full path in ``full_path``. If the file could not be loaded then ``error`` is set to either a :obj:`~gi.repository.GLib.FileError` or ``GBookmarkFileError``. .. versionadded:: 2.12 :param file: a relative path to a filename to open and parse .. method:: load_from_file(filename: str) -> bool Loads a desktop bookmark file into an empty :obj:`~gi.repository.GLib.BookmarkFile` structure. If the file could not be loaded then ``error`` is set to either a :obj:`~gi.repository.GLib.FileError` or ``GBookmarkFileError``. .. versionadded:: 2.12 :param filename: the path of a filename to load, in the GLib file name encoding .. method:: move_item(old_uri: str, new_uri: str | None = None) -> bool Changes the URI of a bookmark item from ``old_uri`` to ``new_uri``. Any existing bookmark for ``new_uri`` will be overwritten. If ``new_uri`` is :const:`None`, then the bookmark is removed. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. .. versionadded:: 2.12 :param old_uri: a valid URI :param new_uri: a valid URI, or :const:`None` .. method:: remove_application(uri: str, name: str) -> bool Removes application registered with ``name`` from the list of applications that have registered a bookmark for ``uri`` inside ``bookmark``. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event that no application with name ``app_name`` has registered a bookmark for ``uri``, :const:`False` is returned and error is set to :const:`~gi.repository.GLib.BookmarkFileError.APP_NOT_REGISTERED`. .. versionadded:: 2.12 :param uri: a valid URI :param name: the name of the application .. method:: remove_group(uri: str, group: str) -> bool Removes ``group`` from the list of groups to which the bookmark for ``uri`` belongs to. In the event the URI cannot be found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`. In the event no group was defined, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.INVALID_VALUE`. .. versionadded:: 2.12 :param uri: a valid URI :param group: the group name to be removed .. method:: remove_item(uri: str) -> bool Removes the bookmark for ``uri`` from the bookmark file ``bookmark``. .. versionadded:: 2.12 :param uri: a valid URI .. method:: set_added(uri: str, added: int) -> None Sets the time the bookmark for ``uri`` was added into ``bookmark``. If no bookmark for ``uri`` is found then it is created. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.set_added_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI :param added: a timestamp or -1 to use the current time .. method:: set_added_date_time(uri: str, added: ~gi.repository.GLib.DateTime) -> None Sets the time the bookmark for ``uri`` was added into ``bookmark``. If no bookmark for ``uri`` is found then it is created. .. versionadded:: 2.66 :param uri: a valid URI :param added: a :obj:`~gi.repository.GLib.DateTime` .. method:: set_app_info(uri: str, name: str, exec: str, count: int, stamp: int) -> bool Sets the meta-data of application ``name`` inside the list of applications that have registered a bookmark for ``uri`` inside ``bookmark``. You should rarely use this function; use :func:`~gi.repository.GLib.BookmarkFile.add_application` and :func:`~gi.repository.GLib.BookmarkFile.remove_application` instead. ``name`` can be any UTF-8 encoded string used to identify an application. ``exec`` can have one of these two modifiers: "\``%f``", which will be expanded as the local file name retrieved from the bookmark's URI; "\``%u``", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the :func:`~gi.repository.GLib.BookmarkFile.get_application_info` function. ``count`` is the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application with ``name`` will be removed from the list of registered applications. ``stamp`` is the Unix time of the last registration; if it is -1, the current time will be used. If you try to remove an application by setting its registration count to zero, and no bookmark for ``uri`` is found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`; similarly, in the event that no application ``name`` has registered a bookmark for ``uri``, :const:`False` is returned and error is set to :const:`~gi.repository.GLib.BookmarkFileError.APP_NOT_REGISTERED`. Otherwise, if no bookmark for ``uri`` is found, one is created. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.set_application_info` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI :param name: an application's name :param exec: an application's command line :param count: the number of registrations done for this application :param stamp: the time of the last registration for this application .. method:: set_application_info(uri: str, name: str, exec: str, count: int, stamp: ~gi.repository.GLib.DateTime | None = None) -> bool Sets the meta-data of application ``name`` inside the list of applications that have registered a bookmark for ``uri`` inside ``bookmark``. You should rarely use this function; use :func:`~gi.repository.GLib.BookmarkFile.add_application` and :func:`~gi.repository.GLib.BookmarkFile.remove_application` instead. ``name`` can be any UTF-8 encoded string used to identify an application. ``exec`` can have one of these two modifiers: "\``%f``", which will be expanded as the local file name retrieved from the bookmark's URI; "\``%u``", which will be expanded as the bookmark's URI. The expansion is done automatically when retrieving the stored command line using the :func:`~gi.repository.GLib.BookmarkFile.get_application_info` function. ``count`` is the number of times the application has registered the bookmark; if is < 0, the current registration count will be increased by one, if is 0, the application with ``name`` will be removed from the list of registered applications. ``stamp`` is the Unix time of the last registration. If you try to remove an application by setting its registration count to zero, and no bookmark for ``uri`` is found, :const:`False` is returned and ``error`` is set to :const:`~gi.repository.GLib.BookmarkFileError.URI_NOT_FOUND`; similarly, in the event that no application ``name`` has registered a bookmark for ``uri``, :const:`False` is returned and error is set to :const:`~gi.repository.GLib.BookmarkFileError.APP_NOT_REGISTERED`. Otherwise, if no bookmark for ``uri`` is found, one is created. .. versionadded:: 2.66 :param uri: a valid URI :param name: an application's name :param exec: an application's command line :param count: the number of registrations done for this application :param stamp: the time of the last registration for this application, which may be :const:`None` if ``count`` is 0 .. method:: set_description(uri: str | None, description: str) -> None Sets ``description`` as the description of the bookmark for ``uri``. If ``uri`` is :const:`None`, the description of ``bookmark`` is set. If a bookmark for ``uri`` cannot be found then it is created. .. versionadded:: 2.12 :param uri: a valid URI or :const:`None` :param description: a string .. method:: set_groups(uri: str, groups: ~typing.Sequence[str] | None = None) -> None Sets a list of group names for the item with URI ``uri``. Each previously set group name list is removed. If ``uri`` cannot be found then an item for it is created. .. versionadded:: 2.12 :param uri: an item's URI :param groups: an array of group names, or :const:`None` to remove all groups .. method:: set_icon(uri: str, href: str | None, mime_type: str) -> None Sets the icon for the bookmark for ``uri``. If ``href`` is :const:`None`, unsets the currently set icon. ``href`` can either be a full URL for the icon file or the icon name following the Icon Naming specification. If no bookmark for ``uri`` is found one is created. .. versionadded:: 2.12 :param uri: a valid URI :param href: the URI of the icon for the bookmark, or :const:`None` :param mime_type: the MIME type of the icon for the bookmark .. method:: set_is_private(uri: str, is_private: bool) -> None Sets the private flag of the bookmark for ``uri``. If a bookmark for ``uri`` cannot be found then it is created. .. versionadded:: 2.12 :param uri: a valid URI :param is_private: :const:`True` if the bookmark should be marked as private .. method:: set_mime_type(uri: str, mime_type: str) -> None Sets ``mime_type`` as the MIME type of the bookmark for ``uri``. If a bookmark for ``uri`` cannot be found then it is created. .. versionadded:: 2.12 :param uri: a valid URI :param mime_type: a MIME type .. method:: set_modified(uri: str, modified: int) -> None Sets the last time the bookmark for ``uri`` was last modified. If no bookmark for ``uri`` is found then it is created. The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of :obj:`~gi.repository.GLib.BookmarkFile` that modifies a bookmark also changes the modification time, except for :func:`~gi.repository.GLib.BookmarkFile.set_visited_date_time`. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.set_modified_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI :param modified: a timestamp or -1 to use the current time .. method:: set_modified_date_time(uri: str, modified: ~gi.repository.GLib.DateTime) -> None Sets the last time the bookmark for ``uri`` was last modified. If no bookmark for ``uri`` is found then it is created. The "modified" time should only be set when the bookmark's meta-data was actually changed. Every function of :obj:`~gi.repository.GLib.BookmarkFile` that modifies a bookmark also changes the modification time, except for :func:`~gi.repository.GLib.BookmarkFile.set_visited_date_time`. .. versionadded:: 2.66 :param uri: a valid URI :param modified: a :obj:`~gi.repository.GLib.DateTime` .. method:: set_title(uri: str | None, title: str) -> None Sets ``title`` as the title of the bookmark for ``uri`` inside the bookmark file ``bookmark``. If ``uri`` is :const:`None`, the title of ``bookmark`` is set. If a bookmark for ``uri`` cannot be found then it is created. .. versionadded:: 2.12 :param uri: a valid URI or :const:`None` :param title: a UTF-8 encoded string .. method:: set_visited(uri: str, visited: int) -> None Sets the time the bookmark for ``uri`` was last visited. If no bookmark for ``uri`` is found then it is created. The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by :func:`~gi.repository.GLib.BookmarkFile.get_application_info` or by the default application for the bookmark's MIME type, retrieved using :func:`~gi.repository.GLib.BookmarkFile.get_mime_type`. Changing the "visited" time does not affect the "modified" time. .. versionadded:: 2.12 .. deprecated:: 2.66 Use :func:`~gi.repository.GLib.BookmarkFile.set_visited_date_time` instead, as ``time_t`` is deprecated due to the year 2038 problem. :param uri: a valid URI :param visited: a timestamp or -1 to use the current time .. method:: set_visited_date_time(uri: str, visited: ~gi.repository.GLib.DateTime) -> None Sets the time the bookmark for ``uri`` was last visited. If no bookmark for ``uri`` is found then it is created. The "visited" time should only be set if the bookmark was launched, either using the command line retrieved by :func:`~gi.repository.GLib.BookmarkFile.get_application_info` or by the default application for the bookmark's MIME type, retrieved using :func:`~gi.repository.GLib.BookmarkFile.get_mime_type`. Changing the "visited" time does not affect the "modified" time. .. versionadded:: 2.66 :param uri: a valid URI :param visited: a :obj:`~gi.repository.GLib.DateTime` .. method:: to_data() -> bytes This function outputs ``bookmark`` as a string. .. versionadded:: 2.12 .. method:: to_file(filename: str) -> bool This function outputs ``bookmark`` into a file. The write process is guaranteed to be atomic by using :func:`~gi.repository.GLib.file_set_contents` internally. .. versionadded:: 2.12 :param filename: path of the output file