• Introduction
• How To Build
  • Integrate Sources
  • Dynamic Link Library
• Creating
  • Classic Approach
  • In Dialog
  • CreateHexCtrl
• Setting Data
• Virtual Data Mode
• Virtual Bookmarks
• Custom Colors
• Templates
• Methods
  Expand

  • ClearData
  • Create
  • CreateDialogCtrl
  • Delete
  • DestroyWindow
  • ExecuteCmd
  • GetActualWidth
  • GetBookmarks
  • GetCacheSize
  • GetCapacity
  • GetCaretPos
  • GetCharsExtraSpace
  • GetCodepage
  • GetColors
  • GetData
  • GetDataSize
  • GetDateInfo
  • GetDlgItemHandle
  • GetFont
  • GetGroupSize
  • GetMenuHandle
  • GetOffset
  • GetPagesCount
  • GetPagePos
  • GetPageSize
  • GetScrollRatio
  • GetSelection
  • GetTemplates
  • GetUnprintableChar
  • GetWndHandle
  • GoToOffset
  • HasInfoBar
  • HasSelection
  • HitTest
  • IsCmdAvail
  • IsCreated
  • IsDataSet
  • IsHexCharsUpper
  • IsMutable
  • IsOffsetAsHex
  • IsOffsetVisible
  • IsVirtual
  • ModifyData
  • PreTranslateMsg
  • Redraw
  • SetCapacity
  • SetCaretPos
  • SetCharsExtraSpace
  • SetCodepage
  • SetColors
  • SetConfig
  • SetData
  • SetDateInfo
  • SetDlgProperties
  • SetFont
  • SetGroupSize
  • SetHexCharsCase
  • SetMutable
  • SetOffsetMode
  • SetPageSize
  • SetRedraw
  • SetScrollRatio
  • SetSelection
  • SetUnprintableChar
  • SetVirtualBkm
  • SetWindowPos
  • ShowInfoBar
• Structures
  Expand

  • HEXBKM
  • HEXBKMINFO
  • HEXCOLOR
  • HEXCOLORINFO
  • HEXCOLORS
  • HEXCREATE
  • HEXDATA
  • HEXDATAINFO
  • HEXHITTEST
  • HEXMENUINFO
  • HEXMODIFY
  • HEXSPAN
  • HEXVISION
• Interfaces
  Expand

  • IHexBookmarks
  • IHexTemplates
  • IHexVirtColors
  • IHexVirtData
• Enums
  Expand

  • EHexCmd
  • EHexDataType
  • EHexModifyMode
  • EHexOperMode
  • EHexWnd
• Notification Messages
  Expand

  • HEXCTRL_MSG_BKMCLICK
  • HEXCTRL_MSG_CONTEXTMENU
  • HEXCTRL_MSG_DESTROY
  • HEXCTRL_MSG_DLGBKMMGR
  • HEXCTRL_MSG_DLGCODEPAGE
  • HEXCTRL_MSG_DLGDATAINTERP
  • HEXCTRL_MSG_DLGGOTO
  • HEXCTRL_MSG_DLGMODIFY
  • HEXCTRL_MSG_DLGSEARCH
  • HEXCTRL_MSG_DLGTEMPLMGR
  • HEXCTRL_MSG_MENUCLICK
  • HEXCTRL_MSG_SETCAPACITY
  • HEXCTRL_MSG_SETCARET
  • HEXCTRL_MSG_SETCODEPAGE
  • HEXCTRL_MSG_SETDATA
  • HEXCTRL_MSG_SETFONT
  • HEXCTRL_MSG_SETGROUPSIZE
  • HEXCTRL_MSG_SETSELECTION
• Licensing

HexCtrl is the fully-featured Hex Control written in pure Win32 API.

• View and edit data up to 16EB (exabyte)
• Two working modes: Memory and Virtual Data Mode
• Fully-featured Bookmarks Manager
• Fully-featured Search and Replace
• Fully-featured Data Interpreter
• Grouping data with arbitrary group size
• Changeable codepage for the text area
• Many options to Copy/Paste to/from clipboard
• Modify data with Filling and many predefined Operations options
• Undo/Redo
• Ability to visually divide data into pages
• Print whole document/pages range/selection
• Customizable colors for data with Custom Colors
• Powerful system of Templates
• Assignable keyboard shortcuts via external config file
• Customizable look and appearance, font, colors
• High-DPI compliant
• Utilizes AVX/AVX2 instruction set for best performance
• Supports compiling for the ARM64 architecture
• Written with the /std:c++20 standard conformance

git clone https://github.com/jovibor/HexCtrl.git

To build HexCtrl from the sources:

1. Add all files from the HexCtrl folder into your project
2. Make sure to disable Precompiled Header usage for all *.ixx files in the project
3. Add #include "HexCtrl.h"
4. Declare HexCtrl object: auto myHex { HEXCTRL::CreateHexCtrl() };
5. Create control instance

To build and use HexCtrl as a DLL:

1. Build HexCtrl{x86/x64/ARM64}.dll and HexCtrl{x86/x64/ARM64}.lib with the HexCtrl DLL.vcxproj project
2. Include HexCtrl.h into your project
3. Add /DHEXCTRL_DYNAMIC_LIB compiler option, or alternatively #define it before including HexCtrl.h:

   #define HEXCTRL_DYNAMIC_LIB
   #include "HexCtrl.h"

4. Declare IHexCtrlPtr object: auto myHex { HEXCTRL::CreateHexCtrl() };
5. Create control instance

First you need to create HexCtrl object:

auto myHex { HEXCTRL::CreateHexCtrl() };

Then call the Create method, which takes the HEXCREATE struct with the all necessary information for the HexCtrl creation. The HEXCREATE::dwStyle and dwExStyle are window and extended window styles respectively, set these styles according to your needs. For all available options see the HEXCREATE struct description.

To use HexCtrl in a Dialog you can create it with the Classic Approach: call Create method and provide all the necessary information.
But there is another option:

1. Put the Custom Control from the Toolbox in Visual Studio dialog designer onto your dialog template.
   
2. In the Properties of this control in the Class field within the Misc section write: HexCtrl_MainWnd.
3. Declare IHexCtrlPtr member variable within your dialog class:

   HEXCTRL::IHexCtrlPtr m_myHex { CreateHexCtrl() };

4. Call the CreateDialogCtrl method from dialog’s OnInitDialog method.

   BOOL CMyDialog::OnInitDialog() {
       CDialogEx::OnInitDialog();
       m_myHex->CreateDialogCtrl(IDC_MY_HEX, m_hWnd);
   }

[[nodiscard]] IHexCtrlPtr CreateHexCtrl();

This is the main factory function for creating HexCtrl object. The IHexCtrlPtr class is a IHexCtrl interface pointer wrapped into a standard std::unique_ptr with custom deleter, so you don’t need to worry about its destruction.

To set a data for the HexCtrl the SetData method is used. The code below shows how to construct HexCtrl object and display first 0x1FF bytes of the current app’s memory:

IHexCtrlPtr myHex { CreateHexCtrl() };

HEXCREATE hcs;
hcs.hWndParent = m_hWnd;
hcs.rect = {0, 0, 600, 400}; //Window rect.
myHex->Create(hcs);

HEXDATA hds;
hds.spnData = { reinterpret_cast<std::byte*>(GetModuleHandle(nullptr)), 0x1FF };
myHex->SetData(hds);

The next example shows how to display std::string‘s text as hex data:

std::string str = "My string";
HEXDATA hds;
hds.spnData = { reinterpret_cast<std::byte*>(str.data()), str.size() };
myHex->SetData(hds);

Besides the standard mode, when the HexCtrl just holds a pointer to a data in a memory, it can also work in the Virtual mode. This mode can be useful in cases where you need to display a very large amount of a data that can’t fit in the memory all at once.

If HEXDATA::pHexVirtData pointer is set, then the whole data routine will be done through it. This pointer is of IHexVirtData class type, which is a pure abstract base class. You have to derive your own class from it and implement all its public methods. Then provide a pointer to the created object of this derived class through the HEXDATA::pHexVirtData member, prior to call the SetData method.

HexCtrl has innate functional to work with any amount of bookmarked regions. These regions can be assigned with individual background and text colors and description.

But if you have big and complicated data logic and want to handle all these bookmarks yourself, you can do it with the help of the Virtual Bookmarks mode. In this mode all bookmark’s burden is handled by yourself, by implementing the IHexBookmarks interface and providing pointer to this implementation to the HexCtrl by calling the SetVirtualBkm method.

If you’d like to colorize data regions with your own custom colors, use the IHexVirtColors interface.

To use it set the HEXDATA::pHexVirtColors member to a valid instance of your own class that implements this interface, prior to calling the SetData method.

The OnHexGetColor method of this interface takes HEXCOLORINFO struct as an argument. The HEXCOLORINFO::ullOffset member indicates the offset for which the color is requested. This method should return true if it sets custom colors for the given offset or false for default colors.

HexCtrl‘s templates is a powerful system of a data structures’ description with a simple .json file. These files can be loaded through the HexControl‘s internal template manager, or through the API.

{
    "$schema": "https://raw.githubusercontent.com/jovibor/HexCtrl/master/docs/HexCtrl.Templates.Schema.json",
    "TemplateName": "SampleTemplate",
    "Data": {
        "endianness": "little",
        "clrBk": "#999999",
        "clrText": "#FFFFFF",
        "Fields": [
            {
                "name": "MyCustomDataSingle",
                "type": "MyCustomType"
            },
            {
                "name": "CustomComplexData",
                "type": "MyCustomComplexType"
            },
            {
                "name": "ArrayOfDWORDs",
                "type": "DWORD",
                "array": 10
            },
            {
                "name": "MyCustomDataArray",
                "type": "MyCustomType",
                "array": 4
            }
        ]
    },
    "CustomTypes": [
        {
            "TypeName": "MyCustomType",
            "Fields": [
                {
                    "name": "myCustomTypeField1",
                    "type": "DWORD"
                },
                {
                    "name": "myCustomTypeField2",
                    "type": "DWORD"
                }
            ]
        },
        {
            "TypeName": "MyCustomComplexType",
            "Fields": [
                {
                    "name": "MyCustomTypeData1",
                    "type": "MyCustomType"
                },
                {
                    "name": "MyCustomTypeData2",
                    "type": "MyCustomType"
                }
            ]
        }
    ]
}

Every such file contains the following properties:

• TemplateName [mandatory, string] – the name of the template
• Data [mandatory, object] – main object that contains all template field’s information
• CustomTypes [optional, array] – array of a user defined types, that can be then referenced in the type property of the Fields

CustomTypes objects are the same as Fields objects, the only difference is the TypeName property which Fields objects don’t have.

Every Data or CustomType object contains Fields property with actual struct members.

Fields [array] – is an array of objects where every object represents a struct data member. Any such object can have its own Fields sub-objects, which will represent nested structs.
The Fields‘s properties include:

• name – [mandatory, string] – name of the field
• description – [optional, string] – field description
• type – [optional, string] – field type, such as:
  bool, char, unsigned char, byte, short, unsigned short, WORD, long, unsigned long, int, unsigned int, DWORD, long long, unsigned long long, QWORD, float, double, time32_t, time64_t, FILETIME, SYSTEMTIME, GUID, or any custom type defined in the CustomTypes section
• size – [optional, int] – size of the field in bytes, if the type field is not provided
• array – [optional, int] – size of the array, if the given field is an array of fields
• endianness – [optional, string] – field endianness, “little” or “big”. By default all fields are little-endian.
• clrBk – [optional, string] – field background color
• clrText – [optional, string] – field text color

The endianness, clrBk and clrText properties that locate at the same level as the Fields property, would mean the default properties for all the Fields objects of that level and below the line, unless they explicitly redefined in the field itself.

For the available templates check the Templates directory.

The HexCtrl has plenty of methods that you can use to manage its behavior.

void ClearData();

Clears data from the HexCtrl view, not touching data itself.

bool Create(const HEXCREATE& hcs);

Main initialization method. Takes the HEXCREATE struct as argument. Returns true if created successfully, false otherwise.

bool CreateDialogCtrl(UINT uCtrlID, HWND hwndDlg);

Creates HexCtrl from a Custom Control dialog’s template. Takes control id, and dialog’s window handle as arguments. See Creating section for more info.

void Delete();

Deletes the HexCtrl object. You only use this method if you want, for some reason, to manually delete the HexCtrl object, otherwise IHexCtrlPtr will invoke this method automatically.

void DestroyWindow();

Destroys the HexCtrl main window.

void ExecuteCmd(EHexCmd eCmd)const;

Executes one of the predefined commands of the EHexCmd enum. All these commands are basically replicating HexCtrl‘s inner menu.

[[nodiscard]] auto GetActualWidth()const->int;

Returns the width of the HexCtrl bounding rectangle, i.e. the width of the drawn working area.

[[nodiscard]] auto GetBookmarks()->IHexBookmarks*;

Returns pointer to the IHexBookmarks interface, which responds for the bookmarks machinery.

[[nodiscard]] auto GetCacheSize()const->DWORD;

Returns current cache size set in HEXDATA.

[[nodiscard]] auto GetCapacity()const->DWORD;

Returns current capacity.

[[nodiscard]] auto GetCaretPos()const->ULONGLNG;

Retrieves current caret position offset.

[[nodiscard]] auto GetCharsExtraSpace()const->DWORD;

Get extra space between chars, in pixels. This extra space can be set with the SetCharsExtraSpace method.

[[nodiscard]] auto GetColors()const->const HEXCOLORS&;

Returns reference to the current HEXCOLORS struct.

[[nodiscard]] auto GetData(HEXSPAN hss)const->std::byte*;

Returns a pointer to the data offset no matter what mode the control works in.

[[nodiscard]] auto GetDataSize()const->ULONGLONG;

Returns currently set data size.

[[nodiscard]] auto GetDateInfo()const->std::tuple<DWORD, wchar_t>;

Returns tuple of the current date format-ordering specifier, and date separator.

[[nodiscard]] auto GetDlgItemHandle(EHexDlgItem eItem)const->HWND;

Returns HWND of a dialog’s internal child control.

[[nodiscard]] auto GetCodepage()const->int;

Returns code page that is currently in use.

[[nodiscard]] auto GetFont(bool fMain)const->LOGFONTW;

Returns current main font if fMain is true, and infobar font if fMain is false.

[[nodiscard]] auto GetGroupSize()const->DWORD;

Returns current data grouping size.

[[nodiscard]] auto GetMenuHandle()const->HMENU;

Returns the HMENU handle of the HexCtrl context menu. You can use this handle to customize menu for your needs.
HexCtrl‘s internal menu uses IDs starting from 0x8001. So if you wish to add your own new menu, assign menu ID starting from 0x9000 to not interfere.
When a user clicks custom menu, control sends WM_NOTIFY message to its parent window with LPARAM pointing to HEXMENUINFO with its hdr.code member set to HEXCTRL_MSG_MENUCLICK, and wMenuID field containing ID of the menu clicked.

[[nodiscard]] auto GetOffset(ULONGLONG ullOffset, bool fGetVirt)const->ULONGLONG;

