A note's 'Key Attributes' are an optional display of a user-defined tabular layout of attribute title/value cells. Attribute names are shown in the left column, attribute values in the right column; from v8.2.2 the width of the first column of the key attribute table now adjusts itself to accommodate long attribute names. The list can be re-ordered, items deleted and attribute value edited. An item is added by:
- using the 'Add Key Attributes' button in the note's text pane's title bar ('+' button to right of the title), and then using the Add Key Attributes pop-over to set the contents and order of the table. As well adding/removing existing attributes, new attributes names can be typed here and on dismissing the pop-up the user will be asked to confirm this is a new attribute and its data type (default:string)
- setting the note's $KeyAttributes
- setting the note's prototype's key attributes (if a prototype is used)
The vertical order of displayed (key) attributes can be altered via drag-drop of the attribute name label (left column cell), or altering the order of the list stored in $KeyAttributes. An item can be deleted from the key attribute display by dragging its label cell out of the table and dropping onto the $Text pane.
Items in bold are set locally for the note. Items in lighter colour are read-only (normally dynamically calculated values like $ChildCount; pre v6 these were in italics). All other rows in normal text use the default or inherited value. Users coming from older Tinderbox versions should note attribute value data is now fully Unicode.
This pop-up can be called via the View menu as well as from the text pane.
At the extreme the right of the panel each string, list or set attribute has a pop-up list of values, allowing quick setting of values already in use for that attribute (or suggested values, if defined).
When a user attribute is renamed, key attributes referring to the new attribute are updated to use the new attribute (and attribute values are transferred).
Boolean-type key attributes are always shown as a tick-box; ticked equates to true, un-ticked to false.
Number-type data. Very large or small numbers can be entered/shown using exponential form, e.g.
0.000001 can be entered as
Color-type data. The data is shown both as a colour chip (showing the currently set colour) and a string showing the value set which is either a Tinderbox named colour or otherwise a hexadecimal value string ("#330099").
Date-type data. Shows the data and time, with the date/time format in the host OS' short date format, so this will vary by the user's locale and their choice of OS settings. Document Settings offer a small selection of variations on the OS format. An alternative date-time string format can be used for all Date-type attributes in KA by setting $KeyAttributeDateFormat at document or note level using a date format string. On entering a date, if no time is specified, the time element of the attribute value defaults to current system time. A date-picker control is offered to the left of the value box. When editing dates in the key attributes table, from v8.2.3 the date string is changed before editing to its value in normal format (medium date, short time). This avoids ambiguity in short dates, where the default US style uses 2-digit years: i.e. does 12/7/41 represent a date in 1941 or 2041?
String-type data. Although generally intended to hold short text values, String attributes can hold larger amounts of text and including line/paragraph breaks. When not selected for edit, all text paragraphs run together. In edit more, the value edit box will only show the first paragraph of text. Use the right arrow to reach first paragraph text overflowing the edit box; use the down arrow key to access paragraph #2, etc. It is not possible to type a line break character in the edit box but it is possible to copy/paste one into it.
URL-type data. A form of string attribute, URL attributes show a globe icon to the left of the data value edit box. Clicking the button will open the URL, stored in the value box, in the user's default web browser. Files can be dropped onto a URL-type attribute (e.g. to give a file:/// type of URL). From v8.7.0, the URL button remains enabled even if the note is read-only.
File-type data. A form of string attribute, File attributes show a folder icon to the left of the data value edit box. Clicking the button will open the file (or folder) path set in the value via Finder. Folders will open in Finder and other file formats in whichever app is registered as the default app for that file type. From v8.7.0, the File button now remains enabled even if the note is read-only. The Browse File… menu option is not available for read-only notes.
Font-type data. Font-type attributes (which are only ever system attributes) show an 'A' button which opens the OS' Font dialog, making it easier to set the correct font name for a font. N.b. altering the text font size does not alter the font size attribute (where pertinent) in Tinderbox.
A note's title ($Name) can be edited directly via the title bar above the key attributes table so there is no need to add it to the table.
Key Attributes are sometimes referred to with the shorthand abbreviation 'KA' in help forums, etc.
Show/Hide Key Attributes
A disclosure triangle allows the visibility Key Attributes table to be toggled, e.g. to allow more space for showing $Text. The control is not shown if there are no Key Attributes for the current note. The 'add key attribute' button still remains available.
Cycling Key Attributes via keyboard
To cycle through key attributes, use the Return key (↩). Boolean attributes accept this process.
Editing Key Attribute values
Once a row in the table has focus (either via keyboard, as above)or by a direct trackpad/mouse-click the value box in the right column can be edited:
- Enter edit mode. Either double-click (mouse/trackpad) or use the Return key (keyboard). The value box contents can now be edited. To tick/un-tick a Boolean attribute via the keyboard use the spacebar. For data types offering it, the pop-up value list of existing/suggested values (see above) can be used to set a new value without typing.
- Complete the edit and save the new value. Click out of the table cell (mouse/trackpad) or use the Return key to toggle out of edit mode.
- Use the Escape key to abandon an incorrect edit.
Key attribute characteristics such as enabling or disabling the URL and File buttons are now updated after editing the key attribute’s textual value.
Changing the text of a key attribute immediately updates that key attribute’s pulldown value menu.
When a Boolean attribute is selected in the key attributes table, pressing the spacebar will toggle its value.
Number of Key Attributes shown
From v8.2.2, the height of the key attribute table can now grow to as much as half the height of the text panel, reducing the need to scroll long lists of key attributes if using a sufficiently-large display. As previously, the table shows scroll bars if not all Key Attributes can be accommodated. In older versions, scroll bars show if there are over 15 key attributes, regardless of text pane height.
Resetting default/inherited values
For displayed String/Set/List data typed attributes only, the default value can be reset by using their pop-up value lists, by selecting the value 'normal'. For all other data types, to repair inheritance select the note in question and do either one of:
- click on the line with the attribute to reset, right click and use the 'Use Inherited Value' option in the pop-up menu.
- open Quickstamp, select the desired attribute and use the reset buttons.
Font/Font Size for the Key Attributes table
The Key Attributes table can be set to a user specified font, for attribute names and their values, via $KeyAttributeFont.
The font size used to render the current note's table can be altered via the Key Attributes sub-menu of the Window menu. The latter offers a small range of suggested sizes (default is 11pt). The actual size is stored is the point size number, i.e.
11 for the default in $KeyAttributesFontSize. It is possible to set values not in the menu by editing the attribute value directly. To change the value for the entire document, use the Document Inspector General tab to alter the the default value for $KeyAttributesFontSize.
Evaluating an attribute
The current value of the key attribute can be evaluated (as action code) and written back as the attribute's value. The Evaluate function is accessed via the table's context's pop-up menu.