Элемент управления ToolBar (Windows Forms) ToolBar Control (Windows Forms)

Элемент управления ToolStrip заменяет элемент управления ToolBar и расширяет его функциональные возможности; однако при необходимости элемент управления ToolBar можно сохранить для обратной совместимости и использования в будущем. The ToolStrip control replaces and adds functionality to the ToolBar control; however, the ToolBar control is retained for both backward compatibility and future use, if you choose.

Элемент управления Windows Forms ToolBar используется в формах в качестве панели управления, на которой выводится ряд раскрывающихся меню и кнопок с растровыми изображениями, активирующих команды. The Windows Forms ToolBar control is used on forms as a control bar that displays a row of drop-down menus and bitmapped buttons that activate commands. То есть щелчок по кнопке на панели инструментов эквивалентен выбору команды в меню. Thus, clicking a toolbar button is equivalent to choosing a menu command. Для кнопок можно настроить режим поведения кнопок, раскрывающихся меню или разделителей. The buttons can be configured to appear and behave as push buttons, drop-down menus, or separators. Обычно на панели инструментов содержатся кнопки и меню, соответствующие элементам в структуре меню приложения, которые предоставляют быстрый доступ к наиболее часто используемым в приложении функциям и командам. Typically, a toolbar contains buttons and menus that correspond to items in an application’s menu structure, providing quick access to an application’s most frequently used functions and commands.

Свойство DropDownMenu элемента управления ToolBar принимает в качестве ссылки экземпляр класса ContextMenu. The ToolBar control’s DropDownMenu property takes an instance of the ContextMenu class as a reference. При использовании подобных кнопок на панели инструментов приложения будьте внимательны в выборе передаваемой ссылки, так как это свойство принимает любой объект, наследуемый от класса Menu. Carefully consider the reference you pass when implementing this sort of button on toolbars in your application, as the property will accept any object that inherits from the Menu class.

в этом разделе In This Section

Общие сведения об элементе управления ToolBar ToolBar Control Overview
Общие понятия, связанные с элементом управления ToolBar , который позволяет разрабатывать пользовательские панели инструментов. Introduces the general concepts of the ToolBar control, which allows you to design custom toolbars that your users can work with.

Практическое руководство. Добавление кнопок в элемент управления ToolBar How to: Add Buttons to a ToolBar Control
Описываются способы добавления кнопок в элемент управления ToolBar . Describes how to add buttons to a ToolBar control.

Практическое руководство. Определение значка для кнопки элемента управления ToolBar How to: Define an Icon for a ToolBar Button
Описываются способы отображения значков на кнопках элемента управления ToolBar . Describes how to display icons within a ToolBar control’s buttons.

Практическое руководство. Генерирование событий меню для кнопок элемента управления Toolbar How to: Trigger Menu Events for Toolbar Buttons
Инструкции по написанию кода для определения нажатой пользователем кнопки элемента управления ToolBar . Gives directions on writing code to interpret which button the user clicks in a ToolBar control.

Справочник Reference

Класс ToolBar ToolBar class
Справочная информация о классе и его членах. Provides reference information on the class and its members.

Связанные разделы Related Sections

Элементы управления для использования в формах Windows Forms Controls to Use on Windows Forms
Полный список элементов управления Windows Forms со ссылками на информацию об их применении. Provides a complete list of Windows Forms controls, with links to information on their use.

Элемент управления ToolStrip ToolStrip Control
Описываются панели инструментов, на которых можно разместить меню, элементы управления и пользовательские элементы управления в приложениях Windows Forms. Describes toolbars that can host menus, controls, and user controls in Windows Forms applications.

Using Application Desktop Toolbars

An application desktop toolbar (also called an appbar) is a window that is similar to the Windows taskbar. It is anchored to an edge of the screen, and it typically contains buttons that give the user quick access to other applications and windows. The system prevents other applications from using the desktop area used by an appbar. Any number of appbars can exist on the desktop at any given time.

This topic contains the following sections.

About Application Desktop Toolbars

