LRESULT npp(UINT Msg, WPARAM wParam, LPARAM lParam)

Sends a message to Notepad++. See this documentation for descriptions of the available messages. Example:
intptr_t cdi1 = npp(NPPM_GETCURRENTDOCINDEX, 0, 0);

sci.function

Sends a message to a Scintilla control. Arguments and return values vary depending on the function; see Using Scintilla.

std::string fromWide(std::wstring_view s, unsigned int codepage)
std::string fromWide(std::wstring_view s)

Converts a wide string to a byte string. If codepage is omitted, it uses the code page of the active Scintilla (which will be either the system default code page or CP_UTF8; don’t let the code page default when processing a Notepad++ notification other than NPPN_BUFFERACTIVATED unless you have called plugin.getScintillaPointers to establish the correct active Scintilla).

std::wstring toWide(std::string_view s, unsigned int codepage)
std::wstring toWide(std::string_view s)

Converts a byte string to a wide string. If codepage is omitted, it uses the code page of the active Scintilla (which will be either the system default code page or CP_UTF8; don’t let the code page default when processing a Notepad++ notification other than NPPN_BUFFERACTIVATED unless you have called plugin.getScintillaPointers to establish the correct active Scintilla).

std::wstring GetWindowString(HWND hWnd)
std::wstring GetDlgItemString(HWND hwndDlg, int item)

Gets the text of a window or a control in a dialog as a wide string. Specify the window handle of the window, or the window handle of the dialog and the control identifier of the control.

bool ShowBalloonTip(HWND hwndDlg, int item, const std::wstring& text)

Shows text as a balloon tip on an edit control in a dialog. Specify the window handle of the dialog as hwndDlg; item specifies the control identifier of an edit control, a combo box or a spin control with an edit control buddy. Returns true if the request is successful.

std::wstring getFilePath(UINT_PTR buffer)
std::wstring getFilePath()

Gets the full path of a file open in Notepad++ as a std::wstring.

• If an argument is supplied, it is the Notepad++ buffer id to be examined.
• If no argument is given, the current buffer is examined; this only works in commands and NPPN_BUFFERACTIVATED notifications, since in Scintilla notifications and most Notepad++ notifications, the "current buffer" is not necessarily meaningful.
• Returns L"" if there is no such buffer id.

std::wstring getFileExtension(const std::wstring& filepath)
std::wstring getFileExtension(UINT_PTR buffer)
std::wstring getFileExtension()

Gets the file extension, converted to lower case, from a path, a buffer id or the current buffer.

• If a string is supplied, it is parsed to isolate the file extension.
• If a numeric argument is supplied, it is the Notepad++ buffer id to be examined.
• If no argument is given, the current buffer is examined; this only works in commands and NPPN_BUFFERACTIVATED notifications, since in Scintilla notifications and most Notepad++ notifications, the "current buffer" is not necessarily meaningful.
• Returns L"." for a file with no extension, L"" for a non-path (i.e., without a backslash, e.g., "new 1") or if there is no such buffer id.

DialogStretch name;
...
name.setup(dialog-window-handle);
...
name.adjust(control-ID, xStretch, yStretch, xMove, yMove)[.adjust(...)...];

DialogStretch helps manage the sizing and placement of controls in resizable dialogs. Settings.cpp and Watcher.cpp include examples of its use. A full description of the structure is in the DialogStretch section of this help. To use it:

• Define an instance of DialogStretch outside your dialog procedure, or as static within your procedure, so that it will persist throughout the life of the dialog.
• When you process WM_INITDIALOG, before doing anything that would resize the dialog from the size implied by its template, call the setup function with the handle to the dialog window as argument. This will analyze and record the default size and placement of your dialog and its controls.
• Process WM_SIZE. Upon receiving that message, call the adjust function for each control that should be moved or sized when the dialog size changes. Specify the control ID of the control and one to four doubles representing the fraction of the change in horizontal and vertical size of the dialog that should be applied to the horizontal and vertical size and position of the control. For example, if IDC_BUTTON1 is meant to stay centered at the bottom of the dialog — so that it should not change size, should move to the right half as far as the dialog increases in width and should move downward as far as the dialog increases in height — write adjust(IDC_BUTTON1, 0, 0, .5, 1).
• You can chain adjust calls for all the controls in the dialog one after another. This is (slightly) more efficient than calling each one independently on the DialogStretch object.

