Developer Center Resources

RDR · ‎05-13-2013

LabVIEW Add-on Dev Center » Developing a VI-Based API » LabVIEW Palette Guidelines

Terms

Category View - This is the view where all of the visible "Categories" appear at the top level, in text, in a single window. The 2-D layout of a given palette is not preserved and empty "holes" are removed.
Icon View, Icon and Text View (AKA 2-D layout view) - The Icon View or Icon and Text View are referred to as the 2-D layout view because the layout of the view is preserved when the user pops up or pins down the palette. This default view of a palette is as the developer created it.
Palette Items - Palette items refer to any of the LabVIEW file types that can appear on a palette; these include: submenus, VIs, controls, merge VIs, VI templates, etc.
Short Name - The short name is the text that appears below the palette item when the palette is viewed in the Icon and Text view. If a Short Name is not assigned, then the name that appears below the palette item is the Palette Name (or Display Name). The parent palette owns the Short Names that appear on the palette - this information is saved to the parent palette's mnu file.
Palette Name (AKA Display Name) - The Display Name is the name that appears at the top of the palette and in tip strips when you hover the mouse over a subpalette. The palette menu file owns the Palette name; however, the parent palette maintains a copy of this name. The parent's copy of this name appears in the Palette Editor view when the child item is not present on the system.
Palette Filename - The actual disk filename - palette menu files include a .mnu file extension.
Merge VI - when configuring a palette item to "place VI contents" you are creating a merge VI where the block diagram of one VI is merged into the block diagram where the user places this item from the palette.

Content Organization Guidelines

Location

As a general rule, all palettes need to reside inside of one of the existing top-level palette categories. The Addons category is now reserved for LabVIEW Tools Network products, but any other top-level category is also acceptable except for User Libraries (user.lib) as this location is reserved for customer code. Instructions for creating a palette using VI Package Manager can be found here: Creating a LabVIEW Palette with VI Package Manager

Palette Names

Avoid making up a palette name to represent groupings on a palette if the name will not be recognized by the LabVIEW Community. For example, the LabVIEW Community would be unfamiliar with a name created solely for the purpose of representing clusters, classes and variants. Therefore, it is best to just list each of the recognizeable items in the palette name (Cluster, Class, & Variant). This was also the case for the "Graphics and Sound" palette. Note also having names that are consistent with the palette contents helps when using 'Search' to find palettes.
Try to use singular names over plural names as this is consistent with most other palettes. This also keeps the names short, allowing for more of the Short Name to be visibile in the Icon and Text view.
When combining muliple concepts into one palette name, use an ampersand in place of the word 'and' to shorten the name for the Icon and Text view.
Name palettes based upon their functionality, not complexity. Avoid naming palettes "Advanced".
Don't create palette names that include the parent palette name. For example, the subpalettes under the Sound palette are "Input", "Output" and "Files" NOT "Sound Input", "Sound Output" and "Sound Files". Similarly, the subpalettes under the 3D Picture Control palette include "Geometries", "Objects", and "Transformations". The user doesn't need the redundant information - they navigated into the palette. Also, there are generally plenty of clues helping to reinforce this information visually - such as a common icon theme, VI names, etc.

Short Names