Converts offset from virtual to flat, and vice versa.

[[nodiscard]] auto GetPagesCount()const->ULONGLONG;

Returns current count of pages set by the SetPageSize method.

[[nodiscard]] auto GetPagePos()const->ULONGLONG;

Returns a page number that the cursor stays at.

[[nodiscard]] auto GetPageSize()const->DWORD;

Returns current page size set by the SetPageSize method.

[[nodiscard]] auto GetScrollRatio()const->std::tuple<float, bool>;

Returns tuple of the current scroll ratio and fLines flag set by the SetScrollRatio method.

[[nodiscard]] auto GetSelection()const->std::vector<HEXSPAN>;

Returns std::vector with the offsets and sizes of the current selection.

[[nodiscard]] auto GetTemplates()->IHexTemplates*;

Returns pointer to the internal IHexTemplates interface that is responsible for templates machinery.

[[nodiscard]] auto GetUnprintableChar()const->wchar_t;

Returns replacement char for unprintable characters.

[[nodiscard]] auto GetWndHandle(EHexWnd eWnd, bool fCreate = true)const->HWND;

Returns HWND for HexCtrl‘s main window or one of its internal dialogs. If fCreate flag is true, the dialog window will be created first before returning, if it was not already.

void GoToOffset(ULONGLONG ullOffset, int iPosAt = 0);

Go to the given offset. The second argument iPosAt can take three values:

• -1 – offset will appear at the top line
•   0 – offset will appear in the center
•   1 – offset will appear at the bottom line

[[nodiscard]] bool HasInfoBar()const;

Shows whether bottom info bar currently visible or not.

[[nodiscard]] bool HasSelection()const;

Returns true if HexCtrl has any area selected.

[[nodiscard]] auto HitTest(POINT pt, bool fScreen = true)const->std::optional<HEXHITTEST>;

Hit testing of given point in a screen fScreen = true, or client fScreen = false coordinates. In case of success returns HEXHITTEST structure.

[[nodiscard]] bool IsCmdAvail(EHexCmd eCmd)const;

Returns true if the given command can be executed at the moment, false otherwise.

[[nodiscard]] bool IsCreated()const;

Shows whether HexCtrl is created or not.

[[nodiscard]] bool IsDataSet()const;

Shows whether a data was set to HexCtrl or not

[[nodiscard]] bool IsHexCharsUpper()const;

Shows if hex chars printed in UPPER or lower case.

[[nodiscard]] bool IsMutable()const;

Shows whether HexCtrl is currently in edit mode or not.

[[nodiscard]] bool IsOffsetAsHex()const;

Is “Offset” currently represented (shown) as Hex or as Decimal. It can be changed by double clicking at offset area.

[[nodiscard]] auto IsOffsetVisible(ULONGLONG ullOffset)const->HEXVISION;

Checks for offset visibility and returns HEXVISION as a result.

[[nodiscard]] bool IsVirtual()const;

Returns true if HexCtrl currently works in Virtual Data Mode.

void ModifyData(const HEXMODIFY& hms);

Modify data currently set in HexCtrl, see the HEXMODIFY struct for details.

[[nodiscard]] bool PreTranslateMsg(MSG* pMsg);

The HexCtrl has many internal dialog windows. In order for dialog keyboard navigation to work correctly, this method must be hooked into your app’s main message loop before TranslateMessage and DispatchMessage, or into MFC’s PreTranslateMessage virtual function.

while (GetMessageW(&msg, nullptr, 0, 0)) {
    if (!TranslateAcceleratorW(msg.hwnd, hAccelTable, &msg)) {
        if (!m_pHexCtrl->PreTranslateMsg(&msg)) { //Process further only if it returns false.
            TranslateMessage(&msg);
            DispatchMessageW(&msg);
        }
    }
}

If this method returns true it means that no further message processing should be made, HexCtrl has done all processing by itself.

void Redraw();

Redraws main window.

void SetCapacity(DWORD dwCapacity);

Sets HexCtrl‘s current capacity.

void SetCaretPos(ULONGLONG ullOffset, bool fHighLow = true, bool fRedraw = true);

Sets the caret to the given offset. The fHighLow flag shows which part of the hex chunk, low or high, a caret must be set to.

void SetCharsExtraSpace(DWORD dwSpace);

Sets extra space to add between chars, in pixels.

void SetCodepage(int iCodePage);

Sets the code page for the HexCtrl‘s text area. Takes code page identifier as an argument, or -1 for default ASCII-only characters.

void SetColors(const HEXCOLORS& clr);

Sets all the colors for the control. Takes HEXCOLORS as the argument.

bool SetConfig(std::wstring_view wsvPath);

Sets the path to a JSON config file with keybindings to use in HexCtrl, or empty path (L"") for default. This file is using EHexCmd enum values as keys and strings array as values:

{
    "CMD_DLG_SEARCH": [ "ctrl+f", "ctrl+h" ],
    "CMD_SEARCH_NEXT": [ "f3" ],
    "CMD_SEARCH_PREV": [ "shift+f3" ]
}

For default values see the IDR_HEXCTRL_JSON_KEYBIND.json file from the project sources.

void SetData(const HEXDATA& hds, bool fAdjust = false)

Main method to set data for HexCtrl. It takes HEXDATA struct as an argument.
The fAdjust flag when set to true allows adjusting already set data. For example to switch between virtual and normal data modes.

void SetDateInfo(DWORD dwFormat, wchar_t wchSepar);

Sets date format-ordering specifier, along with date separator.

void SetDlgProperties(EHexWnd eWnd, std::uint64_t u64Flags);

Sets various properties to the HexCtrl‘s internal dialogs, in form of flags. Flags can be combined together with the OR (|) operation.
Available flags:

HEXCTRL_FLAG_DLG_NOESC //Prevent dialog from closing on Esc key.

void SetFont(const LOGFONTW& lf, bool fMain);

Sets new main font for the HexCtrl if fMain is true, or infobar font when fMain is false. This font has to be monospaced.

void SetGroupSize(DWORD dwSize);

Sets current data grouping size in bytes.

void SetHexCharsCase(bool fUpper);

Sets printed hex chars to an UPPER or lower case.

void SetMutable(bool fMutable);

Enables or disables mutable mode. In the mutable mode all the data can be modified.

void SetOffsetMode(bool fHex);

Sets offset area being shown as Hex (fHex=true) or as Decimal (fHex=false).

void SetPageSize(DWORD dwSize, std::wstring_view wsvName = L"Page");

Sets the size of the page to draw the divider line between. This size should be multiple to the current capacity size to take effect. The second argument sets the name to be displayed in the bottom info area of the HexCtrl (“Page”, “Sector”, etc…).
To remove the divider just set dwSize to 0.

void SetRedraw(bool fRedraw);

Should the main HexCtrl window be redrawn or not. E.g. should the WM_PAINT message be handled or not.

void SetScrollRatio(float flRatio, bool fLines);

Sets the scroll amount for one scroll-page. Page is the one mouse-wheel tick or page-down key. When fLines is true the flRatio is the amount of text lines to scroll. When it’s false flRatio is a ratio of visible screen height to scroll.

void SetSelection(const std::vector<HEXSPAN>& vecSel, bool fRedraw = true, bool fHighlight = false);

Sets current selection or highlight in the selection, if fHighlight is true.

void SetUnprintableChar(wchar_t wch);

Sets replacement char for unprintable characters.

void SetVirtualBkm(IHexBookmarks* pVirtBkm);

Sets a pointer for the Virtual Bookmarks mode, or disables this mode if nullptr is set.

void SetWindowPos(HWND hWndAfter, int iX, int iY, int iWidth, int iHeight, UINT uFlags);

Sets HexCtrl window position. This method replicates behavior of the SetWindowPos Windows function.

void ShowInfoBar(bool fShow);

Show/hide bottom Info bar.

Below are listed all HexCtrl‘s structures.

Main bookmarks structure, used with the IHexBookmarks interface.

struct HEXBKM {
    VecSpan      vecSpan;     //Vector of offsets and sizes.
    std::wstring wstrDesc;    //Bookmark description.
    ULONGLONG    ullID { };   //Bookmark ID, assigned internally by framework.
    ULONGLONG    ullData { }; //User defined custom data.
    HEXCOLOR     stClr;       //Bookmark bk/text color.
};
using PHEXBKM = HEXBKM*;

The member vecSpan is of a std::vector<HEXSPAN> type because a bookmark may have few non adjacent areas. For instance, when selection is made as a block, with Alt pressed.

Bookmark information struct.

struct HEXBKMINFO {
    NMHDR   hdr { };  //Standard Windows header.
    PHEXBKM pBkm { }; //Bookmark pointer.
};
using PHEXBKMINFO = HEXBKMINFO*;

Background and Text color struct.

struct HEXCOLOR {
    COLORREF clrBk { };   //Bk color.
    COLORREF clrText { }; //Text color.
    auto operator<=>(const HEXCOLOR&)const = default;
};
using PHEXCOLOR = HEXCOLOR*;

Struct for hex chunks’ color information.

struct HEXCOLORINFO {
    NMHDR     hdr { };       //Standard Windows header.
    ULONGLONG ullOffset { }; //Offset for the color.
    HEXCOLOR  stClr;         //Colors of the given offset.
};

This structure contains all colors for fonts, background, and all other visual stuff. All these colors have their default values, so you don’t have to set them all during HexCtrl creation, if you don’t want to.

struct HEXCOLORS {
    COLORREF clrFontHex { ::GetSysColor(COLOR_WINDOWTEXT) };       //Hex-chunks font color.
    COLORREF clrFontText { ::GetSysColor(COLOR_WINDOWTEXT) };      //Text font color.
    COLORREF clrFontSel { ::GetSysColor(COLOR_HIGHLIGHTTEXT) };    //Selected hex/text font color.
    COLORREF clrFontBkm { ::GetSysColor(COLOR_WINDOWTEXT) };       //Bookmarks font color.
    COLORREF clrFontDataInterp { ::GetSysColor(COLOR_HIGHLIGHTTEXT) }; //Data Interpreter text/hex font color.
    COLORREF clrFontCaption { RGB(0, 0, 180) };                    //Caption font color
    COLORREF clrFontInfoParam { ::GetSysColor(COLOR_WINDOWTEXT) }; //Font color of the Info bar parameters.
    COLORREF clrFontInfoData { RGB(0, 0, 180) };                   //Font color of the Info bar data.
    COLORREF clrFontCaret { ::GetSysColor(COLOR_HIGHLIGHTTEXT) };  //Caret font color.
    COLORREF clrBk { ::GetSysColor(COLOR_WINDOW) };                //Background color.
    COLORREF clrBkSel { ::GetSysColor(COLOR_HIGHLIGHT) };          //Background color of the selected Hex/Text.
    COLORREF clrBkBkm { RGB(240, 240, 0) };                        //Bookmarks background color.
    COLORREF clrBkDataInterp { RGB(147, 58, 22) };                 //Data Interpreter Bk color.
    COLORREF clrBkInfoBar { ::GetSysColor(COLOR_3DFACE) };         //Background color of the bottom Info bar.
    COLORREF clrBkCaret { RGB(0, 0, 255) };                        //Caret background color.
    COLORREF clrBkCaretSel { RGB(0, 0, 200) };                     //Caret background color in selection.
    COLORREF clrLinesMain { ::GetSysColor(COLOR_SCROLLBAR) };      //Main window and pages lines color.
    COLORREF clrLinesTempl { ::GetSysColor(COLOR_WINDOWTEXT) };    //Templates data confining lines color.
    COLORREF clrScrollBar { ::GetSysColor(COLOR_3DFACE) };         //Scrollbar color.
    COLORREF clrScrollThumb { ::GetSysColor(COLOR_SCROLLBAR) };    //Scrollbar thumb color.
    COLORREF clrScrollArrow { ::GetSysColor(COLOR_GRAYTEXT) };     //Scrollbar arrow color.
};
using PCHEXCOLORS = const HEXCOLORS*;

The main initialization struct used for the HexCtrl creation.

struct HEXCREATE {
    HINSTANCE       hInstRes { };           //Hinstance of the HexCtrl resources, nullptr for current module.
    HWND            hWndParent { };         //Parent window handle.
    PCHEXCOLORS     pColors { };            //HexCtrl colors, nullptr for default.
    const LOGFONTW* pLogFont { };           //Monospaced font for HexCtrl, nullptr for default.
    RECT            rect { };               //Initial window rect.
    UINT            uID { };                //Control ID if it's a child window.
    DWORD           dwStyle { };            //Window styles.
    DWORD           dwExStyle { };          //Extended window styles.
    DWORD           dwCapacity { 16UL };    //Initial capacity size.
    DWORD           dwGroupSize { 1UL };    //Initial data grouping size.
    float           flScrollRatio { 1.0F }; //Either a screen-ratio or lines amount to scroll with Page-scroll (mouse-wheel).
    bool            fScrollLines { false }; //Treat flScrollRatio as screen-ratio (false) or as amount of lines (true).
    bool            fInfoBar { true };      //Show bottom Info bar or not.
    bool            fOffsetHex { true };    //Show offset digits as Hex or Decimal.
    bool            fCustom { false };      //If it's a custom control in a dialog.
};

HINSTANCE hInstRes

The hInstRes member allows you to provide an alternative HINSTANCE of a module where all HexCtrl resources (dialogs, menu, etc…) reside. By default HexCtrl uses its current module, whether it’s a .exe or .dll.

DWORD dwStyle

Standard window style for the main HexCtrl window.

DWORD dwExStyle

Standard extended window style for the main HexCtrl window.

The main struct to set a data to display in the HexCtrl.

struct HEXDATA {
    SpanByte        spnData;                    //Data span to display.
    IHexVirtData*   pHexVirtData { };           //Pointer for VirtualData mode.
    IHexVirtColors* pHexVirtColors { };         //Pointer for Custom Colors class.
    ULONGLONG       ullMaxVirtOffset { };       //Maximum virtual offset.
    DWORD           dwCacheSize { 0x800000UL }; //Data cache size for VirtualData mode.
    bool            fMutable { false };         //Is data mutable or read-only.
    bool            fHighLatency { false };     //Do not redraw until scroll thumb is released.
};

ULONGLONG ullMaxVirtOffset

Used to set maximum virtual data offset in virtual data mode. This is needed for the offset digits amount calculation.

Struct for a data information used in IHexVirtData.

struct HEXDATAINFO {
    NMHDR    hdr { };   //Standard Windows header.
    HEXSPAN  stHexSpan; //Offset and size of the data.
    SpanByte spnData;   //Data span.
};

Structure is used in HitTest method.

struct HEXHITTEST {
    ULONGLONG ullOffset { };     //Offset.
    bool      fIsText { false }; //Is cursor at Text or Hex area.
    bool      fIsHigh { false }; //Is it High or Low part of the byte.
};

This struct is used to represent data modification parameters.
When eModifyMode is set to MODIFY_ONCE, bytes from pData just replace corresponding data bytes as is.
If eModifyMode is equal to MODIFY_REPEAT then block by block replacement takes place few times.
For example, if:

