Windows

Windows are the foundation of interfaces. Ezui windows have three sections:

A toolbar. This is the standard toolbar seen across macOS. Toolbars are optional.
Content. This is the area of the window where the main items are contained.
A footer. This is a common design element in macOS, so ezui provides a shortcut for creating them. Footers are optional.

Window Types

There are several window types, each with their own unique uses. Refer to the macOS HIG for details on when to use the various window types.

`EZWindow`	A window.
`EZPanel`	A floating window.
`EZSheet`	A sheet attached to a parent window.
`EZPopUp`	A pop up window.
`EZPopover`	A popover.

Note

Popovers are not technically windows, but they behave enough like windows that we consider them to be windows within ezui.

A progress window is available, though it is not as customizable as the window types listed above.

ProgressWindow

A progress window.

EZWindow

class ezui.EZWindow

A window. EZWindow is a subclass of vanilla.Window.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        This is a window.
        """
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

Constructor Arguments

size The size of the window. This can be "auto" indicating that the window should calculate it’s size, a tuple of integers (400, 500) indicating a specific width and height, a tuple with a specific specific width (400, "auto") or a tuple with a specific height ("auto", 500). The default value is "auto".

title The title of the window. Optional.

minSize The minimum size for the window. This must be a tuple of integers. Optional.

maxSize The maximum size for the window. This must be a tuple of integers. Optional.

content A content description. See below for details.

toolbar A toolbar description. See below for details. Optional.

footer A footer description. See below for details. Optional.

activeItem The identifier of the item that should be active when the window is open. Optional.

defaultButton The identifier for the button that should be the default button in the window. Optional.

tabLoops A lists of lists containing identifiers defining the desired loops when the tab key is pressed. Optional. See below for an example.

margins The margins between the edge of the window and the window contents. This can be an integer indicating the margin on all sides, a tuple of two integers indicating the (x, y) margins or a tuple of four integers indicating the (left, bottom, right, top) margins. Optional.

document A NSDocument object to assign this window to. Optional.

autosaveName An identifier for this window. This will be used to store the window location in the application preferences. Optional.

controller The controller for this window. This must be a subclass of WindowController. Optional but highly recommended.

descriptionData Description data for the items. Optional.

Content Description

The content description defines a container of items to display in the window. The default container type is VerticalStack. To change the container type, make the first line of your content = ContainerType with ContainerType being the name of the container type you want to use.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        = HorizontalStack
        One.
        Two.
        Three.
        """
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

Toolbar Description

A window may have a toolbar.

class DemoController(ezui.WindowController):

    def build(self):
        toolbar = dict(
            autosaveName="demoToolbar",
            contents=[
                dict(
                    identifier="regularItem",
                    image=ezui.makeImage(symbolName="hare"),
                    text="Faster"
                ),
                dict(
                    identifier="flexibleSpace"
                ),
                dict(
                    identifier="ezuiItem",
                    content="( X {sun.max.fill} X | {cloud.heavyrain.fill} )",
                    text="Weather"
                ),
            ]
        )
        self.w = ezui.EZWindow(
            title="Demo",
            size=(400, 100),
            toolbar=toolbar,
            controller=self
        )

    def started(self):
        self.w.open()

    def regularItemCallback(self, sender):
        print("Faster!")

    def ezuiItemCallback(self, sender):
        value = sender.get()
        if value == 0:
            weather = "Sun"
        else:
            weather = "Rain"
        print(f"Weather: {weather}!")

DemoController()

Toolbars are created with a description in the form of a dictionary. These are the keys and values:

autosaveName A unique identifier for the toolbar. If one is not given, the window’s autosaveName will be used to create a toolbar identifier.

contents A list of toolbar item description dictionaries. These are the key/value pairs:

key	value	default
`"identifier"`	An identifier for the item.
`"text"`	The title for the item.	`""`	optional
`"image"`	The image for the item.	`None`	optional
`"content"`	A description of an ezui item.	`None`	optional
`"visible"`	The default visibility of the item.	`True`	optional
`"selectable"`	If the item is selectable.	`False`	optional
`"callback"`	The callback for the item.	`None`	optional

Common items can be specified with the following identifier strings:

"space"
"flexibleSpace"

displayMode The display mode for the toolbar.

"auto"
"imageAndText"
"image"
"text"

allowCustomization If the toolbar can be customized.

Footer Description

A window may have a footer.

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        This is window content.

        =======================

        (Options ...) @optionsPopUpButton
        (Cancel)      @cancelButton
        (OK)          @okButton
        """
        descriptionData = dict(
            optionsPopUpButton=dict(
                gravity="leading",
                items=[
                    "A",
                    "B",
                    "C"
                ]
            )
        )
        self.w = ezui.EZWindow(
            title="Demo",
            size=(300, "auto"),
            content=content,
            descriptionData=descriptionData,
            controller=self
        )

    def started(self):
        self.w.open()

    def optionsPopUpButtonCallback(self, sender):
        print(f"Option: {sender.get()}")

    def cancelButtonCallback(self, sender):
        print("Cancel!")
        self.w.close()

    def okButtonCallback(self, sender):
        print("OK!")
        self.w.close()

DemoController()

Footers may be defined within the content text description or independently with the footer argument. To indicate the footer’s contents within the content text description, add a line containing only = and all items following that line will be added to the footer. If you want a line to appear above the footer, make the first and last characters of the line = and all middle characters -.

Footer items are displayed in a HorizontalStack with the default alignment for items set to "trailing". If you want to change any of the stack behavior, use the descriptionData to specify your changes.

Tab Loops

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        [__] A              @fieldA
        [__] B              @fieldB
        [__] C              @fieldC
        [__] 1              @field1
        [__] 2              @field2
        [__] Not In A Loop  @fieldXXX
        """
        tabLoops = [
            [
                "fieldA",
                "fieldB",
                "fieldC"
            ],
            [
                "field1",
                "field2",
            ]
        ]
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            tabLoops=tabLoops,
            size=(300, "auto"),
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

