The following are declared as part of the external components interface and are detailed in the Omnis Studio External Components documentation.
The ECOmethodEvent structure defines information about a single component event or method. The WCCcontrol structure takes an array of this structure in its mEvent member to define a control’s events and an array of this structure in its mMethods member to define a control’s methods.
struct ECOmethodEvent
{
qlong mId;
qlong mNameResID;
qlong mReturnDataType;
qlong mParameterCount;
ECOparam* mParameters;
qlong mFlags; qlong mExFlags;
};mId - The unique identifier, within the event table, for the event. All external events must have a positive number and must not be zero. All negative numbers are assumed to be Omnis internal events. For a list of supported internal events, look for ECE_ in EXTDEFS.HE.
mNameResID - Resource id which contains the event name. Event names must be unique and must not clash with Omnis internal events. The string 'ev‘ is used automatically as a prefix for any event. Use zero for internal events.
mReturnDataType - Returned data type of type fftxxx. Specify 0 for no returned data (e.g. void) and fftNone for an unspecified data type.
mParameterCount - Number of parameters for the event. Specify zero for no parameters.
mParameters - Pointer to an array of ECOparam parameters. Specify NULL if there are no parameters.
mFlags - Event flags of type EXTD_FLAG_xxxx. Use zero if you don't need any of the flags.
mExFlags - Use zero. Extended flags for future enhancement.
The ECOparam structure defines information about a single event parameter.
struct ECOparam
{
qlong mNameResID;
qlong mDataType;
qlong mFlags;
qlong mExFlags;
};mNameResID - Resource id for the parameter name. Defined in your .rc file, with the name and description of the parameter (separated by a colon - e.g. '7000 "MyParam:A description of MyParam"') . Standard parameters should use one of the ECE_xxx constants.
mDataType - Data Type of the property. An ffttype value, e.g. fftInteger.
mFlags - Parameter flags of type EXTD_FLAG_xxxx. Examples are EXTD_FLAG_PARAMOPT and EXTD_FLAG_PARAMALTER. Events from the JS Client will generally just use 0, as these flags usually don't apply.
mExFlags - Must be zero. Extended flags for future enhancement.
The ECOproperty structure defines information about a single component property. The WCCcontrol structure takes an array of this structure in its mProperties member to define the properties of a control.
struct ECOproperty
{
qlong mPropID;
qlong mNameResID;
qlong mDataType;
qlong mFlags;
qlong mExFlags;
qlong mEnumStart;
qlong mEnumEnd;
};mPropID - Property Identifier. To use standard properties, use the appropriate anumxxx value, e.g. anumText. Custom properties conventionally use values from 4000.
mNameResID - Resource id for the property name. Defined in your .rc file, with the name and description of the property (separated with a colon - e.g: '4000 "$myproperty:Description of my property"'. Necessary for custom properties but standard properties should use 0. Custom properties conventionally use the same value as mPropID.
mDataType - Data Type of the property. An ffttype value, e.g. fftInteger.
mFlags - An EXTD_FLAG_xxx value. Multiple flags can be set using the bitwise OR operator, e.g. EXTD_FLAG_PROPTEXT | EXTD_FLAG_PWINDCOL.
mExFlags - Extended flags for future enhancement.
mEnumStart - The first constant id in this property's constant enumeration.
mEnumEnd - The last constant id in this property's constant enumeration.
The size of this array must be a multiple of seven.
If you wish to include a $dataname property, this is handled as a special case.
It requires an ECOproperty with all members set to 0, except mFlags, which should be set to EXTD_FLAG_PRIMEDATA.
You will also need to set mControlHasDataName to qtrue in the constructor of your control's JSChtmlOptions struct (in your control's header file).
The JSChtmlOptions structure specifies the inner HTML generation options for a JavaScript client control. A component object passes an instance of this structure to its superclass via the mHtmlOptions member of the WCCcontrol structure.
struct JSChtmlOptions
{
public:
JSChtmlOptions()
{
mInnerStylePositionIsRelative = qfalse;
mInnerStyleHasFont = qtrue;
mInnerStyleHasTextColor = qtrue;
mInnerStyleHasBackgroundColor = qtrue;
mInnerStylePadding = 0;
mInnerStyleHasScrollbars = qfalse;
mInnerStyleHasAlign = qtrue;
mInnerStyleHasNoWrap = qtrue;
mControlHasEvents = qtrue;
mControlHasDataName = qtrue;
mAdjustWidthHeightForBorder = qfalse;
}
qbool mInnerStylePositionIsRelative;
qbool mInnerStyleHasFont;
qbool mInnerStyleHasTextColor;
qbool mInnerStyleHasBackgroundColor;
qbyte mInnerStylePadding;
qbool mInnerStyleHasScrollbars;
qbool mInnerStyleHasAlign;
qbool mInnerStyleHasNoWrap;
qbool mControlHasEvents;
qbool mControlHasDataName;
qbool mAdjustWidthHeightForBorder;
str255 mInnerStyleExtra;
};mInnerStylePositionIsRelative - A boolean which if set to qtrue will set the CSS position property to a value of 'relative' within the HTML inline style attribute. This positions the inner HTML relative to its normal position. The default for this member is false which will set the position property to a value of 'absolute' to position the HTML relative to its parent.
mInnerStyleHasFont - A boolean which if set to qtrue will include the CSS font properties within the HTML inline style attribute, e.g. font-family, font-size, etc. This allows text within the HTML to be styled based on the Omnis instance's text properties, e.g. $font, $fontsize, etc. The default is qtrue.
mInnerStyleHasTextColor - A boolean which if set to qtrue will include the CSS color property within the HTML inline style attribute. This allows the color of text within the HTML to be based on the Omnis instance's $textcolor property. The default is qtrue.
mInnerStyleHasBackgroundColor - A boolean which if set to qtrue will include the CSS background-color property within the HTML inline style attribute. This allows the background within the HTML to be based on the Omnis instance's $backcolor property. The default is qtrue.
mInnerStylePadding - A byte value of between 0 and 255 which if greater than zero will set the CSS padding property within the HTML inline style attribute. This defines the space between the HTML element's border and its content. The default value is zero.
mInnerStyleHasScrollbars - A boolean which if set to qtrue will include the CSS overflow-x and overflow-y properties within the HTML inline style attribute. This controls what happens to the HTML element's content if it overflows the content area. If the Omnis instance has a $autoscroll property set to kTrue the CSS properties will be set to 'auto', i.e. the content will have scrollbars in both directions. If $autoscroll is kFalse, the scroll behavior is based on the values of the $horzscroll and $vertscroll properties. If set to kTrue the CSS property will be set to 'scroll' and a scrollbar will appear in the required direction, if kFalse the property will be set to 'hidden' and there will be no scrollbar. By default the value of mInnerStyleHasScrollbars is false.
mInnerStyleHasAlign - A boolean which if set to qtrue will include the CSS text-align property within the HTML inline style attribute. This sets the horizontal alignment of text in the HTML element. The value is set according to the value of the Omnis instance's $align property. When this is set to kLeftJst, kRightJst or kCenterJst the CSS value will be one of left, right, center. The default for mInnerStyleHasAlign is qtrue.
mInnerStyleHasNoWrap - A boolean which if set to qtrue will include the CSS white-space property within the HTML inline style attribute. This will have a value of 'no-wrap'. This means that sequences of white space will be reduced to a single space and that text will not wrap to the next line. The default for mInnerStyleHasNoWrap is qtrue.
mControlHasEvents - A boolean which if set to qtrue will include the data-event attribute in the outer frame DIV element of the HTML if the component generates events. This is set to provide information to the JavaScript control to identify which events it should support. The data-event attribute uses a comma delimited list of event codes as its value. These codes are based on the list of evXXX constants which are set in the Omnis instance's $events property. If this list is empty then the attribute is not added. The default for mControlHasEvents is qtrue.
mControlHasDataName - A boolean which if set to qtrue will include the data-dataname attribute in the outer frame DIV element of the HTML if the component has a $dataname value. This is set to provide information to the JavaScript control to identify the instance variable providing data to that control. The data-dataname attribute uses the name of the instance variable as its value. The default for mControlHasDataName is qtrue.
mAdjustWidthHeightForBorder - A boolean which if set to qtrue will adjust the width and height of the outer fame DIV element of the HTML by the border width. The default value is false.
mInnerStyleExtra - An Omnis str255 string containing any extra CSS styling information to be appended to the HTML inline style attribute.
The WCCcontrol structure defines information about a JavaScript component. An instance of this structure is stored in the component’s base class when a component is created. It returns information requested by messages sent from Omnis and it is also passed to a component's JSC_GETINNERHTML function for use by utility methods that generate HTML based on the options which this structure defines.
struct WCCcontrol
{
qlong mResourceBase; // NOT USED
qlong mLibResName; // Resource number of library
qlong mObjectID; // External component object id
qlong mIconID; // ICON id for control
qlong mEventCount; // Count of events
ECOmethodEvent *mEvents; // Control events
qlong mPropertyCount; // Count of properties
ECOproperty *mProperties; // Control properties
qlong mFirstConstant; // First constant resource; zero if no constants
qlong mLastConstant; // Last constant resource; zero if no constants
qlong mCompFlags; // EXTIPJS_FLAG_xxx or EXTJS_FLAG_xxx flags sent in response to ECM_IPHONE_OR_JAVASCRIPT_COMPFLAGS
qlong mWccFlags; // WCC_FLAG_... flags
qlong mCompStoreGroupRes; // Resource number of component store group
qlong mMethodCount; // Count of methods
ECOmethodEvent *mMethods; // Control methods
FMTclassMakeFunc mMakeFmtClass; // Function to make class notation object
qlong mCustomTabName; // Resource number of custom tab
qdim mFixedLandscapeWidth; // Fixed landscape width for control (zero if any width allowed)
qdim mFixedLandscapeHeight;// Fixed landscape height for control (zero if any height allowed)
qdim mFixedPortraitWidth; // Fixed portrait width for control (zero if any width allowed)
qdim mFixedPortraitHeight; // Fixed portrait height for control (zero if any height allowed)
JSChtmlOptions *mHtmlOptions; // JavaScript client HTML options
JSC_GETINNERHTML mGetInnerHtml; // JavaScript client function to get inner HTML
JSC_APPENDCONTROLSTYLES mAppendControlStyles; // JavaScript client function to append control-specific styles
const char * mJscCtrlName; // JavaScript client control name
attnumber mControlNameAnum; // Attribute for control name when mJscCtrlName is to be overridden
};mResourceBase - Not used for JavaScript components.
mLibResName - Resource id which contains the component library name.
mObjectID - Resource id which contains the name of the component object within the library.
mIconID - Resource id for the component object’s icon.
mEventCount - The number of component events defined in the component.mEvents - A pointer to an array of component events. Specify NULL if there are no events.
mPropertyCount - The number of component properties that the component defines.
mProperties - A pointer to an array of component properties. Specify NULL if there are no properties.
mFirstConstant - Resource id of the first property constant. Specifiy zero if there are no constants.
mLastConstant - Resource id of the last property constant. Specifiy zero if there are no constants.
mCompFlags - Flags of type EXTIPJS_FLAG_xxx or EXTJS_FLAG_xxx which indicate supported properties and behaviors of the component.
mWccFlags - Flags of type WCC_FLAG_xxx which indicate supported behaviors of the component.
mCompStoreGroupRes - Resource id which contains the name of the Component Store group to which this component belongs.
mMethodCount - The number of component methods that the component defines.
mMethods - A pointer to an array of component methods. Specify NULL if there are no methods.
mMakeFmtClass - A FMTclassMakeFunc function that creates a sub-class of webClientComponent_formatNotation used to handle format notation when it needs to be processed by the control. This is zero if not required.(example). Not used for JS?
mCustomTabName - Resource id which contains the name of the custom tab that this component is using. (example)
mFixedLandscapeWidth - When a device is oriented in landscape mode then if greater than zero the value will fix the width of the control, otherwise any width is allowed. (example)
mFixedLandscapeHeight - When a device is oriented in landscape mode then if greater than zero the value will fix the height of the control, otherwise any width is allowed. (example)
mFixedPortraitWidth - When a device is oriented in portrait mode then if greater than zero the value will fix the width of the control, otherwise any width is allowed. (example)
mFixedPortraitHeight - When a device is oriented in portrait mode then if greater than zero the value will fix the height of the control, otherwise any width is allowed. (example)
mHtmlOptions - A pointer to the JSChtmlOptions structure which defines the options which affect the creation of the inner HTML template generated by the component.
mGetInnerHtml - A JSC_GETINNERHTML function that generates the inner HTML template for the component.
mAppendControlStyles - A JSC_APPENDCONTROLSTYLES function which appends control-specific styles to the inner HTML template. This is zero if there are no control-specific styles.
mJscCtrlName - A C string which is the name of the JavaScript object which implement the control.
mControlNameAnum - If overriding an existing control this is the attribute which specifies the name of the overriding JavaScript class. (example)
The EXTIPJS_FLAG_xxx defines are used in the mCompFlags member of the WCCcontrol structure.
EXTIPJS_FLAG_BACKCOLOR_AND_BACKALPHA
Indicates that the control has the $backcolor and $backalpha properties to change the background color.
EXTIPJS_FLAG_BEFORE_AND_AFTER
Indicates that the control generates before and after events.
EXTIPJS_FLAG_EFFECT
Indicates that the control has the $effect property to change its border style.
EXTIPJS_FLAG_NO_ERASE_BACKGROUND
Indicates that the control does not use the automated erase background processing.
EXTIPJS_FLAG_NOENABLED
Indicates that the control does not have the $enabled property.
EXTIPJS_FLAG_TRANSPARENT_BACKGROUND
Indicates that the control does not have the $backcolor and $backalpha properties and needs a transparent background. EXTIP_FLAG_BACKCOLOR_AND_BACKALPHA must not be set.
The EXTJS_FLAG_xxx defines are used in the mCompFlags member of the WCCcontrol structure.
EXTJS_FLAG_HAS_DEFAULT_BORDER
Indicates that the control can have its $effect property set to kJSborderDefault.
EXTJS_FLAG_HAS_DISPLAY_FORMAT
Indicates that the control has the $jsdateformat, $jsdateformatcustom and $jsnumberformat properties.
EXTJS_FLAG_HASMENUS
Indicates that the control has remote menus which need to be added to the context menu list sent to the client.
EXTJS_FLAG_NOTIFY_FLD_ENABLE
Indicates the control will be sent messages to change its enabled state.
The WCC_FLAG_xxx defines are used in the mWccFlags member of the WCCcontrol structure.
WCC_FLAG_CANFOCUS
Indicates that the control accepts the focus.
WCC_FLAG_USESCROLLVIEW
Indicates that the scroll view takes the focus when an OMBorderedView container is supplied.
The following are the most commonly used Omnis external component messages which are passed to a JavaScript component. For further details and a full list of messages please refer to the Omnis Studio External Components documentation.
The ECM_GETPROPERTY message is sent to the component when Omnis requires the data for a property.
The component should add a return parameter to the associated EXTCompInfo structure. This parameter will contain the property data.
Returns : True if successful, false otherwise.
The ECM_PROPERTYCANASSIGN message is sent to a component when Omnis needs to know if a property can be written to or is read only.
Returns: True if the property can be written to, false otherwise.
The ECM_SETPROPERTY message is sent to a component when Omnis requires a property to change.
The parameter passed in the associated EXTCompInfo structure contains the new data for the property.
Returns : True if successful, false otherwise.
| typedef qbool (*JSC_GETINNERHTML)(HWND pHwnd, WCCcontrol *pControl, webClientComponent *pObject, EXTfldval &pInnerHtml, qdim pWidth, qdim pHeight) |
The JSC_GETINNERHTML function pointer type defines the function used to generate the inner HTML for a JavaScript control. An implementation of a function of this type will return an HTML string representation of the control in the pInnerHtml parameter. This string is constructed based on the values of all other parameters passed into the function. A function of this type is passed as the mGetInnerHtml member of a component's WCCcontrol structure. The function will be called when Omnis sends a message requesting the HTML for a JavaScript control.
Parameters:
pHwnd - The child window associated with a component. This is used to obtain values of the Omnis standard properties for a component.
pControl - This is a WCCcontrol structure used to provide information about the required properties and behaviors of the JavaScript control.
pObject - A pointer to the instance of a component object. This will be NULL if there is no open design window.
pInnerHtml - A reference to a destination data field that will contain the HTML string for a control.
pWidth - The required CSS width of the inner HTML. This may be calculated based on border and padding options.
pHeight - The required CSS height of the inner HTML. This may be calculated based on border and padding options.
Returns: true if successful, false otherwise.
Example:
A typical use of this method is shown in the implementation of jsGenericComponent::jsGetInnerHTML in the jsgeneric.cpp source example.
The webClientComponent class is the top level base component support class and provides the default message handling, functionality and property support. It is inherited through the derived javaScriptComponent class which is itself directly inherited by the bottom level derived class implementation of a JavaScript component object, e.g. jsGenericComponent. This component specific sub-class is required to override and implement a set of virtual class methods declared in the webClientComponent base which are then called to provide the standard JavaScript component behavior.
These are class members that can be accessed directly to alter a component's behavior.
| qbool mNoDesignName; |
An instance of a JavaScript component is required to implement some of the following virtual methods to render a particular type of component and to provide the correct functionality.
| virtual qlong attributeSupport(LPARAM pMessage, WPARAM wParam, LPARAM lParam, EXTCompInfo* eci) |
Implemented by a subclass to provide responses to property management requests from the base class.
Parameters:
pMessage (LPARAM): The message identifier for the request, e.g. ECM_SETPROPERTY.
wParam (WPARAM): Additional message information for the request. Typically this is not used for a JavaScript component.
lParam (LPARAM): Additional message information for the request. Typically this is not used for a JavaScript component.
eci (EXTCompInfo): This is a pointer to a structure used for providing information about the component.
Returns:
| virtual void inval() |
Invalidate the whole of a component's window client area. This will result in a request to repaint the window and a call to paintDesign. Typically a subclass does not need to override this method. It is mainly used when a property changes the content of the window and it is sufficient to call the super class implementation.
| virtual void paintDesign(HDC pHdc); |
Provides drawing commands to render a component in a design window.
Parameters:
The javaScriptComponent class is the support class which must be the base class for all JavaScript component object classes. It provides utility methods for generating the inner HTML which are used to initially setup a JavaScript control in the client browser. It also inherits the webClientComponent base class which provides the default message handling, functionality and property support.
The following are static class methods that are generally used to build the HTML for a JavaScript control.
| javaScriptComponent::escapeHTMLsyntaxChars(EXTfldval &pFval, EXTfldval &pEscapedFval) |
Converts the string in the pFval data field to a version with escaped HTML markup characters (<, >, &, etc.) and places the result in pEscapedFval. This will allow the escaped string to be interpreted as a character literal. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pFval (EXTfldval&): The source data field containing the string to escape.
pEscapedFval (EXTfldval&): The destination data field containing the resulting escaped string.
Example
//
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div$></div>"));
pInner.setChar(innerTemplate);
EXTfldval textAttr;
textAttr(str15(QTEXT(" data-text=\"")));
EXTfldval textValue;
escapeHTMLsyntaxChars(object->mText, textValue);
textAttr.concat(textValue);
textAttr.concat('"');
jsInsert(textAttr, pInner, qfalse);
| void javaScriptComponent::jsAddIconUrl(HWND pHwnd, qlong pIconID, EXTfldval &pFval, qbool pInsert = qtrue) |
Inserts the URL of an icon image into the first '$' placeholder marker in pFval. The icon is identified by the pIconID parameter. The value of the path will be the location of the image relative to the directory containing the HTML page. If there are multiple image sizes for a single image id, each additional image file is appended to the path and separated by a semicolon character. The path is typically added to the inner HTML generated by a component's JSC_GETINNERHTML function to set the value of the HTML data-icon attribute for a JavaScript control. This attribute is used to display the icon image on the JavaScript control.
Parameters:
pHwnd (HWND): The child window associated with this component.
pIconID (qlong): The id of the icon image.
pFVal (EXTfldval&): The destination data field which is usually an HTML string where the URL string of the icon is inserted into the first placeholder.
pInsert (qbool): Optional. The default is qtrue to insert the URL as a replacement for the first placeholder marker. If qfalse then the URL is concatenated onto the end of the existing pFval string.
Example
//
// HWND pHwnd;
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div data-icon=\"$\"></div>"));
pInner.setChar(innerTemplate);
jsAddIconUrl(pHwnd, object->mIconId, pInner); // e.g. <div data-icon="icons/datafile/omnispic/001655n16.png"></div>| void javaScriptComponent::jsGetFontName(HWND pHwnd, EXTfldval &pFontNameFval, qlong pFont = -1, qlong pFontsize = -1) |
Gets the Omnis font name for a component associated with the pHwnd child window and uses it to set the value of the pFontNameFval data field. This value by default is based on the component's $font and $fontsize properties. When not -1 the pFont and pFontsize parameters are used to specify a particular Omnis font index and/or size that should be used. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pHwnd (HWND): The child window associated with a component.
pFontNameFval (EXTfldval&): The destination data field to store the font name.
pFont (qlong): A font index to identify the required font. By default, this is -1 to indicate it is not used.
pFontsize (qlong): A font size to identify the required font. By default, this is -1 to indicate it is not used.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %f - font family marker to be replaced with CSS property values
str255 innerTemplate = str255(QTEXT("<div style=\"%f\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
jsGetFontName(pHwnd, fval); // font name based on $font and $fontsize
jsStyleAppendFontName(fval, fvalResult);
fval.setChar(str15(QTEXT("%f")));
pInner.replaceStr(fval, fvalResult, qtrue); //<div style="font-family:'Courier New', Monospace;"></div>
| void jsGetIconPath(HWND pHwnd, qlong pIconID, str255& pStr) |
Sets the path to an icon image in the pStr string parameter. The icon is identified by the pIconID parameter. The value of the path will be the location of the image relative to the directory containing the HTML page and will be contained in double quotes. If there are multiple image sizes for a single image id, each additional image file is appended to the path and separated by a semicolon character. The path is typically added to the inner HTML generated by a component's JSC_GETINNERHTML function to set the value of the HTML data-icon attribute for a JavaScript control. This attribute is used to display the icon image on the control.
Parameters:
pHwnd (HWND): The child window associated with a component.
pIconID (qlong): The id of the icon image.
pStr(str255&): The string which will store the quoted icon path. This will be an empty set of quotes if the icon is invalid.
Example
//
// HWND pHwnd;
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 strIcon;
str255 innerTemplate = str255(QTEXT("<div data-icon=$></div>"));
pInner.setChar(innerTemplate);
jsGetIconPath(pHwnd, object->mIconId, strIcon);
jsInsert(strIcon, pInner, qfalse); // e.g. <div data-icon="icons/datafile/omnispic/001655n16.png"></div>| void javaScriptComponent::jsInsert(EXTfldval& pInsertStr, EXTfldval& pDst, qbool pEscapeHTMLsyntaxChars = qtrue) |
Inserts the string in pInsertStr into the first '$' placeholder marker in pDst. The string in pInsertStr is typically an HTML attribute value which substitutes for a value marker in an HTML template stored in pDst. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pInsertStr (EXTfldval&): The data field which contains the attribute value string to insert.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place pInsertStr.
pEscapeHTMLsyntaxChars (qbool): Optional. The default is qtrue to substitute pInsertStr with escaped HTML markup characters (<, >, &, etc.). This will allow them to be interpreted as character data.
Example
//
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div data-icon=\"$\"></div>"));
pInner.setChar(innerTemplate);
jsInsert(object->mFldVal, pInner); // e.g. <div data-icon="icons/datafile/omnispic/001655n16.png"></div>| javaScriptComponent::jsInsertBool(char *pAttName, qbool pValue, EXTfldval& pDst) |
If pValue is true this creates a string, in the format of an attribute/value pair, from the name in pAttName and the value '1'. This string is inserted into the first '$' placeholder marker in pDst. A leading space is prepended to the string so it takes the form <space><attname>=1. If pValue is qfalse an empty string is inserted. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pAttName (char*): The attribute name to insert.
pValue (qbool): A boolean qtrue value indicates that the attribute is included in the HTML with a value of 1.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute name/value pair.
Example
//
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div$></div>"));
pInner.setChar(innerTemplate);
jsInsertNum("data-vert", object->mVertical, pInner); // e.g. <div data-vert=1></div>| void javaScriptComponent::jsInsertBorder(HWND pHwnd, EXTfldval &pDest) |
Uses the Omnis border properties for a component associated with the pHwnd child window to create the HTML data attributes which will be inserted into the first '$' placeholder marker in pDest. This is called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function. The HTML data attributes are then used by the JavaScript control, e.g. data-effect, data-linestyle, data-bordercolor, data-borderradius, to calculate the correct border styling and positioning for the control.
Parameters:
pHwnd (HWND): The child window associated with a component. This is used to obtain the value of the Omnis border properties for a component, e.g. $effect, $linestyle, $bordercolor, $borderradius.
pDest (EXTfldval&): The destination data field that contains the HTML string for the control.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %e - border style marker to be replaced with data attributes
str255 innerTemplate = str255(QTEXT("<div %e></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
fvalResult.setChar(str15(QTEXT("$")));
jsInsertBorder(pHwnd, fvalResult);
fval.setChar(str15(QTEXT("%e")));
pInner.replaceStr(fval, fvalResult, qtrue); // e.g. "<div data-effect="10" data-linestyle="1" data-bordercolor="0" data-borderradius="20"></div>
| javaScriptComponent::jsInsertColor(const char *pAttName, qcol pColor, EXTfldval &pDest) |
Replaces a ‘$’ placeholder in pDest with an attribute named as specified in pAttName, and with a color value (RGB integer or constant) as specified by pColor.
Parameters:
pAttName (char*): The name for the attribute to insert.
pColor (qcol): The color value to use.
pDest (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute.
Example
// EXTfldval &pInner;
// $ - marker to be replaced with custom color attribute
str255 innerTemplate = str255("<div $></div>");
pInner.setChar(innerTemplate);
ECOgetProperty(pHwnd, anumBackColor, fval); // get the value of $backcolor
qcol color = fval.getLong();
jsInsertColor("data-mycolor", color, pInner);| javaScriptComponent::jsInsertColorPair(HWND pHwnd, EXTfldval &pDest, qcol pColorValue, qlong pAlpha) |
DEPRECATED in 10.2
Color Pairs are no longer needed (all browsers now support alpha), and they do not support Themed Colors. Use jsInsertColor() instead, and pass the alpha as a separate attribute.
Uses the Omnis qcol color in pColorValue and the alpha value in pAlpha to create the equivalent CSS color property values for the component associated with the child window in pHwnd. If pAlpha is not -1 a pair of color values will be created separated by a semicolon. The first will be the CSS hex color and the second will be the CSS RGBA color. These will be inserted into the first '$' placeholder marker in pDest. This is called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function. The control can the use these color alternatives based on whether it supports an RGBA value.
Parameters:
pHwnd (Object): The child window associated with a component.
pDst (Object): The destination data field which contains the HTML string in which to place the color pair.
pColorValue (qcol): The qcol used to create a CSS hex color value or the RGB part of a CSS RGBA color value if pAlpha is not -1.
pAlpha (qlong): If -1 then only a CSS hex color is created. Otherwise, a value of between 0 and 255 will be used to create the alpha part of a CSS RGBA color value.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// $ - marker to be replaced with CSS color property value
str255 innerTemplate = str255(QTEXT("<div data-control-color=\"$\"></div>"));
pInner.setChar(innerTemplate);
ECOgetProperty(pHwnd, anumBackColor, fval); // get the value of $backcolor
qcol color = fval.getLong();
ECOgetProperty(pHwnd, anumBackgroundAlpha, fval); // get the value of $backalpha
qlong alphaValue = fval.getLong();
jsInsertColorPair(pHwnd, pInner, color, alphaValue); // e.g. "<div data-control-color="#0000FF;rgba(0,0,255,0.5020)"></div>"| javaScriptComponent::jsInsertIcon(HWND pHwnd, char *pAttName, qlong pIconId, EXTfldval& pDst) |
Creates a string, in the format of an attribute/value pair, where the attribute name is the value in pAttName and the attribute value is a URL locating the icon with the id passed in pIconId. This string is inserted into the first '$' placeholder marker in pDst. The value of the URL will be the location of the image relative to the directory containing the HTML page. If there are multiple image sizes for a single image id then each additional image file is appended to the URL and separated by a semicolon character. A leading space is prepended to the string so it takes the form <space><attname>="<icon url>". If the pIconId value does not have a valid ID an empty string is inserted into pDst. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pHwnd (HWND): The child window associated with a component whose icon URL is to be used.
pAttName (char*): The attribute name to insert.
pIconID (qlong): The id of the icon image.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute name/value pair.
Example
// HWND pHwnd;
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div$></div>"));
pInner.setChar(innerTemplate);
jsInsertIcon(pHwnd, "data-icon", object->mIconId, pInner); // e.g. <div data-icon="icons/datafile/omnispic/001655n16.png"></div>| void javaScriptComponent::jsInsertId(HWND pHwnd, EXTfldval &pDest, qbool pFrame, strxxx *pSuffix = 0) |
Inserts the HTML id attribute's name/value pair into the first '$' placeholder marker in pDest. This is called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function. Typically pFrame is qfalse and pSuffix is unused. The value of id placed in the HTML will be the component group's class name, i.e. the remote form name, followed by the unique numeric $ident value of the component within the group and the suffix for the level of the element, i.e. id="<classname>_<ident>_client/frame".
Parameters:
pHwnd (HWND): The child window associated with a component. This is used to obtain the value of the Omnis standard properties for the component.
pDest (EXTfldval&): The destination data field that contains the HTML string for the control.
pFrame (qbool): This is qfalse if the id value is to have a suffix of '_client' when generating the inner HTML of the control. This is qtrue if the suffix is to be '_frame' for the outer HTML of the control.
pSuffix (strxxx*): An alternative suffix for the id value. If set then pFrame is ignored.
// HWND pHwnd;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div $></div>"));
pInner.setChar(innerTemplate);
jsInsertId(pHwnd, pInner, qfalse); // e.g. <div id="testGeneric_1001_client"></div>A typical use of this method is shown in the implementation of jsGenericComponent::jsGetInnerHTML in the jsgeneric.cpp source example.
| javaScriptComponent::jsInsertIfNotEmpty(const char *pAttName, EXTfldval &pInsertStr, EXTfldval &pDst) |
When the value is not empty this method inserts the HTML attribute name/value pair, formed from the attribute name in pAttName and the attribute value in pInsertStr, into the first '$' placeholder marker in pDst. The substitution will place a space before the attribute name. When the value of pInsertStr is empty then the placeholder is replaced with nothing. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pAttName (EXTfldval&): The attribute name to insert.
pInsertStr (const char *): The data field which contains the attribute value string to insert.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute name/value pair.
Example
// HWND pHwnd;
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div$></div>"));
pInner.setChar(innerTemplate);
jsInsertIfNotEmpty("data-text", object->mText, pInner); // results in <div data-text="some text"></div>| javaScriptComponent::jsInsertNum(char *pAttName, qlong pValue, EXTfldval& pDst) |
Creates a string, in the format of an attribute name/value pair, from the name in pAttName and the numeric value in pValue and inserts it into the first '$' placeholder marker in pDst. A leading space is prepended to the string so it takes the form <space><attname>="<value>". If pValue is zero an empty string is inserted. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function.
Parameters:
pAttName (char*): The attribute name to insert.
pValue (qlong): The attribute value to insert. If zero an empty string is inserted.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute name/value pair.
Example
// webClientComponent *object;
// EXTfldval &pInner;
//
str255 innerTemplate = str255(QTEXT("<div$></div>"));
pInner.setChar(innerTemplate);
jsInsertNum("data-max", object->mMax, pInner); // e.g. <div data-max="100"></div>| void javaScriptComponent::jsInsertStyle(HWND pHwnd, WCCcontrol *pControl, EXTfldval &pDest, qdim pWidth, qdim pHeight, javaScriptComponent *pObject) |
Inserts the inline style attribute name/value pair into the first '$' placeholder marker in pDest. This can be called as part of the HTML generation of the inner HTML for a JavaScript control in a component's JSC_GETINNERHTML function. The style attribute value will contain the CSS property values set from the component's standard Omnis property values to set characteristics in the JavaScript control such as padding, position, font, alignment, text color, scrollbars, focus and background color. These are included based on the options that have been used in the pControl parameter.
Parameters:
pHwnd (HWND): The child window associated with this component. This is used to obtain values of the Omnis standard properties for this component.
pControl (WCCcontrol): Describes the JavaScript control's required properties and behavior. This is a WCCcontrol structure where the mHtmlOptions member controls which standard CSS values are added and the mAppendControlStyles member appends control-specific styles to the JavaScript control.
pDest (EXTfldval&): The destination data field to contain the HTML string for the control.
pWidth (qdim): The required CSS width of the inner HTML. This is passed into the JSC_GETINNERHTML function and may be calculated based on border and padding options.
pHeight (qdim): The required CSS height of the inner HTML. This is passed into the JSC_GETINNERHTML function and may be calculated based on border and padding options.
pObject (qdim): An instance of a component object which can be used to retrieve component specific CSS styles.
A typical use of this method is shown in the implementation of jsGenericComponent::jsGetInnerHTML in the jsgeneric.cpp source example.
// HWND pHwnd;
// WCCcontrol* pControl;
// EXTfldval &pInner;
// qdim pWidth, pHeight;
// webClientComponent* object;
//
str255 innerTemplate = str255(QTEXT("<div $></div>"));
pInner.setChar(innerTemplate);
jsInsertStyle(pHwnd, pControl, pInner, pWidth, pHeight, object); // e.g. <div style="position:absolute; padding:10px;top:0px; left:0px; height:81px; width:81px; font-family:Verdana,Arial,Helvetica,Sans-serif;font-size:medium;font-weight:normal;font-style:normal;text-align:left;color:#000000;overflow-y:hidden;overflow-x:hidden;white-space:nowrap;"></div>| javaScriptComponent::jsInsertWithAttName(EXTfldval& pInsertStr, EXTfldval& pDst, strxxx &pAttName) |
Inserts the HTML attribute value string in pInsertStr, prepended with the HTML attribute name in pAttName, into the first '$' placeholder marker in pDst. The substitution places an HTML attribute name/value pair into the HTML template stored in pDst. This is called as part of the HTML generation of the inner HTML for a control in a component's JSC_GETINNERHTML function.
Parameters:
pInsertStr (EXTfldval&): The data field which contains the attribute value string to insert.
pDst (EXTfldval&): The destination data field which contains the HTML string in which to place the attribute name/value pair.
pAttName (strxxx&): The attribute name to insert.
Example
omnis // // HWND pHwnd; // webClientComponent *object; // EXTfldval &pInner; // str255 innerTemplate = str255(QTEXT("<div $></div>")); pInner.setChar(innerTemplate); str255 dataText(QTEXT("data-text")); jsInsertWithAttName(object->mText, pInner, dataText); // results in <div data-text="some text"></div>
| javaScriptComponent::jsStyleAppendColor(HWND pHwnd, attnumber pColorAnum, EXTfldval& pDst, attnumber pAlphaComponent=0) |
Uses the Omnis color and alpha property values of the component associated with the pHwnd child window to create the equivalent CSS color property value. The CSS property value will be appended onto the data field in pDest. The attribute numbers passed in pColorAnum and pAlphaComponent identify the color and alpha properties of the component which are to be used. The pColorAnum value will generate a CSS hex color or if non-zero the pAlphaComponent will generate a CSS RGBA color value formed from both parameters.
Parameters:
pHwnd (HWND): The child window associated with a component. This is used to obtain the value of the component properties specified in pColorAnum and pAlphaComponent.
pColorAnum (attnumber): The attribute number which identifies the Omnis property whose value will be used to create the CSS hex color value or the RGB part of the CSS RGBA color value if pAlphaComponent is not zero.
pDst (EXTfldval&): The destination data field which contains the string onto which the CSS color property value will be appended.
pAlphaComponent (attnumber): Optional. Default is zero. If non-zero then this attribute number identifies the Omnis property whose value will be used to create the alpha part of the CSS RGBA color value.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// qbool alpha;
// $ - marker to be replaced with CSS color property value
str255 innerTemplate = str255(QTEXT("<div style=\"$\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
fvalResult.setEmpty(fftCharacter, dpDefault);
fvalResult.concat(str15(QTEXT("color:")));
if(!alpha)
{
jsStyleAppendColor(pHwnd, anumBackColor, fvalResult); // append the hex color value using $backcolor
fval.setChar(str15(QTEXT("$")));
pInner.replaceStr(fval, fvalResult, qtrue); // e.g. "<div style="color:#0000FF"></div>"
}
else
{
jsStyleAppendColor(pHwnd, anumBackColor, fvalResult, anumBackgroundAlpha); // append the RGBA color value using $backcolor and $backalpha
fval.setChar(str15(QTEXT("$")));
pInner.replaceStr(fval, fvalResult, qtrue); // e.g. "<div style="color:rgba(0,0,255,0.5020)"></div>"
}| javaScriptComponent::jsStyleAppendColorFromValue(HWND pHwnd, qcol pColorValue, EXTfldval &pDest, qlong pAlpha=-1) |
Uses the Omnis qcol color in pColorValue and the alpha value in pAlpha to create the equivalent CSS color property value for the component associated with the child window in pHwnd. The CSS property value will be appended onto the data field in pDest. The qcol value of pColorValue will generate a CSS hex color or if not -1 the pAlpha value will be used to generate a CSS RGBA color value formed from both parameters.
Parameters:
pHwnd (HWND): The child window associated with a component.
pColorValue (qcol): The qcol used to create a CSS hex color value or the RGB part of a CSS RGBA color value if pAlpha is not -1.
pDst (EXTfldval&): The destination data field which contains the string onto which the CSS color property value will be appended.
pAlpha (qlong): Optional. Default is -1. A value of between 0 and 255 will be used to create the alpha part of a CSS RGBA color value.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// qbool alpha;
// $ - marker to be replaced with CSS color property value
str255 innerTemplate = str255(QTEXT("<div style=\"$\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
fvalResult.setEmpty(fftCharacter, dpDefault);
fvalResult.concat(str15(QTEXT("color:")));
ECOgetProperty(pHwnd, anumBackColor, fval); // get the value of $backcolor
qcol color = fval.getLong();
if(!alpha)
{
jsStyleAppendColor(pHwnd, color, fvalResult); // append the hex color value
fval.setChar(str15(QTEXT("$")));
pInner.replaceStr(fval, fvalResult, qtrue); // e.g. "<div style="color:#0000FF"></div>"
}
else
{
ECOgetProperty(pHwnd, anumBackgroundAlpha, fval); // get the value of $backalpha
qlong alphaValue = fval.getLong();
jsStyleAppendColor(pHwnd, color, fvalResult, alphaValue); // append the RGBA color value
fval.setChar(str15(QTEXT("$")));
pInner.replaceStr(fval, fvalResult, qtrue); // e.g. "<div style="color:rgba(0,0,255,0.5020)"></div>"
}| void jsStyleAppendFontAlign(qlong pAlignValue, EXTfldval &pDst) |
Uses the Omnis qjst text justification constant in pAlignValue to create an equivalent CSS text-align property and appends that CSS property string to the value in pDst. This is called as part of the HTML generation of the inner HTML for a control in a component's JSC_GETINNERHTML function.
Parameters:
pAlignValue (qlong): The Omnis qjst constant, e.g. jstLeft, jstRight, etc.
pDst (EXTfldval&): The destination data field to which to append the CSS property string.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %j - font align marker to be replaced with CSS property value
str255 innerTemplate = str255(QTEXT("<div style=\"%j\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
ECOgetProperty(pHwnd, anumAlign, fval); // get the value of $align
fvalResult.setEmpty(fftCharacter, dpDefault);
jsStyleAppendFontAlign(fval.getLong(), fvalResult);
fval.setChar(str15(QTEXT("%j")));
pInner.replaceStr(fval, fvalResult, qtrue);| void javaScriptComponent::jsStyleAppendFontName(EXTfldval& pInsertStr, EXTfldval& pDst) |
Uses the Omnis font name in pInsertStr to create an equivalent CSS font-family property and appends that CSS property string to the value in pDst. This is called as part of the HTML generation of the inner HTML for a control in a component's JSC_GETINNERHTML function. It can be used to provide the correct CSS font styling for the text in an HTML control based on a components $font and $fontsize properties.
Parameters:
pInsertStr (EXTfldval&): The Omnis font name, e.g. "Verdana,Arial,Helvetica,Sans-serif".
pDst (EXTfldval&): The destination data field to which to append the CSS property string.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %f - font family marker to be replaced with CSS font property values
str255 innerTemplate = str255(QTEXT("<div style=\"%f\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
jsGetFontName(pHwnd, fval); // font name based on $font and $fontsize
jsStyleAppendFontName(fval, fvalResult);
fval.setChar(str15(QTEXT("%f")));
pInner.replaceStr(fval, fvalResult, qtrue);| void javaScriptComponent::jsStyleAppendFontSize(qlong pSize, EXTfldval& pDst) |
Maps the pSize value which will be an Omnis font size value to the equivalent CSS font-size property and appends that string to the value in pDst. This is called as part of the HTML generation of the inner HTML for a control in a component's JSC_GETINNERHTML function. It can be used to provide the correct CSS font size for the text in an HTML control based on a components $fontsize property.
Parameters:
pSize (qlong): The Omnis font size value to be mapped to the equivalent CSS font-size property.
pDst (qlong): The destination data field to which to append the CSS property string.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %z - font size marker to be replaced with CSS font-size property value
str255 innerTemplate = str255(QTEXT("<div style=\"%z\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
ECOgetProperty(pHwnd, anumFontsize, fval); // get the $fontsize value
fvalResult.setEmpty(fftCharacter, dpDefault);
jsStyleAppendFontSize(fval.getLong(), fvalResult);
fval.setChar(str15(QTEXT("%z")));
pInner.replaceStr(fval, fvalResult, qtrue);| void jsStyleAppendFontStyle(qlong pStyle, EXTfldval& pDst) |
Maps the pStyle value which will be an Omnis qsty constant to the equivalent CSS font properties and appends that CSS string to the value in pDst. This is called as part of the HTML generation of the inner HTML for a control in a component's JSC_GETINNERHTML function. It can be used to provide the correct CSS font styling for the text in an HTML control based on a component's $fontstyle property.
Parameters:
pStyle (qlong): The Omnis qsty value, e.g. styPlain, styBold, styItalic, styUnderline. This will be mapped to the equivalent CSS font property.
pDst (qlong): The destination data field to which to append the CSS property string.
Example
// HWND pHwnd;
// EXTfldval &pInner;
// %s - font style marker to be replaced with CSS property values
str255 innerTemplate = str255(QTEXT("<div style=\"%s\"></div>"));
pInner.setChar(innerTemplate);
EXTfldval fval;
EXTfldval fvalResult;
ECOgetProperty(pHwnd, anumFontstyle, fval); // get the $fontstyle value
fvalResult.setEmpty(fftCharacter, dpDefault);
jsStyleAppendFontStyle(fval.getLong(), fvalResult);
fval.setChar(str15(QTEXT("%s")));
pInner.replaceStr(fval, fvalResult, qtrue);
| void javaScriptComponent::setRedrawOnSize() |
This is called to specify that all of the client area of a component child window is invalidated when the width or height of its window changes. This allows the correct redrawing of the component contents in a design window. By default only the uncovered areas are invalidated. If the contents of the component need to be adjusted to fit the width and height, this method should be called in the component subclass constructor.
The following are methods that can be overridden by a component subclass.
| qbool getCtrlName(EXTfldval& pFval) |
This method is overridden by a component subclass when it supports an Omnis property to provide the name of an existing JavaScript control. The name is used to identify an existing control which will have its inner HTML generated from this component to override the HTML that the control would normally have used. The control name should be set in the pFval parameter.
A component that uses this mechanism will also specify the Omnis property attribute number in the mControlNameAnum member of the WCCcontrol structure.
The default base class implementation does nothing and returns qfalse.
Parameters:
Returns:
Example:
The JSHTML component uses this method to get the JavaScript control class that was set in its $ctrlname property.