template<typename T> struct config {

    std::string name;
    nlohmann::json* store;
    T value;
    bool loaded = false;

    static bool peek(T& v, const nlohmann::json& j, std::string_view n);
    static bool peek(T& v, HWND w);
    static bool peek(T& v, HWND w, int id);

    T peek(const nlohmann::json& j, std::string_view n) const;
    T peek(HWND w)                                      const;
    T peek(HWND w, int id)                              const;

    static void show(HWND w, const T& v);
    static void show(HWND w, int id, const T& v);

    T& get(const nlohmann::json& j, std::string_view n);
    T& get(HWND w);
    T& get(HWND w, int id);
    T& get();

    const T& put(nlohmann::json& j, std::string_view n) const;
    const T& put(HWND w);
    const T& put(HWND w, int id);

    operator T&();
    config<T>& operator=(const T& v);

    config(const T& initial);
    config(const std::string& name, const T& initial, nlohmann::json& store = configuration);

};

    config<typename T>(const T& initial);
    config<typename T>(const std::string& name, const T& initial, nlohmann::json& store = configuration);

Constructs a config object.

• T specifies the C++ type on which this configuration item is based. You can use any type supported by nlohmann::json; src\Framework\ConfigUtility.h includes a specialization for nlohmann::adl_serializer<std::wstring> which adds support for std::wstring.
• name (usually given as a character literal) specifies the name used for this variable in json objects. If name is omitted, a json object is never accessed unless explicitly specified in a call to peek, get or put.
• store specifies the nlohmann::json object in which values are stored. If omitted when name is specified, the global object configuration is used.
• initial specifies an initial value for the variable.
• You normally use the get and put functions, assignment, and implicit or explicit conversion to type T to access the value of a config variable. If the first access is through assignment or get with an HWND, the assigned or retrieved value is set and, if name was specified, a copy is written to the json store. If the first access is through conversion, get without arguments or put with an HWND and name was specified, an attempt is made to read the value from the json store; if the attempt fails, or if name was not specified, the initial value is used.
• When T is bool, functions that take an HWND assume the designated control is a checkbox.
• When T is an integral type other than bool, functions that take an HWND assume the designated control is either an edit control or a spin control (which can have an edit control buddy).
• When T is std::wstring or a floating point type, functions that take an HWND assume the designated control is an edit control.
• When T is not an arithmetic type or std::wstring, functions that take an HWND are not available.
• In all cases, functions which include:
  HWND w, int id
  among their parameters are equivalent to the same-named functions with HWND w and no int id, substituting:
  GetDlgItem(w, id)
  for w.

std::string name

The name member contains the name under which the variable is saved in a json store. Normally you should set this using the name argument to the config constructor and never change it.

nlohmann::json* store

The store member contains a pointer to the json store in which a copy of this variable is kept, or null if no store is used. Normally you should let the constructor set this to the address of the global configuration object (or to null if name is not specified) and never change it.

T value

Ordinarily, you should use implict or explicit conversion to type T or the get() member function without arguments to read the value of a config variable, and assignment or one of the get functions with an HWND to update it, since these will maintain synchronization with the json store. However, you can access the value directly using the value member.

bool loaded

The loaded member is initially false, and is set to true when any operation (other than direct access to the value member) sets the value of the variable. Its purpose is to control reading from the json store: once a value has been set, whatever value is present is used, and the json store is not read again.

