Docs: add warning regarding operators that use the file selector

This commit is contained in:
Campbell Barton
2025-04-25 16:24:24 +10:00
parent e09d59f9de
commit 4f04f6f8af

View File

@@ -21,4 +21,25 @@ The following properties are supported:
If this property is present and set to ``True``,
the operator will warn if the provided file-path already exists
by highlighting the filename input field in red.
.. warning::
After opening the file-browser the user may continue to use Blender,
this means it is possible for the user to change the context in ways
that would cause the operators ``poll`` function to fail.
Unless the operator reads all necessary data from the context before the file-selector is opened,
it is recommended for operators to check the ``poll`` function from ``execute``
to ensure the context is still valid.
Example from the body of an operators ``execute`` function:
.. code-block:: python
if self.options.is_invoke:
# The context may have changed since invoking the file selector.
if not self.poll(context):
self.report({'ERROR'}, "Invalid context")
return {'CANCELLED'}
"""