Chapter 2—Structures, Messages & Functions

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.

Structures

ECOmethodEvent (for methods)

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.

struct ECOmethodEvent
{
  qlong      mId;
  qlong      mNameResID;
  qlong      mReturnDataType;
  qlong      mParameterCount;
  ECOparam*  mParameters;
  qlong      mFlags;
  qlong      mExFlags;
};
  1. 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).

  2. 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.

  3. mReturnDataType - Returned data type of type fftxxx. Specify 0 for no returned data (e.g. void) and fftNone for an unspecified data type.

  4. mParameterCount - Number of parameters for the method. Specify zero for no parameters.

  5. mParameters - Pointer to an array of parameters. Specify NULL if there are no parameters.

  6. mFlags - Method flags of type EXTD_FLAG_xxxx.

  7. 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.

struct ECOparam
{
  qlong mNameResID;
  qlong mDataType;
  qlong mFlags;
  qlong mExFlags;
};
  1. mNameResID - Resource id which contains the parameters’ name.

  2. mDataType - fftxxx data type of the parameter. Use fftNone for an unspecified data type.

  3. mFlags - Parameter flags of type EXTD_FLAG_xxxx. Examples are EXTD_FLAG_PARAMOPT and EXTD_FLAG_PARAMALTER.

  4. mExFlags - Must be zero. Extended flags for future enhancement.

Example of a method table

