cxMenu.h

Go to the documentation of this file.

// Copyright (c) 2026 E. Oulashin
#ifndef __CXMENU_H__
#define __CXMENU_H__
 
// Copyright (c) 2005-2007 Michael H. Kinney
//
// This represents a pop-up (or pull-down) list of items,
//  one of which may be selected before the menu goes away.
//  The items are text, with the shortcut letter underlined.
 
#include "cxWindow.h"
#include "cxMenuItemType.h"
#include "cxFunction.h"
 
#include <string>
#include <map>
#include <set>
#include <vector>
#include <memory>
 
namespace cx {
 
#define DEFAULT_CXMENU_SEARCH_KEY '/'     // Default search key
#define DEFAULT_CXMENU_ALT_PGUP_KEY '.'   // Default alternate PgUp key
#define DEFAULT_CXMENU_ALT_PGDOWN_KEY ',' // Default alternate PgDown key
 
class cxMenu : public cxWindow
{
   public:
      explicit cxMenu(cxWindow *pParentWindow = nullptr, int pRow = 0, int pCol = 0,
                      int pHeight = DEFAULT_HEIGHT, int pWidth = DEFAULT_WIDTH,
                      const std::string& pTitle = "", cxWindow *pExtTitleWindow = nullptr,
                      cxWindow *pExtStatusWindow = nullptr,
                      eBorderStyle pBorderStyle = eBS_SINGLE_LINE);
 
      cxMenu(const cxMenu& pThatMenu);
 
      virtual ~cxMenu();
 
      virtual void append(const std::string& pDisplayText, long pReturnCode,
                          const std::string& pHelpString = "",
                          cxMenuItemType pType = cxITEM_NORMAL,
                          bool pResize = false, const std::string& pItemText = "");
 
      virtual void appendWithPullRight(const std::string& pDisplayText, cxMenu *pSubMenu,
                                       const std::string& pHelpString = "",
                                       bool pResize = false);
 
      virtual void appendWithPopUp(const std::string& pDisplayText, cxMenu *pSubMenu,
                                   const std::string& pHelpString = "", bool pResize = false);
 
      virtual bool remove(unsigned pItemIndex, bool pResize = false,
                          bool pRefresh = false);
 
      virtual bool remove(const std::string& pItemText, bool pUseDisplayText = true,
                          bool pResize = false, bool pRefresh = false);
 
      virtual bool removeByReturnCode(long pReturnCode, bool pResize = false,
                                      bool pRefresh = false);
 
      virtual void removeAllItems(bool pResize = false, bool pRefresh = false);
 
      virtual void clear(bool pRefresh = false) override;
 
      virtual long showModal(bool pShowSelf = true, bool pBringToTop = true,
                             bool pShowSubwindows = true) override;
 
      virtual bool modalGetsKeypress() const override;
 
      virtual void scrollItems(int pScrollAmt, bool pRefresh = false);
 
      virtual void scrollToTop(bool pRefresh = false);
 
      virtual void scrollToBottom(bool pRefresh = false);
 
      virtual void setTopItem(unsigned pTopItem, bool pRefresh = false);
 
      virtual void setTopItem(const std::string& pItemText, bool pRefresh = false);
 
      virtual void setBottomItem(unsigned pItemIndex, bool pRefresh = false);
 
      virtual bool move(int pNewRow, int pNewCol, bool pRefresh = true) override;
 
      virtual unsigned numMenuItems() const;
 
      virtual void resize(int pNewHeight, int pNewWidth, bool pRefresh = false) override;
 
      virtual void drawMessage() override;
 
      virtual long show(bool pBringToTop = true, bool pShowSubwindows = true) override;
 
      virtual void erase(bool pEraseSubwindows = true) override;
 
      int getSubWinWidth() const;
 
      int getSubWinHeight() const;
 
      virtual long getReturnCode() const override;
 
      virtual long getReturnCode(unsigned pIndex) const;
 
      virtual long getReturnCode(const std::string& pItemText, bool pUseDisplayText = true) const;
 
      virtual long getCurrentItemReturnCode() const;
 
      virtual std::string getItemText(int pIndex, bool pGetDisplayText = true) const;
 
      virtual std::string getCurrentItemText(bool pGetDisplayText = true) const;
 
      virtual void drawBorder() override;
 
      void toggleSelectability(unsigned pIndex, bool pSelectable);
 
      void toggleSelectability(const std::string& pItemText, bool pSelectable);
 
      void setClearOnSearch(bool pClearOnSearch);
 
      void setCaseSensitiveSearch(bool pCaseSensitiveSearch);
 
