cxInput.h

Go to the documentation of this file.

// Copyright (c) 2026 E. Oulashin
#ifndef __CXINPUT_H__
#define __CXINPUT_H__
 
// Copyright (c) 2005-2007 Michael H. Kinney
//
// This class represents an input box with
//  a label.
 
#include "cxWindow.h"
#include "cxFunction.h"
#include "cxTextValidator.h"
#include "cxInputOptions.h"
#include "cxColors.h"
#ifdef WANT_TIMEOUT
#include <sys/signal.h> // For sigaction
#endif
#include <string>
#include <map>
#include <set>
#include <memory>
 
// Forward declaration
namespace cx {
 
class cxMultiLineInput;
 
class cxInput : public cxWindow
{
   public:
      explicit cxInput(cxWindow *pParentWindow = nullptr, int pRow = 0,
                       int pCol = 0, int pWidth = DEFAULT_WIDTH,
                       const std::string& pLabel = "",
                       eBorderStyle pBorderStyle = eBS_NOBORDER,
                       eInputOptions pInputOption = eINPUT_EDITABLE,
                       bool pExitOnFull = false, std::string *pExtVal = nullptr);
 
      cxInput(const cxInput& pThatInput);
 
      cxInput(const cxInput& pThatInput, cxMultiLineInput *pParentMLInput);
 
      virtual ~cxInput();
 
      virtual long show(bool pBringToTop = false, bool pShowSubwindows = false) override;
 
      virtual long showModal(bool pShowSelf = true, bool pBringToTop = true,
                             bool pShowSubwindows = false) override;
 
      virtual std::string getLabel() const;
 
      virtual void setLabel(const std::string& pLabel);
 
      virtual void clearValue(bool pRefresh = false);
 
      virtual void clear(bool pRefresh = false) override;
 
      virtual std::string getValue(bool pRemoveLeadingSpaces = false, bool pRemoveTrailingSpaces = false) const;
 
      virtual bool setValue(const std::string& pValue, bool pRefresh = false);
 
      std::string* getExtValue() const;
 
      void setExtValue(std::string *pExtVal, bool pRefresh = false);
 
      bool getExitOnFull() const;
 
      void setExitOnFull(bool pExitOnFull);
 
      bool getExitOnBackspaceAtFront() const;
 
      void setExitOnBackspaceAtFront(bool pExitOnBackspaceAtFront);
 
      bool getExitOnMouseOutside() const override;
 
      void setExitOnMouseOutside(bool pExitOnMouseOutside) override;
 
      bool getExitOnArrowAtBoundary() const;
 
      void setExitOnArrowAtBoundary(bool pExitOnArrowAtBoundary);
 
      bool getMustFill() const;
 
      void setMustFill(bool pMustFill);
 
      bool getMasked() const { return(mMasked); }
 
      void toggleMasking(bool pMasking) { mMasked = pMasking; }
 
      char getMaskChar() const { return(mMaskChar); }
 
      void setMaskChar(char pMaskChar) { mMaskChar = pMaskChar; }
 
      int getInputOption() const;
 
      void setInputOption(eInputOptions pInputOption);
 
      void setValidator(const std::string& pVString);
 
      const std::string& getValidatorStr() const;
 
      int getInputLen() const;
 
      void setCursorX(int pCursorX);
 
      virtual bool move(int pNewRow, int pNewCol, bool pRefresh = true) override;
 
      virtual void resize(int pNewHeight, int pNewWidth, bool pRefresh = true) override;
 
      void setExitOnFKey(bool pExitOnFunctionKey);
 
      virtual bool textIsValid() const;
 
      virtual bool textIsValid(const std::string& pText) const;
 
      void setLabelColor(e_cxColors pColor);
 
      e_cxColors getLabelColor() const;
 
      void setValueColor(e_cxColors pColor);
 
      e_cxColors getValueColor() const;
 
      virtual void setColor(e_WidgetItems pItem, e_cxColors pColor) override;
 
      void toggleCursor(bool pShowCursor);
 
      static std::string clearInput(void* theInput, void* unused);
 
      bool setValidatorFunction(funcPtr4 pFunction, void *p1, void *p2,
                                void *p3, void *p4);
 
      bool setValidatorFunction(funcPtr2 pFunction, void *p1, void *p2);
 
      bool setValidatorFunction(funcPtr0 pFunction);
 
      void clearValidatorFunction();
 
      virtual bool setOnKeyFunction(const std::shared_ptr<cxFunction>& pFunction);
 
      virtual bool setOnKeyFunction(funcPtr4 pFunction, void *p1, void *p2,
                            void *p3, void *p4);
 
      virtual bool setOnKeyFunction(funcPtr2 pFunction, void *p1, void *p2);
 
      virtual bool setOnKeyFunction(funcPtr0 pFunction);
 
      virtual void toggleOnKeyFunction(bool pRunOnKeyFunction);
 
      virtual void clearOnKeyFunction();
 