• SUM(vecSpan.ullSize) == 9
• spnData.size() == 3
• eModifyMode is set to MODIFY_REPEAT
• bytes in memory at vecSpan.ullOffset are 010203040506070809
• bytes pointed to by spnData.data() are 030405

then, after modification, bytes at vecSpan.ullOffset will become 030405030405030405.

If eModifyMode is equal to the MODIFY_OPERATION then the eOperMode shows what kind of operation must be performed on the data.

struct HEXMODIFY {
    EHexModifyMode eModifyMode { };      //Modify mode.
    EHexOperMode   eOperMode { };        //Operation mode, used if eModifyMode == MODIFY_OPERATION.
    EHexDataType   eDataType { };        //Data type of the underlying data, used if eModifyMode == MODIFY_OPERATION.
    SpanCByte      spnData;              //Span of the data to modify with.
    VecSpan        vecSpan;              //Vector of data offsets and sizes to modify.
    bool           fBigEndian { false }; //Treat data as the big endian, used if eModifyMode == MODIFY_OPERATION.
};

Menu information struct.

struct HEXMENUINFO {
    NMHDR hdr { };        //Standard Windows header.
    POINT pt { };         //Mouse position when clicked.
    WORD  wMenuID { };    //Menu identifier.
    bool  fShow { true }; //Whether to show menu or not, in case of HEXCTRL_MSG_CONTEXTMENU.
};
using PHEXMENUINFO = HEXMENUINFO*;

This struct is used mostly in selection and bookmarking routines. It holds offset and size of the data region.

struct HEXSPAN {
    ULONGLONG ullOffset { };
    ULONGLONG ullSize { };
};
using VecSpan = std::vector<HEXSPAN>;

This struct is returned from IsOffsetVisible method. Two members i8Vert and i8Horz represent vertical and horizontal visibility respectively. These members can be in three different states:

• -1 — offset is higher, or at the left, of the visible area.
•   1 — offset is lower, or at the right.
•   0 — offset is visible.

struct HEXVISION {
    std::int8_t i8Vert { }; //Vertical offset.
    std::int8_t i8Horz { }; //Horizontal offset.
    operator bool()const { return i8Vert == 0 && i8Horz == 0; }; //For test simplicity: if(IsOffsetVisible()).
};

The IHexBookmarks interface responds for the HexCtrl‘s bookmarks machinery. To obtain pointer to this interface use the GetBookmarks method.

class IHexBookmarks {
public:
    virtual auto AddBkm(const HEXBKM& hbs, bool fRedraw = true) -> ULONGLONG = 0; //Add new bookmark, returns the new bookmark's ID.
    [[nodiscard]] virtual auto GetByID(ULONGLONG ullID) -> PHEXBKM = 0;           //Get bookmark by ID.
    [[nodiscard]] virtual auto GetByIndex(ULONGLONG ullIndex) -> PHEXBKM = 0;     //Get bookmark by index.
    [[nodiscard]] virtual auto GetCount() -> ULONGLONG = 0;                       //Get bookmarks count.
    [[nodiscard]] virtual auto HitTest(ULONGLONG ullOffset) -> PHEXBKM = 0;       //HitTest for given offset.
    virtual void RemoveAll() = 0;                                                 //Remove all bookmarks.
    virtual void RemoveByID(ULONGLONG ullID) = 0;                                 //Remove by a given ID.
};

ULONGLONG AddBkm(const HEXBKM& hbs, bool fRedraw = false)

Adds new bookmark to the control, returns created bookmark’s ID.

Example:

HEXBKM hbs;
hbs.vecSpan.emplace_back(0x1, 10);
hbs.clrBk = RGB(0, 255, 0);
hbs.clrText = RGB(255, 255, 255);
hbs.wstrDesc = L"My bookmark, with green bk and white text.";
myHex->GetBookmarks()->Add(hbs);

GetByID(ULONGLONG ullID)->HEXBKM*;

Get bookmark by ID.

auto GetByIndex(ULONGLONG ullIndex)->HEXBKM*;

Get bookmark by index.

ULONGLONG GetCount();

Get bookmarks’ count.

auto HitTest(ULONGLONG ullOffset)->HEXBKM*;

Test given offset and retrieves a pointer to HEXBKM if offset contains a bookmark.

void RemoveAll();

Removes all bookmarks.

void RemoveByID(ULONGLONG ullID);

Removes bookmark with the given ID.

class IHexTemplates {
public:
    virtual auto AddTemplate(const HEXTEMPLATE& hts) -> int = 0; //Adds existing template.
    virtual auto ApplyTemplate(ULONGLONG ullOffset, int iTemplateID) -> int = 0; //Applies template to offset, returns AppliedID.
    virtual void DisapplyAll() = 0;
    virtual void DisapplyByID(int iAppliedID) = 0;
    virtual void DisapplyByOffset(ULONGLONG ullOffset) = 0;
    virtual auto LoadTemplate(const wchar_t* pFilePath) -> int = 0; //Returns TemplateID on success, null otherwise.
    virtual void ShowTooltips(bool fShow) = 0;
    virtual void UnloadAll() = 0;                     //Unload all templates.
    virtual void UnloadTemplate(int iTemplateID) = 0; //Unload/remove loaded template from memory.
    [[nodiscard]] static HEXCTRLAPI auto __cdecl LoadFromFile(const wchar_t* pFilePath)->std::unique_ptr<HEXTEMPLATE>;
};

[[nodiscard]] static auto LoadFromFile(const wchar_t* pFilePath)->std::unique_ptr<HEXTEMPLATE>;

This static method can be used to upfront load a template from a file. The loaded template can then be added to multiple HexCtrl instances, through the IHexTemplates::AddTemplate method. This approach allows to avoid loading the same template from the disk multiple times if multiple HexCtrls would load it through the IHexTemplates::LoadTemplate, each individually.

class IHexVirtColors {
public:
    virtual bool OnHexGetColor(HEXCOLORINFO&) = 0; //Should return true if colors are set.
};

class IHexVirtData {
public:
    virtual void OnHexGetData(HEXDATAINFO&) = 0; //Data to get.
    virtual void OnHexGetOffset(HEXDATAINFO& hdi, bool fGetVirt) = 0; //Offset<->VirtOffset conversion.
    virtual void OnHexSetData(const HEXDATAINFO&) = 0; //Data to set, if mutable.
};

Internally HexCtrl operates with flat data offsets. If you set data of 1MB size, HexCtrl will have working offsets in the [0-1'048'575] range. However, from the user perspective the real data offsets may differ. For instance, in processes memory model very high virtual memory addresses can be used (e.g. 0x7FF96BA622C0). The process data can be mapped by operating system to literally any virtual address. The OnHexGetOffset method serves exactly for the Flat<->Virtual offset converting purpose.

Enum of commands that can be executed within HexCtrl.

enum class EHexCmd : std::uint8_t {
    CMD_SEARCH_DLG = 0x01, CMD_SEARCH_NEXT, CMD_SEARCH_PREV,
    CMD_NAV_GOTO_DLG, CMD_NAV_REPFWD, CMD_NAV_REPBKW, CMD_NAV_DATABEG, CMD_NAV_DATAEND,
    CMD_NAV_PAGEBEG, CMD_NAV_PAGEEND, CMD_NAV_LINEBEG, CMD_NAV_LINEEND, CMD_GROUPDATA_BYTE,
    CMD_GROUPDATA_WORD, CMD_GROUPDATA_DWORD, CMD_GROUPDATA_QWORD, CMD_GROUPDATA_INC, CMD_GROUPDATA_DEC,
    CMD_BKM_ADD, CMD_BKM_REMOVE, CMD_BKM_NEXT, CMD_BKM_PREV, CMD_BKM_REMOVEALL, CMD_BKM_DLG_MGR,
    CMD_CLPBRD_COPY_HEX, CMD_CLPBRD_COPY_HEXLE, CMD_CLPBRD_COPY_HEXFMT, CMD_CLPBRD_COPY_TEXTCP,
    CMD_CLPBRD_COPY_BASE64, CMD_CLPBRD_COPY_CARR, CMD_CLPBRD_COPY_GREPHEX, CMD_CLPBRD_COPY_PRNTSCRN,
    CMD_CLPBRD_COPY_OFFSET, CMD_CLPBRD_PASTE_HEX, CMD_CLPBRD_PASTE_TEXTUTF16, CMD_CLPBRD_PASTE_TEXTCP,
    CMD_MODIFY_OPERS_DLG, CMD_MODIFY_FILLZEROS, CMD_MODIFY_FILLDATA_DLG, CMD_MODIFY_UNDO, CMD_MODIFY_REDO,
    CMD_SEL_MARKSTARTEND, CMD_SEL_ALL, CMD_SEL_ADDLEFT, CMD_SEL_ADDRIGHT, CMD_SEL_ADDUP,
    CMD_SEL_ADDDOWN, CMD_DATAINTERP_DLG, CMD_CODEPAGE_DLG, CMD_APPEAR_FONT_DLG, CMD_APPEAR_FONTINC,
    CMD_APPEAR_FONTDEC, CMD_APPEAR_CAPACINC, CMD_APPEAR_CAPACDEC, CMD_PRINT_DLG, CMD_ABOUT_DLG,
    CMD_CARET_LEFT, CMD_CARET_RIGHT, CMD_CARET_UP, CMD_CARET_DOWN,
    CMD_SCROLL_PAGEUP, CMD_SCROLL_PAGEDOWN,
    CMD_TEMPL_APPLYCURR, CMD_TEMPL_DISAPPLY, CMD_TEMPL_DISAPPALL, CMD_TEMPL_DLG_MGR
};

Enum of the data type used in the HEXMODIFY struct with the EHexModifyMode::MODIFY_OPERATION mode.

enum class EHexDataType : std::uint8_t {
    DATA_INT8, DATA_UINT8, DATA_INT16, DATA_UINT16, DATA_INT32,
    DATA_UINT32, DATA_INT64, DATA_UINT64, DATA_FLOAT, DATA_DOUBLE
};

Enum of the data modification modes, used in HEXMODIFY.

enum class EHexModifyMode : std::uint8_t {
    MODIFY_ONCE, MODIFY_REPEAT, MODIFY_OPERATION, MODIFY_RAND_MT19937, MODIFY_RAND_FAST
};

Enum of the data operation modes, used in HEXMODIFY when HEXMODIFY::enModifyMode is set to MODIFY_OPERATION.

enum class EHexOperMode : std::uint8_t {
    OPER_ASSIGN, OPER_ADD, OPER_SUB, OPER_MUL, OPER_DIV, OPER_CEIL, OPER_FLOOR, OPER_OR,
    OPER_XOR, OPER_AND, OPER_NOT, OPER_SHL, OPER_SHR, OPER_ROTL, OPER_ROTR, OPER_SWAP,
    OPER_BITREV
};

Enum of all HexCtrl‘s internal windows, used in the GetWndHandle method.

enum class EHexWnd : std::uint8_t {
    WND_MAIN, DLG_BKMMGR, DLG_DATAINTERP, DLG_MODIFY,
    DLG_SEARCH, DLG_ENCODING, DLG_GOTO, DLG_TEMPLMGR
};

During its work the HexCtrl sends notification messages to its parent window through WM_NOTIFY mechanism.
The LPARAM of the WM_NOTIFY message contains a pointer to the NMHDR standard Windows struct. Depending on the notification message LPARAM can then be casted to a pointer to another struct, see the messages description for details.

Sent if a bookmark is clicked, LPARAM contains a pointer to the HEXBKMINFO struct.

Sent when a context menu is about to be displayed, LPARAM contains a pointer to the HEXMENUINFO struct. You can disable menu showing-up by setting the PHEXMENUINFO->fShow flag to false in response to this message.

Sent to indicate that the HexCtrl‘s window is about to be destroyed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Bookmark Manager dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Codepage dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Data interpreter dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Go to dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Modify Data dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Search dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Template Manager dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent when a user-defined custom menu has been clicked, LPARAM contains a pointer to the HEXMENUINFO struct.

Sent when the capacity has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the caret position has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the codepage of the text area has changed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the data has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when font has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the data grouping size has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when a selection has been made, LPARAM contains a pointer to the NMHDR struct.

This software is available under “The HexCtrl License”, it is free for any NON-COMMERCIAL use.
See the LICENSE file.

• Introduction
• How To Build
  • Integrate Sources
  • Dynamic Link Library
• Creating
  • Classic Approach
  • In Dialog
  • CreateHexCtrl
• Setting Data
• Virtual Data Mode
• Virtual Bookmarks
• Custom Colors
• Templates
• Methods
  Expand

  • ClearData
  • Create
  • CreateDialogCtrl
  • Delete
  • DestroyWindow
  • ExecuteCmd
  • GetActualWidth
  • GetBookmarks
  • GetCacheSize
  • GetCapacity
  • GetCaretPos
  • GetCharsExtraSpace
  • GetCodepage
  • GetColors
  • GetData
  • GetDataSize
  • GetDateInfo
  • GetDlgItemHandle
  • GetFont
  • GetGroupSize
  • GetMenuHandle
  • GetOffset
  • GetPagesCount
  • GetPagePos
  • GetPageSize
  • GetScrollRatio
  • GetSelection
  • GetTemplates
  • GetUnprintableChar
  • GetWndHandle
  • GoToOffset
  • HasInfoBar
  • HasSelection
  • HitTest
  • IsCmdAvail
  • IsCreated
  • IsDataSet
  • IsHexCharsUpper
  • IsMutable
  • IsOffsetAsHex
  • IsOffsetVisible
  • IsVirtual
  • ModifyData
  • PreTranslateMsg
  • Redraw
  • SetCapacity
  • SetCaretPos
  • SetCharsExtraSpace
  • SetCodepage
  • SetColors
  • SetConfig
  • SetData
  • SetDateInfo
  • SetDlgProperties
  • SetFont
  • SetGroupSize
  • SetHexCharsCase
  • SetMutable
  • SetOffsetMode
  • SetPageSize
  • SetRedraw
  • SetScrollRatio
  • SetSelection
  • SetUnprintableChar
  • SetVirtualBkm
  • SetWindowPos
  • ShowInfoBar
• Structures
  Expand

  • HEXBKM
  • HEXBKMINFO
  • HEXCOLOR
  • HEXCOLORINFO
  • HEXCOLORS
  • HEXCREATE
  • HEXDATA
  • HEXDATAINFO
  • HEXHITTEST
  • HEXMENUINFO
  • HEXMODIFY
  • HEXSPAN
  • HEXVISION
• Interfaces
  Expand

  • IHexBookmarks
  • IHexTemplates
  • IHexVirtColors
  • IHexVirtData
• Enums
  Expand

  • EHexCmd
  • EHexDataType
  • EHexModifyMode
  • EHexOperMode
  • EHexWnd