static bool peek(T& v, const nlohmann::json& j, std::string_view n);
static bool peek(T& v, HWND w);
static bool peek(T& v, HWND w, int id);

T peek(const nlohmann::json& j, std::string_view n) const;
T peek(HWND w)                                      const;
T peek(HWND w, int id)                              const;

The peek member functions retrieve a value from either a json object or a Windows control without setting the value member.

• The versions which return a bool return true if the value was successfully retrieved and false otherwise. The versions which return a value return the current value of value if retrieval was unsuccessful.
• v is a reference to a variable of the same type as the template parameter type. If retrieval is successful, it is set to the retrieved value; otherwise it is unchanged.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object the value of which is to be retrieved.
• w specifies the window handle, or the window handle of the parent window, of the control from which the value is to be retrieved.
• id specifies the resource identifier of the control from which a value is to be retrieved; w is a handle to the parent of the control to be examined (e.g., a dialog). When no id is specified, w is the handle of the control itself.
• If a window handle is given and the template type is bool, the control must be a checkbox.
• If a window handle is given and the template type is an integral type other than bool, the control must be either an edit control or a spin control (which can have an edit control buddy).
• If a window handle is given and the template type is std::wstring or a floating point type, the control must be an edit control.
• If the template type is not an arithmetic type or std::wstring, the member functions that take a window handle will not be available.

static void show(HWND w, const T& v)
static void show(HWND w, int id, const T& v)

The show member functions display a value in a Windows control. They don’t use any data in the config object, but the template type parameter determines the type of Windows controls they can address.

• w specifies the window handle, or the window handle of the parent window, of the control in which the value is to be displayed.
• id specifies the resource identifier of the control in which a value is to be displayed; w is a handle to the parent of the control to be updated (e.g., a dialog). When no id is specified, w is the handle of the control itself.
• v is a const reference to a variable of the same type as the template parameter type.
• If the template type is bool, the control must be a checkbox.
• If the template type is an integral type other than bool, the control must be either an edit control or a spin control (which can have an edit control buddy).
• If the template type is std::wstring or a floating point type, the control must be an edit control.
• If the template type is not an arithmetic type or std::wstring, the show member functions will not be available.

T& get(const nlohmann::json& j, std::string_view n);
T& get(HWND w)
T& get(HWND w, int id)
T& get()

The get member functions retrieve a value from either a json object or a Windows control and set the value member. All versions return a reference to value. If the attempt to retrieve a value is unsuccessful, value is not changed.

• get(), with no arguments, attempts to retrieve the value corresponding to name from the associated json store (usually the global configuration object) if name was specified in the constructor and loaded is false. In all other cases, or if the attempt to retrieve the value fails, get() returns value unchanged.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object the value of which is to be retrieved.
• id specifies the resource identifier of the control from which a value is to be retrieved; w is a handle to the parent of the control to be examined (e.g., a dialog). When no id is specified, w is the handle of the control itself.
• If a window handle is given and the template type is bool, the control must be a checkbox.
• If a window handle is given and the template type is an integral type other than bool, the control must be either an edit control or a spin control (which can have an edit control buddy).
• If a window handle is given and the template type is std::wstring or a floating point type, the control must be an edit control.
• If the template type is not an arithmetic type or std::wstring, the member functions that take a window handle will not be available.

const T& put(nlohmann::json& j, std::string_view n) const;
const T& put(HWND w)
const T& put(HWND w, int id)

The put member functions copy the value of a config object to a json object or a Windows control. All versions return a constant reference to value.

• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object the value of which is to be set to value. This form of put never changes value.
• w specifies the window handle, or the window handle of the parent window, of the control in which the value is to be displayed. This form of put (with or without id) can change value. If name was specified in the constructor and loaded is false, put-to-HWND first attempts to retrieve the value corresponding to name from the json store. In all other cases, or if the attempt to retrieve the value fails, value is unchanged. Regardless of whether retrieval was successful, value is copied to the specified Windows control.
• id specifies the resource identifier of the control in which a value is to be displayed; w is a handle to the parent of the control to be updated (e.g., a dialog). When no id is specified, w is the handle of the control itself.
• If a window handle is given and the template type is bool, the control must be a checkbox.
• If a window handle is given and the template type is an integral type other than bool, the control must be either an edit control or a spin control (which can have an edit control buddy).
• If a window handle is given and the template type is std::wstring or a floating point type, the control must be an edit control.
• If the template type is not an arithmetic type or std::wstring, the member functions that take a window handle will not be available.

operator T&()

Conversion to template type is identical to get().

config<T>& operator=(const T& v)

Assignment assigns the right-side value to value and sets loaded to true. If name was specified in the constructor it then writes the new value to the name member of the associated json store (usually the global configuration object).

struct config_history {

    const std::string name;
    nlohmann::json* store;
    std::vector<std::wstring> history;
    int depth;
    bool retainBlank;
    bool retainDuplicate;
    bool retainEmpty;
    bool loaded = false;

    std::wstring& value();
    const std::wstring& value() const;

    static bool peek(std::vector<std::wstring>& v, const nlohmann::json& j, std::string_view n);
    static std::wstring peek(HWND w);
    static std::wstring peek(HWND w, int id);

    static void show(HWND w, const std::wstring& s);
    static void show(HWND w, int id, const std::wstring& s);

    std::wstring& get(const nlohmann::json& j, std::string_view n);
    std::wstring& get(HWND w);
    std::wstring& get(HWND w, int id);
    std::wstring& get();

    const std::wstring& put(nlohmann::json& j, std::string_view n) const;
    const std::wstring& put(HWND w);
    const std::wstring& put(HWND w, int id);

    operator std::wstring&();
    config_history& operator=(const std::vector<std::wstring>& v);
    config_history& operator=(const std::wstring& v);
    config_history& operator+=(const std::wstring& v);

    constexpr static int Blank     = 1;
    constexpr static int Duplicate = 2;
    constexpr static int Empty     = 4;

    config_history(const std::vector<std::wstring>& initial, int depth = 10, int retain = 0);

    config_history(const std::string& name, const std::vector<std::wstring>& initial = {},
                   int depth = 10, int retain = 0, nlohmann::json& store = configuration);

};

constexpr static int Blank     = 1;
constexpr static int Duplicate = 2;
constexpr static int Empty     = 4;

config_history(const std::vector<std::wstring>& initial, int depth = 10, int retain = 0);

config_history(const std::string& name, const std::vector<std::wstring>& initial = {},
               int depth = 10, int retain = 0, nlohmann::json& store = configuration);

Constructs a config_history object as wrapper for a vector of wide strings which can be read from or written to an array stored as a member in an nlohmann::json object, and read from or written to a Windows combo box control.

• name (usually given as a character literal) specifies the name used for this array in json objects. If name is omitted, a json object is never accessed unless explicitly specified in a call to peek, get or put.
• store specifies the nlohmann::json object in which values are stored. If omitted when name is specified, the global object configuration is used.
• initial specifies an initial value for the vector.
• depth, when positive, specifies the maximum number of items in the vector. Older items are removed. This constraint is enforced during get functions specifying an HWND and during += operations. When depth is zero or negative, no constraint is imposed.
• retain can be zero or a combination of config_history::Blank, config_history::Duplicate and config_history::Empty specifying how items in the history are retained (combine with + or |). By default, empty strings and strings which duplicate the current string (the one in history[0] or the edit control of a combo box) are not retained in history items beyond the first, and for purposes of matching or recognizing the empty string, trailing blanks are removed. This constraint is enforced during get functions specifying an HWND and during += operations.
• Blank indicates that trailing blanks are significant for purposes of matching the current string or recognizing the empty string.
• Duplicate indicates that strings which duplicate the current string (the one in history[0] or the edit control of a combo box) are to be retained in the history.
• Empty indicates that empty strings are to be retained in the history.
• You normally use the get and put functions, assignment, and implicit or explicit conversion to std::wstring to access the value of a config_history variable. If the first access is through assignment or get with an HWND, the assigned or retrieved value is set and, if name was specified, a copy is written to the json store. If the first access is through conversion, get without arguments or put with an HWND and name was specified, an attempt is made to read the value from the json store; if the attempt fails, or if name was not specified, the initial value is used.
• In all cases, functions which include:
  HWND w, int id
  among their parameters are equivalent to the same-named functions with HWND w and no int id, substituting:
  GetDlgItem(w, id)
  for w.

