:right-sidebar: True Download =================================================================== .. currentmodule:: gi.repository.WebKit .. class:: Download(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` :Constructors: :: Download(**properties) Methods ------- .. rst-class:: interim-class .. class:: Download :no-index: .. method:: cancel() -> None Cancels the download. When the ongoing download operation is effectively cancelled the signal :obj:`~gi.repository.WebKit.Download`::failed is emitted with :const:`~gi.repository.WebKit.DownloadError.CANCELLED_BY_USER` error. .. method:: get_allow_overwrite() -> bool Returns the current value of the :obj:`~gi.repository.WebKit.Download`:allow-overwrite property. Returns the current value of the :obj:`~gi.repository.WebKit.Download`:allow-overwrite property, which determines whether the download will overwrite an existing file on disk, or if it will fail if the destination already exists. .. versionadded:: 2.6 .. method:: get_destination() -> str | None Obtains the destination to which the downloaded file will be written. You can connect to :obj:`~gi.repository.WebKit.Download`::created-destination to make sure this method returns a valid destination. .. method:: get_elapsed_time() -> float Gets the elapsed time in seconds, including any fractional part. If the download finished, had an error or was cancelled this is the time between its start and the event. .. method:: get_estimated_progress() -> float Gets the value of the :obj:`~gi.repository.WebKit.Download`:estimated-progress property. Gets the value of the :obj:`~gi.repository.WebKit.Download`:estimated-progress property. You can monitor the estimated progress of the download operation by connecting to the notify::estimated-progress signal of ``download``. .. method:: get_received_data_length() -> int Gets the length of the data already downloaded for ``download``. Gets the length of the data already downloaded for ``download`` in bytes. .. method:: get_request() -> ~gi.repository.WebKit.URIRequest Retrieves the :obj:`~gi.repository.WebKit.URIRequest` object that backs the download process. .. method:: get_response() -> ~gi.repository.WebKit.URIResponse Retrieves the :obj:`~gi.repository.WebKit.URIResponse` object that backs the download process. Retrieves the :obj:`~gi.repository.WebKit.URIResponse` object that backs the download process. This method returns :const:`None` if called before the response is received from the server. You can connect to notify::response signal to be notified when the response is received. .. method:: get_web_view() -> ~gi.repository.WebKit.WebView Get the :obj:`~gi.repository.WebKit.WebView` that initiated the download. .. method:: set_allow_overwrite(allowed: bool) -> None Sets the :obj:`~gi.repository.WebKit.Download`:allow-overwrite property. Sets the :obj:`~gi.repository.WebKit.Download`:allow-overwrite property, which determines whether the download may overwrite an existing file on disk, or if it will fail if the destination already exists. .. versionadded:: 2.6 :param allowed: the new value for the :obj:`~gi.repository.WebKit.Download`:allow-overwrite property .. method:: set_destination(destination: str) -> None Sets the destination to which the downloaded file will be written. This method should be called before the download transfer starts or it will not have any effect on the ongoing download operation. To set the destination using the filename suggested by the server connect to :obj:`~gi.repository.WebKit.Download`::decide-destination signal and call :func:`~gi.repository.WebKit.Download.set_destination`. If you want to set a fixed destination that doesn't depend on the suggested filename you can connect to notify::response signal and call :func:`~gi.repository.WebKit.Download.set_destination`. If :obj:`~gi.repository.WebKit.Download`::decide-destination signal is not handled and destination is not set when the download transfer starts, the file will be saved with the filename suggested by the server in ``%G_USER_DIRECTORY_DOWNLOAD`` directory. :param destination: the destination Properties ---------- .. rst-class:: interim-class .. class:: Download :no-index: .. attribute:: props.allow_overwrite :type: bool Whether or not the download is allowed to overwrite an existing file on disk. If this property is :const:`False` and the destination already exists, the download will fail. .. versionadded:: 2.6 .. attribute:: props.destination :type: str The local path to where the download will be saved. .. attribute:: props.estimated_progress :type: float An estimate of the percent completion for the download operation. This value will range from 0.0 to 1.0. The value is an estimate based on the total number of bytes expected to be received for a download. If you need a more accurate progress information you can connect to :obj:`~gi.repository.WebKit.Download`::received-data signal to track the progress. .. attribute:: props.response :type: ~gi.repository.WebKit.URIResponse The :obj:`~gi.repository.WebKit.URIResponse` associated with this download. Signals ------- .. rst-class:: interim-class .. class:: Download.signals :no-index: .. method:: created_destination(destination: str) -> None This signal is emitted after :obj:`~gi.repository.WebKit.Download`::decide-destination and before :obj:`~gi.repository.WebKit.Download`::received-data to notify that destination file has been created successfully at ``destination``. :param destination: the destination .. method:: decide_destination(suggested_filename: str) -> bool This signal is emitted after response is received to decide a destination for the download using :func:`~gi.repository.WebKit.Download.set_destination`. If this signal is not handled, the file will be downloaded to ``%G_USER_DIRECTORY_DOWNLOAD`` directory using ``suggested_filename``. Since 2.40, you may handle this signal asynchronously by returning :const:`True` without calling :func:`~gi.repository.WebKit.Download.set_destination`. This indicates intent to eventually call :func:`~gi.repository.WebKit.Download.set_destination`. In this case, the download will not proceed until the destination is set or cancelled with :func:`~gi.repository.WebKit.Download.cancel`. :param suggested_filename: the filename suggested for the download .. method:: failed(error: ~gi.repository.GLib.GError) -> None This signal is emitted when an error occurs during the download operation. The given ``error``, of the domain ``%WEBKIT_DOWNLOAD_ERROR``, contains further details of the failure. If the download is cancelled with :func:`~gi.repository.WebKit.Download.cancel`, this signal is emitted with error :const:`~gi.repository.WebKit.DownloadError.CANCELLED_BY_USER`. The download operation finishes after an error and :obj:`~gi.repository.WebKit.Download`::finished signal is emitted after this one. :param error: the :obj:`~gi.repository.GLib.Error` that was triggered .. method:: finished() -> None This signal is emitted when download finishes successfully or due to an error. In case of errors :obj:`~gi.repository.WebKit.Download`::failed signal is emitted before this one. .. method:: received_data(data_length: int) -> None This signal is emitted after response is received, every time new data has been written to the destination. It's useful to know the progress of the download operation. :param data_length: the length of data received in bytes