• Notification Messages
  Expand

  • HEXCTRL_MSG_BKMCLICK
  • HEXCTRL_MSG_CONTEXTMENU
  • HEXCTRL_MSG_DESTROY
  • HEXCTRL_MSG_DLGBKMMGR
  • HEXCTRL_MSG_DLGCODEPAGE
  • HEXCTRL_MSG_DLGDATAINTERP
  • HEXCTRL_MSG_DLGGOTO
  • HEXCTRL_MSG_DLGMODIFY
  • HEXCTRL_MSG_DLGSEARCH
  • HEXCTRL_MSG_DLGTEMPLMGR
  • HEXCTRL_MSG_MENUCLICK
  • HEXCTRL_MSG_SETCAPACITY
  • HEXCTRL_MSG_SETCARET
  • HEXCTRL_MSG_SETCODEPAGE
  • HEXCTRL_MSG_SETDATA
  • HEXCTRL_MSG_SETFONT
  • HEXCTRL_MSG_SETGROUPSIZE
  • HEXCTRL_MSG_SETSELECTION
• Licensing

HexCtrl is the fully-featured Hex Control written in pure Win32 API.

• View and edit data up to 16EB (exabyte)
• Two working modes: Memory and Virtual Data Mode
• Fully-featured Bookmarks Manager
• Fully-featured Search and Replace
• Fully-featured Data Interpreter
• Grouping data with arbitrary group size
• Changeable codepage for the text area
• Many options to Copy/Paste to/from clipboard
• Modify data with Filling and many predefined Operations options
• Undo/Redo
• Ability to visually divide data into pages
• Print whole document/pages range/selection
• Customizable colors for data with Custom Colors
• Powerful system of Templates
• Assignable keyboard shortcuts via external config file
• Customizable look and appearance, font, colors
• High-DPI compliant
• Utilizes AVX/AVX2 instruction set for best performance
• Supports compiling for the ARM64 architecture
• Written with the /std:c++20 standard conformance

git clone https://github.com/jovibor/HexCtrl.git

To build HexCtrl from the sources:

1. Add all files from the HexCtrl folder into your project
2. Make sure to disable Precompiled Header usage for all *.ixx files in the project
3. Add #include "HexCtrl.h"
4. Declare HexCtrl object: auto myHex { HEXCTRL::CreateHexCtrl() };
5. Create control instance

To build and use HexCtrl as a DLL:

1. Build HexCtrl{x86/x64/ARM64}.dll and HexCtrl{x86/x64/ARM64}.lib with the HexCtrl DLL.vcxproj project
2. Include HexCtrl.h into your project
3. Add /DHEXCTRL_DYNAMIC_LIB compiler option, or alternatively #define it before including HexCtrl.h:

   #define HEXCTRL_DYNAMIC_LIB
   #include "HexCtrl.h"

4. Declare IHexCtrlPtr object: auto myHex { HEXCTRL::CreateHexCtrl() };
5. Create control instance

First you need to create HexCtrl object:

auto myHex { HEXCTRL::CreateHexCtrl() };

Then call the Create method, which takes the HEXCREATE struct with the all necessary information for the HexCtrl creation. The HEXCREATE::dwStyle and dwExStyle are window and extended window styles respectively, set these styles according to your needs. For all available options see the HEXCREATE struct description.

To use HexCtrl in a Dialog you can create it with the Classic Approach: call Create method and provide all the necessary information.
But there is another option:

1. Put the Custom Control from the Toolbox in Visual Studio dialog designer onto your dialog template.
   
2. In the Properties of this control in the Class field within the Misc section write: HexCtrl_MainWnd.
3. Declare IHexCtrlPtr member variable within your dialog class:

   HEXCTRL::IHexCtrlPtr m_myHex { CreateHexCtrl() };

4. Call the CreateDialogCtrl method from dialog’s OnInitDialog method.

   BOOL CMyDialog::OnInitDialog() {
       CDialogEx::OnInitDialog();
       m_myHex->CreateDialogCtrl(IDC_MY_HEX, m_hWnd);
   }

[[nodiscard]] IHexCtrlPtr CreateHexCtrl();

This is the main factory function for creating HexCtrl object. The IHexCtrlPtr class is a IHexCtrl interface pointer wrapped into a standard std::unique_ptr with custom deleter, so you don’t need to worry about its destruction.

To set a data for the HexCtrl the SetData method is used. The code below shows how to construct HexCtrl object and display first 0x1FF bytes of the current app’s memory:

IHexCtrlPtr myHex { CreateHexCtrl() };

HEXCREATE hcs;
hcs.hWndParent = m_hWnd;
hcs.rect = {0, 0, 600, 400}; //Window rect.
myHex->Create(hcs);

HEXDATA hds;
hds.spnData = { reinterpret_cast<std::byte*>(GetModuleHandle(nullptr)), 0x1FF };
myHex->SetData(hds);

The next example shows how to display std::string‘s text as hex data:

std::string str = "My string";
HEXDATA hds;
hds.spnData = { reinterpret_cast<std::byte*>(str.data()), str.size() };
myHex->SetData(hds);

Besides the standard mode, when the HexCtrl just holds a pointer to a data in a memory, it can also work in the Virtual mode. This mode can be useful in cases where you need to display a very large amount of a data that can’t fit in the memory all at once.

If HEXDATA::pHexVirtData pointer is set, then the whole data routine will be done through it. This pointer is of IHexVirtData class type, which is a pure abstract base class. You have to derive your own class from it and implement all its public methods. Then provide a pointer to the created object of this derived class through the HEXDATA::pHexVirtData member, prior to call the SetData method.

HexCtrl has innate functional to work with any amount of bookmarked regions. These regions can be assigned with individual background and text colors and description.

But if you have big and complicated data logic and want to handle all these bookmarks yourself, you can do it with the help of the Virtual Bookmarks mode. In this mode all bookmark’s burden is handled by yourself, by implementing the IHexBookmarks interface and providing pointer to this implementation to the HexCtrl by calling the SetVirtualBkm method.

If you’d like to colorize data regions with your own custom colors, use the IHexVirtColors interface.

To use it set the HEXDATA::pHexVirtColors member to a valid instance of your own class that implements this interface, prior to calling the SetData method.

The OnHexGetColor method of this interface takes HEXCOLORINFO struct as an argument. The HEXCOLORINFO::ullOffset member indicates the offset for which the color is requested. This method should return true if it sets custom colors for the given offset or false for default colors.

HexCtrl‘s templates is a powerful system of a data structures’ description with a simple .json file. These files can be loaded through the HexControl‘s internal template manager, or through the API.

{
    "$schema": "https://raw.githubusercontent.com/jovibor/HexCtrl/master/docs/HexCtrl.Templates.Schema.json",
    "TemplateName": "SampleTemplate",
    "Data": {
        "endianness": "little",
        "clrBk": "#999999",
        "clrText": "#FFFFFF",
        "Fields": [
            {
                "name": "MyCustomDataSingle",
                "type": "MyCustomType"
            },
            {
                "name": "CustomComplexData",
                "type": "MyCustomComplexType"
            },
            {
                "name": "ArrayOfDWORDs",
                "type": "DWORD",
                "array": 10
            },
            {
                "name": "MyCustomDataArray",
                "type": "MyCustomType",
                "array": 4
            }
        ]
    },
    "CustomTypes": [
        {
            "TypeName": "MyCustomType",
            "Fields": [
                {
                    "name": "myCustomTypeField1",
                    "type": "DWORD"
                },
                {
                    "name": "myCustomTypeField2",
                    "type": "DWORD"
                }
            ]
        },
        {
            "TypeName": "MyCustomComplexType",
            "Fields": [
                {
                    "name": "MyCustomTypeData1",
                    "type": "MyCustomType"
                },
                {
                    "name": "MyCustomTypeData2",
                    "type": "MyCustomType"
                }
            ]
        }
    ]
}

Every such file contains the following properties:

• TemplateName [mandatory, string] – the name of the template
• Data [mandatory, object] – main object that contains all template field’s information
• CustomTypes [optional, array] – array of a user defined types, that can be then referenced in the type property of the Fields

CustomTypes objects are the same as Fields objects, the only difference is the TypeName property which Fields objects don’t have.

Every Data or CustomType object contains Fields property with actual struct members.

Fields [array] – is an array of objects where every object represents a struct data member. Any such object can have its own Fields sub-objects, which will represent nested structs.
The Fields‘s properties include:

• name – [mandatory, string] – name of the field
• description – [optional, string] – field description
• type – [optional, string] – field type, such as:
  bool, char, unsigned char, byte, short, unsigned short, WORD, long, unsigned long, int, unsigned int, DWORD, long long, unsigned long long, QWORD, float, double, time32_t, time64_t, FILETIME, SYSTEMTIME, GUID, or any custom type defined in the CustomTypes section
• size – [optional, int] – size of the field in bytes, if the type field is not provided
• array – [optional, int] – size of the array, if the given field is an array of fields
• endianness – [optional, string] – field endianness, “little” or “big”. By default all fields are little-endian.
• clrBk – [optional, string] – field background color
• clrText – [optional, string] – field text color

The endianness, clrBk and clrText properties that locate at the same level as the Fields property, would mean the default properties for all the Fields objects of that level and below the line, unless they explicitly redefined in the field itself.

For the available templates check the Templates directory.

The HexCtrl has plenty of methods that you can use to manage its behavior.

void ClearData();

Clears data from the HexCtrl view, not touching data itself.

bool Create(const HEXCREATE& hcs);

Main initialization method. Takes the HEXCREATE struct as argument. Returns true if created successfully, false otherwise.

bool CreateDialogCtrl(UINT uCtrlID, HWND hwndDlg);

Creates HexCtrl from a Custom Control dialog’s template. Takes control id, and dialog’s window handle as arguments. See Creating section for more info.

void Delete();

Deletes the HexCtrl object. You only use this method if you want, for some reason, to manually delete the HexCtrl object, otherwise IHexCtrlPtr will invoke this method automatically.

void DestroyWindow();

Destroys the HexCtrl main window.

void ExecuteCmd(EHexCmd eCmd)const;

Executes one of the predefined commands of the EHexCmd enum. All these commands are basically replicating HexCtrl‘s inner menu.

[[nodiscard]] auto GetActualWidth()const->int;

Returns the width of the HexCtrl bounding rectangle, i.e. the width of the drawn working area.

[[nodiscard]] auto GetBookmarks()->IHexBookmarks*;

Returns pointer to the IHexBookmarks interface, which responds for the bookmarks machinery.

[[nodiscard]] auto GetCacheSize()const->DWORD;

Returns current cache size set in HEXDATA.

[[nodiscard]] auto GetCapacity()const->DWORD;

Returns current capacity.

[[nodiscard]] auto GetCaretPos()const->ULONGLNG;

Retrieves current caret position offset.

[[nodiscard]] auto GetCharsExtraSpace()const->DWORD;

Get extra space between chars, in pixels. This extra space can be set with the SetCharsExtraSpace method.

[[nodiscard]] auto GetColors()const->const HEXCOLORS&;

Returns reference to the current HEXCOLORS struct.

[[nodiscard]] auto GetData(HEXSPAN hss)const->std::byte*;

Returns a pointer to the data offset no matter what mode the control works in.

[[nodiscard]] auto GetDataSize()const->ULONGLONG;

Returns currently set data size.

[[nodiscard]] auto GetDateInfo()const->std::tuple<DWORD, wchar_t>;

Returns tuple of the current date format-ordering specifier, and date separator.

[[nodiscard]] auto GetDlgItemHandle(EHexDlgItem eItem)const->HWND;

Returns HWND of a dialog’s internal child control.

[[nodiscard]] auto GetCodepage()const->int;

Returns code page that is currently in use.

[[nodiscard]] auto GetFont(bool fMain)const->LOGFONTW;

Returns current main font if fMain is true, and infobar font if fMain is false.

[[nodiscard]] auto GetGroupSize()const->DWORD;

Returns current data grouping size.

[[nodiscard]] auto GetMenuHandle()const->HMENU;

Returns the HMENU handle of the HexCtrl context menu. You can use this handle to customize menu for your needs.
HexCtrl‘s internal menu uses IDs starting from 0x8001. So if you wish to add your own new menu, assign menu ID starting from 0x9000 to not interfere.
When a user clicks custom menu, control sends WM_NOTIFY message to its parent window with LPARAM pointing to HEXMENUINFO with its hdr.code member set to HEXCTRL_MSG_MENUCLICK, and wMenuID field containing ID of the menu clicked.

[[nodiscard]] auto GetOffset(ULONGLONG ullOffset, bool fGetVirt)const->ULONGLONG;

Converts offset from virtual to flat, and vice versa.

[[nodiscard]] auto GetPagesCount()const->ULONGLONG;

Returns current count of pages set by the SetPageSize method.

[[nodiscard]] auto GetPagePos()const->ULONGLONG;

Returns a page number that the cursor stays at.

[[nodiscard]] auto GetPageSize()const->DWORD;

Returns current page size set by the SetPageSize method.

[[nodiscard]] auto GetScrollRatio()const->std::tuple<float, bool>;

Returns tuple of the current scroll ratio and fLines flag set by the SetScrollRatio method.

[[nodiscard]] auto GetSelection()const->std::vector<HEXSPAN>;

Returns std::vector with the offsets and sizes of the current selection.

[[nodiscard]] auto GetTemplates()->IHexTemplates*;

Returns pointer to the internal IHexTemplates interface that is responsible for templates machinery.

[[nodiscard]] auto GetUnprintableChar()const->wchar_t;

Returns replacement char for unprintable characters.

[[nodiscard]] auto GetWndHandle(EHexWnd eWnd, bool fCreate = true)const->HWND;

Returns HWND for HexCtrl‘s main window or one of its internal dialogs. If fCreate flag is true, the dialog window will be created first before returning, if it was not already.

void GoToOffset(ULONGLONG ullOffset, int iPosAt = 0);

Go to the given offset. The second argument iPosAt can take three values:

• -1 – offset will appear at the top line
•   0 – offset will appear in the center
•   1 – offset will appear at the bottom line

[[nodiscard]] bool HasInfoBar()const;

Shows whether bottom info bar currently visible or not.

[[nodiscard]] bool HasSelection()const;

Returns true if HexCtrl has any area selected.

[[nodiscard]] auto HitTest(POINT pt, bool fScreen = true)const->std::optional<HEXHITTEST>;

Hit testing of given point in a screen fScreen = true, or client fScreen = false coordinates. In case of success returns HEXHITTEST structure.

[[nodiscard]] bool IsCmdAvail(EHexCmd eCmd)const;

Returns true if the given command can be executed at the moment, false otherwise.

[[nodiscard]] bool IsCreated()const;

Shows whether HexCtrl is created or not.

[[nodiscard]] bool IsDataSet()const;

Shows whether a data was set to HexCtrl or not

[[nodiscard]] bool IsHexCharsUpper()const;

Shows if hex chars printed in UPPER or lower case.

[[nodiscard]] bool IsMutable()const;

Shows whether HexCtrl is currently in edit mode or not.

[[nodiscard]] bool IsOffsetAsHex()const;

Is “Offset” currently represented (shown) as Hex or as Decimal. It can be changed by double clicking at offset area.