std::string name

The name member contains the name under which the vector is saved in a json store. Normally you should set this using the name argument to the config_history constructor and never change it.

nlohmann::json* store

The store member contains a pointer to the json store in which a copy of this vector is kept as an array, or null if no store is used. Normally you should let the constructor set this to the address of the global configuration object (or to null if name is not specified) and never change it.

std::vector<std::wstring> history

Ordinarily, you should use implicit or explicit conversion to std::wstring or the get() member function without arguments to read the most recent entry in a config_history variable, and assignment or one of the get functions with an HWND to update it, since these will maintain synchronization with the json store. However, you can access the vector directly using the history member.

int depth

This member holds the depth setting from the constructor, which determines the maximum number of entries that will be retained in the history.

bool retainBlank
bool retainDuplicate
bool retainEmpty

These three members hold the settings from the constructor for retaining blanks, duplicates and empty items in the history.

bool loaded

The loaded member is initially false, and is set to true when any operation (other than direct access to the history member or value() reference) updates history. Its purpose is to control reading from the json store: once a value has been set, whatever value is present is used, and the json store is not read again.

std::wstring& value()
const std::wstring& value() const

Ordinarily, you should use implicit or explicit conversion to std::wstring or the get() member function without arguments to read the most recent entry in a config_history variable, and assignment or one of the get functions with an HWND to update it, since these will maintain synchronization with the json store. However, you can access the most recent entry (element zero) of the vector directly using the value() member function. The const form never modifies history; however, when the history vector is empty, it returns a reference to a static constant empty string. The non-const form always returns a reference to the first (most recent) element in the history, but if history is empty, it inserts an empty string as the only element of the vector and returns a reference to that element.

static bool peek(std::vector<std::wstring>& v, const nlohmann::json& j, std::string_view n)
static std::wstring peek(HWND w)
static std::wstring peek(HWND w, int id)

The peek member functions retrieve a history from a json object or the current text in the edit control of a Windows combo box without setting the history member.

• v is a reference to a vector of wide strings. If retrieval is successful, it is set to the retrieved history and true is returned; otherwise it is unchanged and false is returned.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object which contains an array that will be copied to v.
• w specifies the window handle, or the window handle of the parent window, of a combo box control. The return value is retrieved from the edit control of the combo box.
• id specifies the resource identifier of a combo box; w is a handle to the parent of the control to be examined (e.g., a dialog). When no id is specified, w is the handle of the combo box itself.

static void show(HWND w, const std::wstring& s)
static void show(HWND w, int id, const std::wstring& s)

The show member functions display the specified value in the edit control of a combobox. No data from the config_history object is used.

• w specifies the window handle, or the window handle of the parent window, of the combo box in which the value is to be displayed.
• id specifies the resource identifier of the combo box in which a value is to be displayed; w is a handle to the parent of the control to be updated (e.g., a dialog). When no id is specified, w is the handle of the control itself.
• s specifies the text to be displayed in the edit control of the combobox.

std::wstring& get(const nlohmann::json& j, std::string_view n)
std::wstring& get(HWND w)
std::wstring& get(HWND w, int id)
std::wstring& get()

