This section describes control, resource allocation and general functions provided by the component library. Where object classes provide additional functions related to their operation, these are documented at the end of the relevant section.
This is the structure defining information about a component method. The address to a table of method items should be used with the ECOreturnMethodsEvents API.
See some of the samples for an example.
mId - The unique identifier, within the method table, for the method. All external methods must have a positive number and must not be zero. All negative numbers are assumed to be Omnis internal methods, presently only Omnis internal methods ECF_CUSTOM & ECF_ABOUT are supported (neither have any parameters).
mNameResID - Resource id which contains the method name. Method names should, ideally, be unique to avoid ambiguity in Omnis notation. If there is a clash between Omnis and the component method names, you may use a prefix of ‘::’ to reference the external method. For example, Calculate #1 as $cobj.$::clashMethod.
mReturnDataType - Returned data type of type fftxxx. Specify 0 for no returned data (e.g. void) and fftNone for an unspecified data type.
mParameterCount - Number of parameters for the method. Specify zero for no parameters.
mParameters - Pointer to an array of parameters. Specify NULL if there are no parameters.
mFlags - Method flags of type EXTD_FLAG_xxxx.
mExFlags - Use zero. Extended flags for future enhancement.
Once a table of methods has been returned, you should be ready to receive the ECM_METHODCALL message.
If the method is to support parameters, you need to supply information describing the parameters’ properties. This is the parameter structure.
mNameResID - Resource id which contains the parameters’ name.
mDataType - fftxxx data type of the parameter. Use fftNone for an unspecified data type.
mFlags - Parameter flags of type EXTD_FLAG_xxxx. Examples are EXTD_FLAG_PARAMOPT and EXTD_FLAG_PARAMALTER.
mExFlags - Must be zero. Extended flags for future enhancement.
Example of a method table
See also ECOreturnMethodsEvents, ECM_METHODCALL,
EXTD_FLAG_PARAMOPT, EXTD_FLAG_PARAMALTER
This is the structure defining information about a component’s events. The address to a table of events information should be used with the ECOreturnMethodsEvents API call.
mId - The unique identifier, within the event table, for the event. All external events must have a positive number and must not be zero. All negative numbers are assumed to be Omnis internal events. For a list of supported internal events, look for ECE_ in EXTDEFS.HE.
mNameResID - Resource id which contains the event name. Event names must be unique and must not clash with Omnis internal events. The string ‘ev’ is used automatically as a prefix for any event.
mReturnDataType - Returned data type of type fftxxx. Specify 0 for no returned data (e.g. void) and fftNone for an unspecified data type.
mParameterCount - Number of parameters for the event. Specify zero for no parameters.
mParameters - Pointer to an array of parameters. Specify NULL if there are no parameters.
mFlags - Event flags of type EXTD_FLAG_xxxx.
mExFlags - Use zero. Extended flags for future enhancement.
Once a table of event information has been returned, you can use the ECOsendEvent API.
If your events support parameters, you need to supply information describing the parameters. See the Component Methods section for a description of the ECOparam structure, or see some of the example components.
Example of an events table
This is the structure of a single property. The address to a table of properties should be used with the ECOreturnProperties API when Omnis calls your component with a ECM_GETPROPNAME message.
See some of the samples for an example.
mPropID - Property Identifier. External properties ids must be positive and unique within the property table. These id’s link the Omnis data with the associated property and therefore must not change.
mNameResID - Resource id for the property name. Property names should, ideally, be unique to avoid ambiguity in Omnis notation. If there is a clash between Omnis and the component property, you may use a prefix of ‘::’ to reference the external property, e.g. Calculate #1 as $cobj.$::clashProperty.
mDataType - fftxxx data type.
mFlags - EXTD_FLAG_xxx.
mExFlags - Extended flags for future enhancements.
mEnumStart - Constant id enumeration start (0 if not required).
mEnumEnd - Constant id enumeration end (0 if not required).
Example Property Table
Once a table of properties has been returned, you should be ready to receive the ECM_PROPERTYCANASSIGN, ECM_SETPROPERTY and ECM_GETPROPERTY messages.
The property flags are used to describe information about a property in the property table that must be returned to Omnis if you intend to support properties.
See also ECOreturnProperties, ECM_GETPROPNAME, ECM_PROPERTYCANASSIGN, ECM_SETPROPERTY, ECM_GETPROPERTY.
The following enum values are used with the function ECOclipboardHasFormat().
eExtClipText – use this enum when testing the clipboard for text data.
eExtClipPicture - use this enum when testing the clipboard for picture data.
See also ECOclipboardHasFormat
mCompLibId - Contains the unique identifier for the component library. This value should only be used by control handlers.
mCompId - Unique identifier for the control.
mGdata - Pointer which is maintained by the external component.
mOmnisInstance - Instance of Omnis.
mParamFirst - Pointer to the first parameter.
mPrivate - Private pointer used by Omnis. The component must not alter this member.
mECOCallBack, mGDICallBack, mHWNDCallBack, mFVALCallBack, mQLISTCallBack, mBMPCallBack, mCRBCallBack, mPRICallBack, mQFILECallBack, mDAMCallBack(v3.1) - Data for Omnis call-back functions. The component must not alter these members.
mLocLocp - The context of the calling Omnis method. When the external component is not called from an Omnis method, it is identical to mInstLocp.
mInstLocp - The context of the Omnis class instance, which contains the object instance. When the external component is not called from a class instance, it points at the library or root.
This structure contains all the parameter information required for many ECM_xxxx messages and functions.
mId – Parameter id. Depends on the context in which the EXTParamInfo structure is used. For example, during property messages this will contain the unique property identifier (mPropID).
mInfo – Not currently used.
mData – Pointer to data.
mParent – Not currently used.
mNum – Specifies the parameter number. A value of zero indicates that it is a return parameter.
mFlags – Flags of type EXTC_FLAG_xxxx for the parameter.
EXTC_FLAG_EXTDEL – Indicates that the parameter should be deleted by the component. The component must not manually set this flag.
EXTC_FLAG_PARAMCHANGED – Indicates that the parameter has been changed. The component must not manually set this flag.
EXTC_FLAG_HASITEM (v3.1) - Indicates that the EXTParamInfo contains valid mItem and mVpt fields. These fields are required by some of the new callbacks in v3.1. If building components for 3.1 you should return this flag during connect.
mNext – Pointer to the next EXTParamInfo structure (may be NULL).
mItem (v3.1) – Contains pointer to an Omnis item reference. Required by some new callbacks in v3.1.
mVpt (v3.1) – Contains pointer to an Omnis parameter info structure. Required by some new callbacks in v3.1.
Returns information about the Omnis data field.
mType – The Omnis data type.
mSubType – The Omnis data sub type.
mLength – The maximum length in bytes or characters of the data field. Zero means unlimited (10,000,000).
mName – The Omnis data field name.
See also ECOgetParamInfo
Structure used by the IS_SERIALISED control message.
mProductCode – Product code supplied by component. Must be 4 alpha/numeric characters.
mFunctionCode – Functionality code returned by Omnis. These consist of 4 alpha/numeric characters describing the enabled functionality.
mSerial – Complete serial number. Returned by Omnis.
mNotes – Notes as entered with the serial number by the user. Returned by Omnis.
See also ECOisSerialised, IS_SERIALISED
These defines are applied to the ECOobject structure which is used to return a list of objects that the component supports.
Indicates that this is a worker object using pushWorkerCallback and can only have a single outstanding notification.
Indicates that this is a worker object.
These defines are used in the mExFlags member of the ECOproperty structure.
Indicates that Omnis should use report fonts for this property.
Indicates that this is a button on an MVDesigner window/form.
anumPropList for this property lists $jsdateformatcustom
anumPropList for this property lists $jsnumberformat
This property needs to be treated like $dataname
This property is not to be exported by Omnis X e.g. because it is read-only
This property is a report measurement: the dps are stored in enumStart.
Set this for standard Omnis properties (defined in anums.he) which are handled by the component rather than using the Omnis core to handle the property.
These defines are used in the mFlags member of the ECOproperty structure.
Indicates that Omnis should provide a button on the Property Manager.
Indicates that Omnis stops editing of the property on the Property Manager.
Indicates that the property is an ENUM. For this type of property, Omnis sends the component the ECM_GETPROPERTYENUMS message.
See also ECM_GETPROPERTYENUMS
Indicates the property is an external constant value. For example, the following property entry (extract from QuickTime) indicates that the property is a external (i.e. Component) constant between constant ids, 23000 & 23004.
Indicates that the property will be searched on during find and replace.
Indicates that the property is a font.
Indicates that the property is hidden, that is, the property does not appear in the Property Manager at all.
Indicates the property is an internal constant value. For example the following property entry (extract from Calendar) indicates that the property is a internal (i.e. Omnis) constant between constant ids, pre3DStyleF & pre3DStyleL (See DMCONST.HE for the entire Omnis constant range).
Indicates that the parameter can be altered during a function call.
See also ECOsetParameterChanged
Indicates that the function parameter (and every parameter after) is optional.
Indicates the property is a data field. Each object may have only one primary data field and appears as the $dataname property in Omnis.
See also ECM_SETPRIMARYDATA, ECM_GETPRIMARYDATA, ECM_GETPRIMARYDATALEN, ECM_CMPPRIMARYDATA, ECM_PRIMARYDATACHANGE
Indicates that the property appears on the Action tab.
Indicates that the property appears on the Appearance tab.
Indicates that the property appears on the Columns tab.
Indicates that the property appears on the Custom tab (default).
Indicates that the property appears on the Data tab.
Indicates that the property appears on the General tab.
Mask for Property Manager tab.
Indicates that the property appears on the Java tab.
Indicates that the property appears on the Preferences tab.
Indicates that the property appears on the Pane tab.
Indicates that the property appears on the sSections tab.
Indicates that the property appears on the Text tab.
Indicates that the popup color window should be provided.
Indicates that the popup 256 color window should be provided. Useful for interfacing with non-Omnis components such as Active-X or Java Beans.
Indicates that the popup cursor window should be provided.
Indicates that the popup font style window should be provided.
Indicates that the popup icon window should be provided.
Indicates that the popup line style window should be provided.
Indicates that the popup pattern window should be provided.
Indicates that the popup checkbox selection window should be provided.
Mask for the popup window types.
Indicates that the property is runtime only, that is, the property appears in the Property Manager during design mode if the Show runtime properties option is switched on.
Indicates that the property appears on the sections tab.
Indicates that the property appears in the Property Manager when only one object is selected.
Indicates that Omnis displays [Empty] or [Not Empty] in the Property Manager.
Indicates that the standard anum (see anums.he) property should be suppressed in the Property Manager.
This section describes some of the messages you receive via your WNDPROC. For additional messages see the HWND and GDI message section.
The ECM_ADDTOPRINTJOB message is send to a report object when the object is to add itself to the print job. This message will only be sent if you returned 1L as a response to the message ECM_CANADDTOPRINTJOB.
lParam - points to the printInfo structure. This structure contains a pointer to the print job mJob of type PRIjob, and a pointer to the object information mObj of type PRIobjectStruct. See print manager documentation for more information about PRIobjectStruct and adding objects to a print job.
Returns:
If the component has added objects to the print job, return 1L. Otherwise return 0L.
The ECM_BOBJ_EXERASE message is sent to the background components to inquire on whether the background objects’ frame region should be excluded from the erase background region.
Returns:
The component should return true if the components’ frame region should be excluded, false otherwise.
External report objects can have full control over what is added to a print job when the object is about to be printed. In order to take advantage of this feature, you must implement this message and return 1L. You will then receive a ECM_ADDTOPRINTJOB message which allows you to add one or more objects supported by the print manager. See print manager documentation for more information about adding objects to a print job.
Returns:
Return 1L if you wish to control what is added to a print job, otherwise return 0L.
The ECM_ CANCLICK message is sent, when the web client needs to know if the component can receive mouse messages.
wParam – is 1 if the component is enabled, otherwise it is 0.
Returns:
Return 1L if the component can receive mouse messages, otherwise return 0.
The ECM_CANFOCUS message is sent, when the web client needs to know if the component can receive the input focus.
wParam – is 1 if the component is enabled, otherwise it is 0.
Returns:
Return 1L if the component can receive the input focus, otherwise return 0.
This message is send to the component when Omnis needs to know if the systems focus border is to be drawn around the component (Macintosh only).
Returns:
Return 1L if a focus border is to be drawn, otherwise return 0.
The ECM_CMPPRIMARYDATA message is sent to the component to compare its objects’ data with the data provided in parameter one.
See also EXTD_FLAG_PRIMEDATA
The ECM_COMPONENTCMD message is sent to the component in response to the $cmd notation method being executed.
The $cmd method provides functionality to Omnis scripting language which might otherwise be inaccessible.
For example, the javabean component provides functionality to enumerate beans. However, this functionality is normally only available via a dialog. $cmd also provides this functionality without the use of the dialog.
Once invoked, all parameters are passed to the component.
An example of use may be :-
The ECM_CONNECT message is sent to the component after an Omnis instance has loaded the component.
Returns:
The component should return one or more of the following flags: -
EXT_FLAG_LOADED - Component has been loaded successfully. The component must return this flag otherwise Omnis assumes the component failed to load.
EXT_FLAG_USABLE Note: FOR INTERNAL USE ONLY. A component must not return this flag.
EXT_FLAG_ALWAYS_USABLE - Component is always available regardless of its load status. This flag enables components to be usable in Omnis without having to load it via the external component dialog. For example, Omnis OLE & Graph components both set this flag.
EXT_FLAG_REMAINLOADED - Component remains loaded even after its usage has returned to zero. This flag provides the best component performance and may be used if the component connection process is too slow.
EXT_FLAG_HIDDEN (v3.3)– Component will not be visible in the object notation tree displayed when creating variables of type ‘Object’.
EXT_FLAG_DAM (v5.0)- The external component is a DAM; must be set in addition to EXT_FLAG_SESSION for DAMs only.
EXT_FLAG_CTRLHANDLER - Component is a control handler . Please refer to the section ‘Control Handlers’ for more information.
EXT_FLAG_EVENTHANDLER – Component in an event handler. Treatment of this flag is the same as EXT_FLAG_CTRLHANDLER.
EXT_FLAG_SESSION (v3.1) – Component is a SQL session object. (Omnis Studio version 3.0 onwards). This flag is also used to elicit thread-safe behavior when writing multi-threaded components.
EXT_FLAG_OWNROOTNODE (v4.1) – Specifies that the component should be assigned its own root node in the object notation tree displayed when creating variables of type ‘Object’.
EXT_FLAG_BCOMPONENTS - Component library contains only background components.
EXT_FLAG_NVOBJECTS – Component library contains non-visual objects (either static functions or Omnis objects).
EXT_FLAG_PRI_OUTPUT - Component library contains output devices.
EXTC_FLAG_HASITEM (v3.1) - Indicates that the EXTParamInfo contains valid mItem and mVpt fields. These fields are required by some of the new callbacks in v3.1. If building components for 3.1 you should return this flag during connect.
Note: Most components do not need to catch this message. The default returned value in WNDdefWindowProc is EXT_FLAG_LOADED.
The ECM_CONSTPREFIX message is sent when Omnis requires the prefix string for all components’ constants.
If the component requires a constant prefix, it should add a parameter containing the string.
Returns:
Return true if the constant prefix has been returned.
The ECM_CONVFROMHPIXMAP message is sent to a picture format component when Omnis requires an HPIXMAP to be converted into raw binary picture data (as stored on disk).
Parameters:
lParam – HPIXMAP required to convert.
Returns:
Return qtrue if the component has successfully converted the HPIXMAP to binary data, qfalse otherwise.
The ECM_CONVHEADER message is sent to a picture format component when Omnis requires a picture formats’ header to be added or removed.
wParam – True if a header should be added, false if it should be removed.
Parameter 1 – Picture data.
The ECM_CONVTOHPIXMAP message is sent to a picture format component when Omnis requires an raw picture data to a HPIXMAP. It is important to note that the data supplied may, or may not, include any headers.
Parameters:
Parameter 1 – Picture data.
Returns:
Return an HPIXMAP handle, NULL otherwise.
The ECM_CUSTOMTABNAME message is sent to the component when Omnis requires the name of the custom tab in the Property Manager.
The component should add a parameter containing the custom tab character name.
A component should call ECOsetCustomTabName to provide the necessary information.
Returns:
Return true if a custom tab name has been supplied.
See also ECOsetCustomTabName
The ECM_DEBUGGING message is sent to the component:
just after a component library has been loaded (immediately after ECM_CONNECT).
when sys(4000) to enable debugging has been called.
when sys(4001) to disable debugging has been called.
Components may utilize this message to provide debugging statements in the trace log, and so on.
The debugging flag is maintained between Omnis sessions.
Parameters:
wParam - True if debugging is enabled, false otherwise.
Returns:
Any returned value is ignored.
The ECM_DISCONNECT message is sent to the component before an Omnis instance unloads the component. It should always be passed to the WNDdefWindowProc.
Returns:
Any returned value is ignored.
Note: Most components do not need to catch this message.
The ECM_EVENTRESULT message is sent to a Web Client external component, when the result of a custom event is returned from the server. Because events are executed on the server, the result returned from ECOsendEvent is meaningless and will always return qtrue in the Web Client environment. The true result will be sent as the ECM_EVENTRESULT message once the server returns control to the client.
Parameters:
wParam - the event code which was specified when ECOsendEvent was called.
lParam - the result 0 or 1.
Returns:
Return 1L.
See also ECOsendEvent
The ECM_FMT_CANASSIGN message is sent to the component when Omnis needs to know if a property can be written to. This message is used for format notation and even if the component does not respond to the message, it is assumed that the property can be written to.
Returns:
Return FMT_CANASSIGN if the property can be written to, return FMT_NOCANASSIGN otherwise.
See also ECM_PROPERTYCANASSIGN,Component Properties section.
The ECM_FMT_GETPROPERTY message is sent to the component when Omnis needs to know the value of a property.. This message is used for format notation and even if the component doesn’t respond to the message the property will be retrieved from the format.
Parameter one contains the current property value.
Returns:
Return FMT_VALID if the property was successfully retrieved, FMT_INVALID otherwise.
See also ECM_GETPROPERTY, Component Properties section.
The ECM_FMT_SETPROPERTY message is sent to the component when Omnis needs to set the value of a property.. This message is used for format notation and even if the component doesn’t respond to the message the property will be modified in the format.
Parameter one contains the new property value.
Returns:
Return FMT_VALID if the property was successfully modified, FMT_INVALID otherwise.
See also ECM_SETPROPERTY,Component Properties section.
The ECM_GETCOMPICON message is sent to the component when Omnis requires the HBITMAP for the component icon. A component should add a long parameter containing the HBITMAP or may call ECOreturnIcon to provide the information. Please note that the HBITMAP returned belongs to Omnis and is deleted by Omnis when the component is of no further use.
Parameters:
wParam - wParam is true if the library is available to the user.
Returns:
Return true if the bitmap has been returned, false otherwise.
The ECM_GETCOMPID message is sent when Omnis requires the object name, type and unique identifier.
The component should add a parameter which contains the character name of the object, it should also set the EXTCompInfo member mCompId to a unique identifier for that object. The mCompId is used by the component to determine to which type of object messages are referring.
Parameters:
wParam - Contains a sequential number (starting from 1) which indicates the object which is being inquired upon.
Returns:
The component should return the object type cRepObjType_xxxx and/or cObjType_xxxx or FALSE if there are no more objects in the component.
See also ECOreturnCompID
The ECM_GETCOMPLIBINFO message is sent when Omnis requires the components’ library name and the number of objects it supports.
Returns:
The component should add a parameter containing the character name of the component library and should also return the number of objects supported. A component may use the function ECOreturnCompInfo to provide the necessary information.
See also ECOreturnCompInfo
The ECM_GETCOMPSTOREGROUP message is sent to the component library when Omnis requires the name of the component store group.
The component should add a parameter containing the component store group name (maximum 31 characters), if required.
A component should call ECOreturnCStoreGrpName to provide the necessary information.
Returns:
Return true if a component store group name has been supplied.
See also ECOreturnCStoreGrpName
The ECM_GETCOMPSTOREICON message is sent to the component when Omnis requires the bitmap of the component store group. This message will only be sent if the component library returned a component store group name (see ECM_GETCOMPSTOREGROUP).
The component should add a parameter containing the bitmap.
A component should call ECOreturnIcon to provide the necessary information.
Returns:
Return true if a bitmap has been supplied.
See also ECM_GETCOMPSTOREGROUP, ECOreturnIcon
The ECM_GETCONSTNAME message is sent to the component when Omnis requires a list of the constants that the component library supports.
Constant resource strings are in the format of: -
Name - The name of the constant as it appears in Omnis methods. Constant names may contain a group name (name prefixed by group name followed by a tilde [‘~’] mark) which informs Omnis that the component constants should be sub-grouped.
Numeric value - The numeric value of the constant.
Character value - The character value of the constant.
Description - The description of the constant.
A component should call ECOreturnConstants to provide the event information.
Returns:
Return true if the event list has been returned.
See also ECOreturnConstants
The ECM_GETEVENTMETHOD message is sent to the component when Omnis requires the list of method lines for the objects’ event. This message is only sent during design mode when a new object has been created.
The component should add a single column list parameter or call function ECOreturnEventMethod.
Returns:
Return true if a method list has been provided, false otherwise.
See also ECOreturnEventMethod
The ECM_GETEVENTNAME message is sent to the component when Omnis requires a list of the events that the object supports.
A component should call ECOreturnFuncsEvents to provide the event information.
Returns:
Return true if the event list has been returned.
See also ECOreturnFuncsEvents
The ECM_GETHANDLERICON message is sent to the component when Omnis requires the HBITMAP for the control handler icon. A component should return the HBITMAP for the bitmap. Note that the HBITMAP returned belongs to Omnis and is deleted by Omnis when the control handler is of no further use.
Returns:
Return the HBITMAP of the handlers’ icon.
The ECM_GETMETHODNAME message is sent to the component when Omnis requires a list of the methods that the object supports.
A component should call ECOreturnMethodsEvents to provide the method information.
Returns:
Return true if the function list has been returned.
See also ECOreturnMethodsEvents
The ECM_GETOBJECT message is sent to a library which supports non-visual objects.
A component should call ECOreturnObjects to provide the object information.
See also ECOreturnObjects, EXT_FLAG_NVOBJECTS, Non-Visual Components
The ECM_GETOBJECTRECT message is sent to the component to retrieve the initial dimensions of the object during design mode when the object is created via the Component Store drag and drop or by double-clicking.
Parameters:
lParam - Pointer to qrect structure which should be populated with the initial dimensions of the object.
Returns:
Return qtrue if the object rectangle has been set, false otherwise.
The ECM_GETPICTFILEDESC message is sent to a picture format component when Omnis requires a string for the “Paste from file” file dialog.
The string returned must be a valid file filter string.
Returns:
Return qtrue if the component has returned a string, qfalse otherwise.
The ECM_GETPICTFORMAT message is sent to the component during the initial loading of the component. A component which supports picture conversion, for example PCX, should return a string containing the name of the format e.g. “JPEG” or “PCX” etc..
The ECM_GETPICTUREDIM message is sent to the component to retrieve the dimensions of the object which has been defined as cObjType_Picture.
Parameters:
lParam - Pointer to a qrect structure. The component should modify the members accordingly.
Returns:
Return true if the component has populated the structure, false otherwise.
The ECM_GETPRIMARYDATA message is sent to the component to obtain the data for an object.
If the component is handling the data for an object, it should return this in parameter one.
Returns:
Return true if the data has been supplied, false otherwise.
See also EXTD_FLAG_PRIMEDATA
The ECM_GETPRIMARYDATALEN message is sent to the component when Omnis requires the object’s data length.
Returns:
The component should return the objects data length.
See also EXTD_FLAG_PRIMEDATA
The ECM_GETPROPERTY message is sent to the component when Omnis requires the data for a property.
The component should add a return parameter which contains the property data.
Returns:
Return true if successful, false otherwise.
See also Component Properties section.
The ECM_GETPROPERTYENUMS message is sent to the component when Omnis requires the enum list for a property (previously defined with EXTD_FLAG_ENUM).
The component should return a list containing the line data and, optionally, the marks which identify each line. After an item has been selected from the list, Omnis sends the component an ECM_SETPROPERTY message with the line data or the line mark (if a line mark was provided).
Returns:
Return true if enum list has been provided, false otherwise.
See also EXTD_FLAG_ENUM
The ECM_GETPROPNAME message is sent to the component when Omnis requires a list of the properties that the object handles.
A component should call ECOreturnProperties to provide the property list.
Returns:
Return true if the property list has been returned.
See also ECOreturnProperties
The ECM_GETSTATICOBJECT message is sent to a library which supports non-visual objects.
A component should call ECOreturnMethods to provide the static object information.
See also ECOreturnMethods, EXT_FLAG_NVOBJECTS, Non-Visual Components
The ECM_GETVERSION message is sent when Omnis requires the version number of the component.
A component should call ECOreturnVersion to provide the version number. If the component fails to respond to this message then Omnis will assume a version number of 1.0.
For web client components, the version number of the component must be implemented as a string in the string resources of the component. The web client plug-in reads this string for the purpose of the automated download mechanism. See ECOreturnVersion for more details.
Returns:
Return the return value from ECOreturnVersion
See also GDIreadVersion, ECOreturnVersion
The ECM_HASPRIMARYDATACHANGED message is sent to web client components to determine if the components primary data has changed since the last ECM_SETPRIMARYDATA or ECM_GETPRIMARYDATA. When writing data bound web client controls, the control is responsible for maintaining its own modified state. This is so the web client only returns data for fields to the server, which have been changed by the user. Return one of the following:
ECMRET_NOTIMPLEMENTED - default return value.
ECMRET_NOTCHANGED - return this if the data has NOT been changed by the user since the last ECM_GETPRIMARYDATA or ECM_SETPRIMARYDATA. This should be the default return value for read only controls.
ECMRET_CHANGED - return this if the data has been changed by the user since the last ECM_GETPRIMARYDATA or ECM_SETPRIMARYDATA.
ECMRET_CURROWCHANGED - return this if the primary data is a single selection list and the current row has changed since the last ECM_GETPRIMARYDATA or ECM_SETPRIMARYDATA.
ECMRET_ROWSELECTCHANGED (v3.1) - return this if the primary data is a multiple selection list and the current row and list selection state has changed since the last ECM_GETPRIMARYDATA or ECM_SETPRIMARYDATA
ECMRET_CURROWSELECTCHANGED (v3.1) - return this if the primary data is a multiple selection list and the current row and list selection state of the current row only has changed since the last ECM_GETPRIMARYDATA or ECM_SETPRIMARYDATA
See also ECM_SETPRIMARYDATA, ECM_GETPRIMARYDATA
The ECM_ICONDRAWENTRY message is sent to inform the component to draw an icon for an object which has been defined as cObjType_IconArray.
Parameters:
lParam - Pointer to EXTIconArrayInfo structure (see Below).
Returns:
Return true if the icon was drawn, false otherwise (which results in Omnis drawing the icon).
mHdc - Device context into which the icon should be drawn.
mLine - The line number.
mEntryRect - The rectangle of the icon array entry/cell.
mDrawRect - The rectangle of the text or icon (dependant on whether the message is ECM_ICONDRAWENTRY or ECM_TEXTDRAWENTRY).
mDrawFocus - True if the icon array entry/cell currently has the input focus.
mSelected - True if the entry/cell is selected.
mDragging - True if the entry is currently being dragged.
mSmallIcons - True if the small icons are to be drawn (as opposed to large icons).
mListPtr - List data pointer. This member contains the list variable pointer as defined in the property member data name.
See also cObjType_IconArray, ECM_TEXTDRAWENTRY
The ECM_INBUILT_OVERRIDE message is sent from Omnis for certain built in properties which are normally handled by Omnis. Built in properties consist of anumFont, anumFontsize, anumTextColor, anumFontStyle, anumAlign, anumVScroll, anumHScroll, anumHScrolltips, anumVScrolltips, anumHorzscroll, anumVertscroll, anumEffect, anumHelpid, anumContextmenu, and anumFldStyle.
A component return 1L if it wants to manually maintain the built in property.
The ECM_INSTALLLIBRARY message is sent to a control handler when a request has been made to install another library via the #EXTCOMPS dialog>>Install button.
Returns:
Return true if message is processed, false otherwise.
The ECM_ISCONVFORMAT message is sent to a picture format component when Omnis is attempting to establish, from binary data, the picture format. This will be sent because the Omnis script function pictformat has been invoked.
It is important to note that the data supplied may, or may not, include any headers.
Parameters:
Parameter 1 – Picture data.
Returns:
Return qtrue if the picture data is in a format that the component supports, false otherwise.
The ECM_LISTDRAWLINE message is sent to inform the component to draw a list line for a object which has been defined as cObjType_List or cObjType_DropList.
Parameters:
lParam - Pointer to EXTListLineInfo structure (see Below).
Returns:
Return true if the list line was drawn, false otherwise (which results in Omnis drawing the line).
See also cObjType_List, cObjType_DropList
The ECM_MEMORYDELETION message is sent to inform the component library it needs to free previously allocated memory. This message should always be passed on to WNDdefWindowProc.
Note: Components do not need to catch this message, just pass it to the WNDdefWindowProc.
See also ECOmemoryDeletion
The ECM_METHODCALL message is sent to inform the component that an objects’ method has been invoked. All parameters for the method have been added to the EXTCompInfo structure. A component should add any return parameter.
Returns:
Return true if method has been invoked, false otherwise.
See also Component Methods Section
The ECM_NEWMETHODFLAGS message is sent to the component in response to the component sending a WM_CONTROL message (wParam = RESET_METHOD_FLAGS) to the objects HWND.
It enables controls such as Graphs to update the Property Manager depending on the context.
Returns:
The component should return the new EXTD_FLAG_xxx flags for the method.
See also RESET_METHOD_FLAGS
The ECM_NEWPROPERTYFLAGS message is sent to the component in response to the component sending a WM_CONTROL message (wParam = RESET_PROPERTY_FLAGS) to the objects HWND.
Enables controls such as Graphs to update the Property Manager depending on the context.
Returns:
The component should return the new EXTD_FLAG_xxx flags for the property.
See also RESET_PROPERTY_FLAGS
The ECM_OBJCONSTRUCT message is sent to instruct the component to construct an instance of the object.
Parameters:
hWnd - The HWND of the object which is being constructed.
wParam – For visual components wParam is either ECM_WPARAM_WINDOWOBJ or ECM_WPARAM_REPORTOBJ depending on the type of object to construct. For non-visual components wParam is either :-
ECM_WPARAM_OBJMSG to indicate that the message is due to $construct.
Or ECM_WPARAM_OBJINFO to indicate that the message is due to a new object being created.
wParam may also contain the flag ECM_WFLAG_NOHWND for background objects.
lParam – A pointer to the calling Omnis object instance. This qobjinst* can be stored an subsequently passed to functions such as ECOdoMethod() that require an object instance pointer.
Returns:
The component should return qtrue if it processes the message.
Note: It is good practice to use the ECO Object chain. New objects can be added to the chain with ECOinsertObject, and removed using ECOremoveObject. All supplied examples use this chain.
Example 1
Example 2
The ECM_OBJDESTRUCT message is sent to instruct the component to destruct an instance of the object.
Parameters:
hWnd - The HWND of the object which is to be destructed.
wParam –For non-visual components wParam is either :-
ECM_WPARAM_OBJMSG to indicate that the message is due to $destruct.
Or ECM_WPARAM_OBJINFO to indicate that the message is due to a new object being destroyed.
Returns:
Any returned value is ignored.
Note: It is good practice to use the ECO Object chain. New objects can be added to the chain with ECOinsertObject, and removed using ECOremoveObject. All supplied examples use this chain.
The ECM_OBJECTDATABLOCK message is sent to the component when Omnis is setting or getting the properties for the object. Most components ignore this message as property assignment/retrieval is provided automatically in Omnis, and in this case the component must return false.
However, some control types (ActiveX for example) require objects to be initialized using a data block. In this case, if wParam = ECM_WPARAM_BLOCKLOAD, the first parameter contains the property data for the object otherwise the component should add a parameter which contains the property data for the object.
Parameters:
wParam - Contains either ECM_WPARAM_BLOCKSAVE or ECM_WPARAM_BLOCKLOAD.
Returns:
Return true if successful (i.e. the object supports data block property assignment), false otherwise.
The ECM_OBJECT_COPY message is sent to the component when a non-visual object assignment is required.
Parameters:
lParam – lParam contains a pointer to a objCopyInfo structure which contains the copy information.
Returns: Any return value is ignored.
See also EXT_FLAG_NVOBJECTS, Non-Visual Components
The ECM_OBJECT_REBUILD message is sent to the component to inquire whether a rebuild of a non-visual objects’ properties and/or methods is required.
Returns:
Return true if the object requires a rebuild.
See also EXT_FLAG_NVOBJECTS, Non-Visual Components
The ECM_OBJINITIALIZE message is sent twice during the construction of an object. Once, just before any properties have been set, and once after.
Parameters:
wParam - wParam contains false before the object is initialized (i.e. properties set), true after the object has been initialized.
Returns:
Any returned value is ignored.
Note: Components do not need to catch this message, just pass it on the WNDdefWindowProc.
The ECM_PAINTCONTENTS message is sent to inform the component to draw the droplist contents window for a object which has been defined as cObjType_DropList.
Parameters:
lParam - Pointer to EXTListLineInfo structure (see ECM_LISTDRAWLINE).
The ECM_PRIMARYDATACHANGE message is sent to inform the component that its objects data has changed. Most components ignore this message, but more specialized components may need to complete additional data processing after the data has changed.
Returns:
Any return value is ignored.
See also EXTD_FLAG_PRIMEDATA
The ECM_PRINT message is sent by Omnis to inform the component to print the object. You will also receive ECM_PRINT messages for background components when they need to be painted. Background objects do not receive WM_PAINT messages.
Parameters:
wParam - Picture object type: wParam contains ECM_WPARAM_PICTNOSCALE bit set if no scaling if required.
lParam - lParam contains a pointer to a WNDpaintStruct structure which contains the printer HDC and the object print rectangle.
Parameter 1 - contains any primary data (as during ECM_SETPRIMARYDATA message).
Returns:
Any return value is ignored.
See also ECM_SETPRIMARYDATA
The ECM_PRINTMAPPING message is sent to the component to inquire on any print mapping required.
Print mapping enables Omnis to suitably scale the object. See CALENDAR and PCX for examples.
Returns:
The component should return true if print mapping is required, false otherwise.
The ECM_PROPERTYCALCTYPE message is sent to the component when Omnis needs to know the calculation type for calculation properties. If a property is not a calculation, do not implement this message.
Returns:
Return ctySquare if the property is of type square bracket calculation (the actual calculations are embedded in text using square brackets. Return ctyCalculation if it is a standard calculation, i.e. field name or functions.
The ECM_PROPERTYCANASSIGN message is sent to the component when Omnis needs to know if a property can be written to or not.
Returns:
Return true if the property can be written to, false otherwise.
See also Component Properties section.
The ECM_SETPRIMARYDATA message is sent by Omnis to inform the component to set the data for the object. The first parameter contains the new data for the object.
Returns:
Return true if the component handles the data, false otherwise.
See also EXTD_FLAG_PRIMEDATA
The ECM_SETPROPERTY message is sent to the component when Omnis requires a property to change.
Parameter one contains the new data for the property.
Parameters:
wParam - wParam is set to ECM_WPARAM_PROPBUTTON if the Property Manager popup button was pressed to set the property. For example, a file name property may wish to use a file open dialog if the popup button was pressed. Please note that if wParam is ECM_WPARAM_PROPBUTTON, parameter one does not contain any data.
See also Component Properties section.
wParam is 0 (add to NV Chain), 1 (remove from NV Chain)
This message can be used to prevent Omnis from creating unnecessary copies of external objects. Once implemented you can simply create a single object instance and increment or decrement the usage count, depending on the value of wParam.
Parameters:
wParam – if 0 increment usage count, if 1 decrement usage count.
The ECM_TEXTDRAWENTRY message is sent to inform the component to draw the text for an object which has been defined as cObjType_IconArray.
Parameters:
lParam - Pointer to EXTIconArrayInfo structure (see Below).
mHdc - Device context into which the text entry should be drawn.
mLine - The line number.
mEntryRect - The rectangle of the icon array entry/cell.
mDrawRect - The rectangle of the text or icon (dependant on whether the message is ECM_ICONDRAWENTRY or ECM_TEXTDRAWENTRY).
mDrawFocus - True if the icon array entry/cell currently has the input focus.
mSelected - True if the entry/cell is selected.
mDragging - True if the entry is currently being dragged.
mSmallIcons - True if the small icons are to be drawn (as opposed to large icons).
mListPtr - List data pointer. This member contains the list variable pointer as defined in the property member data name.
See also cObjType_IconArray, ECM_ICONDRAWENTRY
WM_CONTROL is a group of messages which may be sent to the HWND to instruct Omnis objects to perform specialized actions. Some of the messages described are implemented as functions in Omnis, but are included here for completeness.
Instructs Omnis to set the enabled state of the desktop switch. This is useful if the component supports functionality similar to OLE in-place activation (as Omnis OLE does), whereby, during in-place activation the desktop switch menu should be disabled to avoid the user changing the desktop mode.
Please note that the menu enabled state can be changed on the development version of Omnis only, the runtime version (which doesn’t have the menu) ignores this message.
lParam - qtrue if menu should be enabled, qfalse otherwise.
Instructs Omnis to draw the objects’ name. Functionally the same as ECOdrawDesignName.
lParam – The HDC to draw into.
See also ECOdrawDesignName
Instructs Omnis to draw the multi-selected design knobs. Functionally the same as ECOdrawMultiKnobs.
lParam – The HDC to draw into.
See also ECOdrawMultiKnobs
Instructs Omnis to draw the objects’ number. Functionally the same as ECOdrawNumber.
lParam – The HDC to draw into.
See also ECOdrawNumber
Returns the operating system menu handle for the Omnis menu.
lParam - Menu handle required. Currently only MM_FILE is supported.
Returns the Omnis palette handle.
Returns true if the object has the focus. Functionally the same as ECOhasFocus.
See also ECOhasFocus
Instructs Omnis to hide the on-screen tool tip if it is shown. Functionally the same as ECOhideTooltip.
See also ECOhideTooltip
Returns true if the object is editable (i.e. in runtime and not read-only).
Returns true if in design mode. Functionally the same as ECOisDesign.
See also ECOisDesign
Returns true if the object is currently one of many objects selected. Functionally the same as ECOisMultiSelected.
See also ECOisMultiSelected
Returns qtrue if Omnis is currently in build mode. Build mode is the state when Omnis is debugging an Omnis method. During this state, components should not execute events ( ECOsendEvent ).
See also ECOisOMNISinTrueRuntime
Returns true if the object is currently selected. Functionally the same as ECOisSelected.
See also ECOisSelected
Asks Omnis if the component has been serialised and returns information about the serial number.
See also ECOisSerialised, EXTserialise
Allows the component to inquire on the set-up state of the object. The set-up state of an object is false before properties have been initialized, true afterwards. Functionally the same as ECOisSetup.
See also ECOisSetup
Returns true if the object is in design-mode and ‘Show number’ is true. Functionally the same as ECOisShowNumber.
See also ECOisShowNumber
Returns true if the object is a member of the top-most window. Functionally the same as ECOisWndTop.
See also ECOisWndTop
Informs Omnis of a new line height for cObjType_List objects. Functionally the same as ECOlistSetLineHeight.
lParam - qlong which represents the new line height for the list.
See also ECOlistSetLineHeight
Returns true if the Omnis is currently a background application.
Instructs the cObjType_Picture object to erase the background.
See also cObjType_Picture
Instructs the cObjType_Picture object to recalculate the scroll range for the object. On receipt of this message, Omnis sends the component the ECM_GETPICTUREDIM message.
See also ECM_GETPICTUREDIM
Instructs Omnis to reset all method flags. Omnis sends the component repeated ECM_NEWMETHODFLAGS for each method in the object.
See also ECM_NEWMETHODFLAGS
Instructs Omnis to reset all property flags. Omnis sends the component repeated ECM_NEWPROPERTYFLAGS for each property in the object.
See also ECM_NEWPROPERTYFLAGS
Instructs Omnis to rebuild the edit menu.
Instructs Omnis that the objects’ palette has altered. Functionally the same as GDIsetPalette.
lParam - HPALETTE handle of the new palette.
See also GDIsetPalette
Updates the Omnis status bar with the specified text.
lParam - Pointer to null terminated string.
Instructs Omnis to set the visibility state of all desktop toolbars. This is useful if the component supports functionality similar to OLE in-place activation (as Omnis OLE does), whereby, during in-place activation, all Omnis toolbars should be removed to avoid confusion between Omnis and the activated application.
lParam - qtrue if toolbars are visible, qfalse otherwise.
Instructs Omnis to set the visibility state of all windows, except the window which contains the external component. This is useful if the component supports functionality similar to OLE in-place activation (as Omnis OLE does), whereby, during in-place activation, all Omnis windows should be removed to avoid confusion between Omnis and the activated application.
lParam - qtrue if windows are visible, qfalse otherwise.
This can only be used when deriving from an Omnis picture field (cObjType_Picture ). This message instructs Omnis not to erase the picture field’s client area when data changes. This gives you more control if, for example, you want to fade an image over the previous image. lParam is used to indicate if the erase should happen or not.
See also cObjType_Picture
Instructs Omnis to update the Property Manager. Functionally the same as ECOupdatePropInsp.
lParam - qlong which represents the property to update. Zero updates all properties.
See also ECOupdatePropInsp
EXTParamInfo* ECOaddParam(EXTCompInfo* pEci, EXTfldval* pFval, qlong pParamId = 0, qshort pParamType = 0, qlong pParamFlags = 0, qchar pParamNum=0, qlong pParamParent = 0 ) |
---|
The ECOaddParam function adds a new parameter to EXTCompInfo structure allowing you to pass information to/from Omnis.
Normally a component calls this function passing only the pEci and pFval pointers. It should be noted that after ECOaddParam has been called the data contents ( memory ) of pFval belong to another object inside Omnis, so the deletion of the pFval causes no memory to be deleted.
pFval data belongs to Omnis and may be deleted in the component.
pEci - Specifies the pointer to the EXTCompInfo structure.
pFval - Specifies the pointer to the parameter data.
pParamId - Specifies the id of this parameter. The default value of 0 indicates a returned parameter.
pParamType - Specifies the parameter data type.
pParamFlags - Specifies the parameter flags.
pParamNum - Specifies the parameter number.
pParamParent - Specifies the parameters’ parent id.
returns - Returns a pointer to the EXTParamInfo structure which contains the parameter.
void ECOaddTraceLine( str255* pString ) |
---|
The ECOaddTraceLine function enables the component to add strings to the Omnis trace log.
pString - The pointer to the str255 class which contains the string.
qbool ECOcanSendEvent( HWND pHwnd, qlong pEventID) |
---|
Use ECOcanSendEvent to test if an event can be send now.
pHwnd - The HWND of the object.
pEventID - The id of the event.
returns - Returns true if the event can be send now. If this function returns false and the event must be send, the component should delay the sending by using a timer and checking again later.
See also ECOsendEvent
qbool ECOclipboardGetPicture(qHandle& pPicture) |
---|
This function retrieves picture data from the clipboard.
pHandle – (output) the handle containing the clipboard data
returns – true if the clipboard contained picture data.
See also ECOclipboardHasFormat, ECOclipboardSetPicture, ECOclipboardSetText, ECOclipboardGetText.
qbool ECOclipboardGetPictureEx(qHandle& pPicture) |
---|
This function retrieves a picture from the clipboard; with alpha support.
pHandle – (output) the handle containing the clipboard data
returns – true if the clipboard contained picture data.
qbool ECOclipboardGetText(qHandle& pText) |
---|
This function retrieves text data from the clipboard.
pText – reference to a qHandle.
returns – true if the clipboard contained text data.
See also ECOclipboardHasFormat, ECOclipboardSetText, ECOclipboardGetPicture, ECOclipboardSetPicture
qbool ECOclipboardHasFormat(EXTclipType pType) |
---|
Use this function to check if the clipboard contains data of the specified type.
pType – enum, one of the following
eExtClipText – test the clipboard for text data
eExtClipPicture – test the clipboard for picture data
returns – true if the clipboard contains data of the specified type
See also EXTclipType, ECOclipboardGetPicture, ECOclipboardGetText
qbool ECOclipboardSetPicture(qHandle pPicture) |
---|
This function places the given data as a picture on the clipboard.
pText – the picture data.
returns – true if the call was successful.
See also ECOclipboardGetPicture , ECOclipboardGetText, ECOclipboardSetText
qbool ECOclipboardSetText(qHandle pText) |
---|
This function places the given data as text on the clipboard.
pText – the text data.
returns – true if the call was successful.
See also ECOclipboardGetText, ECOclipboardGetPicture, ECOclipboardSetPicture
qlong ECOconvertHFSToPosix( strxxx& pSrcPath, strxxx& pDstPath ) |
---|
Converts the supplied Mactintosh file/folder path from Hierarchical File System format (colon separators) to Posix format (forward slash separators).
pSrcPath – a strxxx object containing the HFS formatted path string.
pDestPath – a strxxx object which receives the Posix formatted path string.
qlong ECOconvertPosixToHFS( qbyte *pSrcPath, CFStringEncoding pSrcEncoding, strxxx& pDstPath ) |
---|
Converts the supplied Mactintosh file/folder path from Posix format (forward slash separators) to Hierarchical File System format (colon separators).
pSrcPath – a buffer containing the null-terminated Posix formatted path string.
pSrcEncoding – A constant describing the Unicode encoding of the source string.
pDestPath – a strxxx object which receives the HFS formatted path string.
qbool ECOconvKnownJavaObjs(tqappfile* pLib, qlong &pFlag) |
---|
Returns the object’s behavior with regard to Java object types. (Used internally by the Java objects component). The value if pFlag after the call indicates the behavior:
pFlag – (output) qfalse => traditional behaviour object references are returned, qtrue => known objects are converted to Omnis types.
qret ECOdoMethod(qobjinst pObjInst,strxxx* pMethod, EXTfldval* pParams = 0, qshort pParamCnt = 0,qbool pExecNow=qtrue, EXTfldval *pReturnValue = 0) |
---|
Where an Omnis object is superclassed with a non-visual external component, the ECOdoMethod function can be used to invoke a method inside the object class. For example, if an email object has a method called ‘$newmail’ then a component may wish to use ECOdoMethod to inform Omnis of new mail.
This function is basically a wrapper for ECOdoMethodECI.
pObjInst - Pointer which was originally generated by Omnis and passed to the external’s WNDPROC during ECM_OBJCONSTRUCT.
pMethod – A strxxx object containing the name of the method to execute.
pParams - Pointer to an array of EXTfldval which contain the parameters for the method.
pParamCnt - Number of parameters for the method.
pExecNow - True if the method should be processed by Omnis immediately, false otherwise.
pReturnValue – Allows the Omnis method to pass a return value back to the component via the Quit method command.
returns - Returns a qret data type containing the result.
See also ECOdoMethodECI
qbool ECOdoMethodECI( qobjinst pObjInst, strxxx* pMethod, EXTCompInfo* pEci, qbool pExecNow=qtrue ) |
---|
Where an Omnis object is superclassed with a non-visual external component, the ECOdoMethod function can be used to invoke a method inside the object class. For example, if an email object has a method called ‘$newmail’ then a component may wish to use ECOdoMethod to inform Omnis of new mail.
Most components use ECOdoMethod in preference to this function.
pObjInst - Pointer which was originally generated by Omnis and passed to the external during ECM_OBJCONSTRUCT.
pMethod – A strxxx object containing the name of the method to execute.
pEci - The EXTCompInfo structure which contains the method parameters.
pExecNow - True if the method should be processed by Omnis immediately, false otherwise.
returns - Returns a qret data type containing the result.
See also ECOdoMethod
qbool ECOdrawDesignName( HWND pHWnd, HDC pHDC ) |
---|
Allows the component to draw the name in the specified device context. Will have no effect if the object is not in design mode.
pHWnd - The HWND of the object.
pHDC – The device context to draw into.
See also DRAW_DESIGN_NAME
void ECOdrawMultiKnobs( HWND pHWnd, HDC pHDC ) |
---|
Allows the component to draw the multi-select knobs in the specified device context. Will have no effect if only one object is selected or if the object is not selected.
pHWnd - The HWND of the object.
pHDC – The device context to draw into.
See also DRAW_MULTIDESIGN_KNOBS
qbool ECOdrawNumber( HWND pHWnd, HDC pHDC ) |
---|
Allows the component to draw the number in the specified device context. Will have no effect if ‘Show number’ is not active.
pHWnd - The HWND of the object.
pHDC – The device context to draw into.
See also DRAW_NUMBER
void ECOexcludeToolTipRect( HWND pHWnd, HDC pHDC ) |
---|
Allows the component to exclude the tool-tip rectangle from the device contexts’ clipped drawing area.
pHWnd - The HWND of the object.
pHDC – The device context to exclude the tool-tip rectangle from.
See also ECOgetToolTipRect
void* ECOfindObject( HINSTANCE pInstance, HWND pHWnd, WPARAM pWParam =0 ) |
---|
Locates a pointer which has previously been stored via the ECOinsertObject function.
pInstance - The Omnis instance. This may be NULL which results in the function searching all Omnis instances for the HWND.
pHWnd - The HWND being searched for.
pWParam - Background components only. The WPARAM which was passed in from Omnis, this should be passed for background components only.
returns - Returns the pointer previously stored via the call to ECOinsertObject.
See also ECOinsertObject
void* ECOfindNVObject( HINSTANCE pInstance, LPARAM pInstPtr ) |
---|
Locates a pointer which has previously been stored via the ECOinsertNVObject function.
pInstance - The Omnis instance. This may be NULL which results in the function searching all Omnis instances for the HWND.
pInstPtr – The unique object instance reference (as allocated by Omnis)
returns - Returns the pointer previously stored via the call to ECOinsertNVObject.
See also ECOinsertNVObject, Non-visual components
EXTParamInfo* ECOfindParamNum( EXTCompInfo* pEci, qlong pParamID ) |
---|
Locates a parameter in the EXTCompInfo structure. This function should be used to locate method and property parameters.
pEci - The pointer to the EXTCompInfo structure.
pParamID - The id of the parameter to be located.
returns - Returns the pointer to the EXTParamInfo structure if successful, NULL otherwise.
void ECOfindString(str255 &pFindString, str255 &pStringToSearch, lsttype *pResultList) |
---|
Accesses the Omnis string table editor and searches for pFindString inside pStringToSearch at the current find location. If found, a row is added to pResultList containing the current find location and pStringToSearch.
pFindString – The string to search for.
pStringToSearch – The string to be searched.
pResultList – The out list which is appended with the search result.
qapp ECOgetApp( locptype* pLocp ) |
---|
Returns a reference to an Omnis application. The EXTCompInfo structure which is passed to external components contains two context pointers. The context pointer mInstLocp points to the context of the class instance which contains the component. The context pointer mLocLocp points to the context of the calling method.
pLocp - The context pointer.
return - The Omnis library reference.
void *ECOgetBundleRef(qlong pBundleID) |
---|
Returns a CFBundleRef dependant on the pBundleID.
pBundleID - Should be either kXsocket or kCoreGraphics.
qbool ECOgetCrbFieldInfo( strxxx& pFieldName, locptype* pLocp, crbFieldInfo& pFInfo ) |
---|
ECOgetCrbFieldInfo gets the specified fields full format information. See structure crbFieldInfo for full description of the information returned.
pFieldName - The Omnis variable
pLocp - The context pointer.
pFInfo - Pointer the info structure
return - Returns true if the Omnis variable was found.
See also struct crbFieldInfo in EXTfldval class reference
PRIdestParmStruct* ECOgetDeviceParms( locptype* pLocp ) |
---|
Returns a reference to the global device parameters structure. It is not a copy, and altering any values in the structure will effect the Omnis devices.
pLocp - The context pointer. Currently not used.
return - Points to Omnis device parameters.
qbool ECOgetDirectoryDialog( HINSTANCE pInstance, HWND pOwner, qlong pTitle, str255& pDirName, strxxx* pInitDir = 0 ) qbool ECOgetDirectoryDialog( HINSTANCE pInstance, HWND pOwner, strxxx& pTitle, str255& pDirName, strxxx* pInitDir = 0 ) |
---|
The ECOgetDirectoryDialog function enables the component to invoke a dialog to request a directory.
pInstance - The instance which contains the string resources required. This would normally be gInstLib.
pOwner - The HWND of the owner.
pTitle - The resource id for the title OR a str255 object containing the title.
pDirName - The str255 object which contains the directory name upon return, if successful.
pInitDir - The pointer to the str255 object which specifies the initial directory. May be NULL.
returns - Returns true if a directory has been selected, false otherwise.
Note: On MacOS make sure the component project contains the OMNISLIB.RSRC file.
void ECOgetFont( HWND pHwnd , qfnt* pFnt, qshort pFntIndex, qshort pFntSize ) |
---|
The ECOgetFont function enables the component to obtain font details for the given index and font size.
pHwnd - The HWND of the object.
pFnt - Pointer to the qfnt structure which is populated, if successful, by Omnis.
pFntIndex - The index of the font required.
pFntSize - The size of the font required.
void ECOgetFont( qapp pApp, qbool pReportFont, qfnt* pFnt, qshort pFntIndex, qshort pFntSize ) |
---|
The ECOgetFont function enables the component to obtain font details for the given index and font size from the specified Omnis library. It also allows you to specify if you require a report font or windows font.
pApp - Reference to the Omnis library. See ECOgetApp().
pReportFont - Specify qtrue if you require a font from the libraries report font table.
pFnt - Pointer to the qfnt structure which is populated, if successful, by Omnis.
pFntIndex - The index of the font required.
pFntSize - The size of the font required.
qshort ECOgetFontIndex( HWND pHwnd, EXTfldval& pFVal ) |
---|
The ECOgetFontIndex function returns a font index from the specified font name.
pHwnd – The HWND of the component control.
pFVal – Specifies the EXTfldval which contains the font name in character format.
Returns – Returns a font index from 1 to 31 if succeeded, 0 otherwise.
qlong ECOgetId( EXTCompInfo* pEci) |
---|
The ECOgetId function should be used to retrieve the id of the method or property.
pEci - The pointer to the EXTCompInfo structure.
returns - Returns the id of the method or property if successful, zero otherwise.
qulong ECOgetLocalIpAddress(void) |
---|
Returns the client machine’s ethernet IP address as a hexadecimal long integer.
void *ECOgetNVObject(objectinst *pInst) |
---|
Searches for an external component instance in the chain of super instances of this object, returning the first instance found. If no external component instance is found, pInst is returned.
pInst – The initial object instance.
qlong ECOgetOmnisVersionNumber(void) |
---|
Returns the Omnis Studio version number as a five digit long value.
For example: 5.1.1 is returned as 51100
qshort ECOgetParamCount( EXTCompInfo* pEci ) |
---|
The ECOgetParamCount function enables the component to inquire on how many parameters, which have ids sequentially from 1, are in the EXTCompInfo structure. This is especially useful during the ECM_METHODCALL message to ensure that the correct number of parameters have been supplied.
pEci - The pointer to the EXTCompInfo structure.
returns - Returns the number of parameters.
qbool ECOgetParamInfo( EXTparamInfo* pParam, EXTparamTypeInfo&pInfo) |
---|
Returns additional type information about the parameter specified by pParam.
pParam – Pointer to the parameter structure.
pInfo – Reference to the structure which will receive the additional info.
See also EXTparamInfo, EXTparamTypeInfo
qbool ECOgetProperty(HWND pHwnd, qshort pAnum, EXTfldval& pFval ) |
---|
The ECOgetProperty function enables the component to obtain information concerning Omnis standard object properties.
pHwnd - The HWND of the object.
pAnum - The anum of the property which is requested (See ANUMS.HE for the list of possible anums).
pFval - The EXTfldval object which contains the property, if successful.
returns - Returns true if successful, false otherwise.
qbool ECOgetStyle(tqappfile* pApp, qchar* pStyleName, qshort pLen, GDItextSpecStruct* pTextSpec) |
---|
The ECOgetStyle function enables the component to obtain the field style information.
pApp – The tqappfile pointer for the instance of the component.
pStyleName – A pointer to the field style name.
pLen – The length of the field style name.
pTextSpec – A pointer to a GDItextSpecStruct which will be populated upon return.
returns - Returns true if successful, false otherwise.
qbool ECOgetToolTipRect(HWND pHwnd, qrect* pRect) |
---|
The ECOgetToolTipRect function enables the component to obtain the position of the tool tip (if visible).
pHwnd - The HWND of the object.
pRect – The pointer to a qrect object which will contain the tool-tip rectangle upon return (only is a tool-tip is currently visible).
returns - Returns true if successful, false otherwise.
qbool ECOhasFocus( HWND pHWnd ) |
---|
The ECOhasFocus function enables the component to inquire on the focus state of the object.
pHWnd - The HWND of the object.
returns - Returns true if the object currently has the focus, false otherwise.
void ECOhideTooltip( HWND pHwnd ) |
---|
The ECOhideTooltip function can be used by the components to hide the on screen tool tip. The Omnis tool tip is drawn directly to the screen. It saves the bitmap where is it about to be displayed for later restoring when the tool tip is not needed.
As a result, if a tool tip is displayed and partly covers the control, the control paints due to a timer message for example, the bitmap saved by the tool tip that it uses for restoring could now be invalid.
To avoid this problem, controls can call this API, passing their components HWND to hide the tip.
pHwnd - The HWND of the object.
void ECOinsertObject( EXTCompInfo* pEci, HWND pHWnd, void* pObjPointer, WPARAM pWParam ) |
---|
Stores a pointer for the specified HWND in a list of Omnis instances.
pInstance - Specifies the Omnis instance to which this pointer should belong to.
pHWnd - Specifies the HWND which is linked to the pointer.
pObjPointer - Specifies the pointer to be stored.
pWParam - Background components only. The WPARAM which was passed in from Omnis, this should be passed for background components only.
See also ECM_OBJCONSTRUCT
void ECOinsertNVObject( HINSTANCE pInstance, LPARAM pInstPtr, void* pObjPointer ) |
---|
Stores a pointer for the specified HWND in a list of Omnis instances.
pInstance - Specifies the Omnis instance to which this pointer should belong to.
pInstPtr – Specifies the object instance pointer (as supplied by Omnis) to associate the pObjPointer with.
pObjPointer - Specifies the pointer to be stored.
See also ECOfindNVObject, Non-visual components
void ECOinvalBackObj() |
---|
If the object is a background component, ECOinvalBackObj() invalidates the drawing area, causing it to be redrawn.
qbool ECOisDesign( HWND pHWnd ) |
---|
The ECOisDesign function enables the component to inquire on the design state of the object.
pHWnd - The HWND of the object.
returns - Returns true if the object is in design, false otherwise.
qbool ECOisMultiSelected( HWND pHWnd ) |
---|
pHWnd - The HWND of the object.
returns - Returns true if the object is currently multi-selected, false otherwise.
See also IS_MULTISELECTED
qbool ECOisOMNISinTrueRuntime( HWND pHwnd ) |
---|
Returns qtrue if Omnis is in a true runtime state. In this state it is safe for components to send events. In some other states it is not safe. For example, your component maybe a runtime component, but Omnis may be in build mode debugging another method. Omnis always tries to switch to the correct mode when executing a method/event. If you send an event during a debug session, Omnis brings your component to the front immediately, executes your event and returns to the debug session. For some controls such as a clock sending events every second, this is not what should happen.
pHwnd - The HWND of the object.
returns - qtrue if Omnis is in true runtime.
qbool ECOisSelected( HWND pHWnd ) |
---|
Allows the component to inquire on whether the object is currently selected.
pHWnd - The HWND of the object.
returns - Returns true if the object is currently selected, false otherwise.
See also IS_SELECTED
qbool ECOisSerialised( HWND pHOmnisCompHwnd, qchar* pProductCode, qchar* pFunctionCode = NULL, qchar* pSerial = NULL, qchar* pNotes = NULL ) qbool ECOisSerialised(qchar* pProductCode, qchar* pFunctionCode = NULL, qchar* pSerial = NULL, qchar* pNotes = NULL ) |
---|
Asks Omnis if the component has been serialised and returns information about the serial number.
pHOmnisCompHwnd – Components hwnd
pProductCode – Product code supplied by component. Must be 4 alpha/numeric characters.
pFunctionCode – Functionality code returned by Omnis. These consist of 4 alpha/numeric characters describing the enabled functionality.
pSerial – Complete serial number. Returned by Omnis.
pNotes – Notes as entered with the serial number by the user. Returned by Omnis.
See also IS_SERIALISED
qbool ECOisSetup( HWND pHWnd ) |
---|
Allows the component to inquire on the set-up state of the object. The set-up state of an object is false before properties have been initialized, true afterwards.
pHWnd - The HWND of the object.
returns - Returns true if the object is set-up, false otherwise.
See also ECM_OBJINITIALIZE, IS_SETUP
qbool ECOisShowNumber( HWND pHWnd ) |
---|
Allows the component to inquire on whether the design-time option ‘Show number’ is on.
pHWnd - The HWND of the object.
returns - Returns true if ‘Show number’ is on, false otherwise.
See also IS_SHOWNUMBER
qbool ECOisWndTop( HWND pHWnd ) |
---|
Allows the component to inquire on whether the object is a member of the top-most window.
pHWnd - The HWND of the object.
returns - Returns true if the object is a member of the top-most window, false otherwise.
See also IS_WINDOW_TOP
void ECOlistFonts( EXTqlist *pList, qbool pReportFonts) |
---|
Allows the component to obtain a list of window or report fonts installed on the machine.
pList - The list to populate.
pReportFonts – True if a list of report fonts is required.
void ECOlistSetLineHeight( HWND pHOmnisCompHwnd, qlong pLineHeight ) |
---|
The ECOlistSetLineHeight function should be used by the component to specify the line height (in pixels) of objects which have previously been defined as cObjType_List.
pHOmnisCompHwnd - The HWND of the object.
pLineHeight - The list line height.
See also WM_CONTROL - LIST_SETLINEHEIGHT, cObjType_List
qbool ECOloadFileDialog( HINSTANCE pInstance, HWND pOwner, qlong pResTitle, qlong pResFilter, str255& pFileName, str255* pInitDir = 0 ) qbool ECOloadFileDialog( HINSTANCE pInstance, HWND pOwner, strxxx& pTitle, strxxx& pFilter, str255& pFileName, str255* pInitDir = 0 ) |
---|
The ECOloadFileDialog function enables the component to invoke the operating system load file dialog.
pInstance - The instance which contains the string resources required. This would normally be gInstLib.
pOwner - The HWND of the owner.
pResTitle or pTitle - The resource id or string for the title of the load file dialog.
pResFilter or pFilter - The resource id or string for the filter string of the load file dialog. Any platform dependent filters are removed if not required. e.g.
pFileName - The str255 object which contains the file name upon return, if successful.
pInitDir - The pointer to the str255 object which specifies the initial folder. May be NULL.
returns - Returns true if a file has been selected, false otherwise.
Note: On MacOS make sure the component project contains the OMNISLIB.RSRC file.
qlong ECOmapString(qchar *pBuffer, qlong pBufferLen, qlong pLen) |
---|
Accesses the Omnis string table editor and searches for a string with ID matching the contents of pBuffer. If found, pBuffer is assigned the contents of the string table element and the character length is returned.
pBuffer – On input- the ID of the string to match, on output- the contents of the string table element.
pBufferLen – the length in bytes of the buffer (prevents overrun).
pLen – the length in characters of the input ID string.
void ECOmemoryDeletion( EXTCompInfo* pEci) |
---|
Deletes memory previously allocated in the external component (returned parameters for example). WNDdefWindowProc processes the ECM_MEMORYDELETION message. See ECOpushCompEvent for an example of the use of ECOmemoryDeletion.
pEci - Pointer to EXTCompInfo structure which contains the parameters to delete.
See also ECM_MEMORYDELETION
qbool ECOmessageBox(qulong pFlags,qbool pBell,str255& pMsg) |
---|
Provides external components with access to Omnis message box dialogs.
pFlags - Determines the type of message box which can be: MSGBOX_OK, MSGBOX_YESNO, MSGBOX_NOYES, MSGBOXICON_OK, MSGBOXICON_YESNO, MSGBOXICON_NOYES, MSGBOXCANCEL_YESNO or MSGBOXCANCEL_NOYES
pBell – If qtrue, indicates that the system bell should sound
pMsg – The text for the message
void ECOpaintGrayFrame(HDC pHdc, qrect &pRect) |
---|
Draws a gray frame around the control in design mode, so that the control is visible on the design window.
qbool ECOreadLocalisationItem(EXTCompInfo *pEci, qshort pLocItemXn, str255 &pLocItemData) |
---|
Returns the localised text from the localisation database.
pEci - Pointer to EXTCompInfo structure.
pLocItemXn - identifies the localized item. This can be one of the cLOCxn constants. See source file LOCALISE.HE for a listing.
pLocItemData - the localised text is returned in this parameter.
returns - true if the item exists and text has been returned.
qbool ECOreloadLibData(str80& pLibName) |
---|
Instructs the core to rebuild object lists, reloading icons, properties, events and constants for the specified component. The component’s window object is closed if open.
pLibName – object name, usually read from resource string 1000
void* ECOremoveObject(EXTCompInfo* pEci, HWND pHWnd, WPARAM pWParam ) |
---|
Removes a pointer reference which had previously been stored via ECOinsertObject.
pInstance - Specifies the Omnis instance which the pointer was originally inserted into.
pHWnd - Specifies the HWND which is linked to the pointer.
pWParam - Background components only. The WPARAM which was passed in from Omnis, this should be passed for background components only.
returns - Returns the pointer originally passed into the ECOinsertObject function.
See also ECOinsertObject, ECM_OBJDESTRUCT
void* ECOremoveNVObject( HINSTANCE pInstance,LPARAM pInstPtr ) |
---|
Removes a pointer reference which had previously been stored via ECOinsertNVObject.
pInstance - Specifies the Omnis instance which the pointer was originally inserted into.
pInstPtr – Specifies the object instance pointer (as supplied by Omnis in LPARAM) which was originally used during ECOinsertNVObject.
returns - Returns the pointer originally passed into the ECOinsertNVObject function.
See also ECOinsertNVObject, Non-visual components
qbool ECOresetObjDetails(qobjinst pObjInst, EXTfldval& pProps, EXTfldval& pMethods) |
---|
The ECOresetObjDetails function provides a means for non-visual components to dynamically alter the properties and methods which an object provides.
pObjInst - Pointer which was originally generated by Omnis and passed to the external during ECM_OBJCONSTRUCT.
pProps - A list containing the new properties for the object. This list should be in the format as returned by ECOreturnProperties. See the section on Control Handlers for more information on the exact structure of this list.
pMethods - A list containing the new methods for the object. This list should be in the same format as returned by ECOreturnMethods. See the section on Control Handlers for more information on the exact structure of this list.
Returns - Returns true if successful, false otherwise.
See also Non-Visual components
qlong ECOreturnCompID( HINSTANCE pInstance, EXTCompInfo* pEci, qshort pCompResNameID, qshort pCompType ) |
---|
The ECOreturnCompID function provides support for the ECM_GETCOMPID message.
pInstance - The instance which contains the resources(component name) for the component object. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pCompResNameID - The resource id for the component name.
pCompType - The component object base type. Of type cObjType_xxx and/or cRepObjType_xxx.
returns - Returns the pCompType value which should returned to Omnis.
See also ECM_GETCOMPID
qlong ECOreturnCompInfo( HINSTANCE pInstance, EXTCompInfo* pEci, qshort pLibNameResID, qshort pCompCount) |
---|
The ECOreturnCompInfo function provides support for the ECM_GETCOMPLIBINFO message.
pInstance - The instance which contains the resources(library name) for the component library. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pLibNameResID - The resource id for the component library name.
pCompCount - The number of objects within the components’ library.
returns - Returns true if successful, false otherwise.
See also ECM_GETCOMPLIBINFO
qbool ECOreturnConstants( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResStart, qlong pResEnd) |
---|
Provides support for the ECM_GETCONSTNAME message.
pInstance - The instance which contains the resources for the constants. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pResStart - Resource identifier for the first constant.
pResEnd - Resource identifier of the last constant.
returns - Returns true if successful, false otherwise.
It should be noted that this function is successful even if not all the resource slots between pResStart and pResEnd are populated. This would enable the component to easily modify groups of constants.
See also ECM_GETCONSTNAME
qbool ECOreturnCStoreGrpName( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResID ) |
---|
The ECOreturnCStoreGrpName function provides support for the ECM_GETCOMPSTOREGROUP message.
pInstance - The instance which contains the resources(custom component store group name). This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pResID - The resource id for the custom component store group name.
returns - Returns true if successful, false otherwise.
See also ECM_GETCOMPSTOREGROUP
qbool ECOreturnEventMethod( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResStart) |
---|
The ECOreturnEventMethod function provides support for the ECM_GETEVENTMETHOD message.
pInstance - The instance which contains the resources(method lines). This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pResStart - The resource id for the start of the event method instructions. You should note that this function continues to add method lines until an empty string is located in the resources.
returns - Returns true if successful, false otherwise.
See also ECM_GETEVENTMETHOD
qbool ECOreturnEventMethod( HINSTANCE pInstance, EXTCompInfo* pEci, ECOmethodEvent* pTable, qshort pTableElements, qbool pIncDesc = qtrue) |
---|
The ECOreturnEventMethod function provides support for the ECM_GETEVENTMETHOD message. This function generates an event method from the event table rather than from sequence of event lines in resources [see ECOreturnEventMethod(pInstance, pEci, pResStart) above]
pInstance - The instance which contains the resources(method lines). This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pTable - The pointer to the ECOmethodEvent structure.
pTableElements - Number of events in the ECOmethodEvent structure.
pIncDesc - True if description should be included as a comment in the event method.
returns - Returns true if successful, false otherwise.
See also ECM_GETEVENTMETHOD
qbool ECOreturnEvents( HINSTANCE pInstance, EXTCompInfo* pEci, ECOmethodEvent* pTable, qshort pTableElements ) |
---|
The ECOreturnEvents function provides support for the ECM_GETEVENTNAME message.
pInstance - The instance which contains the resources for the events. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pTable - The pointer to the ECOmethodEvent structure.
pTableElements - Number of events in the ECOmethodEvent structure.
returns - Returns true if successful, false otherwise.
See also ECM_GETEVENTNAME, Component Events
qbool ECOreturnIcon(HINSTANCE pInstance, EXTCompInfo* pEci, qshort pBitmapID ) |
---|
The ECOreturnIcon function provides support for the ECM_GETCOMPICON message.
pInstance - The instance which contains the resources(object icon) for the component object. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pBitmapID - The resource id for the components’ object icon.
returns - Returns true if successful, false otherwise.
See also ECM_GETCOMPICON
ECOreturnMethodEvents simply calls ECOreturnMethods.
qbool ECOreturnMethods( HINSTANCE pInstance, EXTCompInfo* pEci, ECOmethodEvent* pTable, qshort pTableElements ) |
---|
The ECOreturnMethods function provides support for the ECM_GETMETHODNAME message.
pInstance - The instance which contains the resources for the methods. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pTable - The pointer to the ECOmethodEvent structure.
pTableElements - Number of functions or events in the ECOmethodEvent structure.
returns - Returns true if successful, false otherwise.
See also ECM_GETMETHODNAME, Component Events
qbool ECOreturnObjects( HINSTANCE pInstance, EXTCompInfo* pEci, ECOobject* pTable, qshort pTableElements ) |
---|
The ECOreturnObjects function provides support for the ECM_GETOBJECT message.
pInstance - The instance which contains the resources for the objects. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pTable - The pointer to the ECOobject structure.
pTableElements - Number of objects in the ECOobject structure.
returns - Returns true if successful, false otherwise.
See also ECM_GETOBJECT, Non-Visual components
qbool ECOreturnProperties( HINSTANCE pInstance, EXTCompInfo* pEci, ECOproperty* pPropTable, qshort pTableElements ) |
---|
The ECOreturnProperties function provides support for the ECM_GETPROPNAME message.
pInstance - The instance which contains the resources for the properties. This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pPropTable - The pointer to the ECOproperty structure.
pTableElements - Number of properties in the ECOproperty structure.
returns - Returns true if successful, false otherwise.
See also ECM_GETPROPNAME, and the Component Events section.
qlong ECOreturnVersion( qshort pMajorNumber, qshort pMinorNumber) |
---|
The ECOreturnVersion function provides support for the ECM_GETVERSION message.
pMajorNumber - The major part of the components’ version number.
pMinorNumber - The minor part of the components’ version number.
See also ECM_GETVERSION, GDIreadVersion
qlong ECOreturnVersion(HINSTANCE pInst) |
---|
Web client components must use this mechanism to return the components version number from its resources. The component must have the following string resource
Please note the spaces. These are important. The 1 specifies the major version, and the 5 specifies the minor version. Non-web client components can also use this new mechanism to return the version number.
pInstance - The instance which contains the string resources required. This would normally be gInstLib.
See also ECM_GETVERSION, GDIreadVersion
ECOsaveFileDialog()
qbool ECOsaveFileDialog( HINSTANCE pInstance, HWND pOwner, qlong pResTitle, qlong pResFilter, str255& pFileName, str255* pInitDir = 0 ) qbool ECOsaveFileDialog( HINSTANCE pInstance, HWND pOwner, strxxx& pTitle, strxxx pFilter, str255& pFileName, str255* pInitDir = 0 ) |
---|
The ECOsaveFileDialog function enables the component to invoke the operating system save file dialog.
pInstance - The instance which contains the string resources required. This would normally be gInstLib.
pOwner - The HWND of the owner.
pResTitle or pTitle - The resource id or string for the title of the save file dialog.
pResFilter or pFilter - The resource id or string for the filter string of the save file dialog. Any platform dependent filters are removed if not required. Note: ONLY used on WINDOWS.
pFileName - The str255 object which contains the file name upon return, if successful.
pInitDir - The pointer to the str255 object which specifies the initial folder. May be NULL.
returns - Returns true if a file has been selected, false otherwise.
qbool ECOsendCompEvent( HWND pHwnd, EXTCompInfo* pEci, qlong pEventID, qbool pExecNow ) |
---|
The ECOsendCompEvent function enables the component to send Omnis object events. This function is useful for components which need to add the parameters manually to the EXTCompInfo structure. Most components use ECOsendEvent in preference to this function.
pHwnd - The HWND of the object.
pEci - The EXTCompInfo structure which contains the event parameters.
pEventID - The id of the event.
pExecNow - True if the event should be processed by Omnis immediately, false otherwise.
returns - Returns true if the event has been processed by Omnis, false if it has been discarded. If pExecNow is false this function always returns true.
See also ECOsendEvent
qbool ECOsendEvent( HWND pHwnd, qlong pEventID, EXTfldval* pParams = 0, qshort pParamCnt = 0, qbool pExecNow = EEN_EXEC_IMMEDIATE) |
---|
The ECOsendEvent function enables the component to send Omnis object events. This function is basically a wrapper for ECOsendCompEvent.
pHwnd - The HWND of the object.
pEventID - The id of the event.
pParams - Pointer to an array of EXTfldval which contain the parameters for the event.
pParamCnt - Number of parameters for the event.
pExecNow - can be one of the following
EEN_EXEC_LATER - the event should be processed by OMNIS later. The event is added to the end of the Omnis event queue
EEN_EXEC_IMMEDIATE - the event should be processed by Omnis immediately
EEN_EXEC_PUSH (v3.1) - the event should be pushed on the Omnis event queue in front off all existing events on the queue.
returns - Returns true if the event has been processed by Omnis, false if it has been discarded. If pExecNow is false this function always returns true. When calling ECOsendEvent from Web Client components, ECOsendEvent will always return qtrue. The correct result is send to the component once the server returns control to the client. See ECM_EVENTRESULT.
See also ECOsendCompEvent
qbool ECOsetCustomTabName( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResID ) |
---|
The ECOsetCustomTabName function provides support for the ECM_CUSTOMTABNAME message.
pInstance - The instance which contains the resources(custom tab name). This would normally be gInstLib.
pEci - The pointer to EXTCompInfo structure.
pResID - The resource id for the custom tab name.
returns - Returns true if successful, false otherwise.
See also ECM_CUSTOMTABNAME
void ECOsetDTformat( str80& pFormat, qshort pFormatType ) |
---|
The ECOsetDTformat function enables the component to set the Omnis internal variables #FD, #FT, #FDT. This function is most useful in the Omnis Web Thin-Client so that controls can localize their date/time routines.
pFormat – The new string format for the required format type. Please note that this variable will contain the old string on return.
pFormatType – The required data type. This can be dpFdate1900, dpFdate1980, dpFdate2000 for #FD (date formatting); or dpFtime for #FT (time formatting); others types will be for #FDT (date and time formatting).
void ECOsetError( qlong pErrNum, str255* pErrText ) |
---|
The ECOsetError function enables the component to set the Omnis variables #ERRCODE and #ERRTEXT.
pErrNum - The error number stored in #ERRCODE.
pErrText - The pointer to the str255 object stored in #ERRTEXT.
void ECOsetParameterChanged( EXTCompInfo* pEci, qshort pParamNum ) |
---|
The ECOsetParameterChanged function should be called by the component when a method parameter has been modified. Failure to call this function results in any modifications made to a method parameter being lost on return to Omnis. The method parameter must previously been defined with the EXTD_FLAG_PARAMALTER flag.
pEci - The pointer to the EXTCompInfo structure containing the function parameters.
pParamNum - The number of the parameter which has been modified.
See also ECM_METHODCALL, EXTD_FLAG_PARAMALTER
qbool ECOsetProperty( HWND pHwnd, qshort pAnum, EXTfldval &pFval ) |
---|
The ECOsetProperty enables the component to set the Omnis standard object properties.
pHwnd - The HWND of the object.
pAnum - The anum of the property which is go to be set (See ANUMS.HE for the list of possible anums).
pFval - The EXTfldval object which contains the property, if successful.
returns - Returns true if successful, false otherwise.
void ECOsetupCallbacks( HWND pHwnd, EXTCompInfo* pEci ) |
---|
The ECOsetupCallbacks function initializes the global array of pointers which contain the callback function pointers. This must be called upon entry to all window procedures that Omnis invokes.
pHwnd - The HWND that received the message.
pEci - The pointer to EXTCompInfo structure which contains the callback pointers.
void ECOupdatePropInsp( HWND pHOmnisCompHwnd, qlong pPropId = 0 ) |
---|
The ECOupdatePropInsp function can be called by the component to update the Property Manager. This function may be called during either design or runtime.
pHOmnisCompHwnd - The HWND of the object.
pPropId - The property id which is updated. If the property id is not supplied all properties are updated.
See also WM_CONTROL - UPDATE_PROPINSPECTOR
ECOAPI qshort OMNISAPI ECOuprCmp(qchar* add1, qchar* add2, qlong len) |
---|
The ECOuprCmp function compares the text of two strings after converting to upper case. Returns 0 if the two strings are equal, -1 if add1 is less than add2, 1 if add1 is greater than add2. The two text strings are left unchanged.
add1- The address of string 1.
add2 - The address of string 2.
len - The number of characters to use in the comparison.
qbool WNDdefWindowProc( HWND pHwnd, LPARAM pMsg, WPARAM wParam, LPARAM lParam, EXTCompInfo* pEci ) |
---|
The WNDdefWindowProc function calls the default window processing. All messages not handled must be passed to this function.
pHwnd - The HWND that received the message.
pMsg - The window message.
wParam - wParam of the message.
lParam - lParam of the message.
pEci - EXTCompInfo pointer that was passed into the window procedure.
returns - The result of Omnis processing the message.
When creating cross-platform external components, you may need to manipulate memory manually. As some objects may need to use greater than 64K of memory, for example imaging components, a set of memory functions are available to cope with the 16bit problems encountered under 16 bit Windows.
The MEM functions are cross-platform allowing your code to remain independent of the operating system in which you develop.
qchar* MEMcalloc( qulong pSize ) |
---|
Allocates a block of memory, and locks it in memory. The allocation can be greater than 64K. The memory allocated is initialized to 0.
pSize - The amount of memory to allocate.
returns - The locked memory address.
qulong MEMdataLen( void* pBuffer ) |
---|
Returns the size of a buffer.
pBuffer - The buffer to return a size for. This buffer must have previous been allocated with MEMmalloc or MEMcalloc.
returns - The length of the buffer.
qchar* MEMdecAddr( qchar* pAddress, qlong pOffset ) |
---|
Decrements a memory address by an offset.
pAddress - The address to decrement.
pOffset - The amount to decrement by.
returns - A new address.
Note: This function is very important under Windows 16bit due to 64K segments. When handling large memory blocks, this function must be used to adjust pointers.
You can use MEMdecAddr() and MEMincAddr() with the result of MEMglobalLock.
void MEMfree( void* pBuffer ) |
---|
Reclaims the memory previous allocated from a MEMmalloc or MEMcalloc call.
pBuffer - The buffer to destroy. This buffer must have previous been allocated with MEMmalloc or MEMcalloc.
HGLOBAL MEMglobalAlloc ( qlong pLength, qbool pZeroInited = qfalse ) |
---|
Allocates a block of memory.
pLength - The amount of memory to allocate.
pZeroInited - qtrue if the memory should be cleared to 0.
returns - A new HGLOBAL handle.
void MEMglobalFree ( HGLOBAL pMemory ) |
---|
Reclaims the memory previously allocated by a MEMglobalAlloc. The data must be in an unlocked state.
pMemory - The memory to be destroyed.
HGLOBAL MEMglobalHandle ( void* pAddress ) |
---|
Returns a memory handle given an address.
pAddress - An address to return the memory handle for.
returns - A memory handle.
void* MEMglobalLock (HGLOBAL pMemory ) |
---|
Locks a memory handle, increments the lock count and returns the address of the handles first byte.
pMemory - The memory handle to lock
returns - The address of the first byte of memory associated with the memory handle.
HGLOBAL MEMglobalReAlloc ( HGLOBAL pMemory, qlong pNewLength ) |
---|
Reallocates a block of memory.
pMemory - The old memory handle.
pNewLength - The new size of the memory block.
returns - A new HGLOBAL handle.
qlong MEMglobalSize ( HGLOBAL pMemory ) |
---|
Returns the size of a memory handle.
pMemory - The memory handle.
returns - The length of the handles data.
void MEMglobalUnlock ( HGLOBAL pMemory ) |
---|
Unlocks a memory handle and decrement the lock count.
pMemory - The memory handle to unlock.
qchar* MEMincAddr( qchar* pAddress, qlong pOffset ) |
---|
Increments a memory address by an offset.
pAddress - The address to be incremented.
pOffset - The amount to increment by.
returns - A new address.
Note: This function is very important under Windows 16bit due to 64K segments. When handling large memory blocks, this function must be used to adjust pointers.
qchar* MEMmalloc( qulong pSize ) |
---|
Allocates a block of memory, and locks it in memory. The allocation can be greater than 64K.
pSize - The amount of memory to allocate.
returns - The locked memory address.
qint2 MEMmemcmp( void* pAddress1, void* pAddress2, qlong pTestLen ) |
---|
Compares two blocks of memory.
pAddress1 - Points to the starting address of the first block of memory.
pAddress2 - Points to the starting address of the second block of memory.
pTestLen - The size of the memory blocks, in bytes, to compare.
returns - 0, -1 or 1.
Returns 0 if both memory blocks match.
Returns -1 if memory block 1 is less than memory block 2.
Returns 1 if memory block 1 is greater than memory block 2.
void MEMmemFill( void* pFillAddress, qint4 pFillLen, qchar pFillChar ) |
---|
Fills memory with a specified character.
pFillAddress - The address in memory to fill.
pFillLen - The number of bytes to fill.
pLen - The character to be used to fill memory.
Example:
void MEMmovel( void* pSrc, void* pDst, qlong pLen ) |
---|
Move memory from source to destination copying data from left to right ( start to end ).
pSrc - The source address.
pDst - The destination address.
pLen - The number of bytes to copy.
Example:
void MEMmover( void* pSrc, void* pDst, qlong pLen ) |
---|
Move memory from source to destination copying data from right to left ( end to start )
pSrc - The source address.
pDst - The destination address.
pLen - The number of bytes to copy.
Example:
qchar* MEMrealloc( void* pBuffer, qulong pNewLen ) |
---|
Alters the size of the buffer to a different size.
pBuffer - The buffer to be re-allocated. This buffer must have previously been allocated with MEMmalloc or MEMcalloc.
pNewLen - The new size for the buffer.
returns - A pointer to the reallocated buffer. The original pointer and new pointer may be different.
qlong MEMscanf(qshort pDirection, qlong pLen, qchar pScanChar, const void * pScanAddress ) |
---|
Scans a memory location for a character.
pDirection - If positive, the scan is performed from the beginning to the end of memory block, otherwise the scan is performed from the end to the beginning.
pLen - The number of characters to scan. If this is positive the search is forward, if this is negative the search is from the end of the buffer ( the length is added to the buffer before scan starts ).
pScanChar - The character to scan for.
pScanAddress - The address to scan.
returns - The index position from the start of the scan or pLen if failed to locate character.
Example:
The following set of memory functions all support greater than 64K allocation blocks. The memory is automatically locked and pointers to the memory are returned. For more control when the memory is locked, use the memory handling functions.
qHandle HANglobalAlloc ( qlong pLength, qbool pZeroInited = qfalse ) |
---|
Allocates a block of memory, from Omnis the internal memory cache.
pLength - The amount of memory to allocate.
pZeroInited - qtrue if the memory should be cleared to 0.
returns - A new qHandle.
qHandle HANglobalReAlloc(qHandle pHandle, qlong pNewLen ) |
---|
Reallocates a block of Omnis memory.
pMemory - The old memory handle.
pNewLength - The new size of the memory block.
returns - A new qHandle.
qlong HANglobalSize ( qHandle pGlobal, qlong pNewLen ) |
---|
Returns the size of a memory handle.
Note: This could be bigger than the data length.
pMemory - The memory handle.
returns - The length of the handles data.
void HANglobalFree ( qHandle pHandle ) |
---|
Reclaims the memory previously allocated by a HANglobalAlloc.
pMemory - The memory to be handed back into the Omnis memory cache.
The qHandlePtr class gives your external components convenient ways to manipulate Omnis cache memory easily.
qHandlePtr:: qHandlePtr() |
---|
Creates an empty qHandlePtr class.
qHandlePtr(qHandle pHandle, qlong pOffset) |
---|
Constructs a qHandlePtr class.
pHandle- The memory to be handed back into the Omnis memory cache.
pOffset - The offset into the memory.
qHandlePtr (const qHandlePtr& pHptr) |
---|
Constructs a qHandlePtr class from an existing qHandlePtr.
pHptr- an Existing qHandlePtr class.
void operator =(qniltype qnil1) |
---|
Assigns the handle of the qHandlePtr to zero.
void qHandlePtr:: operator =(const qHandlePtr& pHptr) |
---|
Duplicates an existing qHandlePtr.
pHptr- an Existing qHandlePtr class.
void operator +=(qlong pInc) |
---|
Increments the offset in to memory block.
pInc- The amount to increment the offset.
void operator -=(qlong pDec) |
---|
Decrements the offset in to memory block.
pDec- The amount to decrement the offset.
qHandlePtr operator +(qlong pDel) |
---|
Makes a copy of itself and increments the copy specified by pDel.
pInc- The amount to increment the offset in the copy.
qHandlePtr operator +(qlong pDel) |
---|
Makes a copy of itself and decrements the copy specified by pDel.
pDec- The amount to decrement the offset in the copy.
qbool operator !() |
---|
Tests whether the handle is non-zero.
qchar* operator *() |
---|
Return a qchar pointer which is calculated as :-
returns - Memory block base + Offset.
qchar* operator *(qlong pDel) |
---|
Return a qchar pointer which is calculated as :-
returns - Memory block base + Offset + pDel.
qchar& operator [](qlong pDel) |
---|
Return a qchar reference which is calculated as
returns - Memory block base + Offset + pDel.
qulong dataLen() |
---|
Return the actual length of the data contained in the handle.
N.B. This might not be the same as the result of HANglobalSize, this is because the data contained in this memory block might not occupy all of it.
returns - Data Length of the Handle.
Sets the actual length of the data contain in the handle.
pSize - Sets the Data Length of the handle.
qulong getOffset() |
---|
Returns the current offset into the memory block
returns - offset into the memory block.
void getHandle(qHandle& pHandle) |
---|
Returns the handle of the qhandleptr
pHan - a qHandle memory block.
void set(qHandle pHandle, qlong pOffset) |
---|
Sets the qhandleptr from the provided parameters
pHandle - a qHandle memory block.
pOffset - Offset into the memory block.
void setOffset(qlong pOffset) |
---|
Set the Offset of the qhandleptr.
pOffset- Offset into the memory block.
void setNull() |
---|
Set the handle to zero.
The following set of RES or Resource functions allow cross-platform access to your external components resources.
void REScloseLibrary ( HINSTANCE pInstance) |
---|
Closes an instance of a DLL previously opened with RESopenLibrary.
pInstance - An instance of a library already opened with RESopenLibrary.
See also RESopenLibrary
void REScloseResourceFork( qshort pResFileNum ) |
---|
Closes a Macintosh resource file.
pResFileNum - The number returned from the RESopenResourceFork API.
See also RESopenResourceFork
HINSTANCE RESgetOmnisDAT( EXTCompInfo* pEci ) |
---|
Returns an instance to the Omnis resources library (OMNISDAT.DLL on Windows).
pEci - The pointer to the EXTCompInfo structure.
returns - An instance to the Omnis resources.
Note: The instance returned must not be closed (i.e. via REScloseLibrary).
HBITMAP RESloadBitmap( HINSTANCE pLibrary, qlong pBmpID ) |
---|
Retrieves a HBITMAP object from the resources.
pLibrary - The library to extract a bitmap from.
pBmpID - The resource id of the bitmap.
returns - A bitmap object.
Note: The bitmap object must be deleted with GDIdeleteBitmap.
qHandle RESloadDialog( HINSTANCE pInstance, qlong pResID ) |
---|
Retrieves a dialog resource for use with custom output devices. RESloadDialog should be called in response to a PM_OUT_GETPARMDLG message (see print manager reference).
pInstance - The library to extract a bitmap from.
pResID - The resource id of the dialog.
returns - An Omnis handle.
Note: The bitmap object must be deleted with GDIdeleteBitmap.
qlong RESloadString( HINSTANCE pInstance, qlong pResID, qchar* pBuffer, qlong pBufferLen ) |
---|
Retrieves a string from an open library resources.
pInstance - The library to extract a string from.
pResID - The resource id of the string.
pBuffer - The address to receive the string
pBufferLen - The maximum number of bytes allowed to copy into pBuffer
returns - The actual number of bytes copied into pBuffer
qlong RESloadString( HINSTANCE pInstance, qlong pResID, strxxx& pString ) |
---|
Retrieves a string from an open library resources.
pInstance - The library to extract a string from.
pResID - The resource id of the string.
pString - The string variable to receive the string.
returns - The actual number of bytes copied into pString
HINSTANCE RESopenLibrary ( strxxx& pLibraryPath ) |
---|
Opens another library file. This can be used if, for example, you keep resources in another file.
The component must call REScloseLibrary when it is finished with the library file.
pInstance - The name of the library file to open
returns - An instance to the opened library if successful, zero otherwise.
See also REScloseLibrary
qshort RESopenResourceFork( HINSTANCE pInstance ) |
---|
This function should be used on the Macintosh if a Macintosh Resource Manager API needs to be called, for example, GetResource. The HINSTANCE can be that normal global component instance gInstLib, or another HINSTANCE that was returned from RESopenLibrary.
pInstance - The instance of the library.
returns - Returns the number of the resource fork.
See also RESopenLibrary, REScloseResourceFork
You can use the following functions for bit operations. The bit index range for all of the functions is 0-31.
void bitClear( qint4& pValue, qshort pBit ) |
---|
Clears a bit in a value.
pValue - The value to clear a bit in
pBit - The bit index to clear
void bitSet( qint4& pValue, qshort pBit ) |
---|
Sets a bit in a value.
pValue - The value to set a bit in
pBit - The bit index to set
void bitset( qint4& pValue, qshort pBit, qbool pState ) |
---|
Alters the state of a bit in a value.
pValue - The value to set a bit in
pBit - The bit index to set
pState - The new state for the bit index
qbool bitTest( qint4 pValue, qshort pBit ) |
---|
Tests a bit in a value.
pValue - The value to use for bit testing.
pBit - The bit index to test
returns - qtrue if the bit is set and qfalse if the bit is clear
Example:
You can use the following functions in order to construct new instances of Omnis objects.
qobjinst EXTobjinst(EXTCompInfo* pEci) |
---|
EXTobjinst constructs a new qobjinst (for use with EXTfldval::setObjInst) from the supplied EXTCompInfo structure. The new qobjinst is an empty external object which is associated with the external library which created it but it has no subtype.
pEci – Pointer to an EXTCompInfo structure which Omnis uses to associate the object with the appropriate external library. EXTCompInfo member mCompId will be used as an identifier for that object.
returns – Returns a new qobjinst pointer if successful, zero otherwise. ECOresetObjDetails can then be used to add properties and/or methods to this dynamic object.
See also ECOresetObjDetails,EXTfldval::setObjInst
qobjinst EXTobjinst(qobjinst pObjInst) |
---|
This EXTobjinst function duplicates the supplied qobjinst to return a new qobjinst pointer.
pObjInst – qobjinst pointer to duplicate.
Returns – returns a new qobjinst if successful, zero otherwise.
See also EXTfldval::setObjInst
qobjinst EXTobjinst(qapp pApp,str255* pClassName) |
---|
This EXTobjinst function creates a new instance of an object from the specified class name.
pApp – qapp pointer which is a unique pointer to the library in Omnis.
pClassName – str255 pointer which contains the class to create.
Returns – returns a new qobjinst if successful, zero otherwise.
See also EXTfldval::setObjInst, ECOgetApp