Filedini Python Scripting API Reference

This document outlines the API available for Python scripting. Scripts can interact with the application through the global host object.

The API is still under development and may not be fully sufficient at this time. We welcome any requests you may have.

日本語 (Japanese)

host Object

The host object is the main entry point for all API functionalities.

host.install(package_name: str) -> bool

Installs a specified Python package. If the package is already importable, installation is skipped.

• Args:
  • package_name (str): The name of the package to install (e.g., "requests").
• Returns:
  • bool: True if installation is successful or the package already exists, False otherwise.
• Example:

  if host.install("requests"):
      import requests

host.log(message: str, level: int = LogLevel.INFO)

Sends a log message to the host application.

• Args:
  • message (str): The message to log.
  • level (int, optional): The log level. Defaults to LogLevel.INFO.

host.LogLevel

An enumeration for log levels.

• Constants:
  • DEBUG (0)
  • INFO (1)
  • WARNING (2)
  • ERROR (3)

host.state Module

Provides access to the application’s current state.

state.get_current_folder_path() -> Optional[str]

Retrieves the path of the currently active folder.

• Returns:
  • Optional[str]: The folder path, or None if it cannot be retrieved.

state.get_cursor_path() -> Optional[str]

Retrieves the path of the item currently under the cursor.

• Returns:
  • Optional[str]: The item path, or None if it cannot be retrieved.

state.get_selected_paths() -> Optional[Iterable[str]]

Retrieves the paths of all selected items.

• Returns:
  • Optional[Iterable[str]]: An iterable of item paths, or None if it cannot be retrieved.

host.scheduler Module

Manages periodic execution of tasks.

scheduler.start(interval_sec: int, function_name: str) -> Optional[str]

Registers a function for periodic execution.

• Args:
  • interval_sec (int): The execution interval in seconds.
  • function_name (str): The name of the function to execute.
• Returns:
  • Optional[str]: A unique schedule ID if successful, None otherwise.

scheduler.stop(schedule_id: str) -> None

Stops a periodic task.

• Args:
  • schedule_id (str): The schedule ID returned by scheduler.start().

host.ui Module

Provides functions for creating user interface elements like dialogs.

Standard Dialogs

ui.input_text_dialog(title: str, message: str, initial_text: str) -> InputTextDialogResponse

Displays a dialog with a text input field.

• Args:
  • title (str): The dialog title.
  • message (str): The message to display.
  • initial_text (str): The initial text in the input field.
• Returns:
  • InputTextDialogResponse: An object with result (int) and text (str) attributes.

ui.ok_cancel_dialog(title: str, message: str) -> int

Displays a dialog with “OK” and “Cancel” buttons.

• Returns:
  • int: A DialogResult constant (OK or CANCEL).

ui.ok_dialog(title: str, message: str) -> int

Displays a dialog with an “OK” button.

• Returns:
  • int: DialogResult.OK.

ui.skip_retry_cancel_dialog(title: str, message: str) -> int

Displays a dialog with “Skip”, “Retry”, and “Cancel” buttons.

• Returns:
  • int: A DialogResult constant (SKIP, RETRY, or CANCEL).

ui.yes_no_dialog(title: str, message: str) -> int

Displays a dialog with “Yes” and “No” buttons.

• Returns:
  • int: A DialogResult constant (YES or NO).

UI Constants

ui.DialogResult

An enumeration for dialog button results.

• Constants:
  • CANCEL (0)
  • OK (1)
  • YES (2)
  • NO (3)
  • SKIP (4)
  • RETRY (5)

ui.ChoiceStyle

Constants for the display style of choice controls.

• Constants:
  • DROPDOWN (0)
  • RADIO_BUTTON (1)

ui.LayoutDirection

Constants for the layout direction of controls in a group.

• Constants:
  • VERTICAL (0)
  • HORIZONTAL (1)

Custom Dialogs (DialogBuilder)

Create complex dialogs by adding controls sequentially.

• Start building: host.ui.dialog(title: str, root_direction: int = LayoutDirection.VERTICAL) -> DialogBuilder
• Show dialog: dialog_builder.show_modal() -> int
• Close dialog: dialog_builder.close(result: int)

Example:

dlg = host.ui.dialog("My Dialog")
name_input = dlg.text("Name:", "Default")
dlg.button("OK").clicked += lambda s, e: dlg.close(host.ui.DialogResult.OK)
result = dlg.show_modal()
if result == host.ui.DialogResult.OK:
    host.log(f"Entered name: {name_input.text}")

DialogBuilder Methods

The DialogBuilder and container elements (GroupProxy, GroupBoxProxy, TabPageProxy) share the following methods for adding controls.

• bool(label: str, initial_value: bool) -> CheckboxProxy
• button(text: str) -> ButtonProxy
• choice(label: str, items: Any, initial_index: int = 0, style: int = ChoiceStyle.DROPDOWN) -> ChoiceProxy
• float(label: str, initial_value: float, min_value: float, max_value: float) -> FloatSliderProxy
• group(direction: int) -> GroupProxy
• group_box(title: str, direction: int) -> GroupBoxProxy
• int(label: str, initial_value: int, min_value: int, max_value: int) -> IntSliderProxy
• label(text: str) -> LabelProxy
• separator() -> SeparatorProxy
• tab() -> TabProxy
• text(label: str, initial_text: str = '') -> TextBoxProxy

Container Controls

• group(direction: int) -> GroupProxy: Creates a container to group controls.
• group_box(title: str, direction: int) -> GroupBoxProxy: Creates a bordered container with a title.
• tab() -> TabProxy: Creates a tab control.
  • tab_proxy.page(title: str) -> TabPageProxy: Adds a new page to the tab control.

Control Proxies

When you add a control to a dialog, a proxy object is returned. You can use this object to access the control’s properties and events.

• Common Properties:

  • enabled (bool): Get or set whether the control is enabled.

• TextBoxProxy:

  • text (str): Get or set the text content.

• CheckboxProxy:

  • value (bool): Get or set the checked state.

• IntSliderProxy:

  • value (int): Get or set the current integer value.

• FloatSliderProxy:

  • value (float): Get or set the current float value.

• ChoiceProxy:

  • selected_index (int): Get or set the index of the selected item.
  • selected_item (str): Get the text of the selected item.

• ButtonProxy:

  • clicked: An event that you can subscribe to. The handler receives (sender, event_args).

• Other Proxies: LabelProxy, SeparatorProxy, GroupProxy, GroupBoxProxy, TabProxy, TabPageProxy. These are primarily for layout and have an enabled property.