Windows provides an API that lets you take advantage of appbar services provided by the system. The services help ensure that application-defined appbars operate smoothly with one another and with the taskbar. The system maintains information about each appbar and sends the appbars messages to notify them about events that can affect their size, position, and appearance.

Sending Messages

An application uses a special set of messages, called appbar messages, to add or remove an appbar, set an appbar’s size and position, and retrieve information about the size, position, and state of the taskbar. To send an appbar message, an application must use the SHAppBarMessage function. The function’s parameters include a message identifier, such as ABM_NEW, and the address of an APPBARDATA structure. The structure members contain information that the system needs to process the given message.

For any given appbar message, the system uses some members of the APPBARDATA structure and ignores the others. However, the system always uses the cbSize and hWnd members, so an application must fill these members for every appbar message. The cbSize member specifies the size of the structure, and the hWnd member is the handle to the appbar’s window.

Some appbar messages request information from the system. When processing these messages, the system copies the requested information into the APPBARDATA structure.

Registration

The system keeps an internal list of appbars and maintains information about each bar in the list. The system uses the information to manage appbars, perform services for them, and send them notification messages.

An application must register an appbar (that is, add it to the internal list) before it can receive appbar services from the system. To register an appbar, an application sends the ABM_NEW message. The accompanying APPBARDATA structure includes the handle to the appbar’s window and an application-defined message identifier. The system uses the message identifier to send notification messages to the window procedure of the appbar window. For more information, see Appbar Notification Messages.

An application unregisters an appbar by sending the ABM_REMOVE message. Unregistering an appbar removes it from the system’s internal list of appbars. The system no longer sends notification messages to the appbar or prevents other applications from using the screen area used by the appbar. An application should always send ABM_REMOVE before destroying an appbar.

Appbar Size and Position

An application should set an appbar’s size and position so that it does not interfere with any other appbars or the taskbar. Every appbar must be anchored to a particular edge of the screen, and multiple appbars can be anchored to an edge. However, if an appbar is anchored to the same edge as the taskbar, the system ensures that the taskbar is always on the outermost edge.

To set the size and position of an appbar, an application first proposes a screen edge and bounding rectangle for the appbar by sending the ABM_QUERYPOS message. The system determines whether any part of the screen area within the proposed rectangle is used by the taskbar or another appbar, adjusts the rectangle (if necessary), and returns the adjusted rectangle to the application.

Next, the application sends the ABM_SETPOS message to set the new bounding rectangle for the appbar. Again, the system may adjust the rectangle before returning it to the application. For this reason, the application should use the adjusted rectangle returned by ABM_SETPOS to set the final size and position. The application can use the MoveWindow function to move the appbar into position.

By using a two-step process to set the size and position, the system enables the application to provide intermediate feedback to the user during the move operation. For example, if the user drags an appbar, the application might display a shaded rectangle indicating the new position before the appbar actually moves.

An application should set the size and position of its appbar after registering it and whenever the appbar receives the ABN_POSCHANGED notification message. An appbar receives this notification message whenever a change occurs in the taskbar’s size, position, or visibility state and whenever another appbar on the same side of the screen is resized, added, or removed.

Whenever an appbar receives the WM_ACTIVATE message, it should send the ABM_ACTIVATE message. Similarly, when an appbar receives a WM_WINDOWPOSCHANGED message, it must call ABM_WINDOWPOSCHANGED. Sending these messages ensures that the system properly sets the z-order of any autohide appbars on the same edge.

Autohide Application Desktop Toolbars

An autohide appbar is one that is normally hidden but becomes visible when the user moves the mouse cursor to the screen edge with which the appbar is associated. The appbar hides itself again when the user moves the mouse cursor out of the bar’s bounding rectangle.

Although the system allows a number of different appbars at any given time, it allows only one autohide appbar at a time for each screen edge on a first-come, first-served basis. The system automatically maintains the z-order of an autohide appbar (within its z-order group only).

