Skip to content

Annotate and document ui.py #820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 2 commits into
base: v1
Choose a base branch
from
Draft

Annotate and document ui.py #820

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
51e634e
Add type annotation and improve documentation.
knutnergaard Mar 1, 2025
e6abdf3
Format fixes by ruff
knutnergaard Mar 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 184 additions & 106 deletions Lib/fontParts/ui.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,72 +1,108 @@
from __future__ import annotations
from typing import TYPE_CHECKING, Optional, Union

from fontParts.world import _EnvironmentDispatcher
from fontParts.base.annotations import CollectionType

if TYPE_CHECKING:
from fontParts.base.font import BaseFont

def AskString(message, value="", title="FontParts"):
"""
An ask a string dialog, a `message` is required.
Optionally a `value` and `title` can be provided.

::
def AskString(
message: str, value: Optional[str] = None, title: Optional[str] = "FontParts"
) -> str:
"""Dispaly a dialog to ask for a string input.

:param message: The message to display in the dialog as a :class:`str`.
:param value: The optional default value to display in the input field as
a :class:`str`. Defaults to :obj:`None`.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:return: A :class:`str` representing the input provided by the user.

from fontParts.ui import AskString
Example::

print(AskString("who are you?"))
>>> AskString("who are you?")

"""
return dispatcher["AskString"](message=message, value=value, title=title)


def AskYesNoCancel(message, title="FontParts", default=0, informativeText=""):
"""
An ask yes, no or cancel dialog, a `message` is required.
Optionally a `title`, `default` and `informativeText` can be provided.
The `default` option is to indicate which button is the default button.
def AskYesNoCancel(
message: str,
title: Optional[str] = "FontParts",
default: Optional[int] = 0,
informativeText: Optional[str] = None,
) -> str:
"""Display a dialog to ask a yes, no, or cancel question.

::
:param message: The message to display in the dialog as a :class:`str`.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:param default: The optional default button as an :class:`int`.
Defaults to ``0``.
:param informativeText: The optional additional informative text to display in the
dialog as a :class:`str`. Defaults to :obj:`None`.
:return: A :class:`str` representing the user's response: ``"Yes"``, ``"No"``, or
``"Cancel"``.

from fontParts.ui import AskYesNoCancel
Example::

print(AskYesNoCancel("who are you?"))
>>> AskYesNoCancel("Do you want to continue?")

"""
return dispatcher["AskYesNoCancel"](
message=message, title=title, default=default, informativeText=informativeText
)


def FindGlyph(aFont, message="Search for a glyph:", title="FontParts"):
"""
A dialog to search a glyph for a provided font.
Optionally a `message`, `title` and `allFonts` can be provided.
def FindGlyph(
aFont: BaseFont, message: str = "Search for a glyph:", title: str = "FontParts"
) -> str:
"""Display a dialog to search for a glyph within a provided font.

:param aFont: The font to search for a glyph in as a :class:`BaseFont`.
:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to ``"Search for a glyph:"``.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:return: A :class:`str` representing the name of the matched glyph.

from fontParts.ui import FindGlyph
from fontParts.world import CurrentFont
glyph = FindGlyph(CurrentFont())
print(glyph)
Example::

>>> FindGlyph(myFont)

"""
return dispatcher["FindGlyph"](aFont=aFont, message=message, title=title)


def GetFile(
message=None,
title=None,
directory=None,
fileName=None,
allowsMultipleSelection=False,
fileTypes=None,
):
"""
An get file dialog.
Optionally a `message`, `title`, `directory`, `fileName` and
`allowsMultipleSelection` can be provided.

::

from fontParts.ui import GetFile