[[nodiscard]] auto IsOffsetVisible(ULONGLONG ullOffset)const->HEXVISION;

Checks for offset visibility and returns HEXVISION as a result.

[[nodiscard]] bool IsVirtual()const;

Returns true if HexCtrl currently works in Virtual Data Mode.

void ModifyData(const HEXMODIFY& hms);

Modify data currently set in HexCtrl, see the HEXMODIFY struct for details.

[[nodiscard]] bool PreTranslateMsg(MSG* pMsg);

The HexCtrl has many internal dialog windows. In order for dialog keyboard navigation to work correctly, this method must be hooked into your app’s main message loop before TranslateMessage and DispatchMessage, or into MFC’s PreTranslateMessage virtual function.

while (GetMessageW(&msg, nullptr, 0, 0)) {
    if (!TranslateAcceleratorW(msg.hwnd, hAccelTable, &msg)) {
        if (!m_pHexCtrl->PreTranslateMsg(&msg)) { //Process further only if it returns false.
            TranslateMessage(&msg);
            DispatchMessageW(&msg);
        }
    }
}

If this method returns true it means that no further message processing should be made, HexCtrl has done all processing by itself.

void Redraw();

Redraws main window.

void SetCapacity(DWORD dwCapacity);

Sets HexCtrl‘s current capacity.

void SetCaretPos(ULONGLONG ullOffset, bool fHighLow = true, bool fRedraw = true);

Sets the caret to the given offset. The fHighLow flag shows which part of the hex chunk, low or high, a caret must be set to.

void SetCharsExtraSpace(DWORD dwSpace);

Sets extra space to add between chars, in pixels.

void SetCodepage(int iCodePage);

Sets the code page for the HexCtrl‘s text area. Takes code page identifier as an argument, or -1 for default ASCII-only characters.

void SetColors(const HEXCOLORS& clr);

Sets all the colors for the control. Takes HEXCOLORS as the argument.

bool SetConfig(std::wstring_view wsvPath);

Sets the path to a JSON config file with keybindings to use in HexCtrl, or empty path (L"") for default. This file is using EHexCmd enum values as keys and strings array as values:

{
    "CMD_DLG_SEARCH": [ "ctrl+f", "ctrl+h" ],
    "CMD_SEARCH_NEXT": [ "f3" ],
    "CMD_SEARCH_PREV": [ "shift+f3" ]
}

For default values see the IDR_HEXCTRL_JSON_KEYBIND.json file from the project sources.

void SetData(const HEXDATA& hds, bool fAdjust = false)

Main method to set data for HexCtrl. It takes HEXDATA struct as an argument.
The fAdjust flag when set to true allows adjusting already set data. For example to switch between virtual and normal data modes.

void SetDateInfo(DWORD dwFormat, wchar_t wchSepar);

Sets date format-ordering specifier, along with date separator.

void SetDlgProperties(EHexWnd eWnd, std::uint64_t u64Flags);

Sets various properties to the HexCtrl‘s internal dialogs, in form of flags. Flags can be combined together with the OR (|) operation.
Available flags:

HEXCTRL_FLAG_DLG_NOESC //Prevent dialog from closing on Esc key.

void SetFont(const LOGFONTW& lf, bool fMain);

Sets new main font for the HexCtrl if fMain is true, or infobar font when fMain is false. This font has to be monospaced.

void SetGroupSize(DWORD dwSize);

Sets current data grouping size in bytes.

void SetHexCharsCase(bool fUpper);

Sets printed hex chars to an UPPER or lower case.

void SetMutable(bool fMutable);

Enables or disables mutable mode. In the mutable mode all the data can be modified.

void SetOffsetMode(bool fHex);

Sets offset area being shown as Hex (fHex=true) or as Decimal (fHex=false).

void SetPageSize(DWORD dwSize, std::wstring_view wsvName = L"Page");

Sets the size of the page to draw the divider line between. This size should be multiple to the current capacity size to take effect. The second argument sets the name to be displayed in the bottom info area of the HexCtrl (“Page”, “Sector”, etc…).
To remove the divider just set dwSize to 0.

void SetRedraw(bool fRedraw);

Should the main HexCtrl window be redrawn or not. E.g. should the WM_PAINT message be handled or not.

void SetScrollRatio(float flRatio, bool fLines);

Sets the scroll amount for one scroll-page. Page is the one mouse-wheel tick or page-down key. When fLines is true the flRatio is the amount of text lines to scroll. When it’s false flRatio is a ratio of visible screen height to scroll.

void SetSelection(const std::vector<HEXSPAN>& vecSel, bool fRedraw = true, bool fHighlight = false);

Sets current selection or highlight in the selection, if fHighlight is true.

void SetUnprintableChar(wchar_t wch);

Sets replacement char for unprintable characters.

void SetVirtualBkm(IHexBookmarks* pVirtBkm);

Sets a pointer for the Virtual Bookmarks mode, or disables this mode if nullptr is set.

void SetWindowPos(HWND hWndAfter, int iX, int iY, int iWidth, int iHeight, UINT uFlags);

Sets HexCtrl window position. This method replicates behavior of the SetWindowPos Windows function.

void ShowInfoBar(bool fShow);

Show/hide bottom Info bar.

Below are listed all HexCtrl‘s structures.

Main bookmarks structure, used with the IHexBookmarks interface.

struct HEXBKM {
    VecSpan      vecSpan;     //Vector of offsets and sizes.
    std::wstring wstrDesc;    //Bookmark description.
    ULONGLONG    ullID { };   //Bookmark ID, assigned internally by framework.
    ULONGLONG    ullData { }; //User defined custom data.
    HEXCOLOR     stClr;       //Bookmark bk/text color.
};
using PHEXBKM = HEXBKM*;

The member vecSpan is of a std::vector<HEXSPAN> type because a bookmark may have few non adjacent areas. For instance, when selection is made as a block, with Alt pressed.

Bookmark information struct.

struct HEXBKMINFO {
    NMHDR   hdr { };  //Standard Windows header.
    PHEXBKM pBkm { }; //Bookmark pointer.
};
using PHEXBKMINFO = HEXBKMINFO*;

Background and Text color struct.

struct HEXCOLOR {
    COLORREF clrBk { };   //Bk color.
    COLORREF clrText { }; //Text color.
    auto operator<=>(const HEXCOLOR&)const = default;
};
using PHEXCOLOR = HEXCOLOR*;

Struct for hex chunks’ color information.

struct HEXCOLORINFO {
    NMHDR     hdr { };       //Standard Windows header.
    ULONGLONG ullOffset { }; //Offset for the color.
    HEXCOLOR  stClr;         //Colors of the given offset.
};

This structure contains all colors for fonts, background, and all other visual stuff. All these colors have their default values, so you don’t have to set them all during HexCtrl creation, if you don’t want to.

struct HEXCOLORS {
    COLORREF clrFontHex { ::GetSysColor(COLOR_WINDOWTEXT) };       //Hex-chunks font color.
    COLORREF clrFontText { ::GetSysColor(COLOR_WINDOWTEXT) };      //Text font color.
    COLORREF clrFontSel { ::GetSysColor(COLOR_HIGHLIGHTTEXT) };    //Selected hex/text font color.
    COLORREF clrFontBkm { ::GetSysColor(COLOR_WINDOWTEXT) };       //Bookmarks font color.
    COLORREF clrFontDataInterp { ::GetSysColor(COLOR_HIGHLIGHTTEXT) }; //Data Interpreter text/hex font color.
    COLORREF clrFontCaption { RGB(0, 0, 180) };                    //Caption font color
    COLORREF clrFontInfoParam { ::GetSysColor(COLOR_WINDOWTEXT) }; //Font color of the Info bar parameters.
    COLORREF clrFontInfoData { RGB(0, 0, 180) };                   //Font color of the Info bar data.
    COLORREF clrFontCaret { ::GetSysColor(COLOR_HIGHLIGHTTEXT) };  //Caret font color.
    COLORREF clrBk { ::GetSysColor(COLOR_WINDOW) };                //Background color.
    COLORREF clrBkSel { ::GetSysColor(COLOR_HIGHLIGHT) };          //Background color of the selected Hex/Text.
    COLORREF clrBkBkm { RGB(240, 240, 0) };                        //Bookmarks background color.
    COLORREF clrBkDataInterp { RGB(147, 58, 22) };                 //Data Interpreter Bk color.
    COLORREF clrBkInfoBar { ::GetSysColor(COLOR_3DFACE) };         //Background color of the bottom Info bar.
    COLORREF clrBkCaret { RGB(0, 0, 255) };                        //Caret background color.
    COLORREF clrBkCaretSel { RGB(0, 0, 200) };                     //Caret background color in selection.
    COLORREF clrLinesMain { ::GetSysColor(COLOR_SCROLLBAR) };      //Main window and pages lines color.
    COLORREF clrLinesTempl { ::GetSysColor(COLOR_WINDOWTEXT) };    //Templates data confining lines color.
    COLORREF clrScrollBar { ::GetSysColor(COLOR_3DFACE) };         //Scrollbar color.
    COLORREF clrScrollThumb { ::GetSysColor(COLOR_SCROLLBAR) };    //Scrollbar thumb color.
    COLORREF clrScrollArrow { ::GetSysColor(COLOR_GRAYTEXT) };     //Scrollbar arrow color.
};
using PCHEXCOLORS = const HEXCOLORS*;

The main initialization struct used for the HexCtrl creation.

struct HEXCREATE {
    HINSTANCE       hInstRes { };           //Hinstance of the HexCtrl resources, nullptr for current module.
    HWND            hWndParent { };         //Parent window handle.
    PCHEXCOLORS     pColors { };            //HexCtrl colors, nullptr for default.
    const LOGFONTW* pLogFont { };           //Monospaced font for HexCtrl, nullptr for default.
    RECT            rect { };               //Initial window rect.
    UINT            uID { };                //Control ID if it's a child window.
    DWORD           dwStyle { };            //Window styles.
    DWORD           dwExStyle { };          //Extended window styles.
    DWORD           dwCapacity { 16UL };    //Initial capacity size.
    DWORD           dwGroupSize { 1UL };    //Initial data grouping size.
    float           flScrollRatio { 1.0F }; //Either a screen-ratio or lines amount to scroll with Page-scroll (mouse-wheel).
    bool            fScrollLines { false }; //Treat flScrollRatio as screen-ratio (false) or as amount of lines (true).
    bool            fInfoBar { true };      //Show bottom Info bar or not.
    bool            fOffsetHex { true };    //Show offset digits as Hex or Decimal.
    bool            fCustom { false };      //If it's a custom control in a dialog.
};

HINSTANCE hInstRes

The hInstRes member allows you to provide an alternative HINSTANCE of a module where all HexCtrl resources (dialogs, menu, etc…) reside. By default HexCtrl uses its current module, whether it’s a .exe or .dll.

DWORD dwStyle

Standard window style for the main HexCtrl window.

DWORD dwExStyle

Standard extended window style for the main HexCtrl window.

The main struct to set a data to display in the HexCtrl.

struct HEXDATA {
    SpanByte        spnData;                    //Data span to display.
    IHexVirtData*   pHexVirtData { };           //Pointer for VirtualData mode.
    IHexVirtColors* pHexVirtColors { };         //Pointer for Custom Colors class.
    ULONGLONG       ullMaxVirtOffset { };       //Maximum virtual offset.
    DWORD           dwCacheSize { 0x800000UL }; //Data cache size for VirtualData mode.
    bool            fMutable { false };         //Is data mutable or read-only.
    bool            fHighLatency { false };     //Do not redraw until scroll thumb is released.
};

ULONGLONG ullMaxVirtOffset

Used to set maximum virtual data offset in virtual data mode. This is needed for the offset digits amount calculation.

Struct for a data information used in IHexVirtData.

struct HEXDATAINFO {
    NMHDR    hdr { };   //Standard Windows header.
    HEXSPAN  stHexSpan; //Offset and size of the data.
    SpanByte spnData;   //Data span.
};

Structure is used in HitTest method.

struct HEXHITTEST {
    ULONGLONG ullOffset { };     //Offset.
    bool      fIsText { false }; //Is cursor at Text or Hex area.
    bool      fIsHigh { false }; //Is it High or Low part of the byte.
};

This struct is used to represent data modification parameters.
When eModifyMode is set to MODIFY_ONCE, bytes from pData just replace corresponding data bytes as is.
If eModifyMode is equal to MODIFY_REPEAT then block by block replacement takes place few times.
For example, if:

• SUM(vecSpan.ullSize) == 9
• spnData.size() == 3
• eModifyMode is set to MODIFY_REPEAT
• bytes in memory at vecSpan.ullOffset are 010203040506070809
• bytes pointed to by spnData.data() are 030405

then, after modification, bytes at vecSpan.ullOffset will become 030405030405030405.

If eModifyMode is equal to the MODIFY_OPERATION then the eOperMode shows what kind of operation must be performed on the data.

struct HEXMODIFY {
    EHexModifyMode eModifyMode { };      //Modify mode.
    EHexOperMode   eOperMode { };        //Operation mode, used if eModifyMode == MODIFY_OPERATION.
    EHexDataType   eDataType { };        //Data type of the underlying data, used if eModifyMode == MODIFY_OPERATION.
    SpanCByte      spnData;              //Span of the data to modify with.
    VecSpan        vecSpan;              //Vector of data offsets and sizes to modify.
    bool           fBigEndian { false }; //Treat data as the big endian, used if eModifyMode == MODIFY_OPERATION.
};

Menu information struct.

struct HEXMENUINFO {
    NMHDR hdr { };        //Standard Windows header.
    POINT pt { };         //Mouse position when clicked.
    WORD  wMenuID { };    //Menu identifier.
    bool  fShow { true }; //Whether to show menu or not, in case of HEXCTRL_MSG_CONTEXTMENU.
};
using PHEXMENUINFO = HEXMENUINFO*;

This struct is used mostly in selection and bookmarking routines. It holds offset and size of the data region.

struct HEXSPAN {
    ULONGLONG ullOffset { };
    ULONGLONG ullSize { };
};
using VecSpan = std::vector<HEXSPAN>;

This struct is returned from IsOffsetVisible method. Two members i8Vert and i8Horz represent vertical and horizontal visibility respectively. These members can be in three different states:

• -1 — offset is higher, or at the left, of the visible area.
•   1 — offset is lower, or at the right.
•   0 — offset is visible.

struct HEXVISION {
    std::int8_t i8Vert { }; //Vertical offset.
    std::int8_t i8Horz { }; //Horizontal offset.
    operator bool()const { return i8Vert == 0 && i8Horz == 0; }; //For test simplicity: if(IsOffsetVisible()).
};

The IHexBookmarks interface responds for the HexCtrl‘s bookmarks machinery. To obtain pointer to this interface use the GetBookmarks method.

