Thursday, February 9, 2012

Captions: More than You Ever Wanted to Know

Every once in a while, the subject of control/indicator captions comes up around here, and every time, confusion arises.  So here we go...everything I know about captions.

The Basics
Enabling a caption on a control or indicator is straightforward enough:

If you select this option, your control doesn't appear to change if you leave the caption as its default value:

But trust me, it has.  We have hidden the label of the control.  You are now viewing its caption (in the same location as the label).  If you give the caption a different value than the label, you will see both in the Context Help window:

Any control with its caption showing (assuming the caption is different than the label) will display the caption at the top, and the label in brackets underneath.  When hovering over the terminal of a subVI, you'll see the caption of the control/indicator in the tip strip instead of the label.

Use Cases
Now why would you ever want to show the caption in the first place?  I know of two possible reasons:
  1. Long caption, short label - If you want your control/indicator to have a long, meaningful description on the panel, but you don't want that long string getting in the way on the diagram, you could show its caption. Personally, I eschew this approach...instead of using a caption, I would opt for a free label on the panel positioned appropriately near the control with appropriately-justified text.
  2. Localization - This is the primary reason we use captions in LabVIEW R&D.  When we localize LabVIEW into other languages, we don't want to change the labels of controls and indicators...that could potentially break code that programmatically refers to controls and indicators by name.  So instead, we show localized captions (and hide the labels) for the controls and indicators in all user-facing VIs that ship with LabVIEW.

Deleting a Caption
In older LabVIEW versions, there was no easy way to delete the caption of a control/indicator.  Thankfully, in LabVIEW 8.2 and later, it is very easy.  All you need to do is select the caption with your selection tool and press the 'Delete' key on your keyboard.  Note that this is not the same as highlighting the text in the caption and pressing the 'Delete' key...if you do that, the control will still have a caption, but it will be an empty string.

Working with Captions Programmatically
This is where it gets a little tricky.  By default, controls and indicators do not have captions.  Let's say you try to read the Caption.Text property of a control like this:

Believe it or not, one of three different things can happen with this code:
  1. If the control already has a caption, you'll get the caption text.
  2. If the control doesn't already have a caption, and the VI that owns the control is in edit mode, then a caption will be created for you, with the same string as the label, and you'll get that text.
  3. If the control doesn't already have a caption, and the VI that owns the control is in run mode, then you'll get error 1320, which tells you that you can't read properties of control parts that haven't been created yet when the VI is in run mode.
Because of all this craziness, there is another helpful VI Server property that you can use:

The "HasCaption" property will tell you if a control even has a caption to begin with, before you start trying to do other caption-related stuff.

One other nifty tip for dealing with captions programmatically...if you want to delete a caption programmatically, this is the way to do it:

So there you have it...way more information than you ever wanted to know about a LabVIEW feature that you probably weren't even using in the first place. :P  But in the event that someone ever does need this information, here's hoping this blog post eventually bubbles up to the top of a "LabVIEW captions" google search.  ;)