      virtual bool onKeyFunctionEnabled() const;
 
      virtual bool isFull() const;
 
      virtual int maxValueLen() const;
 
      virtual bool hasFocus() const override;
 
      virtual void setReadOnlyOnLeave(bool pReadOnlyOnLeave);
 
      bool canBeEditable() const;
 
      void setCanBeEditable(bool pCanBeEditable);
 
      virtual void setBorderStyle(eBorderStyle pBorderStyle) override;
 
      virtual void refreshValue(bool pRefresh = true);
 
      void trapNonAssignedFKeys(bool pTrapNonAssignedFKeys);
 
      virtual void enableInputLoop(bool pDoInputLoop);
 
      virtual bool inputLoopEnabled() const;
 
      bool isEditable() const;
 
      virtual bool getCursorLeftAlign() const;
 
      virtual void setCursorLeftAlign(bool pCursorLeftAlign);
 
      virtual void setValidateOnReverse(bool pValidateOnReverse);
 
      virtual bool getValidateOnReverse() const;
 
      virtual void setLastKey(int pLastKey) override;
 
      virtual bool modalGetsKeypress() const override;
 
      virtual bool runOnFocusFunction(std::string *pFunctionRetval = nullptr) override;
 
      virtual cxWindow* getParent() const override;
 
      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 std::string runValidatorFunction() const;
 
      virtual void setTimeout(int pTimeout);
 
      int getTimeout() const;
 
      virtual std::string cxTypeStr() const override;
 
      void setForceUpper(bool pForceUpper);
 
      bool getForceUpper() const;
 
      void setMaxInputLength(int pLength);
 
      int getMaxInputLength() const;
 
      static int inputClearKey;
 
   protected:
      // Attributes for various element (in addition to the ones provided
      //  in cxWindow)
      std::set<attr_t> mLabelAttrs;
      std::set<attr_t> mDataReadonlyAttrs;
      std::set<attr_t> mDataEditableAttrs;
 
      virtual bool handleFunctionForLastKey(bool *pFunctionExists = nullptr,
                                          bool *pRunOnLeaveFunction = nullptr) override;
 
      virtual void enableAttrs(WINDOW *pWin, e_WidgetItems pItem) override;
 
      virtual void disableAttrs(WINDOW *pWin, e_WidgetItems pItem) override;
 
      virtual e_cxColors getItemColor(e_WidgetItems pItem) const override;
 
   private:
      friend class cxMultiLineInput;  // Because that class uses this class
 
      // The following member is set if this input is in a cxMultiLineInput.
      cxMultiLineInput *mParentMLInput = nullptr;
      std::string mValue; // Holds the user's input
      // mName is an alternative means of identifying the input (by name).
      std::string mName;
      // mExtValue points to an "external" location to load/store the user's input
      // (basically, it will be used for user input storage as well as mValue,
      // but the value in this input will always be the what mExtValue contains).
      // If nullptr, then it won't be used.
      std::string *mExtValue;
      int mInputStartX = 0;                 // Starting X cursor position for text input
      int mYPos = 0;                        // Y cursor position for input
      int mInputLen = 0;                    // Valid length of input
      int mRightMax = 0;                    // Rightmost input boundary
      bool mExitOnFull;                     // Whether the input loop should stop when the input is full
      // mExitOnBackspaceAtFront specifies whether the input loop should stop when
      //  backspace is pressed in the first input position.
      bool mExitOnBackspaceAtFront = false;
      bool mExitOnMouseOutside = false;   // Exit input loop on mouse click outside this window
      bool mExitOnArrowAtBoundary = false; // Exit on left arrow at pos 0 or right arrow at end of text
      bool mMustFill = false;               // Whether or not the user must fill the entire field
      bool mMasked = false;                 // Whether or not the field is masked (i.e. for a password)
      char mMaskChar = '*';                 // The character to display for character masking
      cxTextValidator mValidator;           // For use with text validation
      eInputOptions mInputOption;           // Specifies normal, read-only, etc.
      bool mExitOnFunctionKey = false;      // Whether or not to exit on function key press.
      bool mHasFocus = false;               // Whether or not focus is set
      // mReadOnlyOnLeave stores whether or not the input should go read-only
      //  when setFocus() finishes.
      bool mReadOnlyOnLeave = false;
      bool mCanBeEditable = true;           // Whether or not the input can be editable
      bool mJustStartedFocus = false;       // True immediately when focus is set
      // If mTrapNonAssignedFKeys is true, function keys that aren't
      //  assigned to anything won't cause the input to exit its
      //  input loop.
      bool mTrapNonAssignedFKeys = false;
      bool mDoInputLoop = true; // Whether or not to run the input loop on focus
      // mCursorAfterInput specifies whether to place the cursor after the
      //  input text when showing the input.
      bool mCursorAfterInput = true;
 
