# The Custom Panel Editor

The Custom Panel Editor is used to design custom layouts of fields. You enter the Custom Panel Editor via Edit>Custom Panel Editor... or by right clicking on any edit panel preset button and choosing the Edit Custom Panels... menu item.

You choose which panel you want to configure via the popup button at the upper right corner of the editor window. You can modify any number of custom panels before you save your changes if you wish.

The editor allows you to name a custom panel, supply a tooltip for the panel and to layout controls in a 12 row by 2 column grid. Unoccupied grid elements are displayed in yellow, occupied in white and selected in cyan.

With the exception of Action Buttons, components represent a field, property, or some other collection of metadata. Action Buttons, as the name implies launch an action when pressed. Tip: You can provide a tooltip for an action button by placing a Tooltip statement anywhere in the action. Action buttons on an edit panel can be edited via the context menu of the associated function button. Note that when the context menu is displayed via a right click it is available even if no files are loaded.

As opposed to the built in edit panels, fields which can be associated with lists will only display the list access control if the list association exists. For example if you display Category on a custom panel and have not associated Category with a list in Preferences - Lists, the field will not have a drop down control at the right of the field. If you then associate a field with a list the field's display will automatically be updated.

To assign a component to a grid element, right click on an unoccupied grid element to receive the upper left of the control. A popup menu will list the available components.

Only six component types can occur more than once on a given panel: Action Buttons, UDTIs, UDURLs, UFIDs, Comments (named) and File Properties. Comments (named) are comments with a description field (not the default comment which appears on the Info Panel). When assigning one of these components, you will be prompted for the name of the field. This name is the display name as it appears on the associated multi item edit panel. When appropriate, a disclosure button will be available to make it easier to specify common items. The following table describes the fields, the prefix used to differentiate the names in the Custom Panel and the edit panel on which the items are typically displayed. Note that the prefix will not be displayed on the actual custom panel.

> Field | Prefix | Edit Panel
> --- | --- | ---
> Action Buttons | • (A) |
> User Defined Text Item | • (U) | UD Text
> User Defined URL | • (L) | UD URLS
> Unique File Identifier | • (F) | UFIDs
> Comment | • (C) | Comments
> Property | • (P) | Audio

Every component has a minimum number of rows and will be created with the minimum number required. Components which can be resized vertically can use the Expand Up and Down buttons to grow the area occupied by the component. Certain fields which should not contain multiple lines of text can be displayed in a multi-line control as a convenience. Currently these include the Copyright, Description and Produced Notice fields.

Initially an assigned control will occupy a left or right grid element. For components which can be resized, the Expand Left and Right buttons can be used to increase the area occupied by the component.

Components can be moved by the Move Up, Down, Left and Right buttons. Additionally a component can be moved by by dragging the field and pointing to the new position for the upper left hand corner of the field. If the Shift key is down when the drag terminates you are pointing to the new position for the lower left hand corner of the field.

The Shrink buttons can be used to reduce the size of components.

Certain components appear cropped and by default do not occupy a full half of the panel. This includes components such as Track/Track Count, Disc/Disc Count, Year, etc. Components adjacent to cropped components will automatically horizontally expand to use the additional space. This is much like the default layout on the Info panel. If you disable the cropped option, the component will expand to fill a full single grid element. The cropped state, regardless of its setting, is ignored when a component occupies more than one row or column.

If a component has a Resize vertically option, you can elect to have the component resized when the main window is resized. Extra vertical space is divided equally between all resizable components. Components marked as vertically resizable will be resized when rendered unless they are adjacent to another resizable component which does not have the same first grid row or has a different number of initial grid rows. Note this control is only enabled when the associated component occupies at least two full or partial rows.

Custom fields and UDTIs which only occupy a single row can select Display as checkbox. Note that when a field is displayed as a checkbox, its value is coerced to 0 or 1 when read and when written. When multiple files are selected and a checkbox field displays as -, the meaning is multiple values. The setting is only supported with custom fields for historic reasons. A custom field's definition should set the Yes/No state.

Custom fields will be rendered depending on the assigned number of rows, the custom field's list association and its Yes/No setting. The following rules apply:

- If a custom field is defined as being a Yes/No field, it will always be rendered as a checkbox regardless as to the number of rows it is assigned or to the Display as a checkbox setting.
- If a custom field is not defined as being a Yes/No field and Display as a checkbox is set, it will be rendered as a checkbox.
- If a custom field is associated with a list, it will always be rendered with a single row, regardless as to the number of lines it occupies in this panel.

Custom fields are rendered as follows:

- A custom field displayed as a checkbox is rendered much the same as the Skip While Shuffling field.
- A Custom Field not associated with a list, occupying a single row, will be rendered much the same as the Title field.
- A Custom Field associated with a list, occupying a single row, will be rendered much the same as the Artist field.
- A Custom Field not associated with a list, occupying multiple rows, will be rendered much the same as the Comments field.