The get member functions retrieve a vector of wide strings from either a json object or a Windows combo box and store it in the history member, then return a reference to history[0]. If the attempt to retrieve a vector of wide strings is unsuccessful history is not changed; except that in all cases (successful or not), if an empty vector would otherwise result, {L""} is assigned to history.

• get(), with no arguments, attempts to retrieve the JSON array corresponding to name from the associated json store if name was specified in the constructor and loaded is false, then store it in history as a vector of wide strings. In all other cases, or if the attempt to retrieve the array and convert it to a vector of wide strings fails, history is not changed; except that in all cases (successful or not), if an empty vector would otherwise result, {L""} is assigned to history.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object which contains an array of strings to be retrieved.
• w specifies the window handle, or the window handle of the parent window, of the combo box from which a list of strings is to be retrieved. The content of the edit box becomes the first element of history and the remaining elements are the items in the list. Depth and retention constraints, as specified in the constructor, are applied.
• id specifies the resource identifier of the combo box from which a list of strings is to be retrieved; w is a handle to the parent of the combo box to be examined (e.g., a dialog). When no id is specified, w is the handle of the combo box itself.

const std::wstring& put(nlohmann::json& j, std::string_view n) const
const std::wstring& put(HWND w)
const std::wstring& put(HWND w, int id)

The put member functions copy the value of a config_history object to a json object or a Windows combo box control. All versions return a constant reference to history[0] unless history is empty, in which case they return a reference to L"".

• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object). This form of put never changes history.
• n specifies the name of the member of the JSON object to which an array of strings corresponding to history is assigned.
• w specifies the window handle, or the window handle of the parent window, of the combo box in which the history is to be displayed. This form of put (with or without id) can change history. If name was specified in the constructor and loaded is false, put-to-HWND first attempts to retrieve the history corresponding to name from the JSON store. In all other cases, or if the attempt to retrieve the history fails, history is not changed; except that in all cases (successful or not), if an empty vector would otherwise result, {L""} is assigned to history. Regardless of whether retrieval was successful, the first element of history is copied to the edit control of the combo box and the remaining elements are copied to the drop-down list.
• id specifies the resource identifier of the combo box in which a list of strings is to be displayed; w is a handle to the parent of the combo box to be updated (e.g., a dialog). When no id is specified, w is the handle of the combo box itself.

operator std::wstring&()

Conversion to std::wstring& is identical to get().

config_history& operator=(const std::vector<std::wstring>& v)

Assignment from a vector assigns the vector to history and sets loaded to true. If name was specified in the constructor it then writes the new history to the name member of the JSON store. Depth and retention constraints are not applied.

config_history& operator=(const std::wstring& v)

Assignment from a wide string replaces the first element of history with the wide string and sets loaded to true. If name was specified in the constructor it then writes the new history to the name member of the JSON store. If history is empty before the assignment, a new element is created. Depth and retention constraints are not applied.

config_history& operator+=(const std::wstring& v)

The += operator inserts the right-side string as the first value of history and sets loaded to true. Depth and retention constraints, as specified in the constructor, are applied. If name was specified in the constructor it then writes the new history to the name member of the JSON store.

struct config_rect {

    std::string name;
    nlohmann::json* store;
    RECT value = { 0, 0, 0, 0 };
    bool loaded = false;

    static bool peek(RECT& v, const nlohmann::json& j, std::string_view n);
    static bool peek(RECT& v, HWND w);

    RECT peek(const nlohmann::json& j, std::string_view n) const;
    RECT peek(HWND w)                                      const;

    static void show(HWND w, const RECT& v = RECT());

    RECT& get(const nlohmann::json& j, std::string_view n);
    RECT& get(HWND w);
    RECT& get();

    const RECT& put(nlohmann::json& j, std::string_view n) const;
    const RECT& put(HWND w);

    operator RECT&();
    config_rect& operator=(const RECT& v);

    config_rect();
    config_rect(const std::string& name, nlohmann::json& store = configuration);

};

