Example `gui_notes`¶

Demonstrates how to build and run a modal dialog (a note).

Code¶

"""Demonstrates how to build and run a modal dialog (a note).

This directory contains three examples for notes interfaces. All three implement the same
coffee maker interface, where the user can select a coffee type and then serve it. The examples are:

- ex_gui_notes.py            : A modern Pythonic implementation of a notes interface.
- ex_gui_zscript_port.py     : A literal port of a ZScript notes interface to Python.
- ex_gui_zscript_orginal.txt : The original ZScript notes example for reference.
"""
__author__ = "Ferdinand Hoppe"
__date__ = "21/08/2025"
__copyright__ = "Maxon Computer"

import os
import platform

from zbrush import commands as zbc


class CoffeeSelectionDialog:
    """Implements a coffee selection dialog using ZBrush notes.
    """
    # The IDs of the various buttons in the dialog, they are defined by the order in which we add
    # buttons to the note.
    ID_BTN_BG: int = 1 
    ID_BTN_1: int = 2
    ID_BTN_2: int = 3
    ID_BTN_3: int = 4
    ID_BTN_4: int = 5
    ID_BTN_5: int = 6
    ID_BTN_CUP: int = 7
    ID_BTN_CANCEL: int = 8
    ID_BTN_SERVE: int = 9

    def __init__(self) -> None:
        """Initializes the dialog state.
        """
        self.h_size: int = 20  # The horizontal size of a coffee button.
        self.v_size: int = 18  # The vertical size of a coffee button.
        self.v_pos: int = 87  # The vertical offset of a coffee button.
        self.h_pos: int = 23  # The horizontal position of a coffee button.
        self.space: int = 12  # The horizontal space between the coffee buttons.

        # The paths of the images used to display the coffee choices.
        image_dir: str = os.path.join(os.path.dirname(__file__), "images")
        self.images: list[str] = [os.path.join(image_dir, "expresso.jpg"), 
                                  os.path.join(image_dir, "cappuccino.jpg"), 
                                  os.path.join(image_dir, "latte.jpg"),
                                  os.path.join(image_dir, "mocha.jpg"), 
                                  os.path.join(image_dir, "flat white.jpg")]
        self.background_image: str = os.path.join(image_dir, "ZCoffeeBack.jpg")

        # On macOS, we must prefix absolute paths with '!:' to make ZBrush load them correctly.
        if platform.system() == "Darwin":
            self.images = [f"!:{path}" for path in self.images]
            self.background_image = f"!:{self.background_image}"

        # The currently selected coffee as an index out of the five buttons.
        self.selected_coffee: int = 0

        # The message to return when the user made a choice.
        self.message: str = ""

    def run(self) -> None:
        """Runs the note and returns the result as #self.message.
        """
        while True:
            # Add a button filling the full canvas which we disable and give an icon. So, we repurpose
            # a button to just display the background image.
            zbc.add_note_button(name="", icon_path=self.background_image, initially_pressed=False, 
                                initially_disabled=True, h_rel_position=1, v_rel_position=305, 
                                width=320.0)

            # Add the five buttons to select a coffee, we use the #selected_coffee to decide if the
            # button should have an "x" as the label and if it is in a pressed stated.
            for i in range(5):
                label: str = "x" if i == self.selected_coffee else ""
                is_pressed: bool = i == self.selected_coffee
                zbc.add_note_button(name=label, icon_path="", initially_pressed=is_pressed,
                    initially_disabled=False, h_rel_position=self.h_pos,
                    v_rel_position=self.v_pos + ((self.v_size + self.space) * i),
                    width=self.h_size, height=self.v_size, bg_color=-1, text_color=0xffa000,
                )

            zbc.add_note_button("", self.images[self.selected_coffee], False, True, 149, 135)
            zbc.add_note_button("Cancel", "", False, False, 170, 260, 100, 25)
            zbc.add_note_button("Serve Now", "", False, False, 30, 260, 100, 25, -1, 0xffa000)

            # The trick is now to dummy open the note dialog to poll its interface state. #action
            # will hold the value of the last interaction.
            action: int = zbc.show_note("")

            # The user clicked the cancel button, we set the message.
            if action == self.ID_BTN_CANCEL:
                self.message = "\Cffa000\n  What, no coffee?!\n"
                return
            # The user clicked the serve button, we mangle the selected coffee image name to return a 
            # message with the name of the selected coffee. E.g., ".../expresso.jpg" -> "expresso"
            elif action == self.ID_BTN_SERVE:
                coffee: str = os.path.basename(self.images[self.selected_coffee]).rsplit(".", 1)[0]
                self.message = f"\Cc0c0c0Enjoy your \Cffa000 {coffee} \Cc0c0c0 !\n"
                return
            
            # The user clicked one of the coffees, we update the selection. #action must be offset
            # by the first button ID so that we end up with a selection in the range [0, 4].
            if action in (self.ID_BTN_1, self.ID_BTN_2, self.ID_BTN_3, self.ID_BTN_4, self.ID_BTN_5):
                self.selected_coffee = action - self.ID_BTN_1