class IHexBookmarks {
public:
    virtual auto AddBkm(const HEXBKM& hbs, bool fRedraw = true) -> ULONGLONG = 0; //Add new bookmark, returns the new bookmark's ID.
    [[nodiscard]] virtual auto GetByID(ULONGLONG ullID) -> PHEXBKM = 0;           //Get bookmark by ID.
    [[nodiscard]] virtual auto GetByIndex(ULONGLONG ullIndex) -> PHEXBKM = 0;     //Get bookmark by index.
    [[nodiscard]] virtual auto GetCount() -> ULONGLONG = 0;                       //Get bookmarks count.
    [[nodiscard]] virtual auto HitTest(ULONGLONG ullOffset) -> PHEXBKM = 0;       //HitTest for given offset.
    virtual void RemoveAll() = 0;                                                 //Remove all bookmarks.
    virtual void RemoveByID(ULONGLONG ullID) = 0;                                 //Remove by a given ID.
};

ULONGLONG AddBkm(const HEXBKM& hbs, bool fRedraw = false)

Adds new bookmark to the control, returns created bookmark’s ID.

Example:

HEXBKM hbs;
hbs.vecSpan.emplace_back(0x1, 10);
hbs.clrBk = RGB(0, 255, 0);
hbs.clrText = RGB(255, 255, 255);
hbs.wstrDesc = L"My bookmark, with green bk and white text.";
myHex->GetBookmarks()->Add(hbs);

GetByID(ULONGLONG ullID)->HEXBKM*;

Get bookmark by ID.

auto GetByIndex(ULONGLONG ullIndex)->HEXBKM*;

Get bookmark by index.

ULONGLONG GetCount();

Get bookmarks’ count.

auto HitTest(ULONGLONG ullOffset)->HEXBKM*;

Test given offset and retrieves a pointer to HEXBKM if offset contains a bookmark.

void RemoveAll();

Removes all bookmarks.

void RemoveByID(ULONGLONG ullID);

Removes bookmark with the given ID.

class IHexTemplates {
public:
    virtual auto AddTemplate(const HEXTEMPLATE& hts) -> int = 0; //Adds existing template.
    virtual auto ApplyTemplate(ULONGLONG ullOffset, int iTemplateID) -> int = 0; //Applies template to offset, returns AppliedID.
    virtual void DisapplyAll() = 0;
    virtual void DisapplyByID(int iAppliedID) = 0;
    virtual void DisapplyByOffset(ULONGLONG ullOffset) = 0;
    virtual auto LoadTemplate(const wchar_t* pFilePath) -> int = 0; //Returns TemplateID on success, null otherwise.
    virtual void ShowTooltips(bool fShow) = 0;
    virtual void UnloadAll() = 0;                     //Unload all templates.
    virtual void UnloadTemplate(int iTemplateID) = 0; //Unload/remove loaded template from memory.
    [[nodiscard]] static HEXCTRLAPI auto __cdecl LoadFromFile(const wchar_t* pFilePath)->std::unique_ptr<HEXTEMPLATE>;
};

[[nodiscard]] static auto LoadFromFile(const wchar_t* pFilePath)->std::unique_ptr<HEXTEMPLATE>;

This static method can be used to upfront load a template from a file. The loaded template can then be added to multiple HexCtrl instances, through the IHexTemplates::AddTemplate method. This approach allows to avoid loading the same template from the disk multiple times if multiple HexCtrls would load it through the IHexTemplates::LoadTemplate, each individually.

class IHexVirtColors {
public:
    virtual bool OnHexGetColor(HEXCOLORINFO&) = 0; //Should return true if colors are set.
};

class IHexVirtData {
public:
    virtual void OnHexGetData(HEXDATAINFO&) = 0; //Data to get.
    virtual void OnHexGetOffset(HEXDATAINFO& hdi, bool fGetVirt) = 0; //Offset<->VirtOffset conversion.
    virtual void OnHexSetData(const HEXDATAINFO&) = 0; //Data to set, if mutable.
};

Internally HexCtrl operates with flat data offsets. If you set data of 1MB size, HexCtrl will have working offsets in the [0-1'048'575] range. However, from the user perspective the real data offsets may differ. For instance, in processes memory model very high virtual memory addresses can be used (e.g. 0x7FF96BA622C0). The process data can be mapped by operating system to literally any virtual address. The OnHexGetOffset method serves exactly for the Flat<->Virtual offset converting purpose.

Enum of commands that can be executed within HexCtrl.

enum class EHexCmd : std::uint8_t {
    CMD_SEARCH_DLG = 0x01, CMD_SEARCH_NEXT, CMD_SEARCH_PREV,
    CMD_NAV_GOTO_DLG, CMD_NAV_REPFWD, CMD_NAV_REPBKW, CMD_NAV_DATABEG, CMD_NAV_DATAEND,
    CMD_NAV_PAGEBEG, CMD_NAV_PAGEEND, CMD_NAV_LINEBEG, CMD_NAV_LINEEND, CMD_GROUPDATA_BYTE,
    CMD_GROUPDATA_WORD, CMD_GROUPDATA_DWORD, CMD_GROUPDATA_QWORD, CMD_GROUPDATA_INC, CMD_GROUPDATA_DEC,
    CMD_BKM_ADD, CMD_BKM_REMOVE, CMD_BKM_NEXT, CMD_BKM_PREV, CMD_BKM_REMOVEALL, CMD_BKM_DLG_MGR,
    CMD_CLPBRD_COPY_HEX, CMD_CLPBRD_COPY_HEXLE, CMD_CLPBRD_COPY_HEXFMT, CMD_CLPBRD_COPY_TEXTCP,
    CMD_CLPBRD_COPY_BASE64, CMD_CLPBRD_COPY_CARR, CMD_CLPBRD_COPY_GREPHEX, CMD_CLPBRD_COPY_PRNTSCRN,
    CMD_CLPBRD_COPY_OFFSET, CMD_CLPBRD_PASTE_HEX, CMD_CLPBRD_PASTE_TEXTUTF16, CMD_CLPBRD_PASTE_TEXTCP,
    CMD_MODIFY_OPERS_DLG, CMD_MODIFY_FILLZEROS, CMD_MODIFY_FILLDATA_DLG, CMD_MODIFY_UNDO, CMD_MODIFY_REDO,
    CMD_SEL_MARKSTARTEND, CMD_SEL_ALL, CMD_SEL_ADDLEFT, CMD_SEL_ADDRIGHT, CMD_SEL_ADDUP,
    CMD_SEL_ADDDOWN, CMD_DATAINTERP_DLG, CMD_CODEPAGE_DLG, CMD_APPEAR_FONT_DLG, CMD_APPEAR_FONTINC,
    CMD_APPEAR_FONTDEC, CMD_APPEAR_CAPACINC, CMD_APPEAR_CAPACDEC, CMD_PRINT_DLG, CMD_ABOUT_DLG,
    CMD_CARET_LEFT, CMD_CARET_RIGHT, CMD_CARET_UP, CMD_CARET_DOWN,
    CMD_SCROLL_PAGEUP, CMD_SCROLL_PAGEDOWN,
    CMD_TEMPL_APPLYCURR, CMD_TEMPL_DISAPPLY, CMD_TEMPL_DISAPPALL, CMD_TEMPL_DLG_MGR
};

Enum of the data type used in the HEXMODIFY struct with the EHexModifyMode::MODIFY_OPERATION mode.

enum class EHexDataType : std::uint8_t {
    DATA_INT8, DATA_UINT8, DATA_INT16, DATA_UINT16, DATA_INT32,
    DATA_UINT32, DATA_INT64, DATA_UINT64, DATA_FLOAT, DATA_DOUBLE
};

Enum of the data modification modes, used in HEXMODIFY.

enum class EHexModifyMode : std::uint8_t {
    MODIFY_ONCE, MODIFY_REPEAT, MODIFY_OPERATION, MODIFY_RAND_MT19937, MODIFY_RAND_FAST
};

Enum of the data operation modes, used in HEXMODIFY when HEXMODIFY::enModifyMode is set to MODIFY_OPERATION.

enum class EHexOperMode : std::uint8_t {
    OPER_ASSIGN, OPER_ADD, OPER_SUB, OPER_MUL, OPER_DIV, OPER_CEIL, OPER_FLOOR, OPER_OR,
    OPER_XOR, OPER_AND, OPER_NOT, OPER_SHL, OPER_SHR, OPER_ROTL, OPER_ROTR, OPER_SWAP,
    OPER_BITREV
};

Enum of all HexCtrl‘s internal windows, used in the GetWndHandle method.

enum class EHexWnd : std::uint8_t {
    WND_MAIN, DLG_BKMMGR, DLG_DATAINTERP, DLG_MODIFY,
    DLG_SEARCH, DLG_ENCODING, DLG_GOTO, DLG_TEMPLMGR
};

During its work the HexCtrl sends notification messages to its parent window through WM_NOTIFY mechanism.
The LPARAM of the WM_NOTIFY message contains a pointer to the NMHDR standard Windows struct. Depending on the notification message LPARAM can then be casted to a pointer to another struct, see the messages description for details.

Sent if a bookmark is clicked, LPARAM contains a pointer to the HEXBKMINFO struct.

Sent when a context menu is about to be displayed, LPARAM contains a pointer to the HEXMENUINFO struct. You can disable menu showing-up by setting the PHEXMENUINFO->fShow flag to false in response to this message.

Sent to indicate that the HexCtrl‘s window is about to be destroyed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Bookmark Manager dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Codepage dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Data interpreter dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Go to dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Modify Data dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Search dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the Template Manager dialog is about to be displayed, LPARAM contains a pointer to the NMHDR struct.

Sent when a user-defined custom menu has been clicked, LPARAM contains a pointer to the HEXMENUINFO struct.

Sent when the capacity has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the caret position has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the codepage of the text area has changed, LPARAM contains a pointer to the NMHDR struct.

Sent to indicate that the data has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when font has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when the data grouping size has changed, LPARAM contains a pointer to the NMHDR struct.

Sent when a selection has been made, LPARAM contains a pointer to the NMHDR struct.

This software is available under “The HexCtrl License”, it is free for any NON-COMMERCIAL use.
See the LICENSE file.

Required dependencies requirements.txt

python >=3.8, <= 3.10
disnake >= 2.4.0    #(it's really recommended to use 2.6.0)

To install the required dependencies you can run:

• with bash

pip install -r requirements.txt

• with poetry

poetry install

• Using git

git clone https://github.com/Snipy7374/disnake-ext-paginator

from disnake_ext_paginator import Paginator
import disnake
from disnake.ext import commands

bot = commands.Bot(
    command_prefix=commands.when_mentioned,
    intents=disnake.Intents.default()
)

@bot.slash_command()
async def test_command(inter: disnake.ApplicationCommandInteraction) -> None:

    # Create a list of embeds to paginate.
    embeds = [
        disnake.Embed(
            title="First embed"
        ),
        disnake.Embe(
            title="Second embed"
        ),
        disnake.Embed(
            title="Third embed"
        ),
    ]
    await Paginator().start(inter, pages=embeds)

bot.run('TOKEN')

from disnake_ext_paginator import Paginator
import disnake
from disnake.ext import commands

bot = commands.Bot(
    command_prefix=commands.when_mentioned,
    intents=disnake.Intents.default()
)

@bot.slash_command()
async def test_command(inter: disnake.ApplicationCommandInteraction) -> None:

    # Create a list of embeds to paginate.
    embeds = [
        disnake.Embed(
            title="First embed"
        ),
        disnake.Embe(
            title="Second embed"
        ),
        disnake.Embed(
            title="Third embed"
        ),
    ]
    paginator = Paginator(
        timeout=400,
        previous_button=disnake.ui.Button(...),
        next_button=disnake.ui.Button(...),
        trash_button=disnake.ui.Button(...),
        page_counter_separator="-",
        page_counter_style=disnake.ButtonStyle.danger,
        initial_page=1,
        on_timeout_message="Paginator expired",
        interaction_check=False # this will allow all users to interact with the paginator
    )
    await paginator.start(inter, pages=embeds)

bot.run('TOKEN')

class disnake_ext_paginator.Paginator(
    timeout: Union[int, float, None] = 60,
    previous_button: Optional[disnake.ui.Button] = None,
    next_button: Optional[disnake.ui.Button] = None,
    trash_button: Optional[disnake.ui.Button] = None,
    page_counter_separator: str = "https://github.com/",
    page_counter_style: disnake.ButtonStyle = disnake.ButtonStyle.grey,
    initial_page: int = 0,
    on_timeout_message: Optional[str] = None,
    interaction_check: bool = True,
    interaction_check_message = Union[disnake.Embed, str] = disnake.Embed(...),
    ephemeral: bool = False,
    persistent: bool = False
)

timeout: int

• How long the Paginator should timeout in, after the last interaction. (In seconds) (Overrides default of 60)

Note

If you’re using a persistent paginator then this must be setted to None.

previous_button: disnake.ui.Button

• Overrides default previous button. If not provided or None a default button will be used.

next_button: disnake.ui.Button

• Overrides default next button. If not provided or None a default button will be used.

trash_button: disnake.ui.Button

• Overrides default trash Button. If not provided or None a default button will be used.

page_counter_separator: str

• The separator between page numbers.

page_counter_style: disnake.ButtonStyle

• Overrides default page counter style.

initial_page: int

• Page to start the pagination on.

on_timeout_message: Optional[str]

• Overrides default on_timeout str set as embed footer.
  If None no message will appear on_timeout.

interaction_check: bool

• Check whether the users interacting with the paginator are the onwer
  of the command or not. Default set to True.

interaction_check_message: Union[disnake.Embed, str]

• The message to send when an interaction_check fails e.g a user
  who is not the command owner attempeted to interact with the paginator.
  This feature can be disabled setting interaction_check to False.

ephemeral: bool

• Whether the paginator should only be visible to the command invokator or
  to anyone else.

persistent: bool

• Makes the Paginator pesistent.

Warning

The use of persistent paginators is not recommended as the paginator needs to be cahed in memory. (Soon there’ll be an update to use low_level_components to save memory)

Warning

You must pay attention while using persistent paginators, if used in a normal with several command invokations the memory could be filled completely causing the Bot to crash. This should be used only for single paginators instances e.g. persistent panels that can’t be generated by users with a command invokation.

def disnake_ext_paginator.Paginator.start(
    interaction: disnake.ApplicationCommandInteraction,
    pages: list[disnake.Embed]
)

interaction: disnake.ApplicationCommandInteraction

• The slash command interaction.

pages: list[disnake.Embed]

• A list of disnake.Embed objects.

• If the user is attempting to starts two paginators in the same command function body or if the user is attempting to use the same Paginator object to start a paginator twice.

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Discord – Snipy#7374

MIT – (Snipy7374/disnake-ext-paginator)

MIT – (soosBot-com/Pagination)

AWS Cognito package using the AWS SDK for PHP

This package provides a simple way to use AWS Cognito authentication in Laravel for Web and API Auth Drivers. The idea of this package, and some of the code, is based on the package from Pod-Point which you can find here: Pod-Point/laravel-cognito-auth, black-bits/laravel-cognito-auth and tymondesigns/jwt-auth.

DEMO Application. You can try and register and login. For the first time, it will force the user to change password. The source code of the demo application is also available of the GitHub.

We decided to use it and contribute it to the community as a package, that encourages standarised use and a RAD tool for authentication using AWS Cognito.

