External UserDef library (LDG) API

definition of the API of an external userdef library. More...

Data Structures
struct	UDLIB_CONFIG
	standard windom configuration data see windom _config:: documentation for details More...
struct	UDLIB_FIXCICON
	structure to access windom CICON subroutine from a userdef library More...
struct	APPENV
	environment data set as paramter to all functions of the userdef library More...
Functions
long __CDECL	xobjc_libinit (APPENV *)
	initialisation of the library
void __CDECL	xobjc_udconfig (UDLIB_CONFIG *, APPENV *)
	this function update the configuration
void __CDECL	xobjc_libexit (APPENV *)
	exit the library
long __CDECL	xobjc_extended (OBJECT *, long, long, APPENV *)
	request for transformation of userdef objects
void __CDECL	xobjc_extfree (OBJECT *, long, APPENV *)
	set a userdef object back to its original aspect.
char *__CDECL	xobjc_string (OBJECT *, long, char *, APPENV *)
	read/set the string pointer of a userdefined object.
long __CDECL	xobjc_char (OBJECT *, long, long, APPENV *)
	read/set the character of a userdefined object.
long __CDECL	xobjc_edit (OBJECT *, long, long, short *, long, long, GRECT *, APPENV *)
	similar to objc_edit(tree, ob, the_char, index, kind)
long __CDECL	xobjc_get_edpos (OBJECT *, long, long, long, APPENV *)
	return the character of the editable object at (mouse) position x,y.
long __CDECL	xobjc_get_unextended (OBJECT *, long, APPENV *)
	utility for ObjcDup()

---

Detailed Description

definition of the API of an external userdef library.

ADD THERE some explanations about what is userdef.ldg and recommandations like support of all extended objects type defined by windom (TODO)

---

Function Documentation

long __CDECL xobjc_char (  OBJECT *  tree, long  object, long  the_char, APPENV *  env )

read/set the character of a userdefined object. Parameters: tree  the address of the formular object  the object of the formular the_char  a character (from 0 to 255) or -1L env  the context of this application provided by windom Returns: the character of this object, or -1L if this object doesn't have any character field. If "the_char" equals -1L, this function shall return the character stored in this object (value from 0 to 255). If "the_char" is a valid character (value from 0 to 255), this value will be the new value of the character of this userdef object. this function is optionnal, but highly recommanded if any of the userdefined object transformed by this library may contain character.

long __CDECL xobjc_edit (  OBJECT *  tree, long  object, long  the_char, short *  ob, long  kind, long  nclip, GRECT *  gclip, APPENV *  env )

similar to objc_edit(tree, ob, the_char, index, kind) Parameters: tree  the address of the formular object  the object of the formular the_char  a character (from 0 to 255) ob  kind  nclip  gclip  env  the context of this application provided by windom Returns: as objc_edit(). similar to objc_edit for userdefined object with the EDITABLE flag set. gclip is a array of GRECT. If this function has to draw something to the screen ( a cursor for example), then the list of rectangles given in gclip shall be used as clipping area. nclip is the number of element in the gclip array. This function is mandatory if the library may create an editable userdefined object.

long __CDECL xobjc_extended (  OBJECT *  tree, long  ob, long  type, APPENV *  env )

request for transformation of userdef objects Parameters: tree  the address of the formular ob  the object of the formular type  kind of transformation requested by the user (see mt_RsrcXtype()) env  the context of this application provided by windom Return values: 1L  if the library has transformed this object to a userdef object 0L  if the library has not changed this object -1L  if an error has occured. this function is called by windom when the application requested for extended type (see mt_RsrcXtype()). If tree[ob] should be transformed to a userdefined object, then the library have to do the transformation: change the ob_type of this object to G_USERDEF, and maybe change some other stuff (ob_spec, ob_x, ob_y, ob_flags...). Nota: the extended ob_type (ob_type & 0xFF00) is free - the library may use this extended ob_type to store informations about the object. Nota: Remember that the transformation OBJECT->userdef must be reversible. So the library must be able to restore all the modified data (original ob_type and ob_spec for example). The VDI handle given in env->vdih is the handle of the virtual workstation opened by the windom application that must be used by the userdef subroutine to draw on the screen. The APPENV parameter may be stored in the userblk structure, if the userdef subroutine needs to access to malloc function, or to the udlib_data pointer. this structure (APPENV) will be allocated by windom before calling xobjc_libinit(), and free-ed after xobjc_libexit(), and the same ENVAPP pointer will be given to all the xobjc_xxx functions. this function is mandatory