Short names are intended to help the user quickly recognize the palette by name when viewed in Text and Icon view. Therefore, the following apply:
1. The goal is NOT to avoid elipses (the ... That appear when names don't fit). Stated another way, elipses are OK as long as the user can quickly recognize the palette contents. Put spaces between words in your palettes.
2. Do not use different terms in the short name than the palette name. For example, don't mix usage of terms such as "Serial" and "RS-232" or between "Archive" and "Zip". Use the same terms in the palette name, short name, and the API VIs.
If palette items all start with the common name (e.g., a prefix for an instrument driver), remove the common name. More than likely, the common name appears in the palette hierarchy or palette name. The common name usually dominates the visiible names in the Icon and Text view. Hence, it is impossible to distinguish between items on the palette when all that is viewable is a common name.
If you are adding property nodes or invoke nodes to the palette:
1. If you are only adding the Property nodes (no invoke nodes), give the node the short name of the product, or property node class (such as a DAQmx 'Task Node', or "VISA Property Node")
2. If you are adding both property nodes and invoke nodes (and only one of each), if they are both nodes generically configured for your product class and can also adapt to other types, give them the Short Name "Property Node", and the long name prepend the product name or class name, such as "ProductName Property Node".
3. If you have property nodes and invoke nodes, but the property or invoke nodes are pre-configured for a specific function/property/task, give the Short Name the name of the task/property (such as the "Serial Timeout Property").

Item Names

Item names are really an API review issue, but sometimes the API names aren't considered as a collection until they are viewed on a palette or used in the palettes. Here are a few things to consider:
1. When creating an API, typically the items have a unifying name (e.g., "notify", "queue", "VISA", "GPIB", etc.) that is included in all the item names. There are at least three ways that this unifying theme can be used in the API:
  1. As a prefix to all items in the API. This is a good approach if the unifying word cannot be used as an object to describe an operation. Also, this approach is good if the API includes primitives or a mix of VIs and primitives. Examples: VISA Open, VISA Close, VISA Write, etc.
  2. As an object of the API operations. This is a good approach if the unifying word can be used naturally to describe the operation of the API item and does not introduce ambiguity as to what the operation is. Examples: Obtain Queue, Flush Queue, Dequeue Element, etc.
  3. Namespaced within a project library. This is a good approach if all the API items are VIs AND the unifying name is not needed ot describe the operation to be performed. Examples: Agilent 34401.lvlib:Initialize and Agilent 34401.lvlib:Close
2. Regardless of what approach you use, be consistent throughout the API. When creating your API, consider how the items will appear in the palette search operation. Consider both the use cases of people trying to find the items and those who are attempting to search for something else. If the name is too generic (e.g., just "Open"), then it is possible users will choose the wrong item.
3. Merge VIs are often used to represent block diagram constants. In this case, it is strange to see a ".vi" extension in the palette. Therefore, merge VIs are often saved without a .vi extension or the Appearance Name is used.
4. Polymorphic VI instances appear as pull-right menu items. Since the instances are just options of a polymorphic VI, it is strange to see .vi extensions. Therefore, polymorphic instance VIs use the Appearance Name to change the way they appear in the pull-right menu.
With the advent of Quick Drop in LabVIEW 8.6, you should make sure any items added to the LabVIEW palettes have unique names. Do a palette search with your proposed object names to ensure items with those names don't already exist in the palettes. Note that a VI in a library can have the same name as a VI in another library because Quick Drop uses namespaced VI names.

Palette Hierarchy

It is okay for the ogranization of the Controls palette to differ from the Functions palette. We do not maintain a one-to-one correspondence between these two palettes. Therefore, subpalettes also don't need to be maintained on a one-to-one fashion.
In general, items should not be duplicated in multiple locations within the palette. However, there are a few exceptions:
1. If an item supports different functionality to the point where someone might even name the items differently.
2. If the use of an item in a different context is not obvious, we may want to duplicate items to help educate customers (e.g., placing a palette under the \Addons category and an existing palette category like \Robotics)
Consider source palettes when grouping items. Source palettes are the right-click>Replace palettes. Grouping items that are used together on the same palette helps to promote use of right-click source palettes.
The size of palettes should be considered, but size is just one of many considerations. Along with size, it is important to have visual separation between different groups of nodes that appear within one palette. Therefore, care should be given to laying out items in the Icon View and Icon and Text view.
Frequency of use should be considered when creating palette organization. Ensure that frequently used items aren't burried in a palette structure. Items that aren't used frequently may be moved down in the hierarchy.

Placement of Items within a Palette

When placing items in the 2-D layout view, consider the following:
1. Commonly used items should appear higher and to the left side of the palette. Less commonly used items should appear lower and to the right in the palette.
2. Items that are used together should be placed close together (preferably on the same row); for items that are used in a specified order, place items in the same left-to-right order as the user would use them on a diagram (e.g., Open, Read/Write, Close).
3. Counter-part items should be placed together, for example:
  1. Scan from String & Scan into String
  2. To Lower Case & From Lower Case
  3. Write to Text File & Read from Text File
  4. To More Specific Class & To More Generic Class
4. Consider symmetry, if applicable. Consider the VISA Register Access palette and VISA Low Level palette - the nodes on these palettes differ in I/O direction and # of bits. In this case, the layout is such that each column represents the same # of bits while the rows represent I/O direction and bus transfer.

Icons

Consider localization when creating icons and ensure control palette icons are consistent with the block diagram icons for the same item. Refer to the following document for more guidelines on icon development:

Best Practices for Creating Icons in LabVIEW

Filenames

Name the .mnu file with a meaningful name. Although users typically do no tneed to associate menu files with their palettes, providing meaningful file names help associate files with palettes when viewing the menu files in a file browser. For example, "ff.mnu" would be a bad name, "datalog.mnu" is a good name.
Fienames that start with an underscore are hidden when the parent palette is a sync to folder palette.
Refer to the following document for additional guidelines:
File and Folder Names for Integrating into LabVIEW

Editing Palettes Using LabVIEW Palette Editor (Tools > Advanced > Edit Palettes...)

Synchronization

Synchronize with Directory - A palette can be set to automatically update its content based upon the contents of a directory.
Hide Synchronized Item - On a palette that is synchronizing to a directory, if an item is from that directory, you cannot delete it from the palette because that will violate the definition of "synchronizing with a directory". If you don't want an item from a synchronized directory to show up in this palette, you can right-click the item and select Hide Synchronized Item from the shortcut menu
Reserve Spot for Synch Item

Modify Palette Menu Files

By default, changes made in the LabVIEW palette editor save to copies in the LabVIEW Data directory. If you want to instead save these files to the LabVIEW folder structure, put the following token in your INI file:

InternalPaletteEdit=TRUE

Tip: Always check the "Preview Palette Changes" checkbox on the palette editor dialog to ensure you are not overwriting any menu files shipped with LabVIEW.

Paths Stored in Palette Menu Files

The paths between a parent palette and a child palette may either be a relative path or a pseudopath, depending on where the palette files exist on your disk:

Prior to LabVIEW 8.5, palette menus saved under the Menus directory within the LabVIEW directory under Program Files will result in paths stored as pseudo paths
Palette menus saved outside of the Menus directory under Program Files will result in relative paths between the parent item and child item
In LabVIEW 8.5, if the child palette menu is located in the same directory or a subdirectory relative to the parent, then the path is a relative path. If the path is not a simple relative path, then a pseudo path may be used if the palette file is located under the Menus directory.

Note: If the config token "InternalPaletteEdit=True" is specified in the LabVIEW.INI file, then editing palette menus under the Menus directory will edit them in place. If the config token is set to False or not specified, then editing th epalette menus under the Menus directory will result in copies being placed in the LabVIEW Data Directory. In most cases, the copies of the Menu files will save relative paths to the child items.

Why is this important to know? If you ship a product that supports multiple versions of LabVIEW, it is possible that your installed palette directory for LabVIEW 7.1 is different than your installed palette directory for LabVIEW 8.x+. If the install directory is different, but all the relative paths between the palette files are the same, then ensuring the parent/child links between the palettes is a relative path will alow you to maintain one set of palette files.

The trick to ensuring all the paths are relative is to NOT use InternalPaletteEdit=True and instead rely on the copies saved to the LabVIEW Data Directory. To get relative paths, you need to ensure both the parent file and the child files are saved in the LabVIEW Data Directory.

Question Marks and "readonly.txt"

When objects referenced by a palette are missing, the palette will display question mark icons for the missing objects.

For example, on the "File I/O" palette, the item "Write to Spreadsheeet File.vi" is pointing to \vi.lib\utility\file.llb\Write to Spreadsheet File.vi. If this VI doesn't exist in this file location, the palette would display a "?" at its position to indicate it is missing.

A question mark in a palette is a convenient and fast way of detecting if something is wrong in the configuration of the palette, but sometimes question marks are unavoidable. For example, the "Vision and Motion" palette is shipped with nothing in it by default. One the Vision and Motion toolkits are installed this palette will be populated with these toolkits. In order to force a layout of the Vision and Motion palette, reservations have been made on the palette and their reserved locations are displayed as "?" until the toolkits are installed. If you browse the Vision and Motion palette, you don't see any question marks because a file "readonly.txt" is used to hide the question marks in this case.

The purpose of "readonly.txt" is to hide question marks on a palette. It can be an empty file and should be placed next to the mnu file that has references to missing objects. Let's use the Vision and Motion palette as an example. \menus\categories\VisionMotion\dir.mnu is the file that references missing objects and "readonly.txt" is placed next to it in order to hide question marks.

Note: Question marks will show up in palette editing mode, even when "readonly.txt" exists, to show reserved palette locations

Also Note: If a readonly.txt file exists in the directory of a palette you are modifying, you must first move or rename the file temporarily or you will be unable to edit the palette views for this palette.

Other Notes on Synchronization

LabVIEW can automatically update a palette linked ot an LLB or folder. The palette automatically updates as you add files to or remove files from this linked LLB or folder
When is the palette refreshed? - The palette is refreshed when LabVIEW is launched, when exiting the Palette Editor, and when the 'Refresh Palettes' invoke node is called
The following directories all utilize the synchronization behavior of the parent palette associated with the directory: instr.lib, user.lib, and all of the Category directories. Basically, these palettes adjust depending on the products installed. We cannot know what instrument drivers or toolkits a user will install. Therefore, the palette adjusts dynamically to what is installed.
Synchronization of a single LLB or folder dir.mnu - If the synchronized folder contans a dir.mnu, then only that dir.mnu will appear in the parent palette. Typically, the synchronized palette is the dir.mnu and is placed in the directory with which it is linked to for synchronization. Furthermore, you want to avoid recursive synchronization behavior where the parent and child both synchronize to the same directory.
VIs and Controls - the palette filters items based upon whether the palette is viewed from the Controls or Functions palettes. When viewing a synchronized palette from the controls palette, only items appropriate for the front panel will be visible (e.g., ctl files). Similarly, only items appropriate for the block diagram will be visible from the Functions palette (e.g., VIs). Unless excluded or hidden, the palette will show all applicable items within the LLB or folder on a single palette - regardless of the number of items
How do I exclude or hide items in a synchronized folder? - If you add a subdirectory or LLB file to the directory with which you synchronize and the subdirectory or filename begins with an underscore (_), the contents of the subdirectory or file do not appear on the palette. If an item is synchronized with a directory, you cannot delete the item from the palette, but you can choose to hide an item in the palette editor - items that are hidden do not appear on the palettes and are not included when you search.
Can an items order be specified for a synchronized folder? - By default, the synchronized folder will show items as they appear in a folder explorer window (e.g., alphabetical)