UmyaSpreadsheet.OleObjects (umya_spreadsheet_ex v0.7.0)
View SourceFunctions for working with OLE (Object Linking and Embedding) objects in a spreadsheet.
OLE objects allow you to embed documents and files from other applications into your Excel spreadsheets, such as Word documents, PowerPoint presentations, PDF files, and more.
Overview
This module provides functionality to:
- Create and manage collections of OLE objects
- Add embedded objects to worksheets
- Load and save OLE object data
- Configure object properties and settings
- Check object formats and requirements
Examples
# Create a new OLE objects collection
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.new_ole_objects()
# Add the collection to a worksheet
:ok = UmyaSpreadsheet.OleObjects.set_ole_objects(spreadsheet, "Sheet1", ole_objects)
# Create an OLE object from a file
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
# Add the object to the collection
:ok = UmyaSpreadsheet.OleObjects.add_ole_object(ole_objects, ole_object)
Summary
Functions
Adds an OLE object to a collection.
Determines the ProgID from a file extension.
Gets the ProgID from embedded object properties.
Gets the shape ID from embedded object properties.
Gets the binary data from an OLE object.
Gets the file extension from an OLE object.
Gets the ProgID from an OLE object.
Gets the properties of an OLE object.
Gets the 'requires' attribute from an OLE object.
Gets the count of OLE objects in a collection.
Gets the OLE objects collection from a worksheet.
Checks if an OLE objects collection has any objects.
Checks if an OLE object is in binary format.
Checks if an OLE object is in Excel format.
Lists all OLE objects in a collection.
Loads an OLE object from a file. Note: This function signature differs from the underlying NIF which takes (file_path, prog_id).
Creates new embedded object properties.
Creates a new OLE object.
Creates a new OLE object and loads data from a file.
Creates a new OLE object with binary data.
Creates a new OLE objects collection.
Saves an OLE object to a file.
Sets the ProgID for embedded object properties.
Sets the shape ID for embedded object properties.
Sets the binary data for an OLE object.
Sets the file extension for an OLE object.
Sets the ProgID for an OLE object.
Sets the properties for an OLE object.
Sets the 'requires' attribute for an OLE object.
Sets the OLE objects collection for a worksheet.
Functions
Adds an OLE object to a collection.
Parameters
ole_objects
- The OLE objects collectionole_object
- The OLE object to add
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.new_ole_objects()
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
:ok = UmyaSpreadsheet.OleObjects.add_ole_object(ole_objects, ole_object)
Determines the ProgID from a file extension.
Parameters
extension
- The file extension (without the dot)
Returns
string
- The appropriate ProgID for the extension
Examples
"Word.Document.12" = UmyaSpreadsheet.OleObjects.determine_prog_id("docx")
"Excel.Sheet.12" = UmyaSpreadsheet.OleObjects.determine_prog_id("xlsx")
Gets the ProgID from embedded object properties.
Parameters
properties
- The embedded object properties resource
Returns
{:ok, prog_id}
- The ProgID string value{:error, reason}
on failure
Examples
{:ok, properties} = UmyaSpreadsheet.OleObjects.get_ole_object_properties(ole_object)
{:ok, prog_id} = UmyaSpreadsheet.OleObjects.get_embedded_object_prog_id(properties)
Gets the shape ID from embedded object properties.
Parameters
properties
- The embedded object properties resource
Returns
{:ok, shape_id}
- The shape ID number{:error, reason}
on failure
Examples
{:ok, properties} = UmyaSpreadsheet.OleObjects.get_ole_object_properties(ole_object)
{:ok, shape_id} = UmyaSpreadsheet.OleObjects.get_embedded_object_shape_id(properties)
Gets the binary data from an OLE object.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, data}
- The binary data{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, data} = UmyaSpreadsheet.OleObjects.get_ole_object_data(ole_object)
Gets the file extension from an OLE object.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, extension}
- The file extension string{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, extension} = UmyaSpreadsheet.OleObjects.get_ole_object_extension(ole_object)
Gets the ProgID from an OLE object.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, prog_id}
- The ProgID string value{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, prog_id} = UmyaSpreadsheet.OleObjects.get_ole_object_prog_id(ole_object)
Gets the properties of an OLE object.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, properties}
- The embedded object properties resource{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, properties} = UmyaSpreadsheet.OleObjects.get_ole_object_properties(ole_object)
Gets the 'requires' attribute from an OLE object.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, requires}
- The requires string value{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, requires} = UmyaSpreadsheet.OleObjects.get_ole_object_requires(ole_object)
Gets the count of OLE objects in a collection.
Parameters
ole_objects
- The OLE objects collection
Returns
{:ok, count}
- Number of OLE objects in the collection{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.get_ole_objects_from_worksheet(spreadsheet, "Sheet1")
{:ok, count} = UmyaSpreadsheet.OleObjects.get_ole_objects_count(ole_objects)
Gets the OLE objects collection from a worksheet.
Parameters
spreadsheet
- The spreadsheet structsheet_name
- The name of the worksheet
Returns
{:ok, ole_objects}
- The OLE objects collection from the worksheet{:error, reason}
on failure
Examples
{:ok, spreadsheet} = UmyaSpreadsheet.read_file("input.xlsx")
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.get_ole_objects_from_worksheet(spreadsheet, "Sheet1")
Checks if an OLE objects collection has any objects.
Parameters
ole_objects
- The OLE objects collection
Returns
{:ok, boolean}
- true if collection has objects, false otherwise{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.get_ole_objects_from_worksheet(spreadsheet, "Sheet1")
{:ok, has_objects} = UmyaSpreadsheet.OleObjects.has_ole_objects(ole_objects)
Checks if an OLE object is in binary format.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, boolean}
- true if in binary format, false otherwise{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
{:ok, is_binary} = UmyaSpreadsheet.OleObjects.is_ole_object_binary_format(ole_object)
Checks if an OLE object is in Excel format.
Parameters
ole_object
- The OLE object resource
Returns
{:ok, boolean}
- true if in Excel format, false otherwise{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("spreadsheet.xlsx")
{:ok, is_excel} = UmyaSpreadsheet.OleObjects.is_ole_object_excel_format(ole_object)
Lists all OLE objects in a collection.
Parameters
ole_objects
- The OLE objects collection
Returns
{:ok, objects_list}
- List of OLE object resources{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.get_ole_objects_from_worksheet(spreadsheet, "Sheet1")
{:ok, objects_list} = UmyaSpreadsheet.OleObjects.list_ole_objects(ole_objects)
Loads an OLE object from a file. Note: This function signature differs from the underlying NIF which takes (file_path, prog_id).
Parameters
ole_object
- This parameter is ignored for this functionfile_path
- Path to the file to load
Returns
{:ok, ole_object}
- A new OLE object with file data loaded{:error, reason}
on failure
Examples
# This creates a new OLE object rather than loading into an existing one
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.load_ole_object_from_file(nil, "document.docx")
Creates new embedded object properties.
Returns
{:ok, properties}
- A new embedded object properties resource{:error, reason}
on failure
Examples
{:ok, properties} = UmyaSpreadsheet.OleObjects.new_embedded_object_properties()
Creates a new OLE object.
Returns
{:ok, ole_object}
- A new OLE object resource{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
Creates a new OLE object and loads data from a file.
Parameters
file_path
- Path to the file to embed
Returns
{:ok, ole_object}
- A new OLE object with file data loaded{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("document.docx")
Creates a new OLE object with binary data.
Parameters
data
- Binary data to embedfile_extension
- File extension (e.g., "docx", "pptx")
Returns
{:ok, ole_object}
- A new OLE object with the provided data{:error, reason}
on failure
Examples
data = File.read!("document.docx")
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_with_data(data, "docx")
Creates a new OLE objects collection.
Returns
{:ok, ole_objects}
- A new OLE objects collection resource{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.new_ole_objects()
Saves an OLE object to a file.
Parameters
ole_object
- The OLE object resourcefile_path
- Path where the file should be saved
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object_from_file("input.docx")
:ok = UmyaSpreadsheet.OleObjects.save_ole_object_to_file(ole_object, "output.docx")
Sets the ProgID for embedded object properties.
Parameters
properties
- The embedded object properties resourceprog_id
- The ProgID string value
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, properties} = UmyaSpreadsheet.OleObjects.new_embedded_object_properties()
:ok = UmyaSpreadsheet.OleObjects.set_embedded_object_prog_id(properties, "Word.Document.12")
Sets the shape ID for embedded object properties.
Parameters
properties
- The embedded object properties resourceshape_id
- The shape ID number
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, properties} = UmyaSpreadsheet.OleObjects.new_embedded_object_properties()
:ok = UmyaSpreadsheet.OleObjects.set_embedded_object_shape_id(properties, 1)
Sets the binary data for an OLE object.
Parameters
ole_object
- The OLE object resourcedata
- The binary data to set
Returns
:ok
on success{:error, reason}
on failure
Examples
data = File.read!("document.docx")
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
:ok = UmyaSpreadsheet.OleObjects.set_ole_object_data(ole_object, data)
Sets the file extension for an OLE object.
Parameters
ole_object
- The OLE object resourceextension
- The file extension string
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
:ok = UmyaSpreadsheet.OleObjects.set_ole_object_extension(ole_object, "docx")
Sets the ProgID for an OLE object.
Parameters
ole_object
- The OLE object resourceprog_id
- The ProgID string value
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
:ok = UmyaSpreadsheet.OleObjects.set_ole_object_prog_id(ole_object, "Word.Document.12")
Sets the properties for an OLE object.
Parameters
ole_object
- The OLE object resourceproperties
- The embedded object properties resource
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
{:ok, properties} = UmyaSpreadsheet.OleObjects.new_embedded_object_properties()
:ok = UmyaSpreadsheet.OleObjects.set_ole_object_properties(ole_object, properties)
Sets the 'requires' attribute for an OLE object.
Parameters
ole_object
- The OLE object resourcerequires
- The requires string value
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_object} = UmyaSpreadsheet.OleObjects.new_ole_object()
:ok = UmyaSpreadsheet.OleObjects.set_ole_object_requires(ole_object, "application")
Sets the OLE objects collection for a worksheet.
Parameters
spreadsheet
- The spreadsheet structsheet_name
- The name of the worksheetole_objects
- The OLE objects collection resource
Returns
:ok
on success{:error, reason}
on failure
Examples
{:ok, ole_objects} = UmyaSpreadsheet.OleObjects.new_ole_objects()
:ok = UmyaSpreadsheet.OleObjects.set_ole_objects_to_worksheet(spreadsheet, "Sheet1", ole_objects)