config_rect()
config_rect(const std::string& name, nlohmann::json& store = configuration)

Constructs a config_rect object.

• name (usually given as a character literal) specifies the name used for the member that will store this array in a json object. If name is omitted, a json object is never accessed unless explicitly specified in a call to peek, get or put.
• store specifies the nlohmann::json object containing a member in which this array is stored. If omitted when name is specified, the global object configuration is used.
• You normally use the get and put functions, assignment, and implicit or explicit conversion to RECT to access the value of a config_rect variable. If the first access is through assignment or get with an HWND, the assigned or retrieved value is set and, if name was specified, a copy is written to the json store. If the first access is through conversion, get without arguments or put with an HWND and name was specified, an attempt is made to read the value from the json store; if the attempt fails, or if name was not specified, the value is set to {0, 0, 0, 0}.

std::string name

The name member contains the name under which the array is saved in a json store. Normally you should set this using the name argument to the config_rect constructor and never change it.

nlohmann::json* store

The store member contains a pointer to the json store in which a copy of this array is kept, or null if no store is used. Normally you should let the constructor set this to the address of the global configuration object (or to null if name is not specified) and never change it.

RECT value

Ordinarily, you should use implicit or explicit conversion to RECT or the get() member function without arguments to read the value of a config_rect variable, and assignment or one of the get functions with an HWND to update it, since these will maintain synchronization with the json store. However, you can access the RECT directly using the value member.

bool loaded

The loaded member is initially false, and is set to true when any operation (other than direct access to the value member) updates value. Its purpose is to control reading from the json store: once a value has been set, whatever value is present is used, and the json store is not read again.

static bool peek(RECT& v, const nlohmann::json& j, std::string_view n)
static bool peek(RECT& v, HWND w)
RECT peek(const nlohmann::json& j, std::string_view n) const
RECT peek(HWND w) const

The peek member functions retrieve a value from a json object or from the current bounding rectangle of a dialog or other top-level window without setting the value member.

• v is a reference to a RECT. If retrieval is successful, it is set to the retrieved rectangle and true is returned; otherwise it is unchanged and false is returned.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object which contains an array that will be copied to v.
• w specifies the window handle of a dialog or other top-level window.
• The forms that return a RECT return the retrieved value or the current bounding rectangle of the specified window; if retrieval fails, they return the current value of the value member.

static void show(HWND w, const RECT& v = RECT())

The show member function displays the specified dialog or other top-level window at the position and size indicated by the specified RECT. No data from the config_rect object is used. If the RECT is {0, 0, 0, 0} (the default), the size of the dialog or other top-level window is unchanged, and it is centered on its owner window, or on the desktop if it has no owner window.

• w specifies the window handle of a dialog or other top-level window to be positioned.
• v specifies the RECT containing the desired window bounds.

RECT& get(const nlohmann::json& j, std::string_view n)
RECT& get(HWND w)
RECT& get()

The get member functions retrieve the RECT structure from either a json object or the current bounds of a dialog or other top-level window and return a reference to the value member.

• get(), with no arguments, attempts to retrieve the JSON array corresponding to name from the associated JSON store if name was specified in the constructor and loaded is false, then store it in value. In all other cases, or if the attempt to retrieve the array fails, value is not changed.
• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object).
• n specifies the name of the member of the JSON object which contains the array to be retrieved.
• w specifies the window handle of a dialog or other top-level window the bounds of which are to be retrieved.

const RECT& put(nlohmann::json& j, std::string_view n) const
const RECT& put(HWND w)

The put member functions copy the value of a config_rect object to a json object or set the bounds of a dialog or other top-level window to the stored rectangle. If the value is {0, 0, 0, 0}, the size of the dialog or other top-level window is unchanged, and it is centered on its owner window, or on the desktop if it has no owner window. All versions return a constant reference to value.

