From 4fcc483146f72c52043cea62a9f3d64d5d56523b Mon Sep 17 00:00:00 2001 From: Joseph Yu Date: Mon, 12 Jul 2021 14:52:09 +0100 Subject: [PATCH 1/4] Initial change to reference title --- python/tank/platform/engine.py | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/python/tank/platform/engine.py b/python/tank/platform/engine.py index b7d9ad4cf..0a5b0b41e 100644 --- a/python/tank/platform/engine.py +++ b/python/tank/platform/engine.py @@ -1835,14 +1835,9 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs): The dialog will be created with a standard Toolkit window title bar where the title will be displayed. - .. note:: In some cases, it is necessary to hide the standard Toolkit title - bar. You can do this by adding a property to the widget class you are - displaying:: - - @property - def hide_tk_title_bar(self): - "Tell the system to not show the standard toolkit toolbar" - return True + .. seealso:: + - `Hiding the default Toolkit title bar` + - `Modal dialogs and exit codes` **Notes for engine developers** From 14788d18c74b22cce5d2794bddde6358d213d983 Mon Sep 17 00:00:00 2001 From: Joseph Yu Date: Mon, 12 Jul 2021 14:52:09 +0100 Subject: [PATCH 2/4] Switched to use ref --- docs/platform.rst | 8 ++++++++ python/tank/platform/engine.py | 4 ++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/platform.rst b/docs/platform.rst index d3e5df36d..50e11b0fa 100644 --- a/docs/platform.rst +++ b/docs/platform.rst @@ -915,6 +915,10 @@ What happens in the above calls is that your app widget is parented inside of a Sgtk will add additional potential window constructs, menus etc. Whenever the app widget is closed (for example using the close() method), the parent window that is used to wrap the widget will automatically close too. + + +.. _qdialog-exit-codes: + Modal dialogs and exit codes ======================================== @@ -935,6 +939,10 @@ property called ``exit_code``. Typically, your code for a modal dialog would loo The call to self.engine.show_modal() will return the appropriate status code depending on which button was clicked. + + +.. _hiding-toolkit-title-bar: + Hiding the default Toolkit title bar ======================================== diff --git a/python/tank/platform/engine.py b/python/tank/platform/engine.py index 0a5b0b41e..36324d78b 100644 --- a/python/tank/platform/engine.py +++ b/python/tank/platform/engine.py @@ -1836,8 +1836,8 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs): the title will be displayed. .. seealso:: - - `Hiding the default Toolkit title bar` - - `Modal dialogs and exit codes` + - :ref:`qdialog-exit-codes` + - :ref:`hiding-toolkit-title-bar` **Notes for engine developers** From dd745c8c26d4cee6dae38dc8d15c5b43631acb65 Mon Sep 17 00:00:00 2001 From: Joseph Yu Date: Mon, 12 Jul 2021 14:52:09 +0100 Subject: [PATCH 3/4] Looking decent --- python/tank/platform/engine.py | 48 +++++++++++++++++++--------------- 1 file changed, 27 insertions(+), 21 deletions(-) diff --git a/python/tank/platform/engine.py b/python/tank/platform/engine.py index 36324d78b..e8bcc6b71 100644 --- a/python/tank/platform/engine.py +++ b/python/tank/platform/engine.py @@ -1848,19 +1848,24 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs): Making use of these methods in the correct way allows the base Engine class to manage the lifetime of the dialogs and widgets efficiently and safely without you having to worry about it. - The methods available are listed here in the hierarchy in which they are called:: + The methods available are listed here in the hierarchy in which they are called: - show_dialog()/show_modal() - _create_dialog_with_widget() - _get_dialog_parent() - _create_widget() - _create_dialog() + - :meth:`~Engine.show_dialog`/:meth:`~Engine.show_modal` + + - :meth:`~Engine._create_dialog_with_widget` + + - :meth:`~Engine._get_dialog_parent` + + - :meth:`~Engine._create_widget` + + - :meth:`~Engine._create_dialog` For example, if you just need to make sure that all dialogs use a specific parent widget - then you only need to override _get_dialog_parent() (e.g. the tk-maya engine). + then you only need to override :meth:`~Engine._get_dialog_parent` (e.g. the tk-maya engine). However, if you need to implement a two-stage creation then you may need to re-implement - show_dialog() and show_modal() to call _create_widget() and _create_dialog() directly rather - than using the helper method _create_dialog_with_widget() (e.g. the tk-3dsmax engine). + :meth:`~Engine.show_dialog` and :meth:`~Engine.show_modal` to call :meth:`~Engine._create_widget` + and :meth:`~Engine._create_dialog` directly rather than using the helper method + :meth:`~Engine._create_dialog_with_widget` (e.g. the tk-3dsmax engine). Finally, if the application you are writing an engine for is Qt based then you may not need to override any of these methods (e.g. the tk-nuke engine). @@ -1869,9 +1874,11 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs): :param widget_class: The class of the UI to be constructed. This must derive from QWidget. :type widget_class: :class:`PySide.QtGui.QWidget` - Additional parameters specified will be passed through to the widget_class constructor. + Additional parameters specified will be passed through to the + ``widget_class`` constructor. - :returns: the created widget_class instance + :returns: The created ``widget_class`` instance + :rtype: PySide.QtGui.QWidget """ if not self.has_ui: self.log_error( @@ -1899,23 +1906,22 @@ def show_modal(self, title, bundle, widget_class, *args, **kwargs): The dialog will be created with a standard Toolkit window title bar where the title will be displayed. - .. note:: In some cases, it is necessary to hide the standard Toolkit title - bar. You can do this by adding a property to the widget class you are - displaying:: - - @property - def hide_tk_title_bar(self): - "Tell the system to not show the standard toolkit toolbar" - return True + .. seealso:: + - :ref:`qdialog-exit-codes` + - :ref:`hiding-toolkit-title-bar` :param title: The title of the window :param bundle: The app, engine or framework object that is associated with this window :param widget_class: The class of the UI to be constructed. This must derive from QWidget. :type widget_class: :class:`PySide.QtGui.QWidget` - Additional parameters specified will be passed through to the widget_class constructor. + Additional parameters specified will be passed through to the + ``widget_class`` constructor. - :returns: (a standard QT dialog status return code, the created widget_class instance) + :returns: Tuple of :attr:`QDialog.DialogCode + ` and and the created + ``widget_class`` instance + :rtype: (:class:`int`, :class:`PySide.QtGui.QWidget`) """ if not self.has_ui: self.log_error( From 98ef35677b71e89121453d6b7f713289599a04b1 Mon Sep 17 00:00:00 2001 From: Joseph Yu Date: Mon, 12 Jul 2021 14:52:09 +0100 Subject: [PATCH 4/4] Using tuple() syntax --- python/tank/platform/engine.py | 28 +++++++++++----------------- 1 file changed, 11 insertions(+), 17 deletions(-) diff --git a/python/tank/platform/engine.py b/python/tank/platform/engine.py index e8bcc6b71..9bf8c3cfe 100644 --- a/python/tank/platform/engine.py +++ b/python/tank/platform/engine.py @@ -1835,9 +1835,7 @@ def show_dialog(self, title, bundle, widget_class, *args, **kwargs): The dialog will be created with a standard Toolkit window title bar where the title will be displayed. - .. seealso:: - - :ref:`qdialog-exit-codes` - - :ref:`hiding-toolkit-title-bar` + .. seealso:: :ref:`hiding-toolkit-title-bar` **Notes for engine developers** @@ -1907,7 +1905,9 @@ def show_modal(self, title, bundle, widget_class, *args, **kwargs): the title will be displayed. .. seealso:: + - :ref:`qdialog-exit-codes` + - :ref:`hiding-toolkit-title-bar` :param title: The title of the window @@ -1918,10 +1918,9 @@ def show_modal(self, title, bundle, widget_class, *args, **kwargs): Additional parameters specified will be passed through to the ``widget_class`` constructor. - :returns: Tuple of :attr:`QDialog.DialogCode - ` and and the created - ``widget_class`` instance - :rtype: (:class:`int`, :class:`PySide.QtGui.QWidget`) + :returns: :attr:`QDialog.DialogCode ` + and the created ``widget_class`` instance + :rtype: tuple(int, PySide.QtGui.QWidget) """ if not self.has_ui: self.log_error( @@ -1954,14 +1953,7 @@ def show_panel(self, panel_id, title, bundle, widget_class, *args, **kwargs): The dialog will be created with a standard Toolkit window title bar where the title will be displayed. - .. note:: In some cases, it is necessary to hide the standard Toolkit title - bar. You can do this by adding a property to the widget class you are - displaying:: - - @property - def hide_tk_title_bar(self): - "Tell the system to not show the standard toolkit toolbar" - return True + .. seealso:: :ref:`hiding-toolkit-title-bar` :param panel_id: Unique identifier for the panel, as obtained by register_panel(). :param title: The title of the panel @@ -1969,9 +1961,11 @@ def hide_tk_title_bar(self): :param widget_class: The class of the UI to be constructed. This must derive from QWidget. :type widget_class: :class:`PySide.QtGui.QWidget` - Additional parameters specified will be passed through to the widget_class constructor. + Additional parameters specified will be passed through to the + ``widget_class`` constructor. - :returns: the created widget_class instance + :returns: The created ``widget_class`` instance + :rtype: PySide.QtGui.QWidget """ # engines implementing panel support should subclass this method. # the core implementation falls back on a modeless window.