1 files changed, 137 insertions, 0 deletions
diff --git a/release/scripts/modules/bpy/utils/previews.py b/release/scripts/modules/bpy/utils/previews.py
new file mode 100644
index 00000000000..4e8adf8e209
--- /dev/null
+++ b/release/scripts/modules/bpy/utils/previews.py
@@ -0,0 +1,137 @@
+# ##### BEGIN GPL LICENSE BLOCK #####
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  This program is distributed in the hope that it will be useful,
+#  but WITHOUT ANY WARRANTY; without even the implied warranty of
+#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+#  GNU General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public License
+#  along with this program; if not, write to the Free Software Foundation,
+#  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+#
+# ##### END GPL LICENSE BLOCK #####
+
+# <pep8 compliant>
+
+"""
+This module contains utility functions to handle custom previews.
+
+It behaves as a high-level 'cached' previews manager.
+
+This allows addons to generate their own previews, and use them as icons in UI widgets
+('icon_value' of UILayout functions).
+"""
+
+__all__ = (
+    "new",
+    "remove",
+    )
+
+import _bpy
+_utils_previews = _bpy._utils_previews
+del _bpy
+
+
+_uuid_open = set()
+
+
+# High-level previews manager.
+# not accessed directly
+class _BPyImagePreviewCollection(dict):
+    """
+    Dict-like class of previews.
+    """
+
+    # Internal notes:
+    # - keys in the dict are stored by name
+    # - values are instances of bpy.types.ImagePreview
+    # - Blender's internal 'PreviewImage' struct uses 'self._uuid' prefix.
+
+    def __init__(self):
+        super().__init__()
+        self._uuid = hex(id(self))
+        _uuid_open.add(self._uuid)
+
+    def __del__(self):
+        if self._uuid not in _uuid_open:
+            return
+
+        raise ResourceWarning(
+                "<%s id=%s[%d]>: left open, remove with "
+                "'bpy.utils.previews.remove()'" %
+                (self.__class__.__name__, self._uuid, len(self)))
+        self.close()
+
+    def _gen_key(self, name):
+        return ":".join((self._uuid, name))
+
+    def new(self, name):
+        if name in self:
+            raise KeyException("key %r already exists")
+        p = self[name] = _utils_previews.new(
+                self._gen_key(name))
+        return p
+    new.__doc__ = _utils_previews.new.__doc__
+
+    def load(self, name, path, path_type, force_reload=False):
+        if name in self:
+            raise KeyException("key %r already exists")
+        p = self[name] = _utils_previews.load(
+                self._gen_key(name), path, path_type, force_reload)
+        return p
+    load.__doc__ = _utils_previews.load.__doc__
+
+    def release(self, name):
+        p = self.pop(name, None)
+        if p is not None:
+            _utils_previews.release(self._gen_key(name))
+    release.__doc__ = _utils_previews.release.__doc__
+
+    def clear(self):
+        for name in self.keys():
+            _utils_previews.release(self._gen_key(name))
+        super().clear()
+
+    def close(self):
+        self.clear()
+        _uuid_open.remove(self._uuid)
+
+    def __delitem__(self, key):
+        return self.release(key)
+
+    def __repr__(self):
+        return "<%s id=%s[%d], %s>" % (
+                self.__class__.__name__,
+                self._uuid,
+                len(self),
+                super().__repr__())
+
+
+def new():
+    """
+    Return a new preview collection.
+    """
+
+    return _BPyImagePreviewCollection()
+
+
+def remove(p):
+    """
+    Remove the specified previews collection.
+    """
+    p.close()
+
+
+# don't complain about resources on exit (only unregister)
+import atexit
+
+def exit_clear_warning():
+    del _BPyImagePreviewCollection.__del__
+
+atexit.register(exit_clear_warning)
+del atexit, exit_clear_warning