void __CDECL xobjc_extfree (  OBJECT *  tree, long  object, APPENV *  env )

set a userdef object back to its original aspect. Parameters: tree  the address of the formular object  the object of the formular env  the context of this application provided by windom tree[ob] has been transformed to a userdef object by this library. The userlib doesn't have to check this. this function is mandatory

long __CDECL xobjc_get_edpos (  OBJECT *  tree, long  object, long  x, long  y, APPENV *  env )

return the character of the editable object at (mouse) position x,y. Parameters: tree  the address of the formular object  the object of the formular x  x-position of the mouse, relative to the left border of the object y  y-position of the mouse, relative to the top border of the object env  the context of this application provided by windom Returns: the index of the character in the string, or a negative value in case of error ( x or y point outside of the object...) this function is used when the user clic on such object. Then windom set the cursor just under the mouse position using xobjc_edit(). This function is optional.

long __CDECL xobjc_get_unextended (  OBJECT *  tree, long  object, APPENV *  env )

utility for ObjcDup() Parameters: tree  the address of the formular object  the object of the formular env  the context of this application provided by windom tree[ob] is a userdef object that has been transformed by this library. org is pointer to another OBJECT structure. the org object contain a copy of the userdefined object (*org == tree[ob]). this function will copy in the org structure the original aspect of tree[ob]. In other words, org will be tree[ob] after xobjc_extfree(), but without freeing the userdef tree[ob]. This function is mandatory

void __CDECL xobjc_libexit (  APPENV *  env  )

exit the library Parameters: env  the context of this application provided by windom this function is called by windom when this AES application no more use and no more required this userdef library (application exiting, or change of userdef-lib on the fly). This function shall free all the data allocated by this library. This function is optional

long __CDECL xobjc_libinit (  APPENV *  env  )

initialisation of the library Parameters: env  the context of this application provided by windom Return values: <0  any negative value in case of error, 1  if this library uses the "SIMPLE" interface (not yet specified -- don't use !) 2  if this library uses the "FREEDOM" interface This function is called by windom when a new AES application may use this userdef library. The env data provides a user data field (udlib_data) that the library may use for its own needs. This data may be use to store the configuration of the library for example. This env data will be provided to the library in each function of the interface, so that the private data stored in udlib_data will be available in all interface function. this function is mandatory.

char* __CDECL xobjc_string (  OBJECT *  tree, long  object, char *  string, APPENV *  env )

read/set the string pointer of a userdefined object. Parameters: tree  the address of the formular object  the object of the formular string  a pointer to the new string or NULL env  the context of this application provided by windom Returns: the pointer to the text, or NULL if this object doesn't have any text field. If "string" is NULL, this function shall return a pointer to the text of the userdef object. If "string" is not NULL, this value will be the new value of the text pointer of this userdef object. Nota: the pointer shall be changed. A simple strcpy() is not ok ! For SELECTABLE objects, if the string contains the '[' character, then the following character will be used as shortcut to select this object. When the user presses a key, windom will use this function to find if the key pressed is a shortcut to select this object. tree[ob] has been transformed to userdef object by this library. The userlib doesn't have to check this. this function is optionnal, but highly recommanded if any of the userdefined object transformed by this library may contain some text.

void __CDECL xobjc_udconfig (  UDLIB_CONFIG *  config, APPENV *  env )

this function update the configuration Parameters: config  the configuration of windom that contains options relative to userdef objects. env  the context of this application provided by windom This function is called when the library has just been initialised, and when the windom configuration has changed for this application. The config data contain all the option of windom that define the aspect of userdefined objects. The library may use these parameters (or some of them) to adjust the rendering the userdef objects. This function is optional

---