There are seven artwork oriented components (at most one can be on any panel):

> Artwork Full
>   This is essentially a full featured artwork control. It will display multiple artwork items and is fully editable.
> Artwork Display
>   This is a read only view of the default artwork item. The control can be vertically resized but always occupies one or two full grid columns. ie. it cannot be cropped. The control displays the default artwork item if it is common for all selected files. Double clicking on the image will cause the Artwork panel to be displayed.
> Artwork Metadata
>   This is a read only display of the metadata associated with the default artwork item.
> Thumbnail (1)
>   This is identical to Artwork Display with the exception that it cannot be vertically resized but can be cropped. It occupies a single grid row. Double clicking on the image will cause the Artwork panel to be displayed.
> Thumbnail (2)
>   This is identical to Thumbnail (1) with the exception that it occupies two grid rows.
> Thumbnail (3)
>   This is identical to Thumbnail (1) with the exception that it occupies three grid rows.
> Comments/Thumbnail
>   This is a Comments field as found on the Info edit panel. When a single default artwork item is available for all selected files, the field will display the artwork. Double clicking on the image will cause the Artwork panel to be displayed.

There are three controls which can describe an unnamed comment (at most one can be on any panel):

> Comments
>   The standard multi line display for a Comments field.
> Comments (list)
>   A single line Comments display. This field will use a list association configured in Preferences - Lists. When associated with a list, the generated field will have access to a popup menu as with the Artist, Conductor, etc. fields. There is no reason to use this field type other than to display the field with the list access.
> Comments/Thumbnail
>   This is a Comments field as found on the Info edit panel. When a single default artwork item is available for all selected files, the field will display the artwork. Double clicking on the image will cause the Artwork panel to be displayed.

Link items are available. Link items end with an → character︎. Link items are only visible when there is content to be displayed on the associated multi-item edit panel. eg. the User Defined Text Info Items → link will only be visible on a Custom Panel if there are items to be displayed on the UD Text edit panel.

The Display title field can be used to provide an alternate display title for a component. If you supply an alternate display title for the Rating field, remember that ??? will automatically be appended to the title when multiple values are represented. The dual item components Track Count, Disc Count and Movement have two labels each. Track, Disc, Movement and of. Both labels can be replaced by separating two labels with a / separator. Track and Disc cannot be replaced by an empty label while of can. If a / separator is not found, the of label will not be replaced.

User Defined Text Items can be forced to display contained items separated by the multi-value separator (;;;) one per line with the separators removed. The data is converted appropriately before being displayed and when written. To enable this, add a UDTI item to the panel and configure it to occupy more than one row. Assign the item a display name starting with a semi-colon (;). The semi-colon will not be displayed.

Action Button titles, (the actual action name or the supplied Display Title), are treated the same as names assigned to the default Action 1-10 toolbar buttons. You can implicitly specify a portion of the name to be used as a button label by enclosing the desired text in square brackets. While this really only makes sense on the actual action name, the logic is applied on a supplied Display Title as well.

# Adding Grid Rows

The 12 row by 2 column grid is based on the size required to display the built in editing panels. If you want additional grid rows, simply resize the panel editor vertically. To reduce the number of grid components simply make the Custom Panel Editor window smaller. Depending on how much you reduce the size, components may be shrunk or eliminated entirely.

Custom edit panels can have vertically resizable fields. If the main window is vertically larger than the minimum requirement for a panel, these fields will be expanded. When the main window is vertically smaller than the minimum requirement for a panel, the panel can be scrolled. In this case each field will occupy its minimum amount of space.

# Combining Fields

The minimum width of an edit panel was chosen such that all fields placed in grid cells have sufficient space to display properly. If you do not mind increasing the width of the edit panel area, you can choose to combine two fields into a single grid cell. Combined fields cannot be cropped or expanded. The following fields are exempt from being combined:

- The six component types which can be used more than once on a single panel.
- Any field which requires more than one row.
- Any field which requires more than one column.
- Artwork Display
- Disc/Disc count
- Disc/Track Combined
- Love/Rating Combined
- Movement Number/Count
- Track/Track Count

To assign two fields to a single grid, select the Combine Two Fields... item at the top an unused grid cell's context menu. You will be asked to supply the two fields you want to combine. You can specify a display name for each field by separating the names with a / character in the Display Title field.

# Removing Items

Single grid cells can be deleted by selecting the cell and by entering the Delete key or by using the Delete button. An entire panel can be cleared by using the Clear button.

# Importing and Exporting Edit Panels

The Import/Export button allows you to do the following:

- import the contents of a custom panel other than the one currently displayed. (Essentially copy a panel).
- import a custom panel previously exported to a file. Note that you can choose a plist or zip file. Note that you can also import custom panels via Yate>Import Preferences and by dragging the file to the main window's file list area.
- export a custom panel to a file. The produced file is a plist file. If you specify Export as a zip file the produced file will be zipped and the plist file will be deleted.