      // Function to be run when a key is pressed
      std::shared_ptr<cxFunction> mOnKeyFunction; // Function to be run when a key is pressed
      bool mRunOnKeyFunction = true;              // Whether or not to run the onKey function
      // Function to be run to validate the text before focus is lost
      std::shared_ptr<cxFunction> mValidatorFunction;
      short mValueColorPair;
      bool mShowCursor = true;              // Whether or not to show the cursor
      // Whether or not to run the validator function when the user is
      //  navigating in reverse (i.e., with the up arrow or shift-tab).
      bool mValidateOnReverse = true;
      bool mForceUpper = false;             // Convert letters to upper-case
      int mMaxInputLength = 0;              // Maximum length of text input (0 = unlimited)
      int mScrollOffset = 0;               // Index of first visible character in mValue (for scrolling)
      int mCursorPos = 0;                  // Cursor position within mValue (0-based index)
 
      // Returns the text entered in the window, from mInputStartX (inclusive)
      //  to a given horizontal position (exclusive), as a string.
      //
      // Parameters:
      //  pValue: This is where the text will be stored.
      //  pX: The current horizontal position of the cursor.
      //  pCheckPrintable: Whether or not to check whether the last key
      //   pressed is a printable character before grabbing the value.
      //   Defaults to true.
      void getInputText(std::string& pValue, int pX, bool pCheckPrintable = true);
 
      // Performs a 'backspace' behavior.  This was written as a facilitator for
      //  setFocus().
      // Parameters:
      //  y: The current vertical cursor position
      //  x: The current horizontal cursor position
      //  prevInput: The last contents of the input
      inline void doBackspace(int y, int x, std::string& prevInput);
 
      // Redraws the visible portion of mValue in the ncurses window,
      // accounting for mScrollOffset. Pads with spaces to fill mInputLen.
      void redrawVisibleValue();
 
      // Adjusts mScrollOffset so that mCursorPos is visible within the
      // display area (mInputLen characters wide).
      void ensureCursorVisible();
 
      // Enables the attributes in mValueAttrs.
      inline void enableValueAttrs();
 
      // Disables the attributes in mValueAttrs.
      inline void disableValueAttrs();
 
      // Handles the input loop.  Returns cxID_QUIT or cxID_EXIT,
      //  depending on what happens when the user exits the input.
      // Parameters:
      //  x: The current horizontal position of the cursor
      //  y: The current vertical position of the cursor
      //  rightLimit: The rightmost limit of the cursor position (inclusive)
      //  updatePrevInput: Whether or not to update the previous input value
      //  prevInput: The previous input value
      long doInputLoop(int x, int y, int rightLimit,
                       bool updatePrevInput, std::string& prevInput);
 
      // Adds a key to the list of keys that will stop the input
      //  loop.
      void addStopKey(int pKey);
 
      // Disable the use of setHotkeyHighlighting from the
      //  outside.
      virtual void setHotkeyHighlighting(bool pMessageUnderlines) override;
 
      // Fills mWindow with the current window text, but does not actually
      //  show it.
      virtual void draw() override;
 
#ifdef WANT_TIMEOUT
      // mTimeout is the length of time (in seconds) for the input to be idle
      //  before exiting the input loop.  mTimeoutSigaction is a struct that
      //  specifies the timeout function to call.
      int mTimeout = 0;
      struct sigaction mTimeoutSigaction;
 
      // This function will get called upon idle timeout.  (This function will
      //  get set up for the SIGALRM signal; pSignal is there because signal
      //  functions need to have that particular signature (void return type,
      //  and an int parameter)).  This function will call exitNow() on the
      //  input.
      static void idleTimeoutHandler(int pSignal);
#endif
 
      // Runs the function pointed to by mOnKeyFunction, and returns the return
      //  value of the function.
      std::string runOnKeyFunction() const;
 
      // This is for copying a cxInput - This copies one of the cxFunction
      //  pointers (mOnKeyFunction, mValidatorFunction) from the other input.
      //
      // Parameters:
      //  pThatInput: The cxInput being copied
      //  pDestFunc: The cxFunction pointer being copied into (mOnKeyFunction
      //   or mValidatorFunction) - This is a reference to a cxFunction*,
      //   so mOnKeyFunction or mValidatorFunction can be passed to this
      //   method without any funky syntax.
      //  pSrcFunc: The cxFunction pointer being copied from
      //   (pThatInput.mOnKeyFunction or pThatInput.mValidatorFunction)
      //
      // An example function call:
      //  copyCxFunction(pThatInput, mOnKeyFunction, pThatInput.mOnKeyFunction);
      void copyCxFunction(const cxInput& pThatInput, /*OUT*/std::shared_ptr<cxFunction>& pDestFunc,
                          /*IN*/const std::shared_ptr<cxFunction>& pSrcFunc);
 
      // Returns whether or not the validator function is set (if
      //  mValidatorFunction is not nullptr and if its function pointer is set)
      bool validatorFunctionIsSet() const;
 
};
 
 
} // namespace cx
 
#endif