Palette:popMenu

From TouchDesigner Documentation
Jump to: navigation, search

Pop-up Menu

Summary
[edit]

The popMenu custom Component builds on Container COMP to make an easy-to-use pop-up menu that can be used as a context menu, in dropdown controls, or for other menu needs. The dialog can be set up using parameters or script. Multi-level menus can be created through scripting. Custom formatting of popMenu is set up in the internal config Component. A callback system is provided for more complex needs.

There is a system popMenu available in op.TDResources, so for many needs a call to op.TDResources.op('popMenu').Open(...) is all that is needed to create a menu. The system popMenu has two levels of submenu attached to it to facilitate multi-level context menus.

Just as the system popMenu can be used for many different purposes (as long as only one is open at a time) it is highly recommended to reuse a custom popMenu as much as possible. That is, once you have configured a popMenu to your liking, use Python to open that same one from different places if possible. This saves memory, creates a uniform menu style, and minimizes Window Components.

For examples of how to set up a popMenu, see PopMenu Custom COMP Examples.

TIP: if your popMenu configuration is dependent on rapidly changing values, turning off its viewer will cause it to consume less time when not in use.

Custom Parameters - Pop Menu Page[edit]

Help Page Helppage - Open this wiki page in a browser.

Open Open - Open the pop-up menu.

Close Close - Close the pop-up menu

Input Table Inputtable - Choose the input table format with this menu.

  • Include All Rows, Column 0 is Items: uses all rows in table with the first column as menu items.
  • First Row is Labels, Column 0 is Items: uses first row of table as labels, with the first column of all following rows as menu items.
  • First Row is Labels, Column "name" is Items: uses first row of table as labels, and the column labeled "name" of all following rows as menu items.

Items Items - A python list of menu item strings, in the order they are to appear.

Highlighted Items Highlighteditems - A python list of visually highlighted items from Items parameter.

Disabled Items Disableditems - A python list of disabled items from Items parameter.

Dividers After Items Dividersafteritems - These items will have a line drawn under them.

Checked Items Checkeditems - A list or dictionary of items with check marks after them. If a dictionary is used, the format is '<item name>': True/False. False items will have an empty checkbox.

Columns Columns - The number of columns in the popMenu. All columns will be of equal width, and items will be listed from top to bottom then left to right. If there is more than one column, dividers, submenus, and checked item features will not be available.

Max Height Maxheight - If the menu is taller than this, a scrollbar will be used.

Auto Close Autoclose - If true, the menu will be closed when a choice is made.

Borders Borders - Display menu borders.


Horizontal Align Horizontalalign - Defines the horizontal anchor point of the menu when it is opened.

Vertical Align Verticalalign - Defines the vertical anchor point of the menu when it is opened.

Align Offset Alignoffset - Offset from the anchor point when menu is opened.


Button Comp Buttoncomp - A component that the menu is displayed relative to. If this is not a valid comp, menu will be displayed relative to mouse.

Horizontal Attach Horizontalattach - The horizontal location on Button Comp the menu is attached to.

Vertical Attach Verticalattach - The horizontal location on Button Comp the menu is attached to.

Custom Parameters - Advanced Page[edit]

Edit Callbacks Editcallbacks - Edit the callbacks DAT.

SubMenu Submenu - Another popMenu that opens as a submenu to this one.

Allow Sticky SubMenus Allowstickysubmenus - If True, clicking on a submenu entry will set it to stay open when an item is selected.

Print Callbacks Printcallbacks - Debug messages for callbacks. See Callbacks.

Callback DAT Callbackdat - DAT containing callback definitions. See Callbacks.

Config Comp Configcomp - This popMenu's config Component. See Config Comp.

Window Comp Windowcomp - This popMenu's window Component. Note: the internal window component is not clone immune, so to safely customize, create an external one or switch the internal one's clone immune flag on.

Inputs[edit]

inputTable - A table of items and, optionally, other information. Formatted as defined in the Input Table parameter.

Outputs[edit]

selected - A CHOP containing the currently selected Item index, or -1 if the menu is open but nothing has been selected.

selectedRow - A table containing the currently selected Item or nothing if menu is open but nothing has been selected. When using an input table, this will contain that table's labels and all columns from the selected row

PopMenu Extension Class[edit]

The PopMenuExt extension provides script functionality for working with popMenu. Frequently used members and methods are listed here. A full list can be found using the Python help() function. Note that within the extension, a each clickable Item area is called a cell. The cell number is the same as the Item index. A cell number of -1 is sometimes used to mean "no cell".

Members[edit]

OptimalWidth (Read Only) The best width for the menu to display all cells. Generally used by the width parameter.
OptimalHeight (Read Only) The best width for the menu to display all cells. Generally used by the height parameter.
Items (Read Only) The list of items in the pop menu.

Methods[edit]

Open(items=None, callback=None, callbackDetails=None, disabledItems=None, dividersAfterItems=None, checkedItems=None, subMenuItems=None, autoClose=None, rolloverCallback=None)