def main() -> None:
    """Executed when ZBrush runs this script.
    """
    # Freeze the UI while the note interface is running and then display the returned message.
    dlg: CoffeeSelectionDialog = CoffeeSelectionDialog()
    zbc.freeze(dlg.run)
    zbc.show_note(text=dlg.message, item_path="", display_duration=2.0, 
                  bg_color=zbc.rgb(125, 125, 125))


if __name__ == "__main__":
    main()

Category	Option	Description
Query		The search does not support special search operators. Terms are joined by default with OR unless the AND join mode is enabled. Queries can contain search literals denoted by double quotes. E.g., `foo bar` would search for documents that contain `foo` and/or `bar` (depending on the selected join option). But `"foo bar"` would search for the exact phrase "foo bar". The search is case-insensitive. Note that search literals will always implicitly enable strict search mode, even when the user has selected fuzzy mode.
	/	Toggles the visibility of the facet selection panel.
	/	Toggles the visibility of this help panel.
	OR / AND	Toggles between joining search terms with a logical OR or AND. In OR mode, the search will return results that match any of the search terms, while in AND mode, it will only return results that match all of the search terms.
	/	Toggles between fuzzy and strict mode when searching. In fuzzy mode, the search is more lenient and may return more results, while in strict mode, the search is more exacting. Switching modes may affect the relevance of the results.
	/	Toggles between detailed and compact result views. The detailed view shows more information per search hit.
	/	Toggles sorting the search results by relevance only or by a combination of classification and relevance. When sorting by classification and relevance, results are grouped by their type (e.g., pages, classes, methods) and then sorted by relevance within each group.
Facets		Facets restrict the search to specific content types. You must have at least one facet enabled per facet group to see any results. Domain is the largest facet group, enabling or disabling whole groups of content types. Entities are the next level down, allowing you to search within specific types of content such as generic pages or a function definition. Contexts are the most granular level, allowing you to search within specific contexts of the selected entity such as a code block ot the name of an entity.
Domain	API	Enable matches within API documentation pages.
	Manuals	Enable matches within general documentation pages.
	Examples	Enable matches within example pages.
Entity	Page	Enable matches within a page body that are not one of the following entities.
	Classes	Enable matches within class definitions.
	Methods	Enable matches within class method definitions.
	Functions	Enable matches within module function definitions.
	Attributes	Enable matches within class or module attribute definitions.
Context	Paragraphs	Enable matches within normal text paragraphs of a page.
	Headings	Enable matches within the headings of a page.
	Code	Enable matches within code blocks of a page (e.g., in the Examples domain or code blocks embed elsewhere).
	Names	Enable matches within the names of API entities. This searches the plain names (`func`), not the qualified names (`foo.bar.func`).
	Signatures	Enable matches within the signatures of API entities. The signature is what is shown on top of the entity description, e.g., `foo.bar.func(a: int, b: str = "Hello") -> bool`. When you want to search for fully qualified names, you should enable this option and disable the "Names" option.
	Metadata	Enable matches within the metadata of entities.

Example gui_notes¶

Code¶

Search

Example `gui_notes`¶