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:




Summary
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.  ;)

13 comments:

  1. Thanks, I've been using them of and on for a long time.. However the details on Caption.Text property where new to me.

    Btw. the post already comes up on the first page when searching for "LabVIEW captions". :-)

    ReplyDelete
  2. Why use free labels instead of captions? Seems like it'd be a real hassle if you had to move the control.
    Sure you could group them, but why bother with the hassle if the functionality is already built into the caption?

    ReplyDelete
  3. elset: Messing with captions is generally off limits for VIs that ship with LabVIEW, since the localization team needs them. Also, as I think about it some more, I don't like the idea of having different identifying strings for an object on the panel, and its corresponding terminal, local variables, control references, and property/invoke nodes on the diagram. It could cause confusion when trying to understand the functionality of a VI.

    ReplyDelete
  4. Hi Darren.

    Thanks for an invaluable tip regarding captions. I have been wondering for years how to get rid of captions once created. Now I know, you simply delete them! Not setting them to an empty string, not setting them to the same text as the label (none of which removed the bracketed label from the context help window). You simply...delete them. I never knew that. Thanks :-)

    I use captions for default values and units btw; Label: "Load timeout", Caption: "Load timeout (3000) [ms]" for instance. Can still be localized, but wouldn't want the default values and units in the label and thus all over the BD.

    Cheers,
    Steen (CTA & CLA, but never really in the know when it came to captions apparently ;-)

    ReplyDelete
  5. Here's an example of how I use captions to make case structures have multiple functions. In this example if a simple TCP connection to a data logger. http://i42.tinypic.com/2rd9e9s.png

    ReplyDelete
  6. Richard: Interesting...you're using the captions as a data store for the controls. I've done something similar in apps I've worked on, but not with captions (since again, they're kind of off limits for core LabVIEW VIs). Instead, I've used Object Tags on controls to associate data with a particular control. Check out this weekly nugget I wrote with more information on using object tags. One benefit of this approach over captions is that you can store any data type (not just strings) with object tags.

    ReplyDelete
  7. Darren: I have never used captions at all in my 10+ years in LV; but you have given me some ideas for sure.

    Off topic: I just read your forward in "The LabVIEW Style Book"; and I just wanted to say thanks for talking about your personal evolution in LV. It gives those of us that are turning the corner to better code some hope to approach the perfection we seek as LV programmers. BTW I'm gonna buy that book!

    GBR

    ReplyDelete
  8. Can i ask, I use tab control which have the tab menu name on top of it. When i set the bigger font size, the tab menu name is truncated because of fix width on the tab control. Can i using this caption tu resize the tab menu according to text?

    ReplyDelete
  9. Gopal: I don't know of any way to use captions in relation to the text shown in tab headers. If you're having a problem with tab control font sizes, I recommend posting it to the NI Forums.

    ReplyDelete
  10. Hi Darren, what about if I would like to create the caption of a control programatically is that posible?

    ReplyDelete
  11. If you write a value to the Caption.Text property of a control, it will create the caption if it didn't already exist.

    ReplyDelete
  12. Hello Darren,
    I am using a LV2014 German version and when a control or indicator is created it always shows the caption by default. Is there a way to change the settings so that labels are shown by default??

    ReplyDelete
    Replies
    1. Hi nik, unfortunately I don't think there's a way to do that. In non-English LabVIEW, for the most part, the labels of controls and indicators remain in English, while the captions are localized and displayed.

      Delete