COMBOS_BEGIN – COMBOS_END

  • Artigo

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

The COMBOS_BEGIN — COMBOS_END section contains entries that define a VSPackage's combo boxes.

The Combo Box Entry

The combo-box entry defines a control that appears on a toolbar that provides a drop-down list of options that can be selected. Once an option is selected, it appears in the text field at the top of the combo-box. The text file can also be treated as an edit field, with anything typed into the edit field added to the drop-down list.

All combo box controls are defined in the COMBOS_BEGIN — COMBOS_END section. Each combo box entry contains up to eleven fields, separated by commas and ending with a semicolon. For example:

Combo Box ID, Group ID, Priority, Fill Command ID, Width, Type, Flags, Button Text, Menu Text, ToolTip Text, Command Name;

These fields are described in the following table and must appear in the order given. The last field must end with a semicolon. See "The Combo Box Entry Fields" section later in this topic for more details on each field.

Field

Description

Combo Box ID

A GUID:ID pair that identifies the combo box control.

Group ID

A GUID:ID pair identifying the group that contains this control.

Priority

A value that is used to position the combo box relative to other items in the group.

Fill Command ID

An identifier that is passed to the VSPackage when the contents of the combo box drop-down list needs to be filled in.

Width

The width of the combo box in logical units.

Type

The type of combo box control.

Flags

Attributes that alter the behavior of the combo box control.

Button Text

This is not normally used for a combo box control but if the ToolTip Text is not specified, the Button Text field is used.

Menu Text

This is not normally used for a combo box control.

ToolTip Text

The text that is displayed in a ToolTip for the combo box control. This field is optional; if not specified, the Button Text field is used.

Command Name

The command name for this combo box that can be used in the Command Window and for assigning keys to. This field is optional; if not specified, the Button Text field is converted and used ("My Combo Box" becomes "MyComboBox").

Combo Box Example

The following code example from the File Explorer sample shows the COMBOS_BEGIN – COMBOS_END section. Entries in this example are indented for readability. In an actual entry, all fields should be on a single line. For more information, see CMDS_SECTION – CMDS_END.

COMBOS_BEGIN
    guidEUCmd:cmdidFilesFilter,
          guidEUGrp:IDG_FILEPANE_FILTER,
          0x0010,
          cmdidFilesFilterHandler,
          75,
          DYNAMICCOMBO,
          DEFAULTDISABLED,
          "Filter",
          ,
          "Filter";
COMBOS_END

The Combo Box Entry Fields