An application uses the ABM_SETAUTOHIDEBAR message to register or unregister an autohide appbar. The message specifies the edge for the appbar and a flag that specifies whether the appbar is to be registered or unregistered. The message fails if an autohide appbar is being registered but one is already associated with the specified edge. An application can retrieve the handle to the autohide appbar associated with an edge by sending the ABM_GETAUTOHIDEBAR message.

An autohide appbar does not need to register as a normal appbar; that is, it does not need to be registered by sending the ABM_NEW message. An appbar that is not registered by ABM_NEW overlaps any appbars anchored on the same edge of the screen.

Appbar Notification Messages

The system sends messages to notify an appbar about events that can affect its position and appearance. The messages are sent in the context of an application-defined message. The application specifies the identifier of the message when it sends the ABM_NEW message to register the appbar. The notification code is in the wParam parameter of the application-defined message.

An appbar receives the ABN_POSCHANGED notification message when the taskbar’s size, position, or visibility state changes, when another appbar is added to the same edge of the screen, or when another appbar on the same edge of the screen is resized or removed. An appbar should respond to this notification message by sending ABM_QUERYPOS and ABM_SETPOS messages. If an appbar’s position has changed, it should call the MoveWindow function to move itself to the new position.

The system sends the ABN_STATECHANGE notification message whenever the taskbar’s autohide or always-on-top state has changed—that is, when the user selects or clears the Always on top or Auto hide check box on the taskbar’s property sheet. An appbar can use this notification message to set its state to conform to that of the taskbar, if desired.

When a full-screen application is started or when the last full-screen application is closed, an appbar receives the ABN_FULLSCREENAPP notification message. The lParam parameter indicates whether the full-screen application is opening or closing. If it is opening, the appbar must drop to the bottom of the z-order. The appbar should restore its z-order position when the last full-screen application has closed.

An appbar receives the ABN_WINDOWARRANGE notification message when the user selects the Cascade, Tile Horizontally, or Tile Vertically command from the taskbar’s shortcut menu. The system sends the message two times—before rearranging the windows (lParam is TRUE) and after arranging the windows (lParam is FALSE).

An appbar can use ABN_WINDOWARRANGE messages to exclude itself from the cascade or tile operation. To exclude itself, the appbar should hide itself when lParam is TRUE and show itself when lParam is FALSE. If an appbar hides itself in response to this message, it does not need to send the ABM_QUERYPOS and ABM_SETPOS messages in response to the cascade or tile operation.

Registering an Application Desktop Toolbar

An application must register an appbar by sending the ABM_NEW message. Registering an appbar adds it to the system’s internal list and provides the system with a message identifier to use to send notification messages to the appbar. Before exiting, an application must unregister the appbar by sending the ABM_REMOVE message. Unregistering removes the appbar from the system’s internal list and prevents the bar from receiving appbar notification messages.

The function in the following example either registers or unregisters an appbar, depending on the value of a Boolean flag parameter.

Setting the Appbar Size and Position

An application should set an appbar’s size and position after registering the appbar, after the user user moves or sizes the appbar, and whenever the appbar receives the ABN_POSCHANGED notification message. Before setting the size and position of the appbar, the application queries the system for an approved bounding rectangle by sending the ABM_QUERYPOS message. The system returns a bounding rectangle that does not interfere with the taskbar or any other appbar. The system adjusts the rectangle purely by rectangle subtraction; it makes no effort to preserve the rectangle’s initial size. For this reason, the appbar should readjust the rectangle, as necessary, after sending ABM_QUERYPOS.

Next, the application passes the bounding rectangle back to the system by using the ABM_SETPOS message. Then it calls the MoveWindow function to move the appbar into position.

The following example shows how to set an appbar’s size and position.

Processing Appbar Notification Messages

An appbar receives a notification message when the state of the taskbar changes, when a full-screen application starts (or the last one closes), or when an event occurs that can affect the appbar’s size and position. The following example shows how to process the various notification messages.

The following function adjusts an appbar’s bounding rectangle and then calls the application-defined AppBarQuerySetPos function (included in the previous section) to set the bar’s size and position accordingly.