print(GetFile())
message: Optional[str] = None,
title: Optional[str] = None,
directory: Optional[str] = None,
fileName: Optional[str] = None,
allowsMultipleSelection: bool = False,
fileTypes: Optional[str] = None,
) -> str:
"""Display a dialog to get a file path.

:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to :obj:`None`.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to :obj:`None`.
:param directory: The optional directory to start the dialog in as a :class:`str`.
Defaults to :obj:`None`.
:param fileName: The optional file name to start the dialog with as a :class:`str`.
Defaults to :obj:`None`.
:param allowsMultipleSelection: A flag to allow multiple file selection as
a :class:`bool`. Defaults to :obj:`False`.
:param fileTypes: The optional file types to filter the dialog with as
a :class:`str`. Defaults to :obj:`None`.
:return: A :class:`str` representing the path of the selected file.

Example::

>>> GetFile()

"""
return dispatcher["GetFile"](
Expand All @@ -80,23 +116,33 @@ def GetFile(


def GetFileOrFolder(
message=None,
title=None,
directory=None,
fileName=None,
allowsMultipleSelection=False,
fileTypes=None,
):
"""
An get file or folder dialog.
Optionally a `message`, `title`, `directory`, `fileName`,
`allowsMultipleSelection` and `fileTypes` can be provided.

::

from fontParts.ui import GetFileOrFolder

print(GetFileOrFolder())
message: Optional[str] = None,
title: Optional[str] = None,
directory: Optional[str] = None,
fileName: Optional[str] = None,
allowsMultipleSelection: bool = False,
fileTypes: Optional[str] = None,
) -> Union[str, CollectionType[str]]:
"""Display a dialog to get file or folder paths.

:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to :obj:`None`.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to :obj:`None`.
:param directory: The optional directory to start the dialog in as a :class:`str`.
Defaults to :obj:`None`.
:param fileName: The optional file name to start the dialog with as a :class:`str`.
Defaults to :obj:`None`.
:param allowsMultipleSelection: A flag to allow multiple file selection as
a :class:`bool`. Defaults to :obj:`False`.
:param fileTypes: The optional file types to filter the dialog with as
a :class:`str`. Defaults to :obj:`None`.
:return: A :class:`str` representing the path of the selected file or folder,
or a :class:`tuple` of paths if ``allowsMultipleSelection=True``.

Example::

>>> GetFileOrFolder()

"""
return dispatcher["GetFileOrFolder"](
Expand All @@ -109,100 +155,132 @@ def GetFileOrFolder(
)


def Message(message, title="FontParts", informativeText=""):
"""
An message dialog.
Optionally a `message`, `title` and `informativeText` can be provided.
def Message(
message: str,
title: Optional[str] = "FontParts",
informativeText: Optional[str] = None,
) -> None:
"""Display a message dialog.

::
:param message: The message to display in the dialog as a :class:`str`.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:param informativeText: The optional additional informative text to display in the
dialog as a :class:`str`. Defaults to :obj`None`.

from fontParts.ui import Message
Example::

print(Message("This is a message"))
>>> Message("This is a message")

"""
return dispatcher["Message"](
message=message, title=title, informativeText=informativeText
)


def PutFile(message=None, fileName=None):
"""
An put file dialog.
Optionally a `message` and `fileName` can be provided.
def PutFile(message: Optional[str] = None, fileName: Optional[str] = None) -> str:
"""Display a dialog to put a file.

::
:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to :obj:`None`.
:param fileName: The optional file name to start the dialog with as a :class:`str`.
Defaults to :obj:`None`.
:return: A :class:`str` representing the path of the selected file.

from fontParts.ui import PutFile
Example::

print(PutFile())
>>> PutFile()

"""
return dispatcher["PutFile"](message=message, fileName=fileName)


def SearchList(items, message="Select an item:", title="FontParts"):
"""
A dialgo to search a given list.
Optionally a `message`, `title` and `allFonts` can be provided.
def SearchList(
items: CollectionType[str],
message: Optional[str] = "Select an item:",
title: Optional[str] = "FontParts",
) -> str:
"""Display a dialog to search a given list.

::
:param items: The list of items to search as a :class:`list` of :class:`str`.
:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to ``"Select an item:"``.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:return: A :class:`str` representing the selected item.

from fontParts.ui import SearchList
Example::

result = SearchList(["a", "b", "c"])
print(result)
>>> SearchList(["a", "b", "c"])

"""
return dispatcher["SearchList"](items=items, message=message, title=title)


def SelectFont(message="Select a font:", title="FontParts", allFonts=None):
"""
Select a font from all open fonts.
Optionally a `message`, `title` and `allFonts` can be provided.
If `allFonts` is `None` it will list all open fonts.
def SelectFont(
message: Optional[str] = "Select a font:",
title: Optional[str] = "FontParts",
allFonts: Optional[CollectionType[str]] = None,
) -> str:
"""Display a dialog to select a font from all open fonts.

::
:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to ``"Select a font:"``.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:param allFonts: The optional list of all open fonts as a :class:`list`
of :class:`str`. Defaults to :obj:`None`.
:return: A :class:`str` representing the selected font.

from fontParts.ui import SelectFont
Example::

font = SelectFont()
print(font)
>>> SelectFont()

"""
return dispatcher["SelectFont"](message=message, title=title, allFonts=allFonts)


def SelectGlyph(aFont, message="Select a glyph:", title="FontParts"):
"""
Select a glyph for a given font.
Optionally a `message` and `title` can be provided.
def SelectGlyph(
aFont: BaseFont,
message: Optional[str] = "Select a glyph:",
title: Optional[str] = "FontParts",
) -> str:
"""Display a dialog to select a glyph from a given font.

::
:param aFont: The font to select a glyph from as a :class:`BaseFont`.
:param message: The optional message to display in the dialog as a :class:`str`.
Defaults to ``"Select a glyph:"``.
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"FontParts"``.
:return: A :class:`str` representing the selected glyph.

from fontParts.ui import SelectGlyph
Example::

font = CurrentFont()
glyph = SelectGlyph(font)
print(glyph)
>>> SelectGlyph(myFont)

"""
return dispatcher["SelectGlyph"](aFont=aFont, message=message, title=title)


def ProgressBar(title="RoboFab...", ticks=None, label=""):
"""
A progess bar dialog.
Optionally a `title`, `ticks` and `label` can be provided.
def ProgressBar(
title: Optional[str] = "RoboFab...",
ticks: Optional[int] = None,
label: Optional[str] = None,
) -> None:
"""Display a progress bar dialog.

::
:param title: The optional title of the dialog window as a :class:`str`.
Defaults to ``"RoboFab..."``.
:param ticks: The optional number of ticks to display in the progress bar as
an :class:`int`. Defaults to :obj:`None`.
:param label: The optional label to display in the progress bar as a :class:`str`.
Defaults to :obj:`None`.

from fontParts.ui import ProgressBar
Example::

bar = ProgressBar()
# do something
bar.close()
>>> bar = ProgressBar()
... # do something
>>> bar.close()

"""
return dispatcher["ProgressBar"](title=title, ticks=ticks, label=label)
Expand Down