Opens the menu. Usually, a call to this method and a callback (provided in argument here or defined in Callback DAT) is all that is needed to use popMenu. Arguments set to None will use the values set in the popMenu's parameters.
  • items - a list of item strings for the menu. If this is None or not provided, the default is to use the Items set up in parameters. If provided, these options will replace the ones in the Items parameter, and other Item parameters will be ignored (e.g. Disabled Items).
  • callback - a method that will be called when a selection is made.
  • callbackDetails - will be passed to callbacks in addition to item chosen.
  • disabledItems - list of strings for greyed out, unselectable items.
  • dividersAfterItems - list of strings for items with dividers below them.
  • checkedItems - list of strings for items with check marks next to them. Will show the 'check' graphic in configComp. Also accepts a dict of strings with 'item': bool. Will show the 'checkOn' or 'checkOff' graphic depending on bool. Also accepts a string which will be used as an EXPRESSION to continually evaluate.
  • subMenuItems - list of strings for items with indicator and will select on rollOver instead of click. Always use OpenSubMenu in handler function. Set SubMenu parameter to another popMenu comp. Default is []... no parameter available for submenus.
  • autoClose - will close after selection or click away.
  • rolloverCallback - will be called when a cell is rolledOver. A callback with cell -1 will be called when mouse leaves menu or menu closes. Uses same callbackDetails as selection callback.

OpenSubMenu(items=None, callback=None, callbackDetails=None, disabledItems=None, dividersAfterItems=None, checkedItems=None, subMenuItems=None, autoClose=None, rolloverCallback=None)

Opens the menu's sub-menu. All arguments are exactly as in the Open method above. For all sub-menu items, this method must be called from the selection callback.

SetPlacement(hAlign='Left', vAlign='Top', alignOffset=(0,0), buttonComp=None, hAttach='Left', vAttach='Bottom', matchWidth=False)

Set up placement parameters for the popMenu. This is a convenience function for reusing popMenu as a dropdown menu in multiple places
  • hAlign - set Horizontal Align.
  • vAlign - set Vertical Align.
  • alignOffset - set Align Offset.
  • buttonComp - set Button COMP.
  • hAttach - set Horizontal Attach.
  • vAttach - set Vertical Attach.
  • matchWidth - True = match width of menu to width of button Comp, False = optimal width, number = specific width.

Close()

Close the menu. The selection callback will not be called.

OnSelect(cell, doautoClose=True)

Simulates a click of the provided cell.
  • cell - the cell number to simulate a click on.
  • doautoClose - (Optional) if False, skip all auto close functionality.

Python Callback System[edit]

The CallbackExt extension provides Python callback functionality to custom components. All callbacks will be passed a single argument containing an info dictionary. Callbacks can be defined in the DAT named in the Callback DAT parameter. To report all callbacks to the textport, turn on the Print Callbacks toggle parameter. The Callback DAT and Print Callbacks parameters are often found on the Callbacks parameter page, but their location can be customized.

The info dictionary always contains an "ownerComp" key. It will also have a "callbackName" key holding the callback name. It will sometimes contain an "about" key, describing the callback, and should always contain this key if a return value is expected. Generally, callbacks are called AFTER the internal method they are associated with, to allow over-riding of whatever that method does.

See also: CallbacksExt Extension

PopMenu Callbacks[edit]

  • onSelect: A selection has been made in the dialog. This is another way to achieve the effect of providing a callback via the Open method. The data provided in the info dictionary is as follows:
  • index: The index in the menu's list of items.
  • item: The label in the menu's list of items.
  • row: The full row of info from the wired-in table of items, if there is one. Otherwise, None.
  • details: Callback details, as provided in the Open method.
  • menu: The popMenu itself.
  • onRollover: A cell has been rolled over. The data provided in the info dictionary is the same as for the onSelect callback, however the cell can be -1, meaning that the mouse is not over any cell.
  • onOpen: Called when popMenu is opened. The details and menu are provided as described above.
  • onClose: Called when popMenu is closed. The details and menu are provided as described above.
  • onMouseUp: The mouse has been released. The data provided in the info dictionary is the same as for the onSelect callback, however the cell can be -1, meaning that the mouse is not over any cell.
  • onMouseDown: The mouse has been pressed. The data provided in the info dictionary is the same as for the onSelect callback, however the cell can be -1, meaning that the mouse is not over any cell.
  • onClick: The mouse has been pressed and released on the same cell. The data provided in the info dictionary is the same as for the onSelect callback, however the cell can be -1, meaning that the mouse is not over any cell.
  • onLostFocus: The popMenu has lost focus.

Config Comp[edit]

The internal config Comp is where the colors, fonts, and graphics for popMenu are set up.

colDefine table[edit]

The colDefine table in popMenu's config Comp is only used to define the symbol column for subMenus and check boxes. The only thing that should be changed his the 'width' value if custom symbols with a different size are created.

TOPs[edit]

The subMenu, checkOn, and checkOff TOPs are the graphics used for these elements in the popMenu. The various button____ textTOPs define the cell format for list elements.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.

An Operator Family that manipulates text strings: multi-line text or tables. Multi-line text is often a command Script, but can be any multi-line text. Tables are rows and columns of cells, each containing a text string.

Some operators have a DAT docked to them that contains some python functions. These functions, called "callbacks", get called when something in the operator changes.

Strictly refers to a window in Microsoft Windows. User-created windows are made with Panels inside Window Components, aside from the TouchDesigner editor window and its dialogs.

An Operator Family which operate on Channels (a series of numbers) which are used for animation, audio, mathematics, simulation, logic, UI construction, and many other applications.

An Operator Family that contains its own Network inside. There are twelve 3D Object Component and eight 2D Panel Component types. See also Network Path.