----------------------------------------
                 16Edit - programming interface reference
                 ----------------------------------------


General Notes:
--------------
Per process can only one 16Edit window be opened at the same time.

16Edit uses an own clipboard format, so it's not possible to correspond with
other programms. Anyway one can transfer data between 16Edit instances.

Keep attention on the byte alignment of the 16Edit structures!


API:
----
To open up a 16Edit window instance in your project you always have to call
"HESpecifySettings" first and after that either "HEEnterWindowLoop" or
"HEEnterWindowLoopInNewThread".

-------------------------------------------------------------------------------------

BOOL   __stdcall HESpecifySettings(PHE_SETTINGS sets);


This function configures 16Edit and specifies the input which is either a
memory block (HE_SET_MEMORYBLOCKINPUT) or a file (HE_SET_INPUTFILE).

This function could fail because of the following reasons:
- neither an input file nor an input memory block was specified
- the input file could not be loaded 
- not enough memory available
- the 16Edit window is opened
.. all other errors or bad items in HE_SETTINGS are ignored or validated.

-------------------------------------------------------------------------------------

Possible flags for "HE_SETTINGS.dwMask":

#define HE_SET_FORCEREADONLY             0x00000001
#define HE_SET_NORESIZE                  0x00000002
#define HE_SET_SETCURRENTOFFSET          0x00000004
#define HE_SET_SETSELECTION              0x00000008
#define HE_SET_ACTIONHANDLER             0x00000010
#define HE_SET_INPUTFILE                 0x00000020
#define HE_SET_MEMORYBLOCKINPUT          0x00000040
#define HE_SET_ONTOP                     0x00000080
#define HE_SET_PARENTWINDOW              0x00000100
#define HE_SET_MINIMIZETOTRAY            0x00000200
#define HE_SET_SAVEWINDOWPOSITION        0x00000400
#define HE_SET_RESTOREWINDOWPOSITION     0x00000800
#define HE_SET_USERWINDOWPOSITION        0x00001000


HE_SET_FORCEREADONLY:
Forbids any changes in the buffer, also if read-write-access could be
obtained.

HE_SET_NORESIZE:
Forbids any operations which modify the size of the buffer. In fact the
cutting and pasting functions are disabled.

HE_SET_SETCURRENTOFFSET:
The caret is set to the position specified in "HE_SETTINGS.posCaret" on
startup.

HE_SET_SETSELECTION:
The buffer block defined by "HE_SETTINGS.dwSelStartOff" and
"HE_SETTINGS.dwSelEndOff" is selected on startup.

You can only use either HE_SET_SETCURRENTOFFSET or HE_SET_SETSELECTION !

HE_SET_ACTIONHANDLER:
Installs an action handler which will get called in special effets are
occurring or passed. The address of this handler should be put into
"HE_SETTINGS.pHandler". Look down for the description of "HE_ACTION" for more
information.

HE_SET_INPUTFILE:
A file ("HE_SETTINGS.szFilePath") is used as input. 16Edit tries to get write
access. The client is informed about the result through the
HE_ACTION_FILEACCESSINFO action event.

HE_SET_MEMORYBLOCKINPUT:
A memory block ("HE_SETTINGS.diMem") is used as input. Also if the user is
allowed to resize the memory block, it's not able to make it grow over the
size specifed in "HE_SETTINGS.diData.dwSize" !

You can only specify either HE_SET_INPUTFILE or HE_SET_MEMORYBLOCKINPUT !

HE_SET_ONTOP:
The main window is set to top state on startup.

HE_SET_PARENTWINDOW:
The main window gets a client window of the window whose handle is set it
"HE_SETTINGS.hwndParent".

HE_SET_MINIMIZETOTRAY:
Every time the main window is minimized it inserts an icon in the system tray and the
window isn't visible in the task bar anymore. The minimized window can be restored
either by double clicking on the icon in the tray or by a right click which causes a
menu to appear.

HE_SET_SAVEWINDOWPOSITION:
16Edit saves its window size,position and state in an ini file (16Edit.ini) which
will be saved in the same directory as 16Edit.dll.

HE_SET_RESTOREWINDOWPOSITION:
If you specify this flag then 16Edit will restore the old window size,position and
state if a 16Edit.ini lies in the same directory as 16Edit.dll.
See HE_SET_SAVEWINDOWPOSITION.

HE_SET_USERWINDOWPOSITION:
"HE_SETTINGS.wpUser" is used to setup the main window on startup.
HE_SET_RESTOREWINDOWPOSITION has no effect in this case.

-------------------------------------------------------------------------------------

typedef struct HE_DATA_INFO
{
	void*       pDataBuff;
	DWORD       dwSize;
	BOOL        bReadOnly;
} *PHE_DATA_INFO;


