WinDom: External UserDef library (LDG) API

- Main Page
- Modules
- Data Structures
- Files
- Related Pages

# 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