Docs: add warning regarding operators that use the file selector
This commit is contained in:
@@ -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'}
|
||||
"""
|
||||
|
||||
Reference in New Issue
Block a user