Caption

This property is a true example of polymorphism at work. It contains a user-definable string for every control that has a Caption, but the exact use of the string varies rather a lot from one control to the next.

Usage

oObject.Caption = cCaptionString
cCaptionString = oObject.Caption

Forms put their Caption in the title bar. Pages in a page frame put theirs in the tab (if there is one—if not, Caption is ignored). For labels and column headers in a grid, Caption is pretty much all there is. For the rest of the objects that have Captions, it’s the text that identifies the object so the user knows which one to choose—the label on a command button or next to an option button or check box. Command groups and option groups can put the Caption from their contained buttons in their Value to indicate which button in the group was chosen.

The Caption of an object is not the same as the Name of the object, though they might contain the same string. The Name is the one you use to refer to the object; Caption’s just a pretty face.

For those objects that can receive focus, you can set a hotkey in the Caption by putting “\<” in front of the hotkey letter. Labels can also have hotkeys—when you press the hotkey, focus moves to the first object after the label that can receive focus. (Pretty neat—you can give the label next to a text box or edit box a hotkey. When the user presses the hotkey, focus lands on the text or edit box.) Hotkeys on the tabs of a page frame work only when focus is already on the page frame, but hotkeys on controls in a page of a page frame work as long as the page is on top.

Headers can't handle hotkeys. That's okay—we're not totally sure what they'd mean there anyway. What's not okay is that when you type the hotkey characters "\<" into the Caption of a header, it leaves them there. That is, not only don't they get replaced with an underline, but they don't get removed from the string. You can sort of specify a hotkey for a header with "&", which is the Windows-standard character for hotkeys. When you do, you get an underlined letter, but that still doesn't actually give you a live hotkey—no event fires when the user presses Alt+the specified key.

Keep in mind that SET KEYCOMP affects the use of hotkeys—with KEYCOMP set to DOS, hotkeys don’t always work. (However, there’s really no reason to SET KEYCOMP TO DOS anymore, since there’s no DOS version of VFP.)

In check boxes, option buttons and command buttons, you can combine the caption with a picture. However, there’s no way to specify their relative position. The picture always goes over the caption. In the rare cases where we have needed a bitmap with a caption next to, or on top of, the bitmap, we’ve cheated by using an empty Caption and placing the text in the bitmap itself. Beware of this technique, however—it can cause problems with some of the accessibility tools that users with disabilities depend on.

In VFP 3 and VFP 5, to create a completely borderless form, Caption needed to be empty. (See BorderStyle for a complete list of settings needed for borderless forms.) In VFP 6 and later, TitleBar makes this a lot easier, and messing with Caption is unnecessary.

Example

ThisForm.Caption = "Favorite Things"

* You can change the title on the main Visual FoxPro window:
_SCREEN.Caption = VERSION()

* Here's a button with a hotkey:
ThisForm.cmdClose.Caption = "\<Close"

See Also

Alignment, AutoSize, BorderStyle, Name, Picture, Set KeyComp, Style, TitleBar