feat(examples): add scripts for deleting and filling selections and exporting documents with options

Signed-off-by: longhao <hal.long@outlook.com>

Author: loonghao

examples/delete_and_fill_selection.py

@@ -0,0 +1,62 @@
+"""This script demonstrates how to delete and fill a selection in one operation."""
+
+# Import built-in modules
+import os
+
+# Import third-party modules
+from photoshop import Session
+from photoshop.api import SolidColor
+import photoshop.api as ps
+
+# Import local modules
+from _psd_files import get_psd_files
+
+def delete_and_fill_selection(doc, fill_type, mode=None, opacity=None, preserve_transparency=None):
+    """Delete current selection and fill it with specified color.
+    
+    Args:
+        doc: The active document.
+        fill_type (SolidColor): The color to fill the selection with.
+        mode (ColorBlendMode, optional): The color blend mode.
+        opacity (int, optional): The opacity value.
+        preserve_transparency (bool, optional): If true, preserves transparency.
+    """
+    # First fill the selection
+    doc.selection.fill(fill_type, mode, opacity, preserve_transparency)
+    # Then deselect
+    doc.selection.deselect()
+
+def main():
+    """Create a selection and fill it with a solid color."""
+    psd_file = get_psd_files()["export_layers_as_png.psd"]
+    
+    # Initialize Photoshop application
+    app = ps.Application()
+    
+    # Open the test file
+    if not os.path.exists(psd_file):
+        raise FileNotFoundError(f"Test file not found: {psd_file}")
+    app.load(psd_file)
+    
+    # Get the active document
+    doc = app.activeDocument
+
+    # Create a rectangular selection
+    doc.selection.select(((100, 100), (400, 100), (400, 300), (100, 300)))
+
+    # Create a solid color (red in this case)
+    red_color = SolidColor()
+    red_color.rgb.red = 255
+    red_color.rgb.green = 0
+    red_color.rgb.blue = 0
+
+    # Delete and fill the selection
+    delete_and_fill_selection(doc, red_color, opacity=80)
+
+    # Save the changes
+    doc.save()
+    
+    print("Selection has been filled with red color.")
+
+if __name__ == "__main__":
+    main()

examples/export_document_with_options.py

@@ -0,0 +1,63 @@
+"""This example demonstrates how to export a document with different formats.
+
+References:
+    https://github.com/loonghao/photoshop-python-api/issues/368
+"""
+
+# Import built-in modules
+import os
+
+# Import third-party modules
+from photoshop import Session
+from photoshop.api.enumerations import DitherType
+from photoshop.api.enumerations import ExportType
+from photoshop.api.enumerations import SaveDocumentType
+from photoshop.api.save_options.png import PNGSaveOptions
+from photoshop.api.save_options.jpg import JPEGSaveOptions
+from photoshop.api.save_options.png import ExportOptionsSaveForWeb
+
+
+def main():
+    """Export document with different formats."""
+    psd_file = os.path.join(os.path.dirname(__file__), "files", "export_layers_as_png.psd")
+    if not os.path.exists(psd_file):
+        raise FileNotFoundError(
+            f"File not found: {psd_file}"
+        )
+
+    # Start a new photoshop session
+    with Session(psd_file, "open") as ps:
+        doc = ps.active_document
+
+        # Export as PNG-24
+        png_path = os.path.join(os.path.dirname(__file__), "exported_png24.png")
+        png_options = PNGSaveOptions()
+        png_options.interlaced = False  # Disable interlacing for better quality
+        png_options.compression = 0  # Set compression to 0 for maximum quality
+        doc.saveAs(png_path, png_options, True)  # True for saving as copy
+        print(f"Exported PNG-24: {png_path}")
+
+        # Export as JPEG with high quality
+        jpg_path = os.path.join(os.path.dirname(__file__), "exported_jpeg.jpg")
+        jpg_options = JPEGSaveOptions()
+        jpg_options.quality = 12  # Set quality to maximum (12)
+        jpg_options.embedColorProfile = True  # Preserve color profile
+        jpg_options.formatOptions = 1  # Use standard baseline format
+        jpg_options.scans = 3  # Enable progressive scanning
+        jpg_options.matte = 1  # No background color (matte)
+        doc.saveAs(jpg_path, jpg_options, True)  # True for saving as copy
+        print(f"Exported JPEG: {jpg_path}")
+
+        # Export as GIF using Save for Web
+        gif_path = os.path.join(os.path.dirname(__file__), "exported_gif.gif")
+        gif_options = ExportOptionsSaveForWeb()
+        gif_options.format = SaveDocumentType.CompuServeGIFSave  # Set format to GIF
+        gif_options.colors = 256  # Use maximum number of colors (256)
+        gif_options.dither = DitherType.NoDither  # Disable dithering for sharper edges
+        gif_options.transparency = True  # Preserve transparency in the GIF
+        doc.exportDocument(gif_path, ExportType.SaveForWeb, gif_options)
+        print(f"Exported GIF: {gif_path}")
+
+
+if __name__ == "__main__":
+    main()

photoshop/api/save_options/png.py

@@ -2,6 +2,7 @@
 from photoshop.api._core import Photoshop
 from photoshop.api.enumerations import ColorReductionType
 from photoshop.api.enumerations import DitherType
+from photoshop.api.enumerations import SaveDocumentType
 
 
 class ExportOptionsSaveForWeb(Photoshop):
@@ -11,12 +12,22 @@ class ExportOptionsSaveForWeb(Photoshop):
 
     def __init__(self):
         super().__init__()
-        self.format = 13  # PNG
+        self._format = SaveDocumentType.PNGSave  # Default to PNG
         self.PNG8 = False  # Sets it to PNG-24 bit
 
+    @property
+    def format(self) -> SaveDocumentType:
+        """The file format to use. One of the SaveDocumentType constants."""
+        return self._format
+
+    @format.setter
+    def format(self, value: SaveDocumentType):
+        """Set the file format to use."""
+        self._format = value
+
     @property
     def PNG8(self) -> bool:
-        """If true, uses 8 bits. If false, uses 24 bits. Valid only when ‘format’ = PNG."""
+        """If true, uses 8 bits. If false, uses 24 bits. Valid only when 'format' = PNG."""
         return self.app.PNG8
 
     @PNG8.setter
@@ -59,6 +70,15 @@ def dither(self) -> DitherType:
     def dither(self, value: DitherType):
         self.app.dither = value
 
+    @property
+    def optimized(self) -> bool:
+        """If true, optimization is enabled."""
+        return self.app.optimized
+
+    @optimized.setter
+    def optimized(self, value: bool):
+        self.app.optimized = value
+
     @property
     def quality(self) -> int:
         """The quality of the output image, from 0 to 100."""