// The parameters
ECOparam CALENDARparams[2] =
{
  // string 7000 for param name, fftInteger type
  7000, fftInteger, 0, 0,
  // string 7001 for param name, fftInteger type
  7001, fftInteger, 0, 0
};
// The method table
ECOmethodEvent CALENDARmethods[3] =
{
  cCalendarMethodSetDayIcon, 6000, 0, 2, &CALENDARparams[0], 0, 0,
  cCalendarMethodClearDayIcons, 6001, fftInteger, 1, &CALENDARparams[0], 0, 0, cCalendarMethodGetDayIcon, 6002, 0, 0, 0, 0, 0
};
// method cCalendarFuncSetDayIcon uses string 6000 for its name,
// no return type, 2 parameters, the address to a parameter.
// The last two items are method flags, see member description above.
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETMETHODNAME:
    {
      // you want to support method, so send OMNIS the method table.
      return ECOreturnMethods( gInstLib, eci, &CALENDARmethods[0], 3 );
    }
    case ECM_METHODCALL:
    {
      // OMNIS code is calling your component method
      qlong methodID = ECOgetId(eci);
      switch(methodID)
      {
        case cCalendarMethodSetDayIcon: …….
        case cCalendarMethodClearDayIcons: …….
        case cCalendarMethodGetDayIcon:
        {
          // this method supports parameters
          // so get information for parameter 1
          EXTParamInfo* param = COfindParamNum( eci, 1 );
          // create an EXTfldval from the information data
          EXTfldval passedParam( (qlong)param->mData );
          qlong valuePassed = passedParam.getLong();
          …….
          break;
        }
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnMethodsEvents, ECM_METHODCALL,
EXTD_FLAG_PARAMOPT, EXTD_FLAG_PARAMALTER

ECOmethodEvent (for events)

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.

struct ECOmethodEvent
{
  qlong mId;
  qlong mNameResID;
  qlong mReturnDataType;
  qlong mParameterCount;
  ECOparam* mParameters;
  qlong mFlags;
  qlong mExFlags;
};

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

// The event parameters
ECOparam SLIDERnewPos[1] =
{
  // resource 6000 for its name and type fftInteger
  6000, fftInteger, 0, 0
};
// The event table
ECOmethodEvent SLIDERevents[3] =
{
  cSliderEvStartSlider, 5000, 0, 0, 0, 0, 0,
  cSliderEvEndSlider, 5001, 0, 0, 0, 0, 0,
  cSliderEvNewSliderPos, 5002, 0, 1, &SLIDERnewPos[0], 0, 0
};
// function cSliderEvNewSliderPos uses string 5002 for its name, no return
// type, 1 parameters, the address to a parameter table. The last two items
// are event flags, see memeber description above.
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETEVENTNAME:
    {
      // you want to support events, so send OMNIS the event table.
      return ECOreturnEvents(gInstLib,eci,&SLIDERevents[0],3);
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}
// Events can be sent using the ECOsendEvent API.
// e.g. ECOsendEvent( mHWnd, cSliderEvStartSlider, 0, 0 );
// or with an event parameter
// EXTfldval evParam;
// evParam.setLong( 10 );
// ECOsendEvent( mHWnd, cSliderEvNewSliderPos, &evParam, 1 );

ECOproperty

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.

struct ECOproperty
{
  qlong mPropID;
  qlong mNameResID;
  qlong mDataType;
  qlong mFlags;
  qlong mExFlags;
  qlong mEnumStart;
  qlong mEnumEnd;
};

Example Property Table

ECOproperty OMNISICNproperties[4] =
{
  cOmnisIcnBackColor, 4000, fftInteger, EXTD_FLAG_PWINDCOL, 0, 0, 0,
  cOmnisIcnIsTransparent, 4001, fftBoolean, 0, 0, 0, 0,
  cOmnisIcnIconId, 4002, fftInteger, EXTD_FLAG_PWINDICON, 0, 0, 0,
  cOmnisIcnScale, 4003, fftBoolean, 0, 0, 0, 0
};
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPROPNAME:
    {
      // you want to support properties, so send OMNIS
      // the property table.
      return ECOreturnProperties( gInstLib, eci, &OMNISICNproperties[0], 4 );
    }
    case ECM_PROPERTYCANASSIGN:
    {
      // OMNIS wants to know if you allows assignment to a property
      qlong propID = ECOgetId(eci);
      // you should return 1L if the
      // propID ( e.g. cOmnisIcnBackColor ) can be assigned.
      return 0L;
    }
    case ECM_SETPROPERTY:
    {
      // OMNIS is informing you to set a property value.
      qlong propID = ECOgetId(eci);
      // get the parameter information
      EXTParamInfo* param = ECOfindParamNum( eci, 1 );
      // create a EXTfldval object containing the new value
      EXTfldval newValue( (qlong)param->mData );
      // assign property ‘propID’ the value stored in ‘newValue’
      // always return 1L if you handled the assignment.
      return 1L;
    }
    case ECM_GETPROPERTY:
    {
      // OMNIS wants to know a property value
      qlong propID = ECOgetId(eci);
      // prepare a EXTfldval for return
      EXTfldval returnVal;
      // you must return the value for ‘propID’, the value 10
      // is returned for this example
      returnVal.setLong( 10 );
      // send the return value back to OMNIS
      ECOaddParam(eci,& returnVal);
      // always return 1L if you handled the call.
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

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.

EXTclipType

The following enum values are used with the function ECOclipboardHasFormat().

enum EXTclipType
{
eExtClipText = 0,
eExtClipPicture = 1
};

See also ECOclipboardHasFormat

EXTCompInfo

struct EXTCompInfo
{
  qlong        mCompLibId;
  qlong        mCompId;
  void*        mGdata;
  EXTHANDLE    mOmnisInstance;
  EXTParamInfo*  mParamFirst;
  void*        mPrivate;
  EXTADDR      mECOCallBack;
  EXTADDR      mGDICallBack;
  EXTADDR      mHWNDCallBack;
  EXTADDR      mFVALCallBack;
  EXTADDR      mQLISTCallBack;
  EXTADDR      mBMPCallBack;
  EXTADDR      mCRBCallBack;
  EXTADDR      mPRICallBack;
  EXTADDR      mQFILECallBack;
  locptype*    mLocLocp;
  locptype*    mInstLocp;
  EXTADDR      mDAMCallBack;
};

EXTParamInfo

This structure contains all the parameter information required for many ECM_xxxx messages and functions.

struct EXTParamInfo
{
  long        mId;
  long        mInfo;
  void*       mData;
  long        mParent;
  unsigned char mNum;
  char        mFlags;
  EXTParamInfo* mNext;
  void*       mItem;
  void*       mVpt;
};

EXTParamTypeInfo (v3.1)

Returns information about the Omnis data field.

struct EXTParamInfo
{
  qshort     mType;
  qshort     mSubType;
  qlong      mLength;
  str255     mName
};

See also ECOgetParamInfo

EXTSerialise (v3.1)

Structure used by the IS_SERIALISED control message.

struct EXTserialise
{
  str255    mProductCode;
  str255    mFunctionCode;
  str255    mSerial;
  str255    mNotes;
};

See also ECOisSerialised, IS_SERIALISED

Flags

EXTD_OBJFLAG_xxx

These defines are applied to the ECOobject structure which is used to return a list of objects that the component supports.

EXTD_OBJFLAG_SINGLE_NOTIFY

Indicates that this is a worker object using pushWorkerCallback and can only have a single outstanding notification.

EXTD_OBJFLAG_WORKER

Indicates that this is a worker object.

EXTD_EFLAG_xxx

These defines are used in the mExFlags member of the ECOproperty structure.

EXTD_EFLAG_REPFONT

Indicates that Omnis should use report fonts for this property.

EXTD_EFLAG_MVDBUTTON

Indicates that this is a button on an MVDesigner window/form.

EXTD_EFLAG_LISTDATEFORMATCUSTOM

anumPropList for this property lists $jsdateformatcustom

EXTD_EFLAG_LISTNUMBERFORMAT

anumPropList for this property lists $jsnumberformat

EXTD_EFLAG_ISDATANAME

This property needs to be treated like $dataname

EXTD_EFLAG_NOEXPORT

This property is not to be exported by Omnis X e.g. because it is read-only

EXTD_EFLAG_REPORT_MEASURE

This property is a report measurement: the dps are stored in enumStart.

EXTD_EFLAG_EXT_PROPERTIES_CRB

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.

EXTD_FLAG_xxx

These defines are used in the mFlags member of the ECOproperty structure.

EXTD_FLAG_BUTTON

Indicates that Omnis should provide a button on the Property Manager.

EXTD_FLAG_EDITRONLY

Indicates that Omnis stops editing of the property on the Property Manager.

EXTD_FLAG_ENUM

Indicates that the property is an ENUM. For this type of property, Omnis sends the component the ECM_GETPROPERTYENUMS message.

See also ECM_GETPROPERTYENUMS

EXTD_FLAG_EXTCONSTANT

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.

eQTIME_Movie_scaling, 25017, fftNumber, EXTD_FLAG_EXTCONSTANT, 0, 23000, 23004

EXTD_FLAG_FAR_SRCH

Indicates that the property will be searched on during find and replace.

EXTD_FLAG_FONTPROP

Indicates that the property is a font.

EXTD_FLAG_HIDDEN

Indicates that the property is hidden, that is, the property does not appear in the Property Manager at all.

EXTD_FLAG_INTCONSTANT

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).

cCalendar_HeadingMode,4002,fftInteger,EXTD_FLAG_INTCONSTANT,0,pre3DStyleF,pre3DStyleL

EXTD_FLAG_PARAMALTER

Indicates that the parameter can be altered during a function call.

See also ECOsetParameterChanged

EXTD_FLAG_PARAMOPT

Indicates that the function parameter (and every parameter after) is optional.

EXTD_FLAG_PRIMEDATA

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

EXTD_FLAG_PROPACT

Indicates that the property appears on the Action tab.

EXTD_FLAG_PROPAPP

Indicates that the property appears on the Appearance tab.

EXTD_FLAG_PROPCOLS

Indicates that the property appears on the Columns tab.

EXTD_FLAG_PROPCUSTOM

Indicates that the property appears on the Custom tab (default).

EXTD_FLAG_PROPDATA

Indicates that the property appears on the Data tab.

EXTD_FLAG_PROPGENERAL

Indicates that the property appears on the General tab.

EXTD_FLAG_PROPGRP1

Mask for Property Manager tab.

EXTD_FLAG_PROPJAVA

Indicates that the property appears on the Java tab.

EXTD_FLAG_PROPPREFS

Indicates that the property appears on the Preferences tab.

EXTD_FLAG_PROPPANE

Indicates that the property appears on the Pane tab.

EXTD_FLAG_PROPSECTIONS

Indicates that the property appears on the sSections tab.

EXTD_FLAG_PROPTEXT

Indicates that the property appears on the Text tab.

EXTD_FLAG_PWINDCOL

Indicates that the popup color window should be provided.

EXTD_FLAG_PWINDCOL256

Indicates that the popup 256 color window should be provided. Useful for interfacing with non-Omnis components such as Active-X or Java Beans.

EXTD_FLAG_PWINDCURSOR (v3.1)

Indicates that the popup cursor window should be provided.

EXTD_FLAG_PWINDFSTYLE

Indicates that the popup font style window should be provided.

EXTD_FLAG_PWINDICON

Indicates that the popup icon window should be provided.

EXTD_FLAG_PWINDLSTYLE

Indicates that the popup line style window should be provided.

EXTD_FLAG_PWINDMLINE

EXTD_FLAG_PWINDPAT

Indicates that the popup pattern window should be provided.

EXTD_FLAG_PWINDSET

Indicates that the popup checkbox selection window should be provided.

EXTD_FLAG_PWINDTYPE

Mask for the popup window types.

EXTD_FLAG_RUNTIMEONLY

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.

EXTD_FLAG_SECTIONS

Indicates that the property appears on the sections tab.

EXTD_FLAG_SINGLESEL

Indicates that the property appears in the Property Manager when only one object is selected.

EXTD_FLAG_STATEONLY

Indicates that Omnis displays [Empty] or [Not Empty] in the Property Manager.

EXTD_FLAG_SUPPRESS

Indicates that the standard anum (see anums.he) property should be suppressed in the Property Manager.

General Messages

This section describes some of the messages you receive via your WNDPROC. For additional messages see the HWND and GDI message section.

ECM_ADDTOPRINTJOB

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.

Returns:

If the component has added objects to the print job, return 1L. Otherwise return 0L.

case ECM_ADDTOPRINTJOB:
{
  tqfRepObj *obj = (tqfRepObj*)ECOfindObject( eci, hwnd );
  if ( obj )
  {
    printInfo *info = (printInfo*)lParam;
    info->mObj->mType = PRI_OBJ_TEXT;
    info->mObj->mAddEllipsis = qtrue;
    qprierr err = PRIaddObject( info->mJob, info->mObj );
    return err == PRI_ERR_NONE ? 1L : 0L;
  }
  return 0L;
}

ECM_BOBJ_EXERASE

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.

ECM_CANADDTOPRINTJOB

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.

ECM_CANCLICK (Web Client 1.0)

The ECM_ CANCLICK message is sent, when the web client needs to know if the component can receive mouse messages.

Returns:

Return 1L if the component can receive mouse messages, otherwise return 0.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_ CANCLICK:
    {
      // the component can receive mouse messages if it is enabled
      return wParam;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CANFOCUS (Web Client 1.0)

The ECM_CANFOCUS message is sent, when the web client needs to know if the component can receive the input focus.

Returns:

Return 1L if the component can receive the input focus, otherwise return 0.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_ CANFOCUS:
    {
      // the component can receive the focus if it is enabled
      return wParam;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CANSHOWSYSTEMFOCUS (V3.2)

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.

ECM_CMPPRIMARYDATA

The ECM_CMPPRIMARYDATA message is sent to the component to compare its objects’ data with the data provided in parameter one.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CMPPRIMARYDATA:
    {
      EXTParamInfo* param = ECOfindParamNum(eci,1);
      if ( param && param->mData )
      {
        EXTfldval newValue( (qlong)param->mData );
        if ( newValue.compare( myComponentData )==0 )
          return DATA_CMPDATA_DIFFER;
      }
      return  DATA_CMPDATA_SAME;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_PRIMEDATA

ECM_COMPONENTCMD

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 :-

OMNIS script code :-
  Do $components.MyLibrary.$cmd(1)
External C++ Library code :-
  case ECM_COMPONENTCMD:
  {
    EXTParamInfo* param = ECOfindParamNum( pEci, 1 );
    if ( !param ) return rtnVal; // Method called with too few parameters
    EXTParamInfo* ecp = eci.findParam((qbyte)n);
    EXTfldval fval( (qfldval)ecp->mData );
    If ( fval.getLong()==1 )
      // Do processing …
    break;
  }

ECM_CONNECT

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: -

Note: Most components do not need to catch this message. The default returned value in WNDdefWindowProc is EXT_FLAG_LOADED.

ECM_CONSTPREFIX

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CONSTPREFIX:
    {
      EXTfldval prefixName;
      str15 prefixStr;
      prefixStr[0] = RESloadString( gInstLib, resourceID,
&prefixStr[0], 15 );
      prefixName.setChar(prefixStr);
      ECOaddParam(eci,&prefixName);
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CONVFROMHPIXMAP (Studio 2.1)

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:

Returns:

Return qtrue if the component has successfully converted the HPIXMAP to binary data, qfalse otherwise.

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  case ECM_CONVFROMHPIXMAP:
  {
    qbool rtnVal = qfalse;
    HPIXMAP thePixMap = (HPIXMAP)lParam;
    qHandle binaryPCX;
    if ( PixmapToPCX(thePixMap ,binaryPCX) )
    {
      EXTfldval fval;
      fval.setHandle(fftBinary,binaryPCX,qfalse);
      ECOaddParam(eci,&fval);
      rtnVal = qtrue;
    }
    binaryPCX.setNull();
    return rtnVal;
  }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CONVHEADER (Studio 2.1)

The ECM_CONVHEADER message is sent to a picture format component when Omnis requires a picture formats’ header to be added or removed.

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CONVHEADER:
    {
      EXTParamInfo* param = ECOfindParamNum(eci,1);
      if ( param )
      {
        EXTfldval fldval( (qfldval)param->mData );
        srcHan = fldval.getHandle (qfalse);
        qHandle destHan;
        if ( wParam )
        { // Add tqgpict header (& any other component header)
          addPCXheader(srcHan,destHan);
        }
        else
        { // Remove tqgpict header (& any other component header)
          removePCXheader(srcHan,destHan);
        }
        EXTfldval fval;
        val.setHandle(fftBinary,destHan,qfalse);
        ECOaddParam(eci,&fval);
        return qtrue;
      }
      return qfalse;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CONVTOHPIXMAP (Studio 2.1)

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:

Returns:
Return an HPIXMAP handle, NULL otherwise.

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg,
WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CONVTOHPIXMAP:
    {
      EXTParamInfo* param = ECOfindParamNum(eci,1);
      EXTfldval fldval( (qfldval)param->mData );
      qHandle theData = fldval.getHandle (qtrue);
      HPIXMAP thePixmap = PCXtoPixMap( theData );
      return (qlong) thePixmap;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_CUSTOMTABNAME

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CUSTOMTABNAME:
    {
      // use resource 8000 for the name of the tab in the Property Manager
      ECOsetCustomTabName( gInstLib, eci, 8000 );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOsetCustomTabName

ECM_DEBUGGING

The ECM_DEBUGGING message is sent to the component:

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:

Returns:
Any returned value is ignored.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_DEBUGGING:
    {
      qbool debuggingOn = (qbool)wParam;
      if ( debuggingOn )
      {
        // If debugging is on, the component may wish to provide
        // verbose information to the developer via various
        // methods (e.g. trace log, and so on)
      }
      break;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_DISCONNECT

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.

ECM_EVENTRESULT (Web Client 1.0)

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:

Returns:

Return 1L.

See also ECOsendEvent

ECM_FMT_CANASSIGN

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.

ECM_FMT_GETPROPERTY

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.

ECM_FMT_SETPROPERTY

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.

ECM_GETCOMPICON

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:

Returns:

Return true if the bitmap has been returned, false otherwise.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCOMPICON:
    {
      return ECOreturnIcon( gInstLib, eci, iconResID );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETCOMPID

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:

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCOMPID:
    {
      // returns a single component of id ‘compID’ and
      // of type ‘cObjType_Basic’
      return ECOreturnCompID( gInstLib, eci, compID, cObjType_Basic );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnCompID

ECM_GETCOMPLIBINFO

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCOMPLIBINFO:
    {
      // returns the name of the component library ( resource id )
      // and the number of components this library supports.
      return ECOreturnCompInfo( gInstLib, eci, LIB_RES_NAME, COMPONENT_COUNT );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnCompInfo

ECM_GETCOMPSTOREGROUP (Studio 2.1)

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCOMPSTOREGROUP:
    {
      // use resource 8000 for the name of component store group
      ECOreturnCStoreGrpName( gInstLib, eci, 8000 );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnCStoreGrpName

ECM_GETCOMPSTOREICON (Studio 2.1)

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCOMPSTOREICON:
    {
      // use resource 8000 for the component store groups’ bitmap
      ECOreturnIcon ( gInstLib, eci, 8000 );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECM_GETCOMPSTOREGROUP, ECOreturnIcon

ECM_GETCONSTNAME

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: -

A component should call ECOreturnConstants to provide the event information.

Returns:

Return true if the event list has been returned.

example strings (extracts from QuickTime component):
// Scaling constant group
23000 "Scaling~kQTScaleNone:0:kQTScaleNone:No Scaling is applied to
the movie."
23001 "kQTScaleNoAspectRatio:1:kQTScaleNoAspectRatio:The movie is
expanded to fit the current field."
23002 "kQTScaleKeepAspectRatio:2:kQTScaleKeepAspectRatio:The movie
is expanded to fit the current field."
23003 "kQTScaleProportional:3:kQTScaleProportional:The movie is
equally expanded vertically and horizontally to fit the current field."
23004 "kQTScaleField:4:kQTScaleField:The movie's field is expanded around the movie."
// Resource slots 23005-23009 left for future scaling options
// Controller constant group
23010 "Controller~kQTnoButtons:0:kQTnoButtons:The Controllers all
buttons list."
23011 "kQTstepButton:1:kQTstepButton:The Controllers step and reverse button are removed."
23012 "kQTsoundButton:2:kQTsoundButton:The Controllers sound button
are removed."
23013 "kQTgrowButton:4:kQTgrowButton:The Controllers grow button area are removed."
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg,
WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETCONSTNAME:
    {
      return ECOreturnConstants( gInstLib, eci, 23000, 23013 );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnConstants

ECM_GETEVENTMETHOD

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.

example strings:
8000, “on evMyEvent”
8000, “; This event is sent for xxx reason”
8001, “”
8002, “”
8003, “on evMyEvent2”
8004, “; This event is sent for yyy reason”
// a break in the run is needed ( 8005 is missing )
8010, “”
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETEVENTMETHOD:
    {
      // this uses strings 8000 onward, until a gap in the run
      return ECOreturnEventMethod(gInstLib, eci, 8000 );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnEventMethod

ECM_GETEVENTNAME

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETEVENTNAME:
    {
      return ECOreturnFuncsEvents( gInstLib, eci, &eventTable[0], evtTableCnt );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnFuncsEvents

ECM_GETHANDLERICON

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETHANDLERICON:
    {
      // Provide OMNIS with a bitmap for the Component Store group.
      HBITMAP compStoreIcon = RESloadBitMap( gInstLib, COMP_STORE_GROUP_ID );
      return (qlong)compStoreIcon;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETMETHODNAME

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETMETHODNAME:
    {
      return ECOreturnMethodsEvents(gInstLib, eci, &funcTable[0], funcTableCnt );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnMethodsEvents

ECM_GETOBJECT

The ECM_GETOBJECT message is sent to a library which supports non-visual objects.

A component should call ECOreturnObjects to provide the object information.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETOBJECT:
    {
      return ECOreturnObjects(gInstLib,eci,&objTable[0],objTableCnt);
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnObjects, EXT_FLAG_NVOBJECTS, Non-Visual Components

ECM_GETOBJECTRECT

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:

Returns:

Return qtrue if the object rectangle has been set, false otherwise.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETOBJECTRECT:
    {
      qrect* initialRect = (qrect*)lParam;
      // sets the controls initial size to 100, 100
      GDIsetRect( initialRect, 0, 0, 100, 100 );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETPICTFILEDESC (Studio 2.1)

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.

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg,
WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPICTFILEDESC:
    { // Return a string containing the picture file filter
      str15 name(“PCX Files (*.pcx)|*.pcx|");
      EXTfldval fval; fval.setChar(name);
      ECOaddParam(eci,&fval);
      return qtrue;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETPICTFORMAT (Studio 2.1)

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..

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg,
WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPICTFORMAT:
    { // Return a string (“PCX”) containing the picture format
      str15 name(“PCX”);
      EXTfldval fval; fval.setChar(name);
      ECOaddParam(eci,&fval);
      return qtrue;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETPICTUREDIM

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPICTUREDIM:
    {
      qrect* pictDim = (qrect*)lParam;
      // returns the bounds of the picture you are currently displaying
      GDIsetRect( pictDim, 0, 0, mWidth, mHeight );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_GETPRIMARYDATA

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPRIMARYDATA:
    {
      EXTfldval exfldval;
      EXTParamInfo* newparam = ECOaddParam(eci,&exfldval);
      exfldval.setBinary(fftPicture,mPCXData,mPCXDataLen);
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_PRIMEDATA

ECM_GETPRIMARYDATALEN

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPRIMARYDATALEN:
    {
      return myDataLength;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_PRIMEDATA

ECM_GETPROPERTY

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPROPERTY:
    {
      // propID is the id of the property defined in your proptable
      qlong propID = ECOgetId(eci);
      // Get the value of your property.
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also Component Properties section.

ECM_GETPROPERTYENUMS

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPROPERTYENUMS:
    {
      EXTqlist enumList;
      enumList.clear(listScol);
      for ( qshort i = 1; i<=5; i++ )
      {
        str255 enumName;
        enumName[0] = RESloadString(gInstLib, i, &enumName[1], 255 );
        enumList.insline( 0, &enumName, i );
      }
      EXTfldval returnVal;
      returnVal.setList( &enumList, qtrue );
      ECOaddParam( eci, &returnVal );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_ENUM

ECM_GETPROPNAME

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETPROPNAME:
    {
      return ECOreturnProperties( gInstLib, eci, &propTable[0], propTableCnt );
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnProperties

ECM_GETSTATICOBJECT

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_GETSTATICOBJECT:
    {
      return ECOreturnMethods(gInstLib,eci, &objStaticTable[0], objStaticTableCnt);
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOreturnMethods, EXT_FLAG_NVOBJECTS, Non-Visual Components

ECM_GETVERSION

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

ECM_HASPRIMARYDATACHANGED (Web Client V1.0)

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:

See also ECM_SETPRIMARYDATA, ECM_GETPRIMARYDATA

ECM_ICONDRAWENTRY

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).

struct EXTIconArrayInfo
{
  HDC       mHdc;
  qlong     mLine;
  qrect     mEntryRect;
  qrect     mDrawRect;
  qbool     mDrawFocus;
  qbool     mSelected;
  qbool     mDragging;
  qbool     mSmallIcons;
  EXTqlist* mListPtr;
};
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_ICONDRAWENTRY:
    {
      EXTIconArrayInfo* arrayInfo = (EXTIconArrayInfo*)lParam;
      // Draw icon using info supplied in arrayInfo
      return 1L;
    }
    case ECM_TEXTDRAWENTRY:
    {
      EXTIconArrayInfo* arrayInfo = (EXTIconArrayInfo*)lParam;
      // Draw text using info supplied in arrayInfo
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also cObjType_IconArray, ECM_TEXTDRAWENTRY

ECM_INBUILT_OVERRIDE

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.

ECM_INSTALLLIBRARY

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_INSTALLLIBRARY:
    {
      // Control handler may wish to create a modal window to enable
      // controls to be installed/uninstalled etc…
      doInstallComponent();
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_ISCONVFORMAT (Studio 2.1)

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:

Returns:

Return qtrue if the picture data is in a format that the component supports, false otherwise.

extern "C" qlong OMNISWNDPROC PCXWndProc( HWND hwnd, LPARAM Msg,
WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_ISCONVFORMAT:
    {
      EXTParamInfo* param = ECOfindParamNum(eci,1);
      if ( param )
      {
        EXTfldval fldval( (qfldval)param->mData );
        qHandle srcHan = fldval.getHandle(qfalse);
        if ( PCXObject::isPCXdata(srcHan) )
          return qtrue;
      }
      return qfalse;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_LISTDRAWLINE

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:

Returns:

Return true if the list line was drawn, false otherwise (which results in Omnis drawing the line).

struct EXTListLineInfo
{
HDC mHdc;
qrect mLineRect;
qlong mLine;
qbool mSelected;
EXTqlist* mListPtr;
qbool mDrawFocusRect;
};
mHdc - Device context into which the line should be drawn.
mLineRect - The rectangle of the line.
mLine - The line number.
mSelected - True if the line is selected.
mListPtr - List data pointer. This member contains the list variable pointer as defined in the property member data name.
mDrawFocusRect - True if the focus rectangle should be drawn.
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_LISTDRAWLINE:
    {
      EXTListLineInfo* lineInfo = (EXTListLineInfo *)lParam;
      // paint line using info supplied in lineInfo
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also cObjType_List, cObjType_DropList

ECM_MEMORYDELETION

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

ECM_METHODCALL

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_METHODCALL:
    {
      // OMNIS code is calling your component method
      qlong methodID = ECOgetId(eci);
      switch(methodID)
      {
        case cMyMethod1: …….
        case cMyMethod2: …….
        case cMyMethod3: …….
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also Component Methods Section

ECM_NEWMETHODFLAGS

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_NEWMETHODFLAGS:
    {
      qlong newMethodFlags = 0;
      Cobj* object = (Cobj*)ECOfindObject( eci->mOmnisInstance, hwnd );
      if ( object )
      {
        qlong methodId = (qlong)lParam;
        newMethodFlags = object->getMethodFlags(methodId);
      }
      return newMethodFlags;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also RESET_METHOD_FLAGS

ECM_NEWPROPERTYFLAGS

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_NEWPROPERTYFLAGS:
    {
      qlong newPropertyFlags = 0;
      Cobj* object = (Cobj*)ECOfindObject( eci->mOmnisInstance, hwnd );
      if ( object )
      {
        qlong propId = (qlong)lParam;
        newPropertyFlags = object->getPropertyFlags( propId );
      }
      return newPropertyFlags;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also RESET_PROPERTY_FLAGS

ECM_OBJCONSTRUCT

The ECM_OBJCONSTRUCT message is sent to instruct the component to construct an instance of the object.

Parameters:

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

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_OBJCONSTRUCT:
    {
      // create a new object - Cobj is an example class name
      Cobj* object = new Cobj( hwnd );
      // and add it to the ECO object chain
      ECOinsertObject( eci, hwnd, (void*)object );
      // if your component library supports multiple controls,
      // you can use eci->mCompId to determine what sort of control to create.
      return 1L;
    }
  }…
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

Example 2

extern "C" LRESULT OMNISWNDPROC MySqlObjProc(OMNISHWND hwnd, UINT Msg,WPARAM wParam,LPARAM lParam,EXTCompInfo* eci)
{
  switch (Msg)
  {
    case ECM_OBJCONSTRUCT:
    {
      tqfDAMObjCont* object = (tqfDAMObjCont*)ECOfindNVObject( eci->mOmnisInstance, lParam );
      if ( !object )
      {
        tqfMySqlDAMObj* damObj = new tqfMySqlDAMObj(eci);
        tqfDAMObjCont* obj = new tqfDAMObjCont((qobjinst)lParam, damObj);
        ECOinsertNVObject( eci->mOmnisInstance, lParam, (void*)obj );
        return qtrue;
      }
    }…
  }
  return DAMdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_OBJDESTRUCT

The ECM_OBJDESTRUCT message is sent to instruct the component to destruct an instance of the object.

Parameters:

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_OBJDESTRUCT:
    {
      // retrieve and remove your object from the ECO object chain.
      Cobj* object = (Cobj*)ECOremoveObject( eci, hwnd );
      // and delete it.
      if ( object ) delete object;
        return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_OBJECTDATABLOCK

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:

Returns:

Return true if successful (i.e. the object supports data block property assignment), false otherwise.

ECM_OBJECT_COPY

The ECM_OBJECT_COPY message is sent to the component when a non-visual object assignment is required.

Parameters:

Returns: Any return value is ignored.

See also EXT_FLAG_NVOBJECTS, Non-Visual Components

ECM_OBJECT_REBUILD

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

ECM_OBJINITIALIZE

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:

Returns:

Any returned value is ignored.

Note: Components do not need to catch this message, just pass it on the WNDdefWindowProc.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_OBJINITIALIZE:
    {
      // You may need to load other DLL’s once only.
      // after, you always need to pass this message
      // on to WNDdefWindowProc
      return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_PAINTCONTENTS

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:

ECM_PRIMARYDATACHANGE

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_PRIMARYDATACHANGE:
    {
      Cobj* object = (Cobj*)ECOfindObject( eci->mOmnisInstance, hwnd );
      if ( object )
      {
        // … Additional processing …
        object->inval();
      }
      break;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_PRIMEDATA

ECM_PRINT

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:

Parameter 1 - contains any primary data (as during ECM_SETPRIMARYDATA message).

Returns:

Any return value is ignored.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_PRINT:
    {
      PCXObject* object = (PCXObject*)ECOfindObject( eci->mOmnisInstance, hwnd );
      if ( object )
      {
        EXTParamInfo* param = ECOfindParamNum(eci,1);
        if ( param && param->mData )
        {
          // Set objects’ data from param variable.
          object->setPrimaryData( eci, param );
        }
        WNDpaintStruct* paintInfo = (WNDpaintStruct*)lParam;
        // you can paint your object using
        //
        // paintInfo->hdc
        //
        // using the bounds
        //
        // paintInfo ->rcPaint;
        object->print( paintInfo );
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECM_SETPRIMARYDATA

ECM_PRINTMAPPING

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_PRINTMAPPING:
    {
      return 1L;
      // returns 1L for print mapping - scales object
      // dependent on print DPI
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_PROPERTYCALCTYPE

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_ PROPERTYCALCTYPE:
    {
      // return the property calculation type
      EXTfldval calcType;
      calcType.setLong( ctySquare );
      ECOaddParam( eci, &calcType );
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECM_PROPERTYCANASSIGN

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_PROPERTYCANASSIGN:
    {
      // propID is the id of the property defined in your proptable
      qlong propID = ECOgetId(eci);
      // you should return 1L if the property ‘propID’ is
      // assignable, and 0L if the property is read-only
      return 0L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also Component Properties section.

ECM_SETPRIMARYDATA

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_SETPRIMARYDATA:
    {
      EXTParamInfo* param = ECOfindParamNum(eci,1);
      if ( param && param->mData )
      {
        EXTfldval newValue( (qlong)param->mData );
        // new value stored in EXTfldval ‘newValue’
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also EXTD_FLAG_PRIMEDATA

ECM_SETPROPERTY

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:

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_SETPROPERTY:
    {
      // propID is the id of the property defined in your proptable
      qlong propID = ECOgetId(eci);
      // set the new value of your property.
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also Component Properties section.

ECM_SQLOBJECT_COPY (v3.1)

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:

ECM_TEXTDRAWENTRY

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:

struct EXTIconArrayInfo
{
HDC        mHdc;
qlong      mLine;
qrect      mEntryRect;
qrect      mDrawRect;
qbool      mDrawFocus;
qbool      mSelected;
qbool      mDragging;
qbool      mSmallIcons;
EXTqlist*   mListPtr;
};
extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_TEXTDRAWENTRY:
    {
      EXTIconArrayInfo* arrayInfo = (EXTIconArrayInfo*)lParam;
      // Draw text using info supplied in arrayInfo
      return 1L;
    }
    case ECM_ICONDRAWENTRY:
    {
      EXTIconArrayInfo* arrayInfo = (EXTIconArrayInfo*)lParam;
      // Draw icon using info supplied in arrayInfo
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also cObjType_IconArray, ECM_ICONDRAWENTRY

WM_CONTROL Messages

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.

DESKTOP_MENU_ENABLED

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.

// Disable menu
WNDsendMessage( mHwnd, WM_CONTROL, DESKTOP_MENU_ENABLED, qfalse );
… Processing …
// Enable menu
WNDsendMessage( mHwnd, WM_CONTROL, DESKTOP_MENU_ENABLED, qtrue );

DRAW_DESIGN_NAME

Instructs Omnis to draw the objects’ name. Functionally the same as ECOdrawDesignName.

WNDsendMessage( mHwnd, WM_CONTROL, DRAW_DESIGN_NAME, (LPARAM)hdc );

See also ECOdrawDesignName

DRAW_MULTIDESIGN_KNOBS

Instructs Omnis to draw the multi-selected design knobs. Functionally the same as ECOdrawMultiKnobs.

WNDsendMessage( mHwnd, WM_CONTROL, DRAW_MULTIDESIGN_KNOBS, (LPARAM)hdc );

See also ECOdrawMultiKnobs

DRAW_NUMBER

Instructs Omnis to draw the objects’ number. Functionally the same as ECOdrawNumber.

WNDsendMessage( mHwnd, WM_CONTROL, DRAW_NUMBER, (LPARAM)hdc );

See also ECOdrawNumber

GET_MENUHANDLE (Windows only)

Returns the operating system menu handle for the Omnis menu.

HMENU menuHandle = WNDsendMessage( mHwnd, WM_CONTROL, GET_MENUHANDLE, MM_FILE );
if ( menuHandle )
{
  qshort itemCount = GetMenuItemCount((HMENU)menuHandle );
}

GET_OMNIS_HPALETTE (Windows only)

Returns the Omnis palette handle.

HPALETTE omnisPalette = WNDsendMessage( mHwnd, WM_CONTROL, GET_OMNIS_PALETTE, 0 );
HPALETTE myObjectPalette = 0;
if (omnisPalette)
{
  // Create new palette using OMNIS palette
  HLOCAL hl; LOGPALETTE* Logpal;
  hl = GlobalAlloc(GMEM_MOVEABLE | GMEM_ZEROINIT, sizeof(LOGPALETTE)+(256*sizeof(PALETTEENTRY)));
  if(hl)
  {
    Logpal = (LPLOGPALETTE) GlobalLock(hl);
    GetPaletteEntries(omnisPalette,0,256, Logpal->palPalEntry);
    Logpal->palVersion = 0x300;
    Logpal->palNumEntries = 256;
    myObjectPalette = CreatePalette(Logpal);
    GlobalUnlock(hl);
    GlobalFree(hl);
  }
}

HAS_FOCUS

Returns true if the object has the focus. Functionally the same as ECOhasFocus.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, HAS_FOCUS, 0 );
if ( result )
{
  // object currently has the focus
}

See also ECOhasFocus

HIDE_TOOLTIP

Instructs Omnis to hide the on-screen tool tip if it is shown. Functionally the same as ECOhideTooltip.

// hides tooltip
WNDsendMessage( mHwnd, WM_CONTROL, HIDE_TOOLTIP, 0 );

See also ECOhideTooltip

IS_FLD_EDITABLE

Returns true if the object is editable (i.e. in runtime and not read-only).

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, IS_FLD_EDITABLE, 0 );
if ( result )
{
  // object is in edit mode
}

IS_IN_DESIGN

Returns true if in design mode. Functionally the same as ECOisDesign.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, IS_IN_DESIGN, 0 );
if ( result )
{
  // object is in design mode.
}

See also ECOisDesign

IS_MULTISELECTED

Returns true if the object is currently one of many objects selected. Functionally the same as ECOisMultiSelected.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, IS_MULTISELECTED, 0 );
if ( result )
{
  // object is multi-selected.
}

See also ECOisMultiSelected

IS_OMNIS_IN_BUILDMODE

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 ).

if ( WNDsendMessage( mHwnd, WM_CONTROL, IS_OMNIS_IN_BUILDMODE, 0 )==0 )
{
  // send my event
}

See also ECOisOMNISinTrueRuntime

IS_SELECTED

Returns true if the object is currently selected. Functionally the same as ECOisSelected.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, IS_SELECTED, 0 );
if ( result )
{
  // object is selected.
}

See also ECOisSelected

IS_SERIALISED (v3.1)

Asks Omnis if the component has been serialised and returns information about the serial number.

EXTserialise serInfo;
serInfo.mProductCode = str15(“XXXX”);
// mProductCode = first four alpha/numeric chars of serial number
qbool result = (qbool)WNDsendMessage( mHwnd, WM_CONTROL, IS_SERIALISED, (LAPARAM)&serInfo);
if ( result )
{
  // component has been serialised.
  // on return
  //   serInfo.mFunctionCode contains codes for enabled functions
  //   serInfo.mSerial contains the complete serial number
  //   serInfo.mNotes contains the serial number notes
}

See also ECOisSerialised, EXTserialise

IS_SETUP

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.

qbool result = (qbool)WNDsendMessage( mHwnd, WM_CONTROL, IS_SETUP, 0);
if ( result )
{
  // object is setup and ready for action.
}

See also ECOisSetup

IS_SHOWNUMBER

Returns true if the object is in design-mode and ‘Show number’ is true. Functionally the same as ECOisShowNumber.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, IS_SHOWNUMBER, 0 );
if ( result )
{
  // Show number is on.
}

See also ECOisShowNumber

IS_WINDOW_TOP

Returns true if the object is a member of the top-most window. Functionally the same as ECOisWndTop.

qbool result = (qbool)WNDsendMessage( mHwnd, WM_CONTROL, IS_WINDOW_TOP, 0 );
if ( result )
{
  // object is at top
}

See also ECOisWndTop

LIST_SETLINEHEIGHT

Informs Omnis of a new line height for cObjType_List objects. Functionally the same as ECOlistSetLineHeight.

// Forces all lists lines in a derived picture component to be 50 pixels high.
WNDsendMessage( mHwnd, WM_CONTROL, LIST_SETLINEHEIGHT, 50 );

See also ECOlistSetLineHeight

OMNIS_IN_BACKGROUND

Returns true if the Omnis is currently a background application.

qlong result = WNDsendMessage( mHwnd, WM_CONTROL, OMNIS_IN_BACKGROUND, 0 );
if ( result==0 )
{
// OMNIS is the foremost application
}

PICTURE_ERASEBKGROUND

Instructs the cObjType_Picture object to erase the background.

WNDsendMessage( mHwnd, WM_CONTROL, PICTURE_ERASEBKGROUND, 0 );

See also cObjType_Picture

PICTURE_UPDSCROLLRANGE

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.

WNDsendMessage( mHwnd, WM_CONTROL, PICTURE_UPDSCROLLRANGE, 0 );

See also ECM_GETPICTUREDIM

RESET_METHOD_FLAGS

Instructs Omnis to reset all method flags. Omnis sends the component repeated ECM_NEWMETHODFLAGS for each method in the object.

WNDsendMessage( mHwnd, WM_CONTROL, RESET_METHOD_FLAGS, 0 );

See also ECM_NEWMETHODFLAGS

RESET_PROPERTY_FLAGS

Instructs Omnis to reset all property flags. Omnis sends the component repeated ECM_NEWPROPERTYFLAGS for each property in the object.

WNDsendMessage( mHwnd, WM_CONTROL, RESET_PROPERTY_FLAGS, 0 );

See also ECM_NEWPROPERTYFLAGS

SET_EDITMENU

Instructs Omnis to rebuild the edit menu.

WNDsendMessage( mHwnd, WM_CONTROL, SET_EDITMENU, 0 );

SET_PALETTE

Instructs Omnis that the objects’ palette has altered. Functionally the same as GDIsetPalette.

WNDsendMessage( mHwnd, WM_CONTROL, SET_PALETTE, (LPARAM)myPalette );

See also GDIsetPalette

SET_STATUSBAR_TEXT

Updates the Omnis status bar with the specified text.

str255 newStatusBarMsg = str255( “Text to go into the status bar” );
WNDsendMessage(mHwnd,WM_CONTROL,SET_STATUSBAR_TEXT,(LPARAM)newStatusBarMsg.cString());

SET_TOOLGRPS_VISIBLE

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.

// Hide Toolbars
WNDsendMessage( mHwnd, WM_CONTROL, SET_TOOLGRPS_VISIBLE, qfalse );
… Processing …
// Show Toolbars
WNDsendMessage( mHwnd, WM_CONTROL, SET_TOOLGRPS_VISIBLE, qtrue );

SET_WINDOWS_VISIBLE

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.

// Hide Windows
WNDsendMessage( mHwnd, WM_CONTROL, SET_WINDOWS_VISIBLE, qfalse );
… Processing …
// Show Windows
WNDsendMessage( mHwnd, WM_CONTROL, SET_WINDOWS_VISIBLE, qtrue );

SETNOERASEFORPICTURES

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.

// disables erasing
WNDsendMessage( mHwnd, WM_CONTROL, SETNOERASEFORPICTURES, qtrue );
// enables erasing
WNDsendMessage( mHwnd, WM_CONTROL, SETNOERASEFORPICTURES, qfalse );

See also cObjType_Picture

UPDATE_PROPINSPECTOR

Instructs Omnis to update the Property Manager. Functionally the same as ECOupdatePropInsp.

// Update all properties
WNDsendMessage( mHwnd, WM_CONTROL, UPDATE_PROPINSPECTOR, 0 );
// Update myPropId
WNDsendMessage( mHwnd, WM_CONTROL, UPDATE_PROPINSPECTOR, myPropId );

See also ECOupdatePropInsp

General Functions

ECOaddParam()

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_CONSTPREFIX:
    {
      EXTfldval prefixName;
      str15 prefixStr;
      prefixStr[0] = RESloadString( gInstLib, resourceID, &prefixStr[0], 15 );
      prefixName.setChar(prefixStr);
      ECOaddParam(eci,&prefixName);
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECOaddTraceLine()

void ECOaddTraceLine( str255* pString )

The ECOaddTraceLine function enables the component to add strings to the Omnis trace log.

str255 myTraceLine(“Some trace information”);
ECOaddTraceLine( &myTraceLine );

ECOcanSendEvent() (web client only)

qbool ECOcanSendEvent( HWND pHwnd, qlong pEventID)

Use ECOcanSendEvent to test if an event can be send now.

See also ECOsendEvent

ECOclipboardGetPicture() (v2.4)

qbool ECOclipboardGetPicture(qHandle& pPicture)

This function retrieves picture data from the clipboard.

See also ECOclipboardHasFormat, ECOclipboardSetPicture, ECOclipboardSetText, ECOclipboardGetText.

ECOclipboardGetPictureEx() (v5.1)

qbool ECOclipboardGetPictureEx(qHandle& pPicture)

This function retrieves a picture from the clipboard; with alpha support.

// Paste from clipboard- excerpt from icon edit component
qHandle han;
if (ECOclipboardGetPictureEx(han) && han)
{
  qHandlePtr hp(han,0);
  qlong w1 = hp.dataLen();
  if ( w1>0 )
  {
    mPastePixMap = GDIHPIXMAPfromSharedPicture(*hp, w1);
    if ( mPastePixMap )
    {
      HPIXMAPinfo pixInfo; GDIgetHPIXMAPinfo( mPastePixMap, &pixInfo );
      mPastePixMap = convTo24(pixInfo,mPastePixMap);
      #ifdef ismacosx
        qbool isAlpha = qbool((**mPastePixMap).pixelFormat == k32RGBAPixelFormat);
      #endif
    }
  }
}

ECOclipboardGetText() (v2.4)

qbool ECOclipboardGetText(qHandle& pText)

This function retrieves text data from the clipboard.

See also ECOclipboardHasFormat, ECOclipboardSetText, ECOclipboardGetPicture, ECOclipboardSetPicture

ECOclipboardHasFormat() (v3.1)

qbool ECOclipboardHasFormat(EXTclipType pType)

Use this function to check if the clipboard contains data of the specified type.

eExtClipText – test the clipboard for text data

eExtClipPicture – test the clipboard for picture data

See also EXTclipType, ECOclipboardGetPicture, ECOclipboardGetText

ECOclipboardSetPicture() (v3.1)

qbool ECOclipboardSetPicture(qHandle pPicture)

This function places the given data as a picture on the clipboard.

See also ECOclipboardGetPicture , ECOclipboardGetText, ECOclipboardSetText

ECOclipboardSetText() (v2.4)

qbool ECOclipboardSetText(qHandle pText)

This function places the given data as text on the clipboard.

See also ECOclipboardGetText, ECOclipboardGetPicture, ECOclipboardSetPicture

ECOconvertHFSToPosix() (v3.3)

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).

ECOconvertPosixToHFS() (v3.3)

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).

OpsErr err; EXTfldval srcpath; str255 sdstPath;
err = ECOconvertPosixToHFS(srcpath.getChar().cString(), kCFStringEncodingMacRoman, sdstPath);

ECOconvKnownJavaObjs() (v4.2)

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:

tqappfile *app = ECOgetApp(pEci->mLocLocp);
qbool mConvKnownObjects;
if(app) ECOconvKnownJavaObjs(app, mConvKnownObjects);

ECOdoMethod()

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.

// Inform sub-classed email object of new email
EXTfldval numOfEmail; str255 methodName(“$newemail”)
numOfEmail.setLong( number_of_new_emails );
ECOdoMethod( mObjInst, &methodName, &numOfEmail, 1 );

See also ECOdoMethodECI

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.

// Email event occurred. Invoke OMNIS objects’ method
EXTCompInfo* eci = new EXTCompInfo();
eci->mParamFirst = 0;
// Add parameters to EXTCompInfo structure
EXTfldval myParam1;
myParam1.setlong( someData );
// Add parameter 1
ECOaddParam(eci,&myParam1,0,0,0,1,0);
// Invoke method
str255 methodName(“$newemail”)
qbool eventOk = ECOdoMethodECI( mObjInst, &methodName,eci, qtrue );
// Delete parameters from EXTCompInfo structure
ECOmemoryDeletion( eci );
// Delete eci structure
delete eci;

See also ECOdoMethod

ECOdrawDesignName()

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.

ECOdrawDesignName( mHwnd, hdc );

See also DRAW_DESIGN_NAME

ECOdrawMultiKnobs()

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.

ECOdrawMultiKnobs( mHwnd, hdc );

See also DRAW_MULTIDESIGN_KNOBS

ECOdrawNumber()

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.

ECOdrawNumber( mHwnd, hdc );

See also DRAW_NUMBER

ECOexcludeToolTipRect()

void ECOexcludeToolTipRect( HWND pHWnd, HDC pHDC )

Allows the component to exclude the tool-tip rectangle from the device contexts’ clipped drawing area.

See also ECOgetToolTipRect

ECOfindObject()

void* ECOfindObject( HINSTANCE pInstance, HWND pHWnd, WPARAM pWParam =0 )

Locates a pointer which has previously been stored via the ECOinsertObject function.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
    case WM_PAINT:
    {
      cObj* object = (cObj *)ECOfindObject(eci->mOmnisInstance, hwnd );
      if ( NULL!=object && object->paint() ) return qtrue;
        break;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOinsertObject

ECOfindNVObject()

void* ECOfindNVObject( HINSTANCE pInstance, LPARAM pInstPtr )

Locates a pointer which has previously been stored via the ECOinsertNVObject function.

See also ECOinsertNVObject, Non-visual components

ECOfindParamNum()

EXTParamInfo* ECOfindParamNum( EXTCompInfo* pEci, qlong pParamID )

Locates a parameter in the EXTCompInfo structure. This function should be used to locate method and property parameters.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_METHODCALL:
    {
      // OMNIS code is calling your component method
      qlong methodID = ECOgetId(eci);
      switch(methodID)
      {
        case cMyMethod1:
        {
          EXTParamInfo* param1 = ECOfindParamNum( eci, 1);
          EXTParamInfo* param2 = ECOfindParamNum( eci, 2);
          if ( param1 && param2 )
          {
            // .. Do method processing …
          }
          return 1L;
        }
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECOfindString() (v5.0)

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.

ECOgetApp()

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.

// fetch the library reference which contains the instance of the component
qapp app = ECOgetApp( pEci->mInstLocp );

ECOgetBundleRef() (v3.1) Mac OSX only

void *ECOgetBundleRef(qlong pBundleID)

Returns a CFBundleRef dependant on the pBundleID.

ECOgetCrbFieldInfo() (V2.2)

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.

crbFieldInfo info;
str255 fieldName(“ivTheVariable”);
if ( ECOgetCrbFieldInfo( fieldName, eci->mInstLocp, &info ) )
{
  qlong maxLen = info.fln;
}

See also struct crbFieldInfo in EXTfldval class reference

ECOgetDeviceParms()

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.

// fetch a pointer to the global device parameters
PRIdestParmStruct *deviceParms = ECOgetDeviceParms( pEci->mInstLocp );

ECOgetDirectoryDialog()

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.

Note: On MacOS make sure the component project contains the OMNISLIB.RSRC file.

str255 newDirectory;
if ( ECOgetDirectoryDialog( gInstLib,hwnd,5000,5001,newDirectory ) )
{
  … processing …
}

ECOgetFont()

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.

// Create font from index & size (extract from CALENDAR example)
qfnt fnt = fntSmallFnt;
ECOgetFont( mHWnd, &fnt, mHeadingFont, mHeadingFontSize );
HFONT font = GDIcreateFont( &fnt, mHeadingBold ? styBold : styPlain );
… processing ..
GDIdeleteObject( font );

ECOgetFont()

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.

// sample function retrieves a report font from the library containing the
// instance of the external component.
HFONT myCreateFont( EXTCompInfo* pEci )
{
  qfnt fnt; qapp app = ECOgetApp( pEci->mInstLocp );
  ECOgetFont( app, qtrue, &fnt, 1, 12 );
  return GDIcreateFont( &fnt, styPlain );
}

ECOgetFontIndex()

qshort ECOgetFontIndex( HWND pHwnd, EXTfldval& pFVal )

The ECOgetFontIndex function returns a font index from the specified font name.

str80 s(“Times Roman”);
EXTfldval fval; fval.setChar( s );
qshort fntIndex = ECOgetFontIndex( hwnd, fval );

ECOgetId()

qlong ECOgetId( EXTCompInfo* pEci)

The ECOgetId function should be used to retrieve the id of the method or property.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_METHODCALL:
    {
      // OMNIS code is calling your component method
      qlong methodID = ECOgetId(eci);
      switch(methodID)
      {
        // … Method 1
        case cMyMethod1:
        // … Method 2
        case cMyMethod2:
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECOgetLocalIpAddress() (v4.3)

qulong ECOgetLocalIpAddress(void)

Returns the client machine’s ethernet IP address as a hexadecimal long integer.

ECOgetNVObject() (v3.3)

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.

EXTfldval fval; fftttype ftype1;
//….code excerpt from JavaObjs component
fval.getType(ftype1);
if (ftype1 == fftObjref)
{
  qobjinst objInst = fval.getObjRef();
  if (objInst) objInst = (qobjinst)ECOgetNVObject(objInst); // check for superinst..
  if ( objInst )
  {
    tqfJObjectContainer* object = (tqfJObjectContainer*)ECOFINDNVOBJECT(0, (LPARAM)objInst );
    if ( object && object->mObject )
    {
      EXTfldval fval1,fval2;
      ljline = ljlist->insertRow();
      ljlist->getColValRef(i,1,fval1,qtrue);
      fval1.setLong(object->mObject->mJObjID);
      ljlist->getColValRef(i,2,fval2,qtrue);
      fval2.setChar(lelemsig);
    }
  }
}

ECOgetOmnisVersionNumber() (v5.1.1)

qlong ECOgetOmnisVersionNumber(void)

Returns the Omnis Studio version number as a five digit long value.
For example: 5.1.1 is returned as 51100

ECOgetParamCount()

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.

extern "C" qlong OMNISWNDPROC GenericWndProc( HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci )
{
  ECOsetupCallbacks(hwnd,eci);
  switch (Msg)
  {
    case ECM_METHODCALL:
    {
      // OMNIS code is calling your component method
      qlong methodID = ECOgetId(eci);
      switch(methodID)
      {
        case cMyMethod1:
        {
          if ( ECOgetParamCount(eci) != 2 )
          {
            // Error - Method needs two parameters
            return 0l;
          }
        }
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECOgetParamInfo() (v3.1)

qbool ECOgetParamInfo( EXTparamInfo* pParam, EXTparamTypeInfo&pInfo)

Returns additional type information about the parameter specified by pParam.

See also EXTparamInfo, EXTparamTypeInfo

ECOgetProperty()

qbool ECOgetProperty(HWND pHwnd, qshort pAnum, EXTfldval& pFval )

The ECOgetProperty function enables the component to obtain information concerning Omnis standard object properties.

// Get $dataname property
EXTfldval fldname;
if ( ECOgetProperty( mHwnd, anumFieldname, fldname ) )
{
  // Get the name from the fldval
  str255 str;
  fldname.getChar ( str );
}

ECOgetStyle()

qbool ECOgetStyle(tqappfile* pApp, qchar* pStyleName, qshort pLen, GDItextSpecStruct* pTextSpec)

The ECOgetStyle function enables the component to obtain the field style information.

// Get the fieldstyle name
EXTfldval fval; ECOgetProperty(hwnd,anumFldStyle,fval);
str255 s; fval.getChar(s);
GDItextSpecStruct textSpec;
ECOgetStyle( app, &s[1], s[0], &textSpec );

ECOgetToolTipRect()

qbool ECOgetToolTipRect(HWND pHwnd, qrect* pRect)

The ECOgetToolTipRect function enables the component to obtain the position of the tool tip (if visible).

ECOhasFocus()

qbool ECOhasFocus( HWND pHWnd )

The ECOhasFocus function enables the component to inquire on the focus state of the object.

qbool result = ECOhasFocus( mHwnd );
if ( result )
{
  // object currently has the focus
}

ECOhideTooltip()

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.

ECOinsertObject()

void ECOinsertObject( EXTCompInfo* pEci, HWND pHWnd, void* pObjPointer, WPARAM pWParam )

Stores a pointer for the specified HWND in a list of Omnis instances.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
    case ECM_OBJCONSTRUCT:
    {
      cObj* myNewObject = new cObj();
      if ( myNewObject )
      {
        ECOinsertObject(eci, hwnd, (void*) myNewObject);
      }
      else
      {
        // … Error - Out of memory …
      }
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECM_OBJCONSTRUCT

ECOinsertNVObject()

void ECOinsertNVObject( HINSTANCE pInstance, LPARAM pInstPtr, void* pObjPointer )

Stores a pointer for the specified HWND in a list of Omnis instances.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
    case ECM_OBJCONSTRUCT:
    {
      cObj* obj = new cObj();
      ECOinsertNVObject(eci->mOmnisInstance,lParam,(void*)obj);
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOfindNVObject, Non-visual components

ECOinvalBackObj() (v3.1)

void ECOinvalBackObj()

If the object is a background component, ECOinvalBackObj() invalidates the drawing area, causing it to be redrawn.

ECOisDesign()

qbool ECOisDesign( HWND pHWnd )

The ECOisDesign function enables the component to inquire on the design state of the object.

qbool result = ECOisDesign( mHwnd );
if ( result )
{
  // object is in design mode.
}

ECOisMultiSelected()

qbool ECOisMultiSelected( HWND pHWnd )
qbool result = ECOisMultiSelected( mHwnd );
if ( result )
{
  // object is selected as part of a group
}

See also IS_MULTISELECTED

ECOisOMNISinTrueRuntime()

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.

if (ECOisOMNISinTrueRuntime( mHWnd ) )
{
  // can send events
}

ECOisSelected()

qbool ECOisSelected( HWND pHWnd )

Allows the component to inquire on whether the object is currently selected.

qbool result = ECOisSelected( mHwnd );
if ( result )
{
  // object is selected
}

See also IS_SELECTED

ECOisSerialised()

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.

See also IS_SERIALISED

ECOisSetup()

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.

qbool result = ECOisSetup( mHwnd );
if ( result )
{
  // object is setup and ready for action.
}

See also ECM_OBJINITIALIZE, IS_SETUP

ECOisShowNumber()

qbool ECOisShowNumber( HWND pHWnd )

Allows the component to inquire on whether the design-time option ‘Show number’ is on.

qbool result = ECOisShowNumber( mHwnd );
if ( result )
{
  // Show number is on
}

See also IS_SHOWNUMBER

ECOisWndTop()

qbool ECOisWndTop( HWND pHWnd )

Allows the component to inquire on whether the object is a member of the top-most window.

qbool result = ECOisWndTop( mHwnd );
if ( result )
{
  // object is on top
}

See also IS_WINDOW_TOP

ECOlistFonts()

void ECOlistFonts( EXTqlist *pList, qbool pReportFonts)

Allows the component to obtain a list of window or report fonts installed on the machine.

ECOlistSetLineHeight()

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.

// Forces all lists lines in a derived picture component to be 50 pixels high.
ECOlistSetLineHeight(mHwnd,50);

See also WM_CONTROL - LIST_SETLINEHEIGHT, cObjType_List

ECOloadFileDialog()

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.

Note: On MacOS make sure the component project contains the OMNISLIB.RSRC file.

// Load file (extract from PCX example)
str255 newFile;
if ( ECOloadFileDialog( gInstLib,hwnd,5000,5001,newFile ) )
{
  object->mFile = newFile;
  object->readPCX();
  WNDinvalidateRect( hwnd, NULL );
  ECOupdatePropInsp(hwnd);
}

ECOmapString() (v5.0)

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.

ECOmemoryDeletion()

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.

See also ECM_MEMORYDELETION

ECOmessageBox() (v3.3)

qbool ECOmessageBox(qulong pFlags,qbool pBell,str255& pMsg)

Provides external components with access to Omnis message box dialogs.

RESloadString(gInstLib, needInitialConversion ? 9000 : 9001, msg);
msg.insertStr(strPathName);
if (ECOmessageBox(MSGBOXICON_NOYES, qfalse, msg))
{
  //add conditional processing here
}

ECOpaintGrayFrame() (v5.0)

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.

//Excerpt from the Accordion component paint() method
if (hwnd() == hWnd)
{
  qrect clientRect;
  WNDgetClientRect(hwnd(), &clientRect);
  qrect entryRect(clientRect);
  qdim clientWidth = clientRect.width();
  WNDpaintStruct paintStruct;
  WNDbeginPaint(mHWnd, &paintStruct);
  HDC hdc = paintStruct.hdc;
  qrect rcPaint = paintStruct.rcPaint;
  void *offscreenPaintInfo = GDIoffscreenPaintBegin(NULL, hdc, clientRect, rcPaint);
  if (offscreenPaintInfo)
  {
    WNDdefWindowProc(hwnd(), WM_ERASEBKGND, (WPARAM) hdc, 0, eci)
    qbool isDesign = ECOisDesign(mHWnd);
    if (isDesign)
    {
      // Draw design stuff
      ECOdrawDesignName(mHWnd, hdc);
      ECOdrawNumber(mHWnd, hdc);
      ECOdrawMultiKnobs(mHWnd, hdc);
      #ifndef isRCC
        // If there is no border, draw a gray frame so the object bounds are visible in design mode
        WNDborderStruct bs;
        WNDgetBorderSpec(hwnd(), &bs);
        if (WND_BORD_NONE == bs.mBorderStyle)
          ECOpaintGrayFrame(hdc, clientRect);
      #endif
    }
    else
    {
      //...
    }
    GDIoffscreenPaintEnd(offscreenPaintInfo);
  }
  WNDendPaint(mHWnd, &paintStruct);
}

ECOreadLocalisationItem()

qbool ECOreadLocalisationItem(EXTCompInfo *pEci, qshort pLocItemXn, str255 &pLocItemData)

Returns the localised text from the localisation database.

ECOreloadLibData() (v4.1)

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.

ECOremoveObject()

void* ECOremoveObject(EXTCompInfo* pEci, HWND pHWnd, WPARAM pWParam )

Removes a pointer reference which had previously been stored via ECOinsertObject.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
    case ECM_OBJDESTRUCT:
    {
      CObj* myObject = (CObj *)ECOremoveObject( eci, hwnd );
      if ( NULL!= myObject)
        delete myObject;
        return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOinsertObject, ECM_OBJDESTRUCT

ECOremoveNVObject()

void* ECOremoveNVObject( HINSTANCE pInstance,LPARAM pInstPtr )

Removes a pointer reference which had previously been stored via ECOinsertNVObject.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
    case ECM_OBJDESTRUCT:
    {
      CObj* myObject = (CObj *)ECOremoveNVObject( eci->mOmnisInstance, lParam );
      if ( NULL!= myObject)
        delete myObject;
      return 1L;
    }
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

See also ECOinsertNVObject, Non-visual components

ECOresetObjDetails()

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.

See also Non-Visual components

ECOreturnCompID()

qlong ECOreturnCompID( HINSTANCE pInstance, EXTCompInfo* pEci,
qshort pCompResNameID, qshort pCompType )

The ECOreturnCompID function provides support for the ECM_GETCOMPID message.

See also ECM_GETCOMPID

ECOreturnCompInfo()

qlong ECOreturnCompInfo( HINSTANCE pInstance, EXTCompInfo* pEci,
qshort pLibNameResID, qshort pCompCount)

The ECOreturnCompInfo function provides support for the ECM_GETCOMPLIBINFO message.

See also ECM_GETCOMPLIBINFO

ECOreturnConstants()

qbool ECOreturnConstants( HINSTANCE pInstance, EXTCompInfo* pEci,
qlong pResStart, qlong pResEnd)

Provides support for the ECM_GETCONSTNAME message.

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

ECOreturnCStoreGrpName()

qbool ECOreturnCStoreGrpName( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResID )

The ECOreturnCStoreGrpName function provides support for the ECM_GETCOMPSTOREGROUP message.

See also ECM_GETCOMPSTOREGROUP

ECOreturnEventMethod()

qbool ECOreturnEventMethod( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResStart)

The ECOreturnEventMethod function provides support for the ECM_GETEVENTMETHOD message.

See also ECM_GETEVENTMETHOD

ECOreturnEventMethod()

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]

See also ECM_GETEVENTMETHOD

ECOreturnEvents()

qbool ECOreturnEvents( HINSTANCE pInstance, EXTCompInfo* pEci,
ECOmethodEvent* pTable, qshort pTableElements )

The ECOreturnEvents function provides support for the ECM_GETEVENTNAME message.

See also ECM_GETEVENTNAME, Component Events

ECOreturnIcon()

qbool ECOreturnIcon(HINSTANCE pInstance, EXTCompInfo* pEci, qshort pBitmapID )

The ECOreturnIcon function provides support for the ECM_GETCOMPICON message.

See also ECM_GETCOMPICON

ECOreturnMethodEvents

ECOreturnMethodEvents simply calls ECOreturnMethods.

ECOreturnMethods()

qbool ECOreturnMethods( HINSTANCE pInstance, EXTCompInfo* pEci,
ECOmethodEvent* pTable, qshort pTableElements )

The ECOreturnMethods function provides support for the ECM_GETMETHODNAME message.

See also ECM_GETMETHODNAME, Component Events

ECOreturnObjects()

qbool ECOreturnObjects( HINSTANCE pInstance, EXTCompInfo* pEci,
ECOobject* pTable, qshort pTableElements )

The ECOreturnObjects function provides support for the ECM_GETOBJECT message.

See also ECM_GETOBJECT, Non-Visual components

ECOreturnProperties()

qbool ECOreturnProperties( HINSTANCE pInstance, EXTCompInfo* pEci,
ECOproperty* pPropTable, qshort pTableElements )

The ECOreturnProperties function provides support for the ECM_GETPROPNAME message.

See also ECM_GETPROPNAME, and the Component Events section.

ECOreturnVersion()

qlong ECOreturnVersion( qshort pMajorNumber, qshort pMinorNumber)

The ECOreturnVersion function provides support for the ECM_GETVERSION message.

See also ECM_GETVERSION, GDIreadVersion

ECOreturnVersion() (Web Client 1.2)

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

  31020 “VER 1 5 %%ORFC_VER%%”

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.

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.

// Save file
str255 saveFile;
if ( ECOsaveFileDialog( gInstLib,hwnd,myResTitle,myResFilter, saveFile) )
{
  saveDataToFile( saveFile );
}

ECOsendCompEvent()

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.

// Event myEvent1 occurred. Send event to OMNIS
EXTCompInfo* eci = new EXTCompInfo();
eci->mParamFirst = 0;
// Add parameters to EXTCompInfo structure
EXTfldval myParam1;
myParam1.setlong( someData );
// Add parameter 1
ECOaddParam(eci,&myParam1,0,0,0,1,0);
// Send event to OMNIS
qbool eventOk = ECOsendCompEvent( hwnd, eci, myEventId, qtrue );
// Delete parameters from EXTCompInfo structure
ECOmemoryDeletion( eci );
// Delete eci structure
delete eci;

See also ECOsendEvent

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.

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.

// Send second event code to OMNIS (extract from CLOCK example)
EXTfldval newSeconds;
newSeconds.setLong(datetime->tm_sec);
ECOsendEvent( mHWnd, cClockEvSecs, &newSeconds, 1 );

See also ECOsendCompEvent

ECOsetCustomTabName()

qbool ECOsetCustomTabName( HINSTANCE pInstance, EXTCompInfo* pEci, qlong pResID )

The ECOsetCustomTabName function provides support for the ECM_CUSTOMTABNAME message.

See also ECM_CUSTOMTABNAME

ECOsetDTformat()

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.

// Set the date formatting (#FD for European or American formatting)
str80 s;
if ( EuropeanDateSystem )
  s=str80(“D m Y”);
else
  s=str80(“m D Y”);
ECOsetDTformat(s, dpFdate2000 );
// Get the date string (which will be formatted appropriately)
str255 displayString; myDate.getChar( displayString );
// Set #FD back to the old value
ECOsetDTformat(s, dpFdate2000 );

ECOsetError()

void ECOsetError( qlong pErrNum, str255* pErrText )

The ECOsetError function enables the component to set the Omnis variables #ERRCODE and #ERRTEXT.

// Set OMNIS #ERRCODE & #ERRTEXT variables
// #ERRCODE
qlong errCode = 1;
// #ERRTEXT
str255 errText(“Something bad has happened”);
ECOsetError( errCode, &errText );

ECOsetParameterChanged()

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.

See also ECM_METHODCALL, EXTD_FLAG_PARAMALTER

ECOsetProperty()

qbool ECOsetProperty( HWND pHwnd, qshort pAnum, EXTfldval &pFval )

The ECOsetProperty enables the component to set the Omnis standard object properties.

// Set the name from the fldval
str255 str(“#S1”);
fldname.setChar( str );
// Set $dataname property
EXTfldval fldname;
if ( ECOsetProperty( mHwnd, anumFieldname, fldname ) )
{
  // Successfully set the attribute
}

ECOsetupCallbacks()

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.

extern "C" qlong OMNISWNDPROC GenericWndProc(HWND hwnd, LPARAM Msg, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci)
{
  ECOsetupCallbacks(hwnd, eci);
  switch (Msg)
  {
  }
  return WNDdefWindowProc(hwnd,Msg,wParam,lParam,eci);
}

ECOupdatePropInsp()

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.

// Update all properties
ECOupdatePropInsp( mHwnd );
// Update myPropId
ECOupdatePropInsp( mHwnd, myPropId );

See also WM_CONTROL - UPDATE_PROPINSPECTOR

ECOuprCmp() (v5.1)

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.

WNDdefWindowProc()

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.

Memory Functions

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.

MEMcalloc()

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.

MEMdataLen()

qulong MEMdataLen( void* pBuffer )

Returns the size of a buffer.

MEMdecAddr()

qchar* MEMdecAddr( qchar* pAddress, qlong pOffset )

Decrements a memory address by an offset.

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.

MEMfree()

void MEMfree( void* pBuffer )

Reclaims the memory previous allocated from a MEMmalloc or MEMcalloc call.

MEMglobalAlloc()

HGLOBAL MEMglobalAlloc ( qlong pLength, qbool pZeroInited = qfalse )

Allocates a block of memory.

MEMglobalFree()

void MEMglobalFree ( HGLOBAL pMemory )

Reclaims the memory previously allocated by a MEMglobalAlloc. The data must be in an unlocked state.

MEMglobalHandle()

HGLOBAL MEMglobalHandle ( void* pAddress )

Returns a memory handle given an address.

MEMglobalLock()

void* MEMglobalLock (HGLOBAL pMemory )

Locks a memory handle, increments the lock count and returns the address of the handles first byte.

MEMglobalReAlloc()

HGLOBAL MEMglobalReAlloc ( HGLOBAL pMemory, qlong pNewLength )

Reallocates a block of memory.

MEMglobalSize()

qlong MEMglobalSize ( HGLOBAL pMemory )

Returns the size of a memory handle.

MEMglobalUnlock()

void MEMglobalUnlock ( HGLOBAL pMemory )

Unlocks a memory handle and decrement the lock count.

MEMincAddr()

qchar* MEMincAddr( qchar* pAddress, qlong pOffset )

Increments a memory address by an offset.

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.

MEMmalloc()

qchar* MEMmalloc( qulong pSize )

Allocates a block of memory, and locks it in memory. The allocation can be greater than 64K.

MEMmemcmp()

qint2 MEMmemcmp( void* pAddress1, void* pAddress2, qlong pTestLen )

Compares two blocks of memory.

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.

MEMmemFill()

void MEMmemFill( void* pFillAddress, qint4 pFillLen, qchar pFillChar )

Fills memory with a specified character.

Example:

qchar stringOne[] = “????”;
MEMmemFill(&stringOne[0],4,’*’);
// Would result in stringOne = ****

MEMmovel()

void MEMmovel( void* pSrc, void* pDst, qlong pLen )

Move memory from source to destination copying data from left to right ( start to end ).

Example:

qchar stringOne[] = “*OMNIS*”;
MEMmovel(&stringOne[1],&stringOne[0],6);
// Would result in stringOne = OMNIS**

MEMmover()

void MEMmover( void* pSrc, void* pDst, qlong pLen )

Move memory from source to destination copying data from right to left ( end to start )

Example:

qchar stringOne[] = “*OMNIS*”;
MEMmoveR(&stringOne[0],&stringOne[1],6);
// Would result in stringOne = **OMNIS

MEMrealloc()

qchar* MEMrealloc( void* pBuffer, qulong pNewLen )

Alters the size of the buffer to a different size.

MEMscanf()

qlong MEMscanf(qshort pDirection, qlong pLen, qchar pScanChar, const void * pScanAddress )

Scans a memory location for a character.

Example:

// Find character N in string
qchar stringOne[] = “OMNIS”;
qlong posOfN = MEMscanf(qtrue,5,’N’,&stringOne[0]);
// Would result in posOfN = 2
qlong posOfA = MEMscanf(qtrue,5,’A’,&stringOne[0]);
// Result in posOfA = 5 as MEMscanf failed to find A in memory

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.

HANglobalAlloc()

qHandle HANglobalAlloc ( qlong pLength, qbool pZeroInited = qfalse )

Allocates a block of memory, from Omnis the internal memory cache.

HANglobalReAlloc()

qHandle HANglobalReAlloc(qHandle pHandle, qlong pNewLen )

Reallocates a block of Omnis memory.

HANglobalSize()

qlong HANglobalSize ( qHandle pGlobal, qlong pNewLen )

Returns the size of a memory handle.

Note: This could be bigger than the data length.

HANglobalFree()

void HANglobalFree ( qHandle pHandle )

Reclaims the memory previously allocated by a HANglobalAlloc.

qHandlePtr Class

The qHandlePtr class gives your external components convenient ways to manipulate Omnis cache memory easily.

qHandlePtr::qHandlePtr

qHandlePtr:: qHandlePtr()

Creates an empty qHandlePtr class.

qHandlePtr::qHandlePtr()

qHandlePtr(qHandle pHandle, qlong pOffset)

Constructs a qHandlePtr class.

  1. pHandle- The memory to be handed back into the Omnis memory cache.

  2. pOffset - The offset into the memory.

qHandlePtr::qHandlePtr()

qHandlePtr (const qHandlePtr& pHptr)

Constructs a qHandlePtr class from an existing qHandlePtr.

  1. pHptr- an Existing qHandlePtr class.

qHandlePtr::operator =()

void operator =(qniltype qnil1)

Assigns the handle of the qHandlePtr to zero.

qHandlePtr::operator =()

void qHandlePtr:: operator =(const qHandlePtr& pHptr)

Duplicates an existing qHandlePtr.

  1. pHptr- an Existing qHandlePtr class.

qHandlePtr::operator +=()

void operator +=(qlong pInc)

Increments the offset in to memory block.

  1. pInc- The amount to increment the offset.

qHandlePtr::operator -=()

void operator -=(qlong pDec)

Decrements the offset in to memory block.

  1. pDec- The amount to decrement the offset.

qHandlePtr::operator +()

qHandlePtr operator +(qlong pDel)

Makes a copy of itself and increments the copy specified by pDel.

  1. pInc- The amount to increment the offset in the copy.

qHandlePtr::operator -()

qHandlePtr operator +(qlong pDel)

Makes a copy of itself and decrements the copy specified by pDel.

  1. pDec- The amount to decrement the offset in the copy.

qHandlePtr::operator !()

qbool operator !()

Tests whether the handle is non-zero.

qHandlePtr::operator *()

qchar* operator *()

Return a qchar pointer which is calculated as :-

  1. returns - Memory block base + Offset.

qHandlePtr::operator *()

qchar* operator *(qlong pDel)

Return a qchar pointer which is calculated as :-

  1. returns - Memory block base + Offset + pDel.

qHandlePtr::operator []()

qchar& operator [](qlong pDel)

Return a qchar reference which is calculated as

  1. returns - Memory block base + Offset + pDel.

qHandlePtr::dataLen()

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.

  1. returns - Data Length of the Handle.

qHandlePtr::dataLen()

Sets the actual length of the data contain in the handle.

  1. pSize - Sets the Data Length of the handle.

qHandlePtr::getOffset()

qulong getOffset()

Returns the current offset into the memory block

  1. returns - offset into the memory block.

qHandlePtr::getHandle()

void getHandle(qHandle& pHandle)

Returns the handle of the qhandleptr

  1. pHan - a qHandle memory block.

qHandlePtr::set()

void set(qHandle pHandle, qlong pOffset)

Sets the qhandleptr from the provided parameters

  1. pHandle - a qHandle memory block.

  2. pOffset - Offset into the memory block.

qHandlePtr::setOffset()

void setOffset(qlong pOffset)

Set the Offset of the qhandleptr.

  1. pOffset- Offset into the memory block.

qHandlePtr::setNull()

void setNull()

Set the handle to zero.

Resource Functions

The following set of RES or Resource functions allow cross-platform access to your external components resources.

REScloseLibrary()

void REScloseLibrary ( HINSTANCE pInstance)

Closes an instance of a DLL previously opened with RESopenLibrary.

See also RESopenLibrary

REScloseResourceFork() (MacOS only)

void REScloseResourceFork( qshort pResFileNum )

Closes a Macintosh resource file.

See also RESopenResourceFork

HINSTANCE RESgetOmnisDAT( EXTCompInfo* pEci )

Returns an instance to the Omnis resources library (OMNISDAT.DLL on Windows).

Note: The instance returned must not be closed (i.e. via REScloseLibrary).

RESloadBitmap()

HBITMAP RESloadBitmap( HINSTANCE pLibrary, qlong pBmpID )

Retrieves a HBITMAP object from the resources.

Note: The bitmap object must be deleted with GDIdeleteBitmap.

RESloadDialog()

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).

Note: The bitmap object must be deleted with GDIdeleteBitmap.

RESloadString()

qlong RESloadString( HINSTANCE pInstance, qlong pResID, qchar* pBuffer, qlong pBufferLen )

Retrieves a string from an open library resources.

RESloadString()

qlong RESloadString( HINSTANCE pInstance, qlong pResID, strxxx& pString )

Retrieves a string from an open library resources.

RESopenLibrary()

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.

See also REScloseLibrary

RESopenResourceFork() (MacOS only)

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.

str255 path = str255( “HD:Another File” );
HINSTANCE anotherInst = RESopenLibrary( path );
if ( anotherInst )
{
  qshort resRefNum = RESopenResourceFork(anotherInst );
  Handle macHandle = GetResource( ‘TYPE’, id );
  REScloseResourceFork(resRefNum);
  REScloseLibrary(anotherInst);
}
else
{
  // Open library failed
}

See also RESopenLibrary, REScloseResourceFork

Bit Functions

You can use the following functions for bit operations. The bit index range for all of the functions is 0-31.

bitClear()

void bitClear( qint4& pValue, qshort pBit )

Clears a bit in a value.

bitSet()

void bitSet( qint4& pValue, qshort pBit )

Sets a bit in a value.

bitSet()

void bitset( qint4& pValue, qshort pBit, qbool pState )

Alters the state of a bit in a value.

bitTest()

qbool bitTest( qint4 pValue, qshort pBit )

Tests a bit in a value.

Example:

qlong newValue = 28, oldValue = 28;
if ( bitTest(newValue,4 ) )
{
  bitClear( newValue,4 );
  if ( newValue==12 )
  {
    bitSet( newValue, 1 )
  }
}
if ( newValue==14 )
{
  bitSet( newValue,1, qfalse );
  bitSet( newValue,4, qtrue );
}
if ( newValue==oldValue )
{
  // all is OK.
}

ObjInst Functions

You can use the following functions in order to construct new instances of Omnis objects.

EXTobjinst()

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.

// Example of returning a dynamic object to OMNIS
// First setup mCompId so when we are required to do processing later,
// during WndProc, we know what the object is!
pEci->mCompId = myObjectRef;
qobjinst myNewObj = EXTobjinst( pEci );
if ( myNewObj )
{ // Succeeded, now pass the new object to OMNIS (transferring ownership)
  EXTfldval RtnVal;
  RtnVal.setObjInst( myNewObj, qtrue );
  ECOaddParam( pEci, &RtnVal );
}
else
{ // Failed (usually because of lack of memory )
}

See also ECOresetObjDetails,EXTfldval::setObjInst

EXTobjinst()

qobjinst EXTobjinst(qobjinst pObjInst)

This EXTobjinst function duplicates the supplied qobjinst to return a new qobjinst pointer.

// Example of new operator for the supplied objinst
qobjinst myNewObj = EXTobjinst( sourceObjInst );
if ( myNewObj )
{ // Succeeded, now pass the new object to OMNIS (transferring ownership)
  EXTfldval RtnVal;
  RtnVal.setObjInst( myNewObj, qtrue );
  ECOaddParam( pEci, &RtnVal );
}
else
{ // Failed (usually because of lack of memory )
}

See also EXTfldval::setObjInst

EXTobjinst()

qobjinst EXTobjinst(qapp pApp,str255* pClassName)

This EXTobjinst function creates a new instance of an object from the specified class name.

// Example of constructing a new ‘oMy_OMNIS_Object’
// Get qapp from locpinst held in EXTCompInfo structure
qapp myLibraryApp = ECOgetApp( pEci->mInstLocp );
// Set up the classname from which to construct the new object
str255 myClassName(“oMy_OMNIS_Object”);
// Create the new object
qobjinst myNewObj = EXTobjinst( myLibraryApp, &myClassName );
if ( myNewObj )
{ // Succeeded, now pass the new object to OMNIS (transferring ownership)
  EXTfldval RtnVal;
  RtnVal.setObjInst( myNewObj, qtrue );
  ECOaddParam( pEci, &RtnVal );
}
else
{ // Failed. Maybe due to lack of memory or that
  // oMy_OMNIS_Object doesn’t exist in the specified qapp
}

See also EXTfldval::setObjInst, ECOgetApp