Each entry in the COMBOS_BEGIN – COMBOS_END section contains up to ten fields. A comma separates all fields and a semicolon denotes the end of each entry. The fields, in order, are:

  • Combo Box ID

    The Combo Box ID field identifies the combo box that you want to create. The Combo Box ID is always a GUID:ID pair that uniquely identifies the combo box. The ID must be different from any other command, menu, or group.

    The Combo Box ID in the example is:

    guidEUCmd:cmdidFilesFilter

  • Group ID

    The Group ID field identifies the primary group to which the combo box belongs.

    To create a combo box without a primary group, it should either be self-hosted, that is, using its own Combo Box ID as its parent group, for instance:

    guidEUCmd:cmdidFilesFilter, guidEUCmd:cmdidFilesFilter, ...

    or use the combo box's GUID and a group ID of 0:

    guidEUCmd:cmdidFilesFilter, guidEUCmd:0, ...

    If a combo box does not have a primary group, it must be placed on a toolbar with an entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section or it will not appear in the environment.

    The Group ID in the example is:

    guidEUGrp:IDG_FILEPANE_FILTER

    Note

    Although a combo box can be placed on a normal menu, it is not acceptable user interface (UI) design. If you want a dynamic submenu, create a command with the type Button and a flag of DynamicItemStart.

  • Priority

    The Priority field specifies the placement of the combo box within the specified group relative to the other items in the group. Items with a lower priority value appear before items with a larger priority value. The Priority field in the example is:

    0x0010

    When a combo box's hosting is defined by command placement, the priority value specified here is ignored in favor of that specified by the entry in the CMDPLACEMENT_SECTION – CMDPLACEMENT_END section.

  • Fill Command ID

    The Fill Command ID field specifies the secondary identifier that the environment uses to get the items that should appear in the combo box. The VSPackage's QueryStatus method is called with this command ID to obtain a list of items that should be placed in the combo box.

    In the example, the Fill Command ID is:

    CmdidFilesFilterHandler

  • Width

    The Width field specifies the width of the combo box in pixels. In the above example, the Width field is:

    75

  • Combo Box Type

    The Combo Box Type field is case-insensitive and specifies the type of combo box that is being implemented. There are four types of combo boxes available to VSPackages:

    Combo Box Type

    Description

    MRUCombo

    The Most Recently Used (MRUCombo) combo box is created and filled by the environment on behalf of the VSPackage. The user is able to type in the combo box, and the environment remembers up to the last 16 entries per combo box. When the user selects something in the combo box, or types in something new, the environment sends the text string to the appropriate VSPackage.

    DynamicCombo

    The DynamicCombo is created by the environment on behalf of the VSPackage. The VSPackage is responsible for filling in the contents of this combo box. The user is allowed to type in this combo box as well as select items within it. When the environment makes calls to the Exec method on the combo box, your VSPackage must return the contents of the combo box in a safe array. The environment then populates the combo box with the array data.

    DropDownCombo

    The DropDownCombo is also created by the environment on the VSPackage's behalf. The VSPackage is responsible for filling in the contents for this combo box as well. However, the user cannot type anything into the edit field of the drop-down list — it is simply a place where a user can choose from a list of items.

    IndexCombo

    The IndexCombo is similar to a DropDownCombo, with the difference being the way command execution is initiated. In a DropDownCombo, the environment uses the command text to identify the command. In an IndexCombo, the environment uses the index number of the item in the drop down list as the command identifier.

  • Flags

    The Flags field specifies attributes that you can place on the combo. The following table lists the combo flags that Visual Studio supports.

    Flag

    Description

    NoKeyCustomize

    Disables key customization.

    NoButtonCustomize

    Disables button customization

    NoCustomize

    Inhibits both key and button customization.

    DefaultInvisible

    Combo box is invisible by default.

    DefaultDisabled

    Combo box is disabled by default.

    DynamicVisibility

    Visibility is controlled through QueryStatus.

    This applies to combo boxes that appear on menus, not on toolbars. Top-level toolbar items can be are disabled, but not hidden, when OLECMDF_INVISIBLE is returned from QueryStatus.

    CommandWellOnly

    The combo box does not appear on the top-level menu. The user can add the combo box to its parent menu through the Command Well dialog box. This flag does not affect placements on context menus, toolbars, menu controllers, or cascade menus.

    IconAndText

    Text for the combo box is to be displayed. Default is no text.

    FilterKeys

    Described in the "Filtering Keys" section after this table.

    NoAutoComplete

    Auto complete feature is disabled.

    CaseSensitive

    User entries are case sensitive.

    StretchHorizontally

    When this flag is set, the width becomes the minimum width for the combo box, and if there is room on the toolbar, the combo box stretches to fill any spare space. This happens only if the toolbar is horizontally docked, and only one combo box on the toolbar can use the flag (the flag is ignored on all but the last combo box). This flag is new to Visual Studio SDK.

    Filtering Keys

    The environment passes a number of Win32 messages to the VSPackage's Exec method. If the combo box is marked for filtering with the FilterKeys flag, key press messages are also sent. One of these messages, WM_CHAR, can be used to deny any character that has just been typed.

    The Exec method may receive as input (depending on the message that has been sent) an array of values that are associated with the message. One of these values is the key that has been pressed and another value is the current string in the combo box. The Exec method has an output parameter that can be set to a flag indicating the key has been handled or not, thereby filtering certain key presses.

    More specifically, the input array is a VARIANT that has a VT_VARIANT type of SafeArray, and contains the following elements in this order:

    1. The handle of the window (HWND) that sent the message (VT_I4, a 4 byte value).

    2. The Win32 message code, such as WM_KEYDOWN, WM_SETFOCUS, or WM_CHAR (VT_I4, a 4 byte value).

    3. The message's WPARAM value (VT_I4, a 4 byte value).

    4. The message's LPARAM value (VT_I4, a 4 byte value).

    5. The text that is currently in the combo box's edit control (VT_BSTR, a string).

    The out parameter is a VARIANT that should be set to a VT_I4 type and given a value indicating what the environment should do with the message (alternatively, the out parameter can be set to a VT_BSTR type and the value set to a string that is copied into the edit control).

    For filtering keys, the following values from the VSFILTERKEYSFLAGS enumeration can be returned in the out parameter:

    • VSFILTERKEYS_DODEFAULT

      Proceed with normal processing; let the message continue through normal routing. This is the default code if the out parameter is not set.

    • VSFILTERKEYS_HANDLED

      The Exec method handled the message; stop further processing. This is the value to use when denying certain key presses.

    • VSFILTERKEYS_TRANSLATE

      The key press is to be treated as an accelerator and mapped to a command if possible. If the key press does not map to a command, the message continues through normal routing.

  • Button Text

    The Button Text field specifies the name of the combo box and is generally the only text field set. The Button Text field is used if the Menu Text or ToolTip Text fields are not set.

    The Button Text field in the example is:

    "Filter"

  • Menu Text

    The Menu Text field specifies the text that is displayed for the combo box if it is in a normal menu. The Menu Text field is normally not specified as it is not good UI practice to put a combo box in a normal menu. In the example, the Menu Text field is blank.

  • ToolTip Text

    The ToolTip Text field specifies the text that appears in the ToolTip for the combo box. If the ToolTip Text field is blank or not specified, the ToolTip text is taken from the Button Text field. In the example, the ToolTip Text field is set to:

    "Filter"

  • Command Name

    The Command Name field specifies the text that appears in the Command Window and the Keyboard window of the Customize dialog box (available from the Tools menu). If the Command Name field is not specified, then the Button Text field is used by stripping out all but letters, digits, underscores, and embedded periods. For example, "My Combo Box" becomes "MyComboBox". In the example, the Command Name field is not specified so the Button Text field of "Filter" is used.

See Also

Concepts

Command Table Format Reference

How VSPackages Add User Interface Elements to the IDE

NEWGROUPS_BEGIN – NEWGROUPS_END

Other Resources

File Explorer