      void setSearchKey(int pSearchKey);
 
      void setAltPgUpKey(int pPgUpKey);
 
      int getAltPgUpKey() const;
 
      void setAltPgDownKey(int pPgDownKey);
 
      int getAltPgDownKey() const;
 
      virtual void setStatus(const std::string& pStatus, bool pRefreshStatus = true) override;
 
      void disableCustomStatus(bool pRefreshStatus = true);
 
      cxMenu& operator =(const cxMenu& pThatMenu);
 
      virtual void refreshMenuItems();
 
      virtual bool setItemTextByReturnCode(long pReturnCode, const std::string& pItemText,
                                 bool pSetAll = false, bool pRefresh = false);
 
      virtual bool setItemTextByIndex(int pIndex, const std::string& pItemText,
                                 bool pRefresh = false);
 
      virtual void setBorderStyle(eBorderStyle pBorderStyle) override;
 
      virtual bool itemExists(const std::string& pItemText, bool pUseDisplayText = true) const;
 
      void setAllowQuit(bool pAllowQuit);
 
      bool getAllowQuit() const;
 
      void setAllowExit(bool pAllowExit);
 
      bool getAllowExit() const;
 
      int getIndexByReturnCode(long pReturnCode) const;
 
      std::string getItemTextByReturnCode(long pReturnCode, bool pGetDisplayText = true);
 
      void setLoopStartFunction(const std::shared_ptr<cxFunction>& pFuncPtr);
 
      void setLoopEndFunction(const std::shared_ptr<cxFunction>& pFuncPtr);
 
      virtual bool runLoopStartFunction();
 
      virtual bool runLoopEndFunction();
 
      cxMenuItemType getItemType(unsigned pIndex) const;
 
      cxMenuItemType getItemType(const std::string& pItemText) const;
 
      virtual void setWrapping(bool pWrap);
 
      virtual bool getWrapping() const;
 
      virtual void setWaitForInputIfEmpty(bool pWaitForInputIfEmpty);
 
      virtual bool getWaitForInputIfEmpty() const;
 
      virtual int getCurrentMenuItem() const;
 
      virtual void setCurrentMenuItem(int pItemIndex, bool pRefresh = false);
 
      void setExitWhenLeaveFirst(bool pExitWhenLeaveFirst);
 
      bool getExitWhenLeaveFirst() const;
 
      void setExitWhenLeaveLast(bool pExitWhenLeaveLast);
 
      void setExitOnOutsideClick(bool pExitOnOutsideClick);
 
      bool getExitWhenLeaveLast() const;
 
      void setRefreshItemsWhenModal(bool pRefreshItemsWhenModal);
 
      bool getRefreshItemsWhenModal() const;
 
      virtual void addAttr(e_WidgetItems pItem, attr_t pAttr) override;
 
      virtual void setAttr(e_WidgetItems pItem, attr_t pAttr) override;
 
      virtual void removeAttr(e_WidgetItems pItem, attr_t pAttr) override;
 
      virtual void removeAttrs(e_WidgetItems pItem) override;
 
      virtual void getAttrs(e_WidgetItems pItem, std::set<attr_t>& pAttrs) const override;
 
      virtual void setHotkeyHighlighting(bool pHotkeyHighlighting) override;
 
      virtual std::string cxTypeStr() const override;
 
      virtual void sortByReturnCode(bool pRefresh = false);
 
      long getHighestReturnCode() const;
 
      virtual bool itemWasSelected() const;
 
      bool mouseEvtWasInItemArea(int& pItemIndex) const;
 
      virtual bool setOnSelectItemFunction(funcPtr4 pFunction, void *p1,
                                           void *p2, void *p3, void *p4,
                                           bool pExitAfterRun,
                                           bool pRunOnLeaveFunction);
 
      virtual bool setOnSelectItemFunction(funcPtr2 pFunction, void *p1,
                                           void *p2, bool pExitAfterRun,
                                           bool pRunOnLeaveFunction);
 
      virtual bool setOnSelectItemFunction(funcPtr0 pFunction,
                                           bool pExitAfterRun,
                                           bool pRunOnLeaveFunction);
 
      std::shared_ptr<cxFunction> getOnSelectItemFunction() const;
 
   protected:
      std::set<attr_t> mMenuSelectionAttrs;
 
      void copyCxMenuStuff(const cxMenu* pThatMenu);
 
      int subWinTop() const;
 
      int subWinLeft() const;
 
      long doInputLoop(bool& pRunOnLeaveFunction);
 