open

close

Close the window.

Once a window has been closed it can not be re-opened.

hide: Hide the window.

show: Show the window if it is hidden.

getTitle: The title in the window’s title bar.

center: Center the window within the screen.

EZPanel

class ezui.EZPanel

A floating window. EZPanel is a subclass of vanilla.FloatingPanel. Panel usage documentation.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        This is panel content.
        """
        self.w = ezui.EZPanel(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

Constructor Arguments

EZPanel supports all of the constructor arguments in ezui.EZWindow.

open

close

Close the window.

Once a window has been closed it can not be re-opened.

hide: Hide the window.

show: Show the window if it is hidden.

getTitle: The title in the window’s title bar.

center: Center the window within the screen.

EZSheet

class ezui.EZSheet

A sheet attached to a parent window. EZSheet is a subclass of vanilla.Sheet. Sheet usage documentation.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        (Open Sheet) @openSheetButton
        """
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

    def openSheetButtonCallback(self, sender):
        DemoSheetController(self.w)


class DemoSheetController(ezui.WindowController):

    def build(self, parent):
        content = """
        This is sheet content.

        ======================

        (Cancel) @cancelButton
        (OK)     @okButton
        """
        descriptionData = dict(
        cancelButton = dict(
            keyEquivalent=chr(27)  # call button on esc keydown
            )
        )

        self.w = ezui.EZSheet(
            content=content,
            descriptionData=descriptionData,
            parent=parent,
            controller=self
        )

    def started(self):
        self.w.open()

    def cancelButtonCallback(self, sender):
        self.w.close()

    def okButtonCallback(self, sender):
        self.w.close()

DemoController()

Constructor Arguments

EZSheet supports all of the constructor arguments in ezui.EZWindow. It also supports the following arguments:

parent The parent window the sheet should be attached to. This must be an instance of EZWindow, EZPanel or vanilla.Window. Required.

If a footer is not given, a “Close” button will be automatically added to the footer.

open

close

Close the window.

Once a window has been closed it can not be re-opened.

EZPopUp

class ezui.EZPopUp

A pop up window. This window type is useful for interfaces that appear and are quickly dismissed. This is not a standard macOS window type, but it is a common need in type design tools.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        (Open PopUp) @openPopUpButton
        """
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

    def openPopUpButtonCallback(self, sender):
        DemoPopUpController(self.w)


class DemoPopUpController(ezui.WindowController):

    def build(self, parent):
        content = """
        This is PopUp content.
        """
        self.w = ezui.EZPopUp(
            content=content,
            parent=parent,
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

Constructor Arguments

EZPopUp supports the size, content, footer and margin constructor arguments in ezui.EZWindow. It also supports the following arguments:

parent A parent control or window to position the pop up over. Optional.

parentAlignment The alignment position within the parent. This should be a tuple of the following values. Optional.

X alignment options:

`"left" `"right" `"center"

Y alignment options:

`"top" `"bottom" `"center"

parentOffset An (x, y) offset within the parent.

close

open

center: Center the window within the screen.

EZPopover

class ezui.EZPopover

A popover. EZPopover is a subclass of vanilla.Popover. Popover usage documentation.

import ezui

class DemoController(ezui.WindowController):

    def build(self):
        content = """
        (Open Popover) @openPopoverButton
        """
        self.w = ezui.EZWindow(
            title="Demo",
            content=content,
            controller=self
        )

    def started(self):
        self.w.open()

    def openPopoverButtonCallback(self, sender):
        DemoPopoverController(self.w)


class DemoPopoverController(ezui.WindowController):

    def build(self, parent):
        content = """
        This is Popover content.
        """
        self.w = ezui.EZPopover(
            content=content,
            parent=parent,
            controller=self
        )

    def started(self):
        self.w.open()

DemoController()

Constructor Arguments

EZPopover supports the size, content, footer and margin constructor arguments in ezui.EZWindow. It also supports the following arguments:

parent A parent control to position the popover near.

parentAlignment Where to position the popover. Options:

`"left" `"right" `"top" `"bottom"

behavior The behavior of the popover. Options:

"applicationDefined"
"transient"
"semitransient"

open(parent=None, parentAlignment=None, location=None)

Open the Popover.

The parent and parentAlignment arguments are the same as the arguments in the constructor. These are used to override the arguments given in the constructor if needed.

location A tuple of four integers indicating the (x, y, width, height) rectangle to which the Popover should be opened near. If not given, the frame of parent given in the constructor will be used.

close()

Close the popover.

Once a popover has been closed it can not be re-opened.

resize(width, height): Change the size of the popover to width and height.

ProgressWindow

class ezui.ProgressWindow(*args, **kwargs)

A progress window. This is usually created with the startProgress() method of WindowController.

build(text='', maxValue=None, parent=None): This will be called when the controller is initialized. Subclasses should override this to build the window that this controller controls. The window must not be opened while this method is executing. Open the window in the started method.

started(): This will be called after the build process is completed. Subclasses should override this to open the window that this controller controls and do any other work that can’t be completed in the build method.

close(): Stop the progress bar and close the window.

set(value): Set the value of the progress bar.

increment(): Increment the progress bar.

setText(text): Set the contents of the label.

setMaxValue(value): Set the total tick count.