comet.dialog

This module provides helper functionality to create commonly used dialogs for querying user input.

See also

Class CDialog

Create custom dialogs dialogs for your scripts.

Methods

comet.dialog.create(dialogSpec='')

Create a new CDialog object which can then be further modified using the class functions.

The dialog can either be created using an existing dialog specification - which is a JSON string - or by not providing a specification, resulting in a new empty dialog.

Parameters:

dialogSpec (str) –

The JSON specification.

  • Empty str: Empty dialog

Returns:

The newly created dialog. This dialog is not shown yet!

Return type:

CDialog

Raises:

CometError – On internal error

Available:

InDesign® Illustrator®

comet.dialog.askStr(title='', label='', text='', okay='', cancel='', multiLine=True, maxChars=-1)

Open a dialog to enter text.

Parameters:

  • title (str) – The dialog title.

  • label (str) – Hint for the text field.

  • text (str) – The initial text for the entry field.

  • okay (str) –

    Caption for the ‘Ok’ button.

    • Empty str: ‘Okay’

  • cancel (str) –

    Caption for the ‘Cancel’ button.

    • Empty str: ‘Cancel’

  • multiLine (bool) – Whether the dialog should have a text field for entering multi line text.

  • maxChars (int) –

    Impose a limit to the number of characters that can be entered.

    • <0: No limit.

    Warning

    Illustrator® Not implemented when parameter multiLine is True

Returns:

Whether the user accepted the dialog, and the content of the text field.

Return type:

tuple[bool, str]

Raises:
Available:

InDesign® Illustrator®

CScript:

askstring

comet.dialog.selectFile(title='', askForNew=False, suggestion='')

Open a dialog to select an existing file or get the path for a new file.

Parameters:

  • title (str) – The dialog title.

  • askForNew (bool) –

    • True: Ask for a filepath for a new file

    • False: Ask for an existing file

  • suggestion (str) –

    Full path for a suggested file.

    May contain tokens like $DESKTOP, etc…

Returns:

  • User selected a path: The selected filepath

  • User cancelled: None

Return type:

str | None

Raises:
Available:

InDesign® Illustrator®

CScript:

file::select_file

comet.dialog.selectFolder(title='', suggestion='')

Open a dialog to select an existing folder.

Parameters:

  • title (str) – The dialog title.

  • suggestion (str) –

    Full path for a suggested folder.

    May contain tokens like $DESKTOP, etc…

Returns:

  • User selected a path: The selected folder

  • User cancelled: None

Return type:

str | None

Raises:
Available:

InDesign® Illustrator®

CScript:

file::select_folder

comet.dialog.selectImage(title, label, input)

Open a dialog to select an image from a list of inputs.

Parameters:

  • title (str) – The dialog title.

  • label (str) – Descriptive label for the list.

  • input (str | list[tuple[str, str, str, str]]) –

    Data for filling the image list.

    The parameter type can be:

    • str:

      SQL or xmlquery statement for loading the key-value pairs.

      The statement must provide five result columns (int, image, string, string, string) for ID, image, name, type and status.

      For XML and SOAP connections, a complete path to the image file is expected instead of the image.

    • list [tuple [str, str, str, str]]

      Data to fill the dialog.

      Each list entry represents an image to display.

      The values per tuple must be as follows:

Returns:

  • User selected an entry: Index, ID, Name, Type, State

  • User cancelled: None

Return type:

tuple[int, int, str, str, str] | None

Available:

InDesign® Illustrator®

CScript:

retint_dialog

Examples:

Select an image from a folder on the file system.

#!py
#pragma plain

import os
import comet

def main():
    entries = []

    #Select up to 20 images from a folder on the desktop
    for i in range(20):
        #Filenames are 001.jpg, 002.jpg, ...
        path = f'$DESKTOP/Images/{str(i).zfill(3)}.jpg'
        name = os.path.basename(path)
        entries.append((path, name, 'Image', 'Ok'))

    #Open the dialog to prompt the user to select an entry
    results = comet.dialog.selectImage(
        'Select an image',
        'Paintings',
        entries
    )

    if not results:
        #User cancelled
        return 0

    #Get the path for the image from the input set
    path = entries[results[0]][0]

    #Set the image to the current frame
    comet.gFrame.setImage(path)

    return 0