• j designates a json object (in the C++ sense of object) which contains an object (in the JSON sense of object). This form of put never changes value.
• n specifies the name of the member of the JSON object to which an array representing the rectangle is assigned.
• w specifies the window handle of a dialog or other top-level window to be positioned. This form of put can change value. If name was specified in the constructor and loaded is false, put-to-HWND first attempts to retrieve the windows bounds corresponding to name from the JSON store. In all other cases, or if the attempt to retrieve the bounds fails, value is not changed.

operator RECT&()

Conversion to RECT& is identical to get().

config_rect& operator=(const RECT& v);

Assignment from a RECT copies the RECT to value and sets loaded to true. If name was specified in the constructor it then writes the new array to the name member of the JSON store.

struct DialogStretch {

    HWND dialog;
    RECT original;
    std::map<HWND, RECT> controls;

    DialogStretch();

    void setup(HWND hwndDlg);

    int originalWidth () const;
    int originalHeight() const;

    class Stretched {
    public:
        Stretched& adjust(HWND h, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);
        Stretched& adjust(int control, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);
    };

    Stretched adjust(HWND h, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);
    Stretched adjust(int control, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);

};

DialogStretch()

Constructs a DialogStretch object. This object must persist throughout the lifetime of the dialog box.

HWND dialog

Holds the handle to the dialog window. The setup member function sets this; you should not change it.

RECT original

Holds the bounds of the dialog window at the time setup was called; you should not change this.

std::map<HWND, RECT> controls

Maps the IDs of all controls in the dialog to the bounds of their windows at the time setup was called; you should not change this.

void setup(HWND hwndDlg)

Saves information about a dialog that will allow the adjust function to adjust the size and position of controls in the dialog. This function must be called during WM_INITDIALOG before there are any changes to the size of the dialog window, so it can record the positions and sizes established by the dialog template.

• hwndDlg specifies the handle of the dialog window.

int originalWidth () const

Returns the width of the dialog box at the time setup was called.

int originalHeight() const

Returns the height of the dialog box at the time setup was called.

Stretched adjust(HWND h, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);
Stretched adjust(int control, double xStretch, double yStretch = 0, double xMove = 0, double yMove = 0);

Resizes a control in a dialog based on the original size of the dialog and the control, the new size of the dialog, and specified ratios for stretching and moving. This function is normally called when the dialog procedure receives a WM_SIZE message.

• h specifies the window handle of a control in the dialog box.
• control specifies the control ID of a control in the dialog box.
• xStretch specifies the fraction of change in the width of the dialog box which should be reflected as a change in the width of the control. Typically this will be either 0, meaning the width of the control does not change, or 1, meaning the control stretches as much as the dialog box stretches; but other values can be used as needed.
• yStretch specifies the fraction of change in the height of the dialog box which should be reflected as a change in the height of the control. Typically this will be either 0, meaning the height of the control does not change, or 1, meaning the control stretches as much as the dialog box stretches; but other values can be used as needed.
• xMove specifies the fraction of change in the width of the dialog box which should be reflected as a change in the horizontal position of the control, as measured from the left edge of the dialog box. Typically this will be either 0, meaning the left edge of the control does not move relative to the left edge of the dialog; 1, meaning the left edge of the control does not move relative to the right edge of the dialog; or 0.5, meaning the left edge of the control does not move relative to the horizontal center of the dialog; but other values can be used as needed.
• yMove specifies the fraction of change in the height of the dialog box which should be reflected as a change in the vertical position of the control, as measured from the top of the dialog box. Typically this will be either 0, meaning the top of the control does not move relative to the top of the dialog; 1, meaning the top of the control does not move relative to the bottom of the dialog; or 0.5, meaning the top of the control does not move relative to the vertical center of the dialog; but other values can be used as needed.
• The adjust functions can be applied to either a DialogStretch object or to the object returned by another adjust function. This allows adjust functions to be chained, which is slightly more efficient than repeating the DialogStretch reference for each adjust call, since the first call must retrieve information about the current size of the dialog.