This is the structure for an input memory block (HE_SET_MEMORYBLOCKINPUT). All structure
items are self-explaining, I think.

-------------------------------------------------------------------------------------

typedef struct HE_POS
{
	DWORD       dwOffset;
	BOOL        bHiword;       // (opt.) first digit of the pair ? ...or the 2nd one ?
	BOOL        bTextSection;  // (opt.) Caret in the text part ?
} *PHE_POS;


This structure is used if you wish to set the caret on startup (HE_SET_SETCURRENTOFFSET).

-------------------------------------------------------------------------------------

typedef struct _HE_WIN_POS
{
	int                 iState;             // SW_SHOWNORMAL/SW_MAXIMIZE/SW_MINIMIZE
	int                 ix, iy, icx, icy;   // left, top, width, height
} HE_WIN_POS, *PHE_WIN_POS;


Used to describe the state of a window.

-------------------------------------------------------------------------------------

typedef struct _HE_SETTINGS
{
	DWORD              dwMask;             // HE_SET_XXX flags

	procActionHandler  pHandler;           // HE_SET_ACTIONHANDLER

	HE_POS             posCaret;           // HE_SET_SETCURRENTOFFSET

	DWORD              dwSelStartOff;      // HE_SET_SETSELECTION
	DWORD              dwSelEndOff;        // 

	HWND               hwndParent;         // HE_SET_PARENTWINDOW

	union
	{
		char*                szFilePath;         // HE_SET_INPUTFILE

		HE_DATA_INFO         diMem;              // HE_SET_MEMORYBLOCKINPUT
	};

	HE_WIN_POS         wpUser;             // HE_SET_USERWINDOWPOSITION
} HE_SETTINGS, *PHE_SETTINGS;


dwMask:
is a combination of HE_SET_XXX flags.

pHandler:  (HE_SET_ACTIONHANDLER)
Optional address of a action handler routine.

posCaret:  (HE_SET_SETCURRENTOFFSET)
Optional address of a HE_POS structure for the caret position.

dwSelStartOff/dwSelEndOff:  (HE_SET_SETSELECTION)
Optional selection start/end.

hwndParent:  (HE_SET_PARENTWINDOW)
Optional parent window handle.

szFilePath:  (HE_SET_INPUTFILE)
Optional NUL terminated string pointer to the input file path.

diMem:  (HE_SET_MEMORYBLOCKINPUT)
Optional information about the input memory block.

wpUser: (HE_SET_USERWINDOWPOSITION)
Apply user window state on startup.

Look at the HE_SET_XXX flag definition above for more information.

-------------------------------------------------------------------------------------

typedef struct HE_ACTION
{
	DWORD        dwActionCode;

	DWORD        dwNewSize;            // HE_ACTION_SAVED

	BOOL         bReadWrite;           // HE_ACTION_FILEACCESSINFO

	HWND         hwnd16Edit;           // HE_ACTION_WINDOWCREATED
} *PHE_ACTION;

typedef BOOL (__stdcall* procActionHandler)(PHE_ACTION pa);


As mentioned you can specify an action handler. Every time if one of the following
mentioned events occurres, the action handler is called. The event type is signed by
"PHE_ACTION->dwActionCode".
The BOOL return value is up to now useless.

-------------------------------------------------------------------------------------

Possible values for "HE_ACTION.dwActionCode":

#define HE_ACTION_EXITING                0x00000001
#define HE_ACTION_SAVED                  0x00000002
#define HE_ACTION_FILEACCESSINFO         0x00000004
#define HE_ACTION_WINDOWCREATED          0x00000008


HE_ACTION_EXITING:
The user is closing the window. No additional information.

HE_ACTION_SAVED:
The modification were saved to the input file/memory block. "HE_ACTION.dwNewSize"
holds the new size.

HE_ACTION_FILEACCESSINFO:
This event occurs if input is a file and 16Edit finished the file opening
process. "HE_ACTION.bReadWrite" shows whether 16Edit was able to gain read and
write access.

HE_ACTION_WINDOWCREATED:
The handler will be called after the main window was created and set up.
"HE_ACTION.hwnd16Edit" will hold the handle of the 16Edit main window.

-------------------------------------------------------------------------------------

BOOL   __stdcall HEEnterWindowLoop();
BOOL   __stdcall HEEnterWindowLoopInNewThread();


Both routines open the 16Edit main window up.
But "HEEnterWindowLoop" enters the window loop within the thread which calls
the function and "HEEnterWindowLoopInNewThread" creates a new thread which is
entering the window loop.
Both routines fail if the window of the 16Edit.dll instance is already opened.