• Registration and Confirmation E-Mail (Sign Up)
• Forced password change at first login (configurable)
• Login (Sign In)
• Token Validation for all Session and Token Guard Requests
• Remember Me Cookie
• Single Sign On Updated (Fix: Issue #86)
• Forgot Password (Resend – configurable)
• User Deletion
• Edit User Attributes
• Reset User Password
• Confirm Sign Up
• Easy API Token handling (uses the cache driver)
• DynamoDB support for Web Sessions and API Tokens (useful for server redundency OR multiple containers)
• Easy configuration of Token Expiry (Manage using the cognito console, no code or configurations needed)
• Support for App Client without Secret
• Support for Cognito Groups, including assigning a default group to a new user
• Session (Web) now has AccessToken and RefreshToken as part of the claim object
• Logout (Sign Out) – Remove access tokens from AWS
• Forced Logout (Sign Out) – Revoke the RefreshToken from AWS
• MFA Implementation for Session and Token Guards
• Password validation based on Cognito Configuration
• Mapping Cognito User using Subject UUID NEW

You can install the package via composer.

composer require ellaisys/aws-cognito

Using a version prior to Laravel 5.5 you need to manually register the service provider.

    // config/app.php
    'providers' => [
        ...
        Ellaisys\Cognito\Providers\AwsCognitoServiceProvider::class,
        
    ];

    php artisan vendor:publish --provider="Ellaisys\Cognito\Providers\AwsCognitoServiceProvider"

Last but not least you want to change the auth driver. To do so got to your config\auth.php file and change it to look the following:

    'guards' => [
        'web' => [
            'driver' => 'cognito-session', // This line is important for using AWS Cognito as Web Driver
            'provider' => 'users',
        ],
        'api' => [
            'driver' => 'cognito-token', // This line is important for using AWS Cognito as API Driver
            'provider' => 'users',
        ],
    ],

The AWS Cognito service provider registers its own database migration directory, so remember to migrate your database after installing the package. The AWS Cognito migrations will add a few columns to your users table:

    php artisan migrate

If you need to overwrite the migrations that ship with AWS Cognito, you can publish them using the vendor:publish Artisan command:

    php artisan vendor:publish --tag="cognito-migrations"

If you would like to prevent AWS Cognito’s migrations from running entirely, you may use the ignoreMigrations method provided by AWS Cognito. Typically, this method should be called in the register method of your AppServiceProvider:

    use Ellaisys\Cognito\AwsCognito;
    
    /**
     * Register any application services.
     */
    public function register(): void
    {
        AwsCognito::ignoreMigrations();
    }

In order to use AWS Cognito as authentication provider, you require a Cognito User Pool.

If you haven’t created one already, go to your Amazon management console and create a new user pool.

Next, generate an App Client. This will give you the App client id and the App client secret you need for your .env file.

IMPORTANT: Don’t forget to activate the checkbox to Enable sign-in API for server-based Authentication. The Auth Flow is called: ADMIN_USER_PASSWORD_AUTH (formerly ADMIN_NO_SRP_AUTH)

You also need a new IAM Role with the following Access Rights:

• AmazonCognitoDeveloperAuthenticatedIdentities
• AmazonCognitoPowerUser
• AmazonESCognitoAccess

From this IAM User you must use the AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in the laravel environment file.

Add the following fields to your .env file and set the values according to your AWS settings:

    # AWS configurations for cloud storage
    AWS_ACCESS_KEY_ID="Axxxxxxxxxxxxxxxxxxxxxxxx6"
    AWS_SECRET_ACCESS_KEY="mxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+"

    # AWS Cognito configurations
    AWS_COGNITO_CLIENT_ID="6xxxxxxxxxxxxxxxxxxxxxxxxr"
    AWS_COGNITO_CLIENT_SECRET="1xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx1"
    AWS_COGNITO_USER_POOL_ID="xxxxxxxxxxxxxxxxx"
    AWS_COGNITO_REGION="xxxxxxxxxxx" //optional - default value is 'us-east-1'
    AWS_COGNITO_VERSION="latest" //optional - default value is 'latest'

For more details on how to find AWS_COGNITO_CLIENT_ID, AWS_COGNITO_CLIENT_SECRET and AWS_COGNITO_USER_POOL_ID for your application, please refer COGNITOCONFIG File

If you are already working on an existing project and want to integrate Cognito you have to import a user csv file to your Cognito Pool.

Our package is providing you 6 traits you can just add to your Auth Controllers to get our package running.

• Ellaisys\Cognito\Auth\AuthenticatesUsers
• Ellaisys\Cognito\Auth\RegistersUsers
• Ellaisys\Cognito\Auth\ResetsPasswords
• Ellaisys\Cognito\Auth\RespondsMFAChallenge
• Ellaisys\Cognito\Auth\SendsPasswordResetEmails
• Ellaisys\Cognito\Auth\VerifiesEmails

In the simplest way you just go through your Auth Controllers and change namespaces from the traits which are currently implemented from Laravel.

You can change structure to suit your needs. Please be aware of the @extend statement in the blade file to fit into your project structure. At the current state you need to have those 4 form fields defined in here. Those are token, email, password, password_confirmation.

With our package and AWS Cognito we provide you a simple way to use Single Sign-Ons. For configuration options take a look at the config cognito.php.

When you want SSO enabled and a user tries to login into your application, the package checks if the user exists in your AWS Cognito pool. If the user exists, he will be created automatically in your database provided the add_missing_local_user is to true, and is logged in simultaneously.

That’s what we use the fields sso_user_model and cognito_user_fields for. In sso_user_model you define the class of your user model. In most cases this will simply be App\Models\User.

With cognito_user_fields you can define the fields which should be stored in Cognito. Put attention here. If you define a field which you do not send with the Register Request this will throw you an InvalidUserFieldException and you won’t be able to register.

Now that you have registered your users with their attributes in the AWS Cognito pool and your database and you want to attach a second app which should use the same pool. Well, that’s actually pretty easy. You can use the API provisions that allows multiple projects to consume the same AWS Cognito pool.

*IMPORTANT: if your users table has a password field you are not going to need this anymore. What you want to do is set this field to be nullable, so that users can be created without passwords. From now on, Passwords are stored in Cognito.

Any additional registration data you have, for example firstname, lastname needs to be added in cognito.php cognito_user_fields config to be pushed to Cognito. Otherwise they are only stored locally and are not available if you want to use Single Sign On’s.*

In case the user has not activated the account, AWS Cognito as a default feature does not allow user of use the forgot password feature. We have introduced the AWS documented feature that allows the password to be resent.

We have made this configurable for the developers so that they can use it as per the business requirement. The configuration takes a boolean value. Default is true (allows resend of forgot password)

    AWS_COGNITO_ALLOW_FORGOT_PASSWORD_RESEND=true

In case you are using this library as API driver, you can register the middleware into the kernal.php in the $routeMiddleware

    protected $routeMiddleware = [
        ...
        'aws-cognito' => \Ellaisys\Cognito\Http\Middleware\AwsCognitoAuthenticate::class
    ]

To use the middleware into the Web routes, you can use the std auth middleware as shown below

    Route::middleware('auth')->get('user', 'NameOfTheController@functionName');

To use the middleware into the API routes, as shown below

    Route::middleware('aws-cognito')->get('user', 'NameOfTheController@functionName');

As a default, if you are registering a new user with Cognito, Cognito will send you an email during signUp that includes the username and temporary password for the users to verify themselves.

Using this library in conjunction with AWS Lambda, once can look to customize the email template and content. The email template can be text or html based. The Lambda code for not included in this code repository. You can create your own. Any object (array) that you pass to the registration method is transferred as is to the lambda function, we are not prescriptive about the attribute names.

We have made is very easy for anyone to use the default behaviour.

1. You don’t need to create an extra field to store the verification token.
2. You don’t have to bother about the Sessions or API tokens, they are managed for you. The session or token is managed via the standard mechanism of Laravel. You have the liberty to keep it where ever you want, no security loop holes.
3. If you use the trait provided by us ‘Ellaisys\Cognito\Auth\RegistersUsers’, the code will be limited to just a few lines
4. if you are using the Laravel scafolding, then make the password nullable in DB or drop it from schema. Passwords will be only managed by AWS Cognito.

    use Ellaisys\Cognito\Auth\RegistersUsers;

    class UserController extends BaseController
    {
        use RegistersUsers;

        public function register(Request $request)
        {
            $validator = $request->validate([
                'name' => 'required|max:255',
                'email' => 'required|email|max:64|unique:users',
                'password' => 'sometimes|confirmed|min:6|max:64',
            ]);

            //Create credentials object
            $collection = collect($request->all());
            $data = $collection->only('name', 'email', 'password'); //passing 'password' is optional.

            //Register User in cognito
            if ($cognitoRegistered=$this->createCognitoUser($data)) {

                //If successful, create the user in local db
                User::create($collection->only('name', 'email'));
            } //End if

            //Redirect to view
            return view('login');
        }
    }

5. You don’t need to turn off Cognito to send you emails. We rather propose the use of AWS Cognito or AWS SMS mailers, such that user credentials are always secure.

6. In case you want to suppress the mails to be sent to the new users, you can configure the parameter given below to skip welcome mails to new user registration. Default configuration shall send the welcome email.

    AWS_COGNITO_NEW_USER_MESSAGE_ACTION="SUPPRESS"

7. The configuration given below allows the new user’s email address to be auto marked as verified.

    AWS_COGNITO_FORCE_NEW_USER_EMAIL_VERIFIED=true //optional - default value is false.

8. To assign a default group to a new user when registering set a name of the user group as per the configuration done via AWS Cognito Management Console. The default value is set to null.

    AWS_COGNITO_DEFAULT_USER_GROUP="Customers"

9. To enable custom password or user defined password, the below configuration if set to true will force the user to set the password during registration, else cognito will generate a random password and send over email and/or SMS based on the configurations.

    AWS_COGNITO_FORCE_NEW_USER_PASSWORD=true //optional - default value is false.  

We have provided you with a useful trait that make the authentication very simple (with Web or API routes). You don’t have to worry about any additional code to manage sessions and token (for API).

The trait takes in some additional parameters, refer below the function signature of the trait. Note that the function takes the object of Illuminate\Support\Collection instead of Illuminate\Http\Request. This will allow you to use this function in any tier of the code.

Also, the ‘guard’ name reference is passed, so that you can reuse the function for multiple guard drivers in your project. The function has the capability to handle the Session and Token Guards with multiple drivers and providers as defined in /config/auth.php

    namespace Ellaisys\Cognito\Auth;

    protected function attemptLogin (
        Collection $request, string $guard='web', 
        string $paramUsername='email', string $paramPassword='password', 
        bool $isJsonResponse=false
    ) {
        ...
        ...


        ...
    }

In case you want to use this trait for Web login, you can write the code as shown below in the AuthController.php

    namespace App\Http\Controllers;

    ...

    use Ellaisys\Cognito\AwsCognitoClaim;
    use Ellaisys\Cognito\Auth\AuthenticatesUsers as CognitoAuthenticatesUsers;

    class AuthController extends Controller
    {
        use CognitoAuthenticatesUsers;

        /**
         * Authenticate User
         * 
         * @throws \HttpException
         * 
         * @return mixed
         */
        public function login(\Illuminate\Http\Request $request)
        {
            ...

            //Convert request to collection
            $collection = collect($request->all());

            //Authenticate with Cognito Package Trait (with 'web' as the auth guard)
            if ($response = $this->attemptLogin($collection, 'web')) {
                if ($response===true) {
                    return redirect(route('home'))->with('success', true);
                } else if ($response===false) {
                    // If the login attempt was unsuccessful you may increment the number of attempts
                    // to login and redirect the user back to the login form. Of course, when this
                    // user surpasses their maximum number of attempts they will get locked out.
                    //
                    //$this->incrementLoginAttempts($request);
                    //
                    //$this->sendFailedLoginResponse($collection, null);
                } else {
                    return $response;
                } //End if
            } //End if

        } //Function ends

        ...
    } //Class ends

In case you want to use this trait for API based login, you can write the code as shown below in the AuthApiController.php

    namespace App\Api\Controller;

    ...

    use Ellaisys\Cognito\AwsCognitoClaim;
    use Ellaisys\Cognito\Auth\AuthenticatesUsers as CognitoAuthenticatesUsers;

    class AuthApiController extends Controller
    {
        use CognitoAuthenticatesUsers;

        /**
         * Authenticate User
         * 
         * @throws \HttpException
         * 
         * @return mixed
         */
        public function login(\Illuminate\Http\Request $request)
        {
            ...

            //Convert request to collection
            $collection = collect($request->all());

            //Authenticate with Cognito Package Trait (with 'api' as the auth guard)
            if ($claim = $this->attemptLogin($collection, 'api', 'username', 'password', true)) {
                if ($claim instanceof AwsCognitoClaim) {
                    return $claim->getData();
                } else {
                    return response()->json(['status' => 'error', 'message' => $claim], 400);
                } //End if
            } //End if

        } //Function ends


        ...
    } //Class ends

The logout methods are now part of the guard implementations, the logout method removes the access-tokens from AWS and also removes from Application Storage managed by this library. Just calling the auth guard logout method will be sufficient. You can implement it into the routes or controller based on your development preference.

The logout method now takes an optional boolean parameter (true) to revoke RefreshToken. The default value is (false) and that will persist the Refresh Token with AWS Cognito.

   ...

   Auth::guard('api')->logout();


   ...

   Auth::guard('api')->logout(true); //Revoke the Refresh Token.

You can use this trait for API to generate new token

    namespace App\Api\Controller;

    ...

    use Ellaisys\Cognito\AwsCognitoClaim;
    use Ellaisys\Cognito\Auth\RefreshToken;

    class AuthApiController extends Controller
    {
        use RefreshToken;

        /**
         * Generate a new token using refresh token.
         * 
         * @throws \HttpException
         * 
         * @return mixed
         */
        public function refreshToken(\Illuminate\Http\Request $request)
        {
            ...

            $validator = $request->validate([
                'email' => 'required|email',
                'refresh_token' => 'required'
            ]);
            
            try {
                return $this->refresh($request, 'email', 'refresh_token');
            } catch (Exception $e) {
                return $e;
            }

        } //Function ends


        ...
    } //Class ends

If you want to give your users the ability to delete themselves from your app you can use our deleteUser function from the CognitoClient.

To delete the user you should call deleteUser and pass the email of the user as a parameter to it. After the user has been deleted in your cognito pool, delete your user from your database too.

        $cognitoClient->deleteUser($user->email);
        $user->delete();

We have implemented a new config option delete_user, which you can access through AWS_COGNITO_DELETE_USER env var. If you set this config to true, the user is deleted in the Cognito pool. If it is set to false, it will stay registered. Per default this option is set to false. If you want this behaviour you should set USE_SSO to true to let the user restore themselves after a successful login.

To access our CognitoClient you can simply pass it as a parameter to your Controller Action where you want to perform the deletion.

    public function deleteUser(Request $request, AwsCognitoClient $client)

Laravel will take care of the dependency injection by itself.

    IMPORTANT: You want to secure this action by maybe security questions, a second delete password or by confirming 
    the email address.

If you have a deployment architecture, that involves multiple servers and you want to maintain the web sessions or API tokens across the servers, you can use the AWS DynamoDB. The library is capable of handling the DynamoDB with ease. All that you need to do is create the table in AWS DynamoDB and change a few configurations.

1. Go to the AWS Console and create a new table.
2. Enter the unique table name as per your preferences.
3. The primary key (or partition key) should be key of type string
4. Use default settings and click the Create button

Add/Edit the following fields to your .env file and set the values according to your AWS settings:

    # Cache Configuration
    CACHE_DRIVER="dynamodb"
    DYNAMODB_CACHE_TABLE="table-name-of-your-choice" //This should match the table name provided above

    # Session Configuration
    SESSION_DRIVER="dynamodb"
    SESSION_LIFETIME=120
    SESSION_DOMAIN="set-your-domain-name" //The domain name can be as per your preference
    SESSION_SECURE_COOKIE=true

    # DynamoDB Configuration
    DYNAMODB_ENDPOINT="https://dynamodb.us-west-2.amazonaws.com" // You can change the endpoint based of different regions

Refer the AWS DynamoDB Documentation and refer the endpoints provided in Service endpoints section.

Update the DynamoDB table for the TTL columns as expires_at

In case of the new cognito users, the AWS SDK will send a session key and the user is expected to change the password, in a forced mode. Make sure you force the users to change the password for the first login by new cognito user.

However, if you have an API based implementation, and want to automatically authenticate the user without forcing the password change, you may do that with below setting fields to your .env file

    AWS_COGNITO_FORCE_PASSWORD_CHANGE_API=false     //Make true for forcing password change
    AWS_COGNITO_FORCE_PASSWORD_AUTO_UPDATE_API=true //Make false for stopping auto password change

The library now supports where the AWS configuration of App Client with the Client Secret set to disabled. Use the below configuration into the environment file to enable/disable this. The default is marked as enable (i.e. we expect the App Client Secret to be enabled in AWS Cognito configuration)

   AWS_COGNITO_CLIENT_SECRET_ALLOW=false

This library fetches the password policy from the cognito pool configurations. The laravel request validations are done based on the regular expression that is created based on this policy. This validations are performed during the Sign Up (Registation), Sign In (Login), Reset and Change password based flows. The validation messages for the password are also dynamic in nature and change based on the configurations.

The library maps the Cognito user subject UUID with the local repository. Everytime a new user is created in cognito, the sub UUID is mapped with the local user table with an user specified column name.

The column in the local BD is identified with the config parameter user_subject_uuid with the default value set to sub.

However, to customize the column name in the local DB user table, you may do that with below setting fields to your .env file

    AWS_COGNITO_USER_SUBJECT_UUID="sub"
    

We are working on making sure that pipe character is handled soon.

Please see CHANGELOG for more information on what has changed recently.

If you discover any security related issues, please email support@ellaisys.com and also add it to the issue tracker.

https://github.com/ellaisys/aws-cognito/wiki/RoadMap

• Star this project on GitHub.
• Report bugs or suggest features by creating new issues or adding comments to issues
• Submit pull requests
• Spread the word by blogging about SimplCommerce or sharing it on social networks
• Donate to us

This project exists thanks to all the people who contribute.

• EllaiSys Team
• GitHub Contributors

Click on these badges to see how you might be able to help:

EllaiSys was a web and consulting agency specialized in Cloud Computing (AWS and Azure), DevOps, and Product Engneering. We closed our professional services offerings from Oct 2021, however the team continues to support the open source projects as our commitment towards the community. Anyone interested to support the development is welcome.

The MIT License (MIT). Please see License File for more information.

This package is currently in production ready mode with already a few implementations done. We would be happy to hear from you, about the defects or new feature enhancements. However, this being a free support, we would not be able to commit to support SLAs or timelines.

Sociahigh is a complete application developed using the concept of containerized microservices. This application includes a node with fastify and typescript backend, a react, tailwind and typescript frontend, nginx as http server and a custom npm package for use in the backend environment. Every microservice and the http server is containerized with docker. The purpose of the application is the management of small events, providing the management of guests, the items they are taking to the event and updating everyone about changes.

The first step after downloading the project is to create a docker network

docker network create \
  --driver=bridge \
  --subnet=171.1.0.0/16 \
  sociahigh_network

Build all the Docker images in the root of the main projects

docker build -t sociahigh_user_microservice ./sociahigh_user_microservice

docker build -t sociahigh_event_microservice ./sociahigh_event_microservice

docker build -t sociahigh_nginx ./ sociahigh_nginx

Run the containers

docker run -d \
  --name sociahigh_user_microservice \
  --restart always \
  -p 8800:8800 \
  --ip 171.1.0.88 \
  --network sociahigh_network \
  sociahigh_user_microservice

docker run -d \
  --name sociahigh_event_microservice \
  --restart always \
  -p 8900:8900 \
  --ip 171.1.0.89 \
  --network sociahigh_network \
  sociahigh_event_microservice

docker run -d \
  --name sociahigh_nginx \
  --restart always \
  -p 80:80 \
  --ip 171.1.0.80 \
  --network sociahigh_network \
  sociahigh_nginx

The server will go up at port 80 and you can call every microservice using it routes through nginx. You can run a portainer server using the command below:

docker volume create portainer_data
docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest

Go to the `sociahigh_frontend_web` folder and run the script:

npm run dev

The server will go up at port 5173

A POSTMAN COLLECTION IS INCLUDED IN THE PROJECT. So, you can import this collection and have fun.

See some system screens below

The complete database structure:

Ítalo Sérvio

If you need additional information, do not hesitate to contact me by email annbl.mrcn@gmail.com (Annabel)!

_________ English version bellow _________

Note : to create a new python environment allowing the execution of the code, execute the following command in the command prompt : “conda create -n <Dicmath_Microsoft> –file environment.txt”. The environment.txt file is given in the github repository.

Notre projet vise à développer un logiciel alimenté par l’IA pour aider les lycéens malvoyants à résoudre des équations mathématiques en utilisant leur voix. L’objectif est de permettre aux étudiants de dicter des équations, de recevoir un retour vocal de l’équation comprise par le logiciel et de naviguer pour les modifier. Les principaux utilisateurs seront des étudiants aveugles jusqu’au niveau bac et mais le logiciel permet également de fournir que des opérateurs mathématiques avancés (intégrales, etc.).

Pour atteindre cet objectif, nous avons utilisé plusieurs technologies et méthodes de travail. Tout d’abord, nous avons utilisé Whisper, un outil récent de Speech-To-Text de OpenAI pour transcrire la voix de l’utilisateur en équations mathématiques texte. Nous avons ensuite développé une fonction de traduction texte-Latex, qui est le format le plus adapté pour gérer des équations mathématiques. Enfin, nous avons utilisé des services cognitifs Microsoft Azure pour implémenter un bot Text-To-Speech pour relire les équations à l’utilisateur.

En ce qui concerne l’interface utilisateur, nous avons développé une interface graphique, basée sur Python, qui permet à l’utilisateur de dicter une équation mathématique via le microphone et affiche l’équation transcrite, en utilisant des technologies HTML, CSS et JS. L’interface est travaillée pour être simple et accessible : l’élève peut interagir avec l’interface avec la voix, grâce à des commandes vocales, ou grâce au clavier, l’utilisation de la souris étant impossible pour eux.

Pour assurer la qualité du logiciel, nous avons mis en place une méthode de travail en équipe, où chaque membre a été assigné à des tâches spécifiques. Certains membres ont travaillé sur l’interface graphique et d’autres encore sur l’intégration des services d’IA. Nous avons également effectué des tests utilisateur réguliers pour vérifier la facilité d’utilisation et la pertinence des fonctionnalités. Enfin, une fois que tous les modules ont été développés, nous les avons fusionnés en un seul projet pour créer une expérience utilisateur fluide. En plus d’être un défi technique car aucune technologie actuelle permet de faire ce que nous avons réalisé, cette expérience nous a permis d’aborder la notion d’accessibilité. Nous sommes extrêmement reconnaissants envers Microsoft de nous avoir offert cette opportunité.

Tout le module d’IA, de reconnaissance et retour vocal, sont 100% opérationnels. Cependant, il reste du travail, notamment sur l’interface et tout le module de navigation. Voici les pistes de travail que nous proposons :

• améliorer l’interface : la rendre plus accessible pour les malvoyants (couleurs, emplacement des boutons…)
• continuer le travail sur les commandes clavier pour pouvoir actionner TOUS les boutons de l’interface
• ajouter des commandes vocale pour activer les boutons de l’interface par la voix
• travailler l’affichage des équations (pour le moment, on affiche des images dont les dimentions sont fixes, il faudrait que la taille de l’image soit modulée par la longueur de l’équation pour ne pas la couper)

• permettre le changement de langue
• permettre le choix de la voix (sexe, rapidité de lecture…). Ces paramètres sont possibles avec le module Microsoft Azure que nous avons utilisé, il s’agit juste de relier les paramètres de l’interface et les variables dans la fonction Microsoft Azure.

• permettre de modifier une équation ou un élément de l’équation (qui est dans l’historique ou dans l’équation en court) Nous avons commencé un travail sur la navigation en fonctionnant sur des blocs séparés par les opérateurs +,-,*,/,(,), mais notre travail n’a pas été intégré à l’interface, n’hésitez pas à nous contacter pour plus de détail.

• développer un tuto d’utilisation (accessible aux malvoyanrs), détaillant les commandes et fonctionnalités de l’interface.
• aller voir des élèves lycées de l’INJA (Institut National des Jeunes Aveugles à Paris) et tester le logiciel
• tester également le logiciel sur des malvoyants (personnes dont la vision est réduite)

Our project aims to develop AI-powered software to help visually impaired high school students solve math equations using their voice. The goal is to allow students to dictate equations, receive voice feedback of the equation understood by the software, and navigate to edit them. The main users will be blind students up to baccalaureate level, but the software also makes it possible to provide only advanced mathematical operators (integrals, etc.).

To achieve this goal, we used several technologies and working methods. First, we used Whisper, a recent Speech-To-Text tool from OpenAI to transcribe the user’s voice into text math equations. We then developed a text-Latex translation function, which is the most suitable format for managing mathematical equations. Finally, we used Microsoft Azure Cognitive Services to implement a Text-To-Speech bot to read the equations back to the user.

Regarding the user interface, we have developed a graphical interface, based on Python, which allows the user to dictate a mathematical equation via the microphone and displays the transcribed equation, using HTML, CSS and JS technologies. . The interface is worked to be simple and accessible: the student can interact with the interface with the voice, thanks to voice commands, or thanks to the keyboard, the use of the mouse being impossible for them.

To ensure the quality of the software, we have implemented a teamwork method, where each member has been assigned to specific tasks. Some members worked on the GUI and still others on the integration of AI services. We also performed regular user testing to check the usability and relevance of features. Finally, once all the modules were developed, we merged them into a single project to create a smooth user experience. In addition to being a technical challenge because no current technology allows us to do what we have achieved, this experience allowed us to approach the notion of accessibility. We are extremely grateful to Microsoft for giving us this opportunity.

All the AI module, recognition and voice feedback, are 100% operational. However, there is still work to be done, especially on the interface and the entire navigation module. Here are the lines of work we offer:

• improve the interface: make it more accessible for the visually impaired (colors, location of buttons, etc.)
• continue working on the keyboard commands to be able to operate ALL the buttons of the interface
• add voice commands to activate interface buttons by voice
• work on the display of equations (for the moment, we display images whose dimensions are fixed, the size of the image should be modulated by the length of the equation so as not to cut it)

• allow language change
• allow the choice of the voice (sex, speed of reading…). These parameters are possible with the Microsoft Azure module that we used, it is just a matter of linking the interface parameters and the variables in the Microsoft Azure function.

• allow to modify an equation or an element of the equation (which is in the history or in the current equation) We have started a work on the navigation by working on blocks separated by the operators +,-,*,/,(,), but our work has not been integrated into the interface, do not hesitate to contact us for more detail.

• develop a user tutorial (accessible to the visually impaired), detailing the commands and features of the interface.
• go see high school students from INJA (National Institute for Young Blind People in Paris) and test the software
• also test the software on visually impaired people (people with reduced vision)

This is a python library that allows you to integrate middlewares-based system to your project. It contains base tools for creating and running middlewares with async-await style

import asyncio

import middletools


async def middleware1(request, call_next):
    print(f"Run middleware1 (request: {request})")
    response = await call_next()
    print(f"End middleware1 (response: {response})")
    return response


async def middleware2(request, call_next):
    print(f"Run middleware2 (request: {request})")
    response = await call_next()
    print(f"End middleware2 (response: {response})")
    return response


async def main():
    read_afterwords = await middletools.read_forewords(
        middleware1, middleware2,
        inbox_value=123  # Pass `request` value
    )
    print("Some other code...")
    await read_afterwords(456)  # Pass `response` value


asyncio.run(main())

Output is

Run middleware1 (request: 123)
Run middleware2 (request: 123)
Some other code...
End middleware2 (response: 456)
End middleware1 (response: 456)

python -m pip install middletools

python -m pip install https://github.com/deknowny/middlewares/archive/main.zip

The main idea is give an ability just passing the middlewares and inbox/outbox payload values in a few methods instead of running and saving middlewares state by hand

Standard case: a function runs RESTful API routers and requires a middleware that checks a header in client’s request

There are 2 endpoints for an abstract GET and POST methods

# Some abstract router
@router.get("https://github.com/")
async def route_get(request):
    return 200, {"response": "some content"}


@router.post("https://github.com/")
async def route_post(request):
    return 201, {"response": "ok"}

In the core of web framework you used a function like this that just call all routers

class Router:
    ...
    ...
    
    async def call_routers(self, request):
        for router in self.routers:
            ... # Pass request to routers and check it matched

middlewares library allows you easy integrate middleware system to your call_routers

import middletools

...
...

# Adding a middleware handler to an abstract 
@router.add_middleware
async def my_middleware(
    request: SomeRequest, call_next: middletools.types.CallNext
) -> SomeResponse:
    # Just check if header exists, id not set the default value
    if "X-Required-Header" not in request.headers:
        request.header["X-Required-Header"] = "default"
    response = await call_next()
    return response

Here we add a header to client request if clint didn’t do it. Then await call_next() give control to other middlewares or to our call_routers handler and response from this is the value call_next() returns

call_routers should looks like this

import typing

import middletools


class Router:
    # You can use generics to describe middleware hand;er
    middlewares: typing.List[
        middletools.types.MiddlewareHandler[
            SomeRequest, SomeResponse
        ]
    ]
    ...
    ...

    async def call_routers(self, request):
        read_afterwords = await middletools.read_forewords(
            *self.middlewares, inbox_value=request
        )
        for router in self.routers:
            ... # Pass request to routers and check it matched
            response = ...
            await read_afterwords(response)
            break