From a78b280178a1c96e2c5088b3a43994340601e793 Mon Sep 17 00:00:00 2001 From: dahall Date: Tue, 1 Mar 2022 11:06:03 -0700 Subject: [PATCH] Added further XML docs to Shell32.ABM --- PInvoke/Shell32/ShellApi.cs | 221 +++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 208 insertions(+), 13 deletions(-) diff --git a/PInvoke/Shell32/ShellApi.cs b/PInvoke/Shell32/ShellApi.cs index 33ca3782..f4081771 100644 --- a/PInvoke/Shell32/ShellApi.cs +++ b/PInvoke/Shell32/ShellApi.cs @@ -40,53 +40,248 @@ namespace Vanara.PInvoke { /// /// Registers a new appbar and specifies the message identifier that the system should use to send notification messages to the appbar. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that contains the new appbar's window handle and message identifier. You must specify + /// the cbSize, hWnd, and uCallbackMessage members when sending this message; all other members are ignored. + /// + /// Return value + /// Returns TRUE if successful, or FALSE if an error occurs or if the appbar is already registered. /// ABM_NEW = 0x00000000, - /// Unregisters an appbar, removing the bar from the system's internal list. + /// + /// Unregisters an appbar, removing the bar from the system's internal list. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that contains the handle to the appbar to unregister. You must specify the cbSize and + /// hWnd members when sending this message; all other members are ignored. + /// + /// Return value + /// Always returns TRUE. + /// + /// This message causes the system to send the ABN_POSCHANGED notification message to all appbars. ABM_REMOVE = 0x00000001, - /// Requests a size and screen position for an appbar. + /// + /// Requests a size and screen position for an appbar. When the request is made, the message proposes a screen edge and a + /// bounding rectangle for the appbar. The system adjusts the bounding rectangle so that the appbar does not interfere with the + /// Windows taskbar or any other appbars. + /// Parameters + /// + /// A pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the proposed + /// bounding rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify + /// the cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored. + /// + /// Return value + /// Always returns TRUE. + /// + /// An appbar should send this message before sending the ABM_SETPOS message. ABM_QUERYPOS = 0x00000002, - /// Sets the size and screen position of an appbar. + /// + /// Sets the size and screen position of an appbar. The message specifies a screen edge and the bounding rectangle for the + /// appbar. The system may adjust the bounding rectangle so that the appbar does not interfere with the Windows taskbar or any + /// other appbars. + /// Parameters + /// + /// A pointer to an APPBARDATA structure. The uEdge member specifies a screen edge, and the rc member contains the bounding + /// rectangle. When the SHAppBarMessage function returns, rc contains the approved bounding rectangle. You must specify the + /// cbSize, hWnd, uEdge, and rc members when sending this message; all other members are ignored. + /// + /// Return value + /// Always returns TRUE. + /// + /// This message causes the system to send the ABN_POSCHANGED notification message to all appbars. ABM_SETPOS = 0x00000003, - /// Retrieves the autohide and always-on-top states of the Windows taskbar. + /// + /// Retrieves the autohide and always-on-top states of the Windows taskbar. + /// Parameters + /// + /// Pointer to an APPBARDATA structure. You must specify the cbSize member when sending this message; all other members are ignored. + /// + /// Return value + /// + /// Returns zero if the taskbar is neither in the autohide nor always-on-top state. Otherwise, the return value is one or both of + /// the following: + /// + /// + /// + /// Return code + /// Description + /// + /// + /// ABS_ALWAYSONTOP + /// + /// The taskbar is in the always-on-top state. As of Windows 7, ABS_ALWAYSONTOP is no longer returned because + /// the taskbar is always in that state. Older code should be updated to ignore the absence of this value in not assume that + /// return value to mean that the taskbar is not in the always-on-top state. + /// + /// + /// + /// ABS_AUTOHIDE + /// The taskbar is in the autohide state. + /// + /// + /// + /// This message causes the system to send the ABN_POSCHANGED notification message to all appbars. ABM_GETSTATE = 0x00000004, /// + /// /// Retrieves the bounding rectangle of the Windows taskbar. Note that this applies only to the system taskbar. Other objects, /// particularly toolbars supplied with third-party software, also can be present. As a result, some of the screen area not /// covered by the Windows taskbar might not be visible to the user. To retrieve the area of the screen not covered by both the /// taskbar and other app bars—the working area available to your application—, use the GetMonitorInfo function. + /// + /// Parameters + /// + /// A pointer to an APPBARDATA structure whose rc member receives the bounding rectangle, in screen coordinates, of the taskbar. + /// You must specify the cbSize when sending this message; all other members are ignored. + /// + /// Return value + /// Returns TRUE if successful; otherwise, FALSE. /// + /// + /// Note that this applies only to the system taskbar. Other objects, particularly toolbars supplied with third-party software, + /// also can be present. As a result, some of the screen area not covered by the Windows taskbar might not be visible to the + /// user. To retrieve the area of the screen not covered by both the taskbar and other app bars the working area available to + /// your application , use the GetMonitorInfo function. + /// ABM_GETTASKBARPOS = 0x00000005, /// - /// Notifies the system to activate or deactivate an appbar. The lParam member of the APPBARDATA pointed to by pData is set to - /// TRUE to activate or FALSE to deactivate. + /// Notifies the system that an appbar has been activated. An appbar should call this message in response to the WM_ACTIVATE message. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members + /// when sending this message; all other members are ignored. + /// + /// Return value + /// Always returns TRUE. /// + /// + /// This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar. The system + /// automatically sets the z-order for autohide appbars. + /// ABM_ACTIVATE = 0x00000006, - /// Retrieves the handle to the autohide appbar associated with a particular edge of the screen. + /// + /// Retrieves the handle to the autohide appbar associated with an edge of the screen. If the system has multiple monitors, the + /// monitor that contains the primary taskbar is used. To query for an autohide appbar on a specific monitor, + /// use ABM_GETAUTOHIDEBAREX. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that specifies the screen edge. You must specify the cbSize and uEdge members when + /// sending this message; all other members are ignored. + /// + /// Return value + /// + /// Returns the handle to the autohide appbar. The return value is NULL if an error occurs or if no autohide appbar is associated + /// with the given edge. + /// + /// ABM_GETAUTOHIDEBAR = 0x00000007, - /// Registers or unregisters an autohide appbar for an edge of the screen. + /// + /// Registers or unregisters an autohide appbar for a given edge of the screen. If the system has multiple monitors, the monitor + /// that contains the primary taskbar is used. To register or unregister an autohide appbar on a specific + /// monitor, use ABM_SETAUTOHIDEBAREX. + /// Parameters + /// + /// A pointer to an APPBARDATA structure. Set the lParam member to TRUE to register the appbar or FALSE to unregister it. You + /// must specify the cbSize, hWnd, uEdge, and lParam members when sending this message; all other members are ignored. + /// + /// Return value + /// + /// Returns TRUE if successful, or FALSE if an error occurs or if an autohide appbar is already registered for the given edge. + /// + /// + /// + /// The system allows only one autohide appbar for each edge of the screen. This is determined when the member uEdge of the + /// APPBARDATA structure is set. + /// ABM_SETAUTOHIDEBAR = 0x00000008, - /// Notifies the system when an appbar's position has changed. + /// + /// Notifies the system when an appbar's position has changed. An appbar should call this message in response to the + /// WM_WINDOWPOSCHANGED message. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that identifies the appbar to activate. You must specify the cbSize and hWnd members + /// when sending this message; all other members are ignored. + /// + /// Return value + /// Always returns TRUE. + /// + /// This message is ignored if the hWnd member of the structure pointed to by pabd identifies an autohide appbar. ABM_WINDOWPOSCHANGED = 0x00000009, - /// Windows XP and later: Sets the state of the appbar's autohide and always-on-top attributes. + /// + /// Sets the autohide and always-on-top states of the Windows taskbar. + /// Parameters + /// + /// A pointer to an APPBARDATA structure. You must specify the cbSize and hWnd members when sending this message. Data for the + /// desired state is sent in the lParam member using one of the following values. + /// + /// + /// + /// 0 + /// Autohide and always-on-top both off + /// + /// + /// ABS_ALWAYSONTOP + /// Always-on-top on, autohide off + /// + /// + /// ABS_AUTOHIDE + /// Autohide on, always-on-top off + /// + /// + /// ABS_AUTOHIDE | ABS_ALWAYSONTOP + /// Autohide and always-on-top both on + /// + /// + /// Return value + /// Always returns TRUE. + /// ABM_SETSTATE = 0x0000000A, /// - /// Windows XP and later: Retrieves the handle to the autohide appbar associated with a particular edge of a particular monitor. + /// Retrieves the handle to the autohide appbar associated with an edge of the screen. This message extends ABM_GETAUTOHIDEBAR by + /// enabling you to specify a particular monitor, for use in multiple monitor situations. + /// Parameters + /// + /// A pointer to an APPBARDATA structure that specifies the screen edge and monitor. You must specify the cbSize, uEdge, and rc + /// members when sending this message; all other members are ignored. + /// + /// Return value + /// + /// Returns the handle to the autohide appbar. The return value is NULL if an error occurs or if no autohide appbar is associated + /// with the given edge of the given monitor. + /// /// ABM_GETAUTOHIDEBAREX = 0x0000000B, - /// Windows XP and later: Registers or unregisters an autohide appbar for an edge of a particular monitor. + /// + /// Registers or unregisters an autohide appbar for a given edge of the screen. This message extends ABM_SETAUTOHIDEBAR by + /// enabling you to specify a particular monitor, for use in multiple monitor situations. + /// Parameters + /// + /// A pointer to an APPBARDATA structure. Set the lParam member is to TRUE to register the appbar or FALSE to unregister it. You + /// must specify the cbSize, hWnd, uEdge, rc, and lParam members when sending this message; all other members are ignored. + /// + /// Return value + /// + /// Returns TRUE if successful, or FALSE if an error occurs or if an autohide appbar is already registered for the given edge on + /// the given monitor. + /// + /// + /// + /// The system allows only one autohide appbar for each edge of each monitor. The monitor is determined by the rc member and the + /// edge is determined by the uEdge member of the APPBARDATA structure. + /// ABM_SETAUTOHIDEBAREX = 0x0000000C, } @@ -2042,7 +2237,7 @@ namespace Vanara.PInvoke // dwMessage, PAPPBARDATA pData ); [DllImport(Lib.Shell32, SetLastError = false, ExactSpelling = true)] [PInvokeData("shellapi.h", MSDNShortId = "173d6eff-b33b-4d7d-bedd-5ebfb1e45954")] - public static extern UIntPtr SHAppBarMessage(ABM dwMessage, ref APPBARDATA pData); + public static extern IntPtr SHAppBarMessage(ABM dwMessage, ref APPBARDATA pData); /// /// Sends a message to the taskbar's status area.