      virtual void enableAttrs(WINDOW *pWin, e_WidgetItems pItem) override;
 
      virtual void disableAttrs(WINDOW *pWin, e_WidgetItems pItem) override;
 
   private:
      WINDOW *mSubWindow = nullptr;                      // For scrolling
      int mSubWinHeight;                                 // Height of the subwindow
      int mSubWinWidth;                                  // Width of the subwindow
      int mCurrentMenuItem = 0;                          // Keeps track of the currently highlighted item
      int mTopMenuItem = 0;                              // The index of the topmost menu item shown
      int mAltPgUpKey = DEFAULT_CXMENU_ALT_PGUP_KEY;     // Alternate key for doing a pageUp
      int mAltPgDownKey = DEFAULT_CXMENU_ALT_PGDOWN_KEY; // Alternate key for doing a pageDown
      int mSearchKey = DEFAULT_CXMENU_SEARCH_KEY;        // Key to use for item searching
      std::string mSearchText;                           // For item searching
      std::string mLastSearchText;                       // For item searching
      bool mClearOnSearch = false;                       // Whether or not to clear the search text
      bool mCaseSensitiveSearch = false;                 // Whether or not searches are case-sensitive
      // mCustomStatus will be true if we're using custom
      //  status text (not the help text for the menu items)
      bool mCustomStatus = false;
      bool mAllowQuit = true;                            // Whether or not to allow the user to quit
      bool mAllowExit = true;                            // Whether or not to allow the user to exit
      bool mSelectableItemExists = false;                // Whether or not a selectable item exists
      bool mWrap = true;                                 // Whether or not to wrap around when scrolling
      bool mWaitForInputIfEmpty = true;                  // Whether or not to get input in showModal()
                                                         // if there are no menu items
      std::vector<long> mReturnCodes;                    // Return codes for the menu items
      std::vector<std::string> mHelpStrings;             // Help strings for the menu items
      std::vector<cxMenuItemType> mItemTypes;            // Stores the type of each menu item
      std::vector<std::string> mAltItemText;             // Alternate text for each item
      // mSubMenus stores submenus for menu items.  The keys to this
      // map are the indexes in mMessageLines that the submenus belong
      // to.
      std::map<int, cxMenu*> mSubMenus;
      std::set<unsigned> mUnselectableItems; // Contains indexes of unselectable items
 
      // Functions to be run at various points in the input loop
      std::shared_ptr<cxFunction> mLoopStartFunction; // At the start of each input loop iteration
      std::shared_ptr<cxFunction> mLoopEndFunction;   // At the end of each input loop iteration
 
      // mOnSelectItemFunction is a function that can be fired when the user
      // selects an item.
      std::shared_ptr<cxFunction> mOnSelectItemFunction;
 
      // mItemHotkeys keeps track of which keys are mapped to which menu items.
      std::multimap<char, int> mItemHotkeys;
      // If there is a hotkey that goes to more than 1 menu item, we
      //  want the user to be able to continue pressing the hotkey to
      //  go to the next item, rather than automatically selecting the
      //  item, which is the default behavior.  mHotkeyIndex keeps
      //  track of the "index" into mItemHotkeys of the current element with
      //  the hotkey that should be checked when the user presses a
      //  hotkey.
      unsigned int mItemHotkeyIndex = 0;
      // Keeps track of the last hotkey that was pressed If different,
      // mItemHotkeyIndex will need to be reset to 0)
      int mLastItemHotkey = NOKEY;
      // mExitWhenLeaveFirst and mExitWhenLeaveLast control whether the menu
      //  will exit the input loop when the user is scrolling through the menu
      //  items and leaves the first or  last menu item, respectively.
      bool mExitWhenLeaveFirst = false;
      bool mExitWhenLeaveLast = false;
      // mRefreshItemsWhenModal controls whether or not the menu items will
      //  be refreshed when showModal() is called.
      bool mRefreshItemsWhenModal = false;
      // mNumParentMenus is incremented when a cxMenu is added to another menu
      //  as a pull-right or pop-up menu.  It is decremented when the menu is
      //  removed.
      int mNumParentMenus = 0;
      // mExitOnOutsideClick: when true, any mouse click outside the menu
      // window will close the menu, even without a parent menu/panel.
      bool mExitOnOutsideClick = false;
      // mLastInputWasMouseEvent will be set true if the last input
      //  was a mouse event in the input loop.
      bool mLastInputWasMouseEvent = false;
 
      // Returns the index of the bottommost item to show in the subwindow.
      //  Note: If there are less items than will fill the menu, this returns
      //  the index of the last item.
      inline int getBottomItemIndex();
 
