1 /* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
3 * This file is part of the LibreOffice project.
5 * This Source Code Form is subject to the terms of the Mozilla Public
6 * License, v. 2.0. If a copy of the MPL was not distributed with this
7 * file, You can obtain one at http://mozilla.org/MPL/2.0/.
9 * This file incorporates work covered by the following license notice:
11 * Licensed to the Apache Software Foundation (ASF) under one or more
12 * contributor license agreements. See the NOTICE file distributed
13 * with this work for additional information regarding copyright
14 * ownership. The ASF licenses this file to you under the Apache
15 * License, Version 2.0 (the "License"); you may not use this file
16 * except in compliance with the License. You may obtain a copy of
17 * the License at http://www.apache.org/licenses/LICENSE-2.0 .
20 #ifndef INCLUDED_VCL_MENU_HXX
21 #define INCLUDED_VCL_MENU_HXX
24 #include <string_view>
26 #include <vcl/vclenum.hxx>
27 #include <tools/link.hxx>
28 #include <tools/long.hxx>
29 #include <vcl/dllapi.h>
30 #include <vcl/keycod.hxx>
31 #include <vcl/vclreferencebase.hxx>
32 #include <vcl/vclevent.hxx>
33 #include <com/sun/star/uno/Reference.hxx>
34 #include <o3tl/typed_flags_set.hxx>
42 namespace tools
{ class Rectangle
; }
49 class MenuFloatingWindow
;
52 struct SystemMenuData
;
53 enum class FloatWinPopupFlags
;
55 namespace com::sun::star::awt
{ class XPopupMenu
; }
56 namespace com::sun::star::accessibility
{ class XAccessible
; }
57 namespace com::sun::star::frame
{ class XFrame
; }
62 struct MenuLayoutData
;
63 typedef OutputDevice RenderContext
; // same as in include/vcl/outdev.hxx
64 class ILibreOfficeKitNotifier
;
67 constexpr sal_uInt16 MENU_APPEND
= 0xFFFF;
68 constexpr sal_uInt16 MENU_ITEM_NOTFOUND
= 0xFFFF;
70 // Must match the definitions in css::awt::PopupMenuDirection.idl
71 enum class PopupMenuFlags
76 ExecuteRight
= 0x0008,
77 NoMouseUpClose
= 0x0010,
78 //If there isn't enough space to put the menu where it wants
79 //to go, then they will be autoplaced. Toggle this bit
80 //on to force menus to be placed either above or below
81 //the starting rectangle and shrunk to fit and then scroll rather than place
82 //the menu beside that rectangle
83 NoHorzPlacement
= 0x0020,
88 template<> struct typed_flags
<PopupMenuFlags
> : is_typed_flags
<PopupMenuFlags
, 0x003b> {};
94 NoAutoMnemonics
= 0x0001,
95 HideDisabledEntries
= 0x0002,
96 // overrides default hiding of disabled entries in popup menus
97 AlwaysShowDisabledEntries
= 0x0004,
102 template<> struct typed_flags
<MenuFlags
> : is_typed_flags
<MenuFlags
, 0x0007> {};
105 /// Invalid menu item id
106 constexpr auto ITEMPOS_INVALID
= 0xFFFF;
108 struct ImplMenuDelData
110 ImplMenuDelData
* mpNext
;
111 VclPtr
<const Menu
> mpMenu
;
113 explicit ImplMenuDelData( const Menu
* );
116 bool isDeleted() const { return mpMenu
== nullptr; }
119 typedef void (*MenuUserDataReleaseFunction
)(void*);
121 class VCL_DLLPUBLIC Menu
: public VclReferenceBase
123 friend class MenuBar
;
124 friend class MenuBarWindow
;
125 friend class MenuButton
;
126 friend class MenuFloatingWindow
;
127 friend class PopupMenu
;
128 friend class SystemWindow
;
129 friend struct ImplMenuDelData
;
131 ImplMenuDelData
* mpFirstDel
;
132 std::unique_ptr
<MenuItemList
> pItemList
; // list with MenuItems
133 VclPtr
<Menu
> pStartedFrom
;
134 VclPtr
<vcl::Window
> pWindow
;
136 Link
<Menu
*, bool> aActivateHdl
; // Active-Handler
137 Link
<Menu
*, bool> aDeactivateHdl
; // Deactivate-Handler
138 Link
<Menu
*, bool> aSelectHdl
; // Select-Handler
140 std::list
<Link
<VclMenuEvent
&,void> > maEventListeners
;
144 OUString aTitleText
; // PopupMenu text
145 sal_uInt16 nTitleHeight
;
147 ImplSVEvent
* nEventId
;
148 sal_uInt16 mnHighlightedItemPos
; // for native menus: keeps track of the highlighted item
149 MenuFlags nMenuFlags
;
150 sal_uInt16 nSelectedId
;
151 OString sSelectedIdent
;
154 sal_uInt16 nImgOrChkPos
;
157 bool bCanceled
: 1; ///< Terminated during a callback
158 bool bInCallback
: 1; ///< In Activate/Deactivate
159 bool bKilled
: 1; ///< Killed
161 css::uno::Reference
<css::accessibility::XAccessible
> mxAccessible
;
162 mutable std::unique_ptr
<vcl::MenuLayoutData
> mpLayoutData
;
163 std::unique_ptr
<SalMenu
> mpSalMenu
;
166 SAL_DLLPRIVATE Menu
* ImplGetStartMenu();
167 SAL_DLLPRIVATE Menu
* ImplFindSelectMenu();
168 SAL_DLLPRIVATE Menu
* ImplFindMenu( sal_uInt16 nId
);
169 SAL_DLLPRIVATE Size
ImplCalcSize( vcl::Window
* pWin
);
170 SAL_DLLPRIVATE
bool ImplIsVisible( sal_uInt16 nPos
) const;
171 SAL_DLLPRIVATE
bool ImplCurrentlyHiddenOnGUI(sal_uInt16 nPos
) const;
172 SAL_DLLPRIVATE
bool ImplIsSelectable( sal_uInt16 nPos
) const;
173 SAL_DLLPRIVATE sal_uInt16
ImplGetVisibleItemCount() const;
174 SAL_DLLPRIVATE sal_uInt16
ImplGetFirstVisible() const;
175 SAL_DLLPRIVATE sal_uInt16
ImplGetPrevVisible( sal_uInt16 nPos
) const;
176 SAL_DLLPRIVATE sal_uInt16
ImplGetNextVisible( sal_uInt16 nPos
) const;
177 SAL_DLLPRIVATE
void ImplPaint(vcl::RenderContext
& rRenderContext
, Size
const & rSize
,
178 sal_uInt16 nBorder
, tools::Long nOffY
= 0, MenuItemData
const * pThisDataOnly
= nullptr,
179 bool bHighlighted
= false, bool bLayout
= false, bool bRollover
= false ) const;
180 SAL_DLLPRIVATE
void ImplPaintMenuTitle(vcl::RenderContext
&, const tools::Rectangle
& rRect
) const;
181 SAL_DLLPRIVATE
void ImplSelect();
182 SAL_DLLPRIVATE
void ImplCallHighlight( sal_uInt16 nHighlightItem
);
183 SAL_DLLPRIVATE
void ImplCallEventListeners( VclEventId nEvent
, sal_uInt16 nPos
);
184 DECL_DLLPRIVATE_LINK(ImplCallSelect
, void*, void );
186 SAL_DLLPRIVATE
void ImplFillLayoutData() const;
187 SAL_DLLPRIVATE SalMenu
* ImplGetSalMenu() { return mpSalMenu
.get(); }
188 SAL_DLLPRIVATE OUString
ImplGetHelpText( sal_uInt16 nItemId
) const;
190 // returns native check and option menu symbol height in rCheckHeight and rRadioHeight
191 // return value is maximum width and height of checkboxes and radiobuttons
192 SAL_DLLPRIVATE Size
ImplGetNativeCheckAndRadioSize(vcl::RenderContext
const & rRenderContext
, tools::Long
& rCheckHeight
, tools::Long
& rRadioHeight
) const;
194 // returns native submenu arrow size and spacing from right border
195 // return value is whether it's supported natively
196 SAL_DLLPRIVATE
static bool ImplGetNativeSubmenuArrowSize(vcl::RenderContext
const & rRenderContext
, Size
& rArrowSize
, tools::Long
& rArrowSpacing
);
198 SAL_DLLPRIVATE
void ImplAddDel( ImplMenuDelData
&rDel
);
199 SAL_DLLPRIVATE
void ImplRemoveDel( ImplMenuDelData
&rDel
);
201 SAL_DLLPRIVATE MenuItemData
* NbcInsertItem(sal_uInt16 nId
, MenuItemBits nBits
,
202 const OUString
& rStr
, Menu
* pMenu
,
203 size_t nPos
, const OString
&rIdent
);
205 /// Close the 'pStartedFrom' menu window.
206 virtual void ClosePopup(Menu
* pMenu
) = 0;
208 /// Forward the KeyInput call to the MenuBar.
209 virtual void MenuBarKeyInput(const KeyEvent
& rEvent
);
212 SAL_DLLPRIVATE
void ImplKillLayoutData() const;
214 SAL_DLLPRIVATE
vcl::Window
* ImplGetWindow() const { return pWindow
; }
216 void ImplSelectWithStart( Menu
* pStartMenu
= nullptr );
221 /** The Menu constructor is protected.
223 The callers are supposed to instantiate either PopupMenu or MenuBar, but
229 virtual ~Menu() override
;
230 virtual void dispose() override
;
234 virtual void Select();
236 void InsertItem(sal_uInt16 nItemId
, const OUString
& rStr
,
237 MenuItemBits nItemBits
= MenuItemBits::NONE
,
238 const OString
&rIdent
= OString(),
239 sal_uInt16 nPos
= MENU_APPEND
);
240 void InsertItem(sal_uInt16 nItemId
, const Image
& rImage
,
241 MenuItemBits nItemBits
= MenuItemBits::NONE
,
242 const OString
&rIdent
= OString(),
243 sal_uInt16 nPos
= MENU_APPEND
);
244 void InsertItem(sal_uInt16 nItemId
,
245 const OUString
& rString
, const Image
& rImage
,
246 MenuItemBits nItemBits
= MenuItemBits::NONE
,
247 const OString
&rIdent
= OString(),
248 sal_uInt16 nPos
= MENU_APPEND
);
249 void InsertItem(const OUString
& rCommand
,
250 const css::uno::Reference
<css::frame::XFrame
>& rFrame
);
251 void InsertSeparator(const OString
&rIdent
= OString(), sal_uInt16 nPos
= MENU_APPEND
);
252 void RemoveItem( sal_uInt16 nPos
);
255 void CreateAutoMnemonics();
257 void SetMenuFlags( MenuFlags nFlags
) { nMenuFlags
= nFlags
; }
258 MenuFlags
GetMenuFlags() const { return nMenuFlags
; }
260 sal_uInt16
GetItemCount() const;
261 sal_uInt16
GetItemId(sal_uInt16 nPos
) const;
262 sal_uInt16
GetItemId(std::string_view rIdent
) const;
263 sal_uInt16
GetItemPos( sal_uInt16 nItemId
) const;
264 OString
GetItemIdent(sal_uInt16 nItemId
) const;
265 MenuItemType
GetItemType( sal_uInt16 nPos
) const;
266 sal_uInt16
GetCurItemId() const { return nSelectedId
;}
267 OString
const & GetCurItemIdent() const { return sSelectedIdent
; }
268 void SetItemBits( sal_uInt16 nItemId
, MenuItemBits nBits
);
269 MenuItemBits
GetItemBits( sal_uInt16 nItemId
) const;
271 void SetUserValue(sal_uInt16 nItemId
, void* nUserValue
, MenuUserDataReleaseFunction aFunc
=nullptr);
272 void* GetUserValue(sal_uInt16 nItemId
) const;
274 void SetPopupMenu( sal_uInt16 nItemId
, PopupMenu
* pMenu
);
275 PopupMenu
* GetPopupMenu( sal_uInt16 nItemId
) const;
277 void SetAccelKey( sal_uInt16 nItemId
, const vcl::KeyCode
& rKeyCode
);
278 vcl::KeyCode
GetAccelKey( sal_uInt16 nItemId
) const;
280 void CheckItem( sal_uInt16 nItemId
, bool bCheck
= true );
281 void CheckItem( std::string_view rIdent
, bool bCheck
= true );
282 bool IsItemChecked( sal_uInt16 nItemId
) const;
284 virtual void SelectItem(sal_uInt16 nItemId
) = 0;
286 void EnableItem( sal_uInt16 nItemId
, bool bEnable
= true );
287 void EnableItem(std::string_view rIdent
, bool bEnable
= true)
289 EnableItem(GetItemId(rIdent
), bEnable
);
291 bool IsItemEnabled( sal_uInt16 nItemId
) const;
293 void ShowItem( sal_uInt16 nItemId
, bool bVisible
= true );
294 void HideItem( sal_uInt16 nItemId
) { ShowItem( nItemId
, false ); }
296 bool IsItemPosVisible( sal_uInt16 nItemPos
) const;
297 bool IsMenuVisible() const;
298 virtual bool IsMenuBar() const = 0;
300 void RemoveDisabledEntries( bool bCheckPopups
= true, bool bRemoveEmptyPopups
= false );
302 void UpdateNativeMenu();
304 void SetItemText( sal_uInt16 nItemId
, const OUString
& rStr
);
305 OUString
GetItemText( sal_uInt16 nItemId
) const;
307 void SetItemImage( sal_uInt16 nItemId
, const Image
& rImage
);
308 Image
GetItemImage( sal_uInt16 nItemId
) const;
310 void SetItemCommand( sal_uInt16 nItemId
, const OUString
& rCommand
);
311 OUString
GetItemCommand( sal_uInt16 nItemId
) const;
313 void SetHelpText( sal_uInt16 nItemId
, const OUString
& rString
);
314 OUString
GetHelpText( sal_uInt16 nItemId
) const;
316 void SetTipHelpText( sal_uInt16 nItemId
, const OUString
& rString
);
317 OUString
GetTipHelpText( sal_uInt16 nItemId
) const;
319 void SetHelpCommand( sal_uInt16 nItemId
, const OUString
& rString
);
320 OUString
GetHelpCommand( sal_uInt16 nItemId
) const;
322 void SetHelpId( sal_uInt16 nItemId
, const OString
& rHelpId
);
323 OString
GetHelpId( sal_uInt16 nItemId
) const;
325 void SetActivateHdl( const Link
<Menu
*, bool>& rLink
)
327 aActivateHdl
= rLink
;
330 void SetDeactivateHdl( const Link
<Menu
*, bool>& rLink
)
332 aDeactivateHdl
= rLink
;
335 void SetSelectHdl( const Link
<Menu
*,bool>& rLink
)
340 sal_uInt16
GetTitleHeight() const
345 void AddEventListener( const Link
<VclMenuEvent
&,void>& rEventListener
);
346 void RemoveEventListener( const Link
<VclMenuEvent
&,void>& rEventListener
);
348 Menu
& operator =( const Menu
& rMenu
);
350 // for menu functions
351 MenuItemList
* GetItemList() const
353 return pItemList
.get();
356 // returns the system's menu handle if native menus are supported
357 // pData must point to a SystemMenuData structure
358 void GetSystemMenuData( SystemMenuData
* pData
) const;
360 // accessibility helpers
362 // returns the bounding box for the character at index nIndex
363 // where nIndex is relative to the starting index of the item
364 // with id nItemId (in coordinates of the displaying window)
365 tools::Rectangle
GetCharacterBounds( sal_uInt16 nItemId
, tools::Long nIndex
) const;
366 // -1 is returned if no character is at that point
367 // if an index is found the corresponding item id is filled in (else 0)
368 tools::Long
GetIndexForPoint( const Point
& rPoint
, sal_uInt16
& rItemID
) const;
369 // returns the bounding rectangle for an item at pos nItemPos
370 tools::Rectangle
GetBoundingRectangle( sal_uInt16 nItemPos
) const;
372 css::uno::Reference
<css::accessibility::XAccessible
> GetAccessible();
373 void SetAccessible(const css::uno::Reference
<css::accessibility::XAccessible
>& rxAccessible
);
375 // gets the activation key of the specified item
376 KeyEvent
GetActivationKey( sal_uInt16 nItemId
) const;
378 vcl::Window
* GetWindow() const { return pWindow
; }
380 void SetAccessibleName( sal_uInt16 nItemId
, const OUString
& rStr
);
381 OUString
GetAccessibleName( sal_uInt16 nItemId
) const;
383 void SetAccessibleDescription( sal_uInt16 nItemId
, const OUString
& rStr
);
384 OUString
GetAccessibleDescription( sal_uInt16 nItemId
) const;
386 // returns whether the item a position nItemPos is highlighted or not.
387 bool IsHighlighted( sal_uInt16 nItemPos
) const;
389 void HighlightItem( sal_uInt16 nItemPos
);
390 void DeHighlight() { HighlightItem( 0xFFFF ); } // MENUITEMPOS_INVALID
392 bool HandleMenuCommandEvent(Menu
*pMenu
, sal_uInt16 nEventId
) const;
393 bool HandleMenuActivateEvent(Menu
*pMenu
) const;
394 bool HandleMenuDeActivateEvent(Menu
*pMenu
) const;
399 void set_id(const OUString
& rID
) { maID
= rID
; }
402 * Get the ID of the window.
404 const OUString
& get_id() const { return maID
; }
407 class VCL_DLLPUBLIC MenuBar
: public Menu
409 Link
<void*,void> maCloseHdl
;
410 bool mbCloseBtnVisible
: 1;
411 bool mbFloatBtnVisible
: 1;
412 bool mbHideBtnVisible
: 1;
413 bool mbDisplayable
: 1;
415 friend class Application
;
417 friend class MenuBarWindow
;
418 friend class MenuFloatingWindow
;
419 friend class SystemWindow
;
421 SAL_DLLPRIVATE
static VclPtr
<vcl::Window
> ImplCreate(vcl::Window
* pParent
, vcl::Window
* pWindow
, MenuBar
* pMenu
);
422 SAL_DLLPRIVATE
static void ImplDestroy(MenuBar
* pMenu
, bool bDelete
);
423 SAL_DLLPRIVATE
bool ImplHandleKeyEvent(const KeyEvent
& rKEvent
);
424 SAL_DLLPRIVATE
bool ImplHandleCmdEvent(const CommandEvent
& rCEvent
);
428 /// Return the MenuBarWindow.
429 MenuBarWindow
* getMenuBarWindow();
433 MenuBar( const MenuBar
& rMenu
);
434 virtual ~MenuBar() override
;
435 virtual void dispose() override
;
437 MenuBar
& operator =( const MenuBar
& rMenu
);
439 virtual bool IsMenuBar() const override
{ return true; }
441 /// Close the 'pStartedFrom' menu window.
442 virtual void ClosePopup(Menu
* pMenu
) override
;
444 /// Forward the KeyInput call to the MenuBar.
445 virtual void MenuBarKeyInput(const KeyEvent
& rEvent
) override
;
447 void ShowCloseButton( bool bShow
);
448 bool HasCloseButton() const { return mbCloseBtnVisible
; }
449 bool HasFloatButton() const { return mbFloatBtnVisible
; }
450 bool HasHideButton() const { return mbHideBtnVisible
; }
451 void ShowButtons( bool bClose
, bool bFloat
, bool bHide
);
453 virtual void SelectItem(sal_uInt16 nId
) override
;
454 bool HandleMenuHighlightEvent(Menu
*pMenu
, sal_uInt16 nEventId
) const;
455 bool HandleMenuButtonEvent(sal_uInt16 nEventId
);
457 void SetCloseButtonClickHdl( const Link
<void*,void>& rLink
) { maCloseHdl
= rLink
; }
458 const Link
<void*,void>& GetCloseButtonClickHdl() const { return maCloseHdl
; }
460 // - by default a menubar is displayable
461 // - if a menubar is not displayable, its MenuBarWindow will never be shown
462 // and it will be hidden if it was visible before
463 // - note: if a menubar is displayable, this does not necessarily mean that it is currently visible
464 void SetDisplayable( bool bDisplayable
);
465 bool IsDisplayable() const { return mbDisplayable
; }
467 struct MenuBarButtonCallbackArg
469 sal_uInt16 nId
; // Id of the button
470 bool bHighlight
; // highlight on/off
472 // add an arbitrary button to the menubar (will appear next to closer)
473 // passed link will be call with a MenuBarButtonCallbackArg on press
474 // passed string will be set as tooltip
475 sal_uInt16
AddMenuBarButton( const Image
&, const Link
<MenuBar::MenuBarButtonCallbackArg
&,bool>&, const OUString
& );
476 // set the highlight link for additional button with ID nId
477 // highlight link will be called with a MenuBarButtonHighlightArg
478 // the bHighlight member of that struct shall contain the new state
479 void SetMenuBarButtonHighlightHdl( sal_uInt16 nId
, const Link
<MenuBar::MenuBarButtonCallbackArg
&,bool>& );
480 // returns the rectangle occupied by the additional button named nId
481 // coordinates are relative to the systemwindow the menubar is attached to
482 // if the menubar is unattached an empty rectangle is returned
483 tools::Rectangle
GetMenuBarButtonRectPixel( sal_uInt16 nId
);
484 void RemoveMenuBarButton( sal_uInt16 nId
);
485 void LayoutChanged();
486 // get the height of the menubar, return the native menubar height if that is active or the vcl
488 int GetMenuBarHeight() const;
491 inline MenuBar
& MenuBar::operator=( const MenuBar
& rMenu
)
493 Menu::operator=(rMenu
);
497 class VCL_DLLPUBLIC PopupMenu
: public Menu
500 friend class MenuFloatingWindow
;
501 friend class MenuBarWindow
;
502 friend struct MenuItemData
;
505 SAL_DLLPRIVATE MenuFloatingWindow
* ImplGetFloatingWindow() const;
508 SAL_DLLPRIVATE sal_uInt16
ImplExecute( const VclPtr
<vcl::Window
>& pW
, const tools::Rectangle
& rRect
, FloatWinPopupFlags nPopupModeFlags
, Menu
* pSFrom
, bool bPreSelectFirst
);
509 SAL_DLLPRIVATE
void ImplFlushPendingSelect();
510 SAL_DLLPRIVATE
tools::Long
ImplCalcHeight( sal_uInt16 nEntries
) const;
511 SAL_DLLPRIVATE sal_uInt16
ImplCalcVisEntries( tools::Long nMaxHeight
, sal_uInt16 nStartEntry
, sal_uInt16
* pLastVisible
= nullptr ) const;
515 PopupMenu( const PopupMenu
& rMenu
);
516 virtual ~PopupMenu() override
;
518 virtual bool IsMenuBar() const override
{ return false; }
520 /// Close the 'pStartedFrom' menu window.
521 virtual void ClosePopup(Menu
* pMenu
) override
;
523 void SetText( const OUString
& rTitle
)
528 sal_uInt16
Execute( vcl::Window
* pWindow
, const Point
& rPopupPos
);
529 sal_uInt16
Execute( vcl::Window
* pWindow
, const tools::Rectangle
& rRect
, PopupMenuFlags nFlags
= PopupMenuFlags::NONE
);
533 virtual void SelectItem(sal_uInt16 nId
) override
;
534 void SetSelectedEntry( sal_uInt16 nId
); // for use by native submenu only
536 css::uno::Reference
<css::awt::XPopupMenu
> CreateMenuInterface();
538 static bool IsInExecute();
539 static PopupMenu
* GetActivePopupMenu();
541 PopupMenu
& operator=( const PopupMenu
& rMenu
);
544 inline PopupMenu
& PopupMenu::operator=( const PopupMenu
& rMenu
)
546 Menu::operator=( rMenu
);
550 #endif // INCLUDED_VCL_MENU_HXX
552 /* vim:set shiftwidth=4 softtabstop=4 expandtab: */