      // Shows the submenu for the current menu item and returns the
      //  return code returned by the submenu.  Returns -1 if the
      //  current menu item isn't a submenu type.
      inline long doSubmenu();
 
      // Writes a menu item line (from mMessageLines) to the subwindow.
      //  Checks for hotkeys (ampersands), and pads with spaces on the
      //  right so it fills the entire row in the subwindow.
      // pItemIndex: The index of the item (in mMessageLines) to write
      // pSubWinRow: The row in the subwindow to write on
      // pRefreshSubwindow: Whether or not to refresh the subwindow
      // pHighlight: Whether or not to highlight the item
      void drawMenuItem(int pItemIndex, int pSubWinRow, bool pRefreshSubwindow,
                        bool pHighlight = false);
 
      // Scans a string for a hotkey and adds it hotkey to mItemHotkeys, if the
      //  string contains one.
      void addHotKey(const std::string& pItemText);
 
      // Makes sure this window is exactly the size needed to
      //  surround the menu items.
      //void fitToItems();
 
      // Copies the current menu item's help string to the
      //  status string, and optionally updates the status.
      inline void useHelpAsStatus(bool pRefreshStatus = false);
 
      // Goes through the menu items and resizes their text
      //  to make sure they're all exactly the width of the inside of
      //  this window.
      void fitItemsToWidth();
 
      // Makes sure mCurrentItem is a selectable menu item.
      // Parameters:
      //  pForward: If true, go downward.  If false, go upward.
      //  pBringToTop: Whether or not to bring the item to the top
      void goToSelectableItem(bool pForward, bool pBringToTop);
 
      // Handles item searching
      void doSearch();
 
      // Scrolls up one menu item (helper for doInputLoop()).
      //
      // Parameters:
      //  pContinueOn (INOUT): This is the continueOn boolean that is used
      //   in the input loop.
      void scrollUpOne(bool& pContinueOn);
 
      // Scrolls down one menu item (helper for doInputLoop()).
      //
      // Parameters:
      //  pContinueOn (INOUT): This is the continueOn boolean that is used
      //   in the input loop.
      void scrollDownOne(bool& pContinueOn);
 
      // Scrolls up one page
      inline void doPgUp();
 
      // Scrolls down one page
      inline void doPgDown();
 
      // Re-creates the subwindow
      inline void reCreateSubWindow();
 
      // Frees the memory used by the subwindow
      inline void freeSubWindow();
 
      // Updates mSelectableItemExists.  Returns the value of
      //  mSelectableItemExists (to support recursive calls).
      bool lookForSelectableItem();
 
      // For scrolling - Goes to the first menu item
      void doHome();
 
      // For scrolling - Goes to the last menu item
      void doEnd();
 
      // Returns a return code for the currently-selected menu item.  For use
      //  in the input loop when the user presses enter or tab.
      // Parameters:
      //  pLastKey: The last key pressed by the user
      //  pContinueOn: This variable gets set to whether the input loop
      //     should continue on.
      long getCurrentItemReturnCode(const int& pLastKey, bool& pContinueOn);
 
      // Returns the index of the first selectable item.  Returns -1 if there
      //  are no selectable items.
      int firstSelectableItem() const;
 
      // Returns the index of the last selectable item.  Returns -1 if there
      //  are no selectable items.
      int lastSelectableItem() const;
 
      // Makes an item highlighted.  Also uses its help as the status, etc.
      //
      // Parameters:
      //  pItemIndex: The index of the item to highlight
      void highlightItem(int pItemIndex);
 
      // Frees the memory used by mOnSelectItemFunction and sets it to nullptr.
      void freeOnSelectItemFunction();
 
      // Runs the function for when the user selects an item, if one is set.
      //
      // Parameters:
      //  pExitAfterRun (OUT): This will store whether or not the menu should
      //   exit after the function runs.
      // pRunOnLeaveFunction (OUT): This will store whether or not the onLeave
      //  function should run.
      void runOnSelectItemFunction(bool& pExitAfterRun,
                                   bool& pRunOnLeaveFunction);
 
      // This function is used when copying another cxMenu.  It checks the
      //  parameters of the event functions (i.e., mOnSelectItemFunction), and
      //  if any of the parameters of the other menu's event functions point
      //  to the other menu, they will be changed to point to this one.
      //
      // Parameters:
      //  pMenu: Another cxMenu being copied
      void checkEventFunctionPointers(const cxMenu& pMenu);